From 8bef817bca6e6b76100905b6508b3798d54b6ba6 Mon Sep 17 00:00:00 2001
From: Chris Sangwin <C.J.Sangwin@ed.ac.uk>
Date: Thu, 2 Jan 2025 17:48:33 +0000
Subject: [PATCH] Update the documentation, and add in test cases.

---
 doc/en/Authoring/Answer_Tests/Equivalence.md | 4 ++--
 doc/en/Authoring/Inputs/index.md             | 2 ++
 doc/en/CAS/Numbers.md                        | 1 +
 stack/cas/cassecurity.class.php              | 3 +--
 tests/fixtures/answertestfixtures.class.php  | 4 ++++
 5 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/en/Authoring/Answer_Tests/Equivalence.md b/doc/en/Authoring/Answer_Tests/Equivalence.md
index f6b4940f9..9b1d770f9 100644
--- a/doc/en/Authoring/Answer_Tests/Equivalence.md
+++ b/doc/en/Authoring/Answer_Tests/Equivalence.md
@@ -32,9 +32,9 @@ This is the most commonly used test.  The pseudo code
 This test will work with a variety of [types of object](../../CAS/Maxima_background.md#Types_of_object) of mathematical objects, including lists, sets, equations, inequalities and matrices.
 
 * This test disregards whether [simplification](../../CAS/Simplification.md) is switched on, it always fully simplifies all its arguments.
-* Use `AlgEquiv(predicate(ex),true)` with [predicate functions](../../CAS/Predicate_functions.md).
+* Use `AlgEquiv(predicate(ex),true)` with [predicate functions](../../CAS/Predicate_functions.md), to test the result is true.  But note that many predicate functions only work without simplification!  In particular, testing for "form" such as scientific notation need `simp:false`, in which case use `EqualComAss(predicate(ex),true)` rather than algebraic equivalence.
 
-Note: exactly what it does depends on what objects are given to it.  In particular the pseudo code above only applies to expressions.  We cannot subtract one list or set from another, so we have to use other tests.
+Note: exactly what this answer test does depends on what objects are given to it.  In particular the pseudo code above only applies to expressions.  We cannot subtract one list or set from another, so we have to use other tests.
 
 For sets, the CAS tries to write the expression in a canonical form.  It then compares the string representations these forms to remove duplicate elements and compare sets.  This is subtly different from trying to simplify the difference of two expressions to zero.  For example, imagine we have \(\{(x-a)^{6000}\}\) and \(\{(a-x)^{6000}\}\).  One canonical form is to expand out both sides.  While this work in principal, in practice this is much too slow for assessment.
 
diff --git a/doc/en/Authoring/Inputs/index.md b/doc/en/Authoring/Inputs/index.md
index f8051cb1a..1dec0f847 100644
--- a/doc/en/Authoring/Inputs/index.md
+++ b/doc/en/Authoring/Inputs/index.md
@@ -109,6 +109,8 @@ There are groups of common keywords which you can forbid simply as
 * `[[BASIC-CALCULUS]]` common calculus operations such as `int`, `diff`, `taylor`, etc.
 * `[[BASIC-MATRIX]]` common matrix operations such as `transpose`, `invert`, `charpoly`, etc.
 
+These list are hard-wired into the code [here](https://github.com/maths/moodle-qtype_stack/blob/master/stack/cas/cassecurity.class.php#L56).
+
 If you have suggestions for more lists, or additional operations which should be added to the existing lists, please contact the developers.
 
 
diff --git a/doc/en/CAS/Numbers.md b/doc/en/CAS/Numbers.md
index ed536b1fe..75ed1faa0 100644
--- a/doc/en/CAS/Numbers.md
+++ b/doc/en/CAS/Numbers.md
@@ -155,3 +155,4 @@ The following commands generate displayed forms of numbers.  These will not be m
 | `anyfloatex(ex)`            | Decides if any floats are in the expression.
 | `scientific_notationp(ex)` | Determines if \(ex\) is written in the form \(a10^n\) where \(a\) is an integer or float, and \(n\) is an integer.
 
+Please note that these predicate functions need to be used with `simp:false`.  Some answer tests, including the default algebraic equivalence (`ATAlgEquiv`) always simplify their arguments.  Instead use a non-simplifying answer test such as `EqualComAss`.
diff --git a/stack/cas/cassecurity.class.php b/stack/cas/cassecurity.class.php
index ece45b76d..ead8634ca 100644
--- a/stack/cas/cassecurity.class.php
+++ b/stack/cas/cassecurity.class.php
@@ -49,8 +49,7 @@ class stack_cas_security {
 
     /**
      * These lists are used by question authors for groups of words.
-     * They should be lower case, because Maxima is lower case, and these correspond to Maxima names.
-     * Actually, not lower case, Maxima is not case insensitive just check "ModeMatrix" for an example.
+     * These correspond to Maxima names, and should follow the case in maxima, e.g. "ModeMatrix" for an example.
      */
     public static $keywordlists = [
         '[[basic-algebra]]' => [
diff --git a/tests/fixtures/answertestfixtures.class.php b/tests/fixtures/answertestfixtures.class.php
index 35a668294..3a3cd5d78 100644
--- a/tests/fixtures/answertestfixtures.class.php
+++ b/tests/fixtures/answertestfixtures.class.php
@@ -75,6 +75,7 @@ class stack_answertest_test_data {
         ['AlgEquiv', '', 'lowesttermsp(-y/-x)', 'true', 1, 'ATLogic_True.', ''],
         ['AlgEquiv', '', 'lowesttermsp((x^2-1)/(x-1))', 'true', 0, '', ''],
         ['AlgEquiv', '', 'lowesttermsp((x^2-1)/(x+2))', 'true', 1, 'ATLogic_True.', ''],
+        ['AlgEquiv', '', 'scientific_notationp(4.1561*10^16)', 'true', 0, '', ''],
         ['AlgEquiv', '', 'X', 'x', 0, 'ATAlgEquiv_WrongCase.', 'Case sensitivity'],
         ['AlgEquiv', '', '1/(R-r)', '1', 0, '', ''],
         ['AlgEquiv', '', 'exdowncase(X)', 'x', 1, '', ''],
@@ -997,6 +998,9 @@ class stack_answertest_test_data {
         ['EqualComAss', '', 'lowesttermsp((x^2-1)/(x-1))', 'true', 0, 'ATEqualComAss (AlgEquiv-false).', ''],
         ['EqualComAss', '', 'lowesttermsp((x^2-1)/(x+2))', 'true', 1, '', ''],
 
+        ['EqualComAss', '', 'scientific_notationp(1/3)', 'true', 0, 'ATEqualComAss (AlgEquiv-false).', ''],
+        ['EqualComAss', '', 'scientific_notationp(4.1561*10^16)', 'true', 1, '', ''],
+
         // We can't use ATAlgEquiv with rationalized as Maxima simplified sqrt(3)/3 to 1/sqrt(3).
         ['EqualComAss', '', 'rationalized(1+sqrt(3)/3)', 'true', 1, '', 'Bad things in denominators'],
         ['EqualComAss', '', 'rationalized(1+1/sqrt(3))', '[sqrt(3)]', 1, '', ''],
-- 
GitLab