Merge branch 'dev' of https://github.com/maths/moodle-qtype_stack into catform-namespace

Author: EJMFarrow

.github/workflows/moodle-ci.yml

@@ -36,12 +36,12 @@ jobs:
             moodle-branch: 'main'
             database: 'pgsql'
             maxima: 'GCL'
-            moodle-app: true
+            moodle-app: false
           - php: '8.4'
             moodle-branch: 'MOODLE_502_STABLE'
             database: 'pgsql'
             maxima: 'SBCL'
-            moodle-app: true
+            moodle-app: false
           - php: '8.2'
             moodle-branch: 'MOODLE_500_STABLE'
             database: 'pgsql'

api/controller/TestController.php

@@ -188,15 +188,13 @@ public function qtype_stack_test_question($question, $testcases, $seed = null) {
                 // We could just check if score === 1 at this point but by creating
                 // a test and running it we get the full outcomes in the same
                 // format as above.
-                $answernotes = $result->get_answernotes();
-                $answernote = [end($answernotes)];
                 $qtest->add_expected_result($prtname, new \stack_potentialresponse_tree_state(
                     1,
                     true,
                     1,
                     0,
                     '',
-                    $answernote
+                    $result->get_answernotes_testcase()
                 ));
             }
             $results = $qtest->process_results($question, $response);

db/install.xml

@@ -175,7 +175,7 @@
         <FIELD NAME="prtname" TYPE="char" LENGTH="32" NOTNULL="true" SEQUENCE="false" COMMENT="The name of the PRT for which these are the expected outcomes."/>
         <FIELD NAME="expectedscore" TYPE="number" LENGTH="12" NOTNULL="false" SEQUENCE="false" DECIMALS="7" COMMENT="The expected score."/>
         <FIELD NAME="expectedpenalty" TYPE="number" LENGTH="12" NOTNULL="false" SEQUENCE="false" DECIMALS="7" COMMENT="The expected penalty."/>
-        <FIELD NAME="expectedanswernote" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" COMMENT="The expected answer note."/>
+        <FIELD NAME="expectedanswernote" TYPE="char" LENGTH="1023" NOTNULL="true" SEQUENCE="false" COMMENT="The expected answer note."/>
       </FIELDS>
       <KEYS>
         <KEY NAME="primary" TYPE="primary" FIELDS="id"/>

db/upgrade.php

@@ -1035,6 +1035,16 @@ function xmldb_qtype_stack_upgrade($oldversion) {
         // STACK savepoint reached.
         upgrade_plugin_savepoint(true, 2025042500, 'qtype', 'stack');
     }
+
+    if ($oldversion < 2026042402) {
+        $table = new xmldb_table('qtype_stack_qtest_expected');
+        $field = new xmldb_field('expectedanswernote', XMLDB_TYPE_CHAR, '1023', null, XMLDB_NOTNULL, null, null, 'expectedpenalty');
+
+        $dbman->change_field_type($table, $field);
+
+        // STACK savepoint reached.
+        upgrade_plugin_savepoint(true, 2026042402, 'qtype', 'stack');
+    }
     // Add new upgrade blocks just above here.
 
     // Check the version of the Maxima library code that comes with this version

doc/en/AbInitio/Authoring_quick_start_1.md

@@ -22,7 +22,7 @@ There are lots of fields, but only a few are compulsory:
 
 1. The "question name",
 2. The "question text", which is shown to the student,
-3. The teacher's "model answer" `ta` using a variable in the "question variables",
+3. The teacher's "model answer" `ta1` using a variable in the "question variables",
 4. A test of "correctness" (defaults to Algebraic equivalence).
 
 By default a new question automatically has one [input](../Authoring/Inputs/index.md), and one algorithm to test correctness of the answer.
@@ -39,10 +39,10 @@ You must give the question a name, for example `question1`.
 
 There should be text in question variables by default.
 
-    ta:?;
+    ta1:?;
 We should replace `?` with the model answer to the question. In this case, this wil be the derivative of \((x-1)^3\), which is \(3(x-1)^2\). So we should replace `?` with `3*(x-1)^2`.
 
-    ta:3*(x-1)^2;
+    ta1:3*(x-1)^2;
 
 
 ### Question text ###
@@ -110,7 +110,7 @@ Each branch can then
 We can leave the default settings for a minimal question, which is the following:
 
 1. Specify the variable `ans1` in the `SAns` setting.
-2. Specify the correct answer in the `TAns` setting: `ta`.
+2. Specify the correct answer in the `TAns` setting: `ta1`.
 3. `AlgEquiv` in the _Answer test_ drop-down menu.
 
 ## Saving the question
@@ -123,7 +123,7 @@ To recap, we have
 
 1. The "question name",
 2. The "question text",
-3. The teacher's "model answer", (`ta` in the question variables).
+3. The teacher's "model answer", (`ta1` in the question variables).
 4. A test of "correctness" (set to Algebraic equivalence).
 
 Next we should try out our question by pressing the `Preview` link at the bottom of the page.

doc/en/AbInitio/Authoring_quick_start_2.md

@@ -25,8 +25,8 @@ We make more use of the question text field. For instance, we can start to use t
 Add the following to the question variables
 
 ```
-exp: 3*(x-1)^(-4);
-ta: int(exp,x)+c;
+ex1: 3*(x-1)^(-4);
+ta1: int(ex1,x)+c;
 ```
 
 The coding in question variables is based on Maxima, which has an unusual syntax for assignment.  In particular, the colon `:` is used to assign a value to a variable.  So to assign the value of `5` to `a1`, we use the syntax `a1:5`. In general, it is good practice to give variables multi-character names, as single-character names are meant for student input. This is because multi-character variables the author defined cannot by default be input by students. Additionally, adding semicolons to the end of each line is optional, but good practice.
@@ -35,21 +35,21 @@ Notice we are using the CAS to determine the model answer by calling the `int()`
 
 Now it will be a lot faster to fill out the rest of the question. Add the following to the question text:
 
-	<p>Find \(\int{@exp@} \mathrm{d}x\)</p>
+	<p>Find \(\int{@ex1@} \mathrm{d}x\)</p>
 	<p>[[input:ans1]] [[validation:ans1]]</p>
 
-Notice that we have defined a local variable `exp`, and used the value of this in the Question text. There is a difference between mathematics enclosed between `\(..\)` symbols and `{@..@}` symbols. All the text-based fields in the question, including feedback, are [CAS text](../Authoring/CASText.md).  This is HTML into which mathematics can be inserted.  LaTeX is placed between `\(..\)`s, and CAS expressions (including your variables) between matching `{@..@}` symbols.  The CAS expressions are evaluated in the context of the question variables and displayed as LaTeX.
+Notice that we have defined a local variable `ex1`, and used the value of this in the Question text. There is a difference between mathematics enclosed between `\(..\)` symbols and `{@..@}` symbols. All the text-based fields in the question, including feedback, are [CAS text](../Authoring/CASText.md).  This is HTML into which mathematics can be inserted.  LaTeX is placed between `\(..\)`s, and CAS expressions (including your variables) between matching `{@..@}` symbols.  The CAS expressions are evaluated in the context of the question variables and displayed as LaTeX.
 
-Since we have used `{@exp@}` here, the user will not see a \(exp\) on the screen when the question is instantiated, but the _displayed value_ of `exp`: \(\frac{3}{(x-1)^{-4}}\)
+Since we have used `{@ex1@}` here, the user will not see a \(ex1\) on the screen when the question is instantiated, but the _displayed value_ of `ex1`: \(\frac{3}{(x-1)^{-4}}\)
 
-In the input `ans1`, confirm the default `model answer` is the variable `ta`.
+In the input `ans1`, confirm the default `model answer` is the variable `ta1`.
 
-In the potential response tree, confirm the default `Answer test` is  `AlgEquiv`, `SAns` is `ans1` and `TAns` is `ta`.
+In the potential response tree, confirm the default `Answer test` is  `AlgEquiv`, `SAns` is `ans1` and `TAns` is `ta1`.
 
 It is good practice to use question variables often, as they save time and let you change properties of the question easily in the future.
 
 # Next step #
 
 You should now be able to use question variables in STACK.
 
-##### The next part of the authoring quick start guide looks at [improving feedback](Authoring_quick_start_3.md).
+##### The next part of the authoring quick start guide looks at [improving feedback](Authoring_quick_start_3.md).

doc/en/AbInitio/Authoring_quick_start_3.md

@@ -9,7 +9,7 @@ This part of the Authoring Quick Start Guide deals with improving feedback. The
 <iframe width="560" height="315" src="https://www.youtube.com/embed/l6QAMmUA5Pk" frameborder="0" allowfullscreen></iframe>
 ## Introduction
 
-In the last part we started working with question variables. Specifically, we defined the variable  `exp` for the expression to be integrated, and `ta` for the teacher's answer. Then we asked the student to find \(\int 3(x-1)^{-4}dx\).
+In the last part we started working with question variables. Specifically, we defined the variable  `ex1` for the expression to be integrated, and `ta1` for the teacher's answer. Then we asked the student to find \(\int 3(x-1)^{-4}dx\).
 
 Try previewing this question and typing in  `-1*(x-1)^(-3)+c`. The system should accept this as correct.  Next type in `-1*(x-1)^(-3)+C`.  This will be compared to the teacher's answer `-1*(x-1)^(-3)+c` by algebraic equivalence (recall we specified `AlgEquiv` in the potential response tree), and will not be accepted as equivalent.  The reason is that `c` and `C` are different.  A reasonable teacher will probably not care which letter is used for the constant of integration. Let us fix this problem.
 

doc/en/AbInitio/Authoring_quick_start_4.md

@@ -14,23 +14,23 @@ In the last part, we worked with a problem about integrating \(3(x-1)^{-4}\) wit
 Let's take a look again at the question variables we declared:
 
 ```
-exp: 3*(x-1)^(-4);
-ta: int(exp,x)+c;
+ex1: 3*(x-1)^(-4);
+ta1: int(ex1,x)+c;
 ```
 
-We defined two local variables `exp` and `ta`, and used these values in other places such as the question text, input and potential response tree. 
+We defined two local variables `ex1` and `ta1`, and used these values in other places such as the question text, input and potential response tree. 
 
 We are now in a position to generate a random question. To do this, modify the [question variables](../Authoring/Variables.md#Question_variables) to be
 
 ```
 a1 : 1+rand(6);
 a2 : 1+rand(6);
 nn : 1+rand(4);
-exp : a1*(x-a2)^(-nn);
-ta: int(exp, x)+c;
+ex1 : a1*(x-a2)^(-nn);
+ta1: int(ex1, x)+c;
 ```
 
-In this new question we are asking the student to find the anti-derivative of a question with a definite form \( a_1(x-a_2)^{-nn} \). `a1`, `a2` and `nn` are all variables which are assigned random positive integers.  These are then used to define the variable `exp`, used in the question itself. We also have the CAS integrate the expression `exp` and store the result in the variable `ta`. It is good practice to use variables names with more than one character as single-character variables, like `x`, are meant for student input.
+In this new question we are asking the student to find the anti-derivative of a question with a definite form \( a_1(x-a_2)^{-nn} \). `a1`, `a2` and `nn` are all variables which are assigned random positive integers.  These are then used to define the variable `ex1`, used in the question itself. We also have the CAS integrate the expression `ex1` and store the result in the variable `ta1`. It is good practice to use variables names with more than one character as single-character variables, like `x`, are meant for student input.
 
 Remember that when generating random questions in STACK we talk about _random numbers_ when we really mean _pseudo-random numbers_. To keep track of which random numbers are generated for each user, there is a special `rand` command in STACK, which you should use instead of [Maxima](../CAS/Maxima_background.md)'s random command. The `rand` command is a general "random thing" generator, see the page on [random generation](../CAS/Random.md) for full details. `rand` can be used to generate random numbers and also to make selections from a list. `rand(n)` will select a random integer from 0 up to, **and not including**, `n`. So  `rand(3)` will select a random number from the list  `[0,1,2]` .
 
@@ -40,7 +40,7 @@ Now that as our question contains random numbers, we need to record the actual q
 Fill the question note in as
 
 ```
-\[ \int {@exp@} \mathrm{d}x = {@ta@}.\]
+\[ \int {@ex1@} \mathrm{d}x = {@ta1@}.\]
 ```
 
 Two question variants are considered to be the same if and only if the question note is the same. It is the teacher's responsibility to create sensible notes.

doc/en/AbInitio/Authoring_quick_start_5.md

@@ -13,8 +13,8 @@ In the last couple of parts, we have been working with a simple integration ques
 a1 : 1+rand(6);
 a2 : 1+rand(6);
 nn : 2+rand(4);
-exp : a1*(x-a2)^(-nn);
-ta: int(exp, x)+c;
+ex1 : a1*(x-a2)^(-nn);
+ta1: int(ex1, x)+c;
 ```
 
 Testing questions is time consuming and tedious, but important to ensure questions work.  To help with this process, STACK enables teachers to define "question tests".  The principle is the same as "unit testing" in software engineering.
@@ -30,22 +30,22 @@ The penalty is a number deducted from the total mark for each incorrect attempt
 Fill in the following information for your first test case:
 
 ```
-ans1 = ta
+ans1 = ta1
 score = 1
 penalty = 0
 answernote = prt1-2-T
 ```
 
 I.e., if the student puts in the model answer they should pass the first node (checks if they have integrated correctly) and pass the second node (tests that their answer is factored) and end up with a score of 1 and no penalty. 
 
-Note that the input is evaluated before the test is conducted. Students are not allowed to enter the variable  `ta` because it is a teacher-defined variable, however the evaluated form, fx.  `-1*(x-1)^(-3)+c`, is an allowed input. For each test case, you can see the un-evaluated input under `Test input`, and the actual input tested under `Value entered`. 
+Note that the input is evaluated before the test is conducted. Students are not allowed to enter the variable  `ta1` because it is a teacher-defined variable, however the evaluated form, fx.  `-1*(x-1)^(-3)+c`, is an allowed input. For each test case, you can see the un-evaluated input under `Test input`, and the actual input tested under `Value entered`. 
 
 You can run the test on all deployed versions by clicking on  `Run all tests on all deployed variants` .
 
 You can add as many tests as you think is needed, and it is usually a sensible idea to add one for each case you anticipate.  Add in another test case for
 
 ```
-ans1 = int(exp,x)
+ans1 = int(ex1,x)
 score = 0
 penalty = 0.1
 answernote = prt1-1-F

doc/en/Authoring/Answer_Tests/Equivalence.md

@@ -20,7 +20,7 @@ This list is in approximate order of the size of the equivalence classes from mo
 
 ### AlgEquiv {#AlgEquiv}
 
-This is the most commonly used test.  The pseudo code
+This is the most commonly used test.  The pseudo code (for mathematical _expressions_ at least) is
 
     If
       simplify(ex1-ex2) = 0
@@ -38,7 +38,24 @@ Note: exactly what this answer test does depends on what objects are given to it
 
 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.
 
-Currently we do check multiplicity of roots, so that \( (x-2)^2=0\) and \( x=2\) are not considered to be equivalent.  Similarly \(a^3b^3=0\) is not \(a=0 \text{ or } b=0\).  This is a long-standing issue and we would need a separate test to ignore multiplicity of roots.
+Equations and expressions are very different.  Two equations are equivalent if they have the same roots with the same multiplicity of roots.  For example, \((x-2)^2=0\) and \(x=2\) are not considered to be equivalent.  Similarly \(a^3b^3=0\) is not \(a=0 \text{ or } b=0\).  To establish equivalence of equations we use the pseudo code
+
+    If
+      numberp( (lhs(ex1)-rhs(ex1))/(lhs(ex2)-rhs(ex2)) )
+    then
+      true
+    else
+      false.
+
+That is to say, we turn the equation `ex1` into an expression `x1:simplify(lhs(ex1)-rhs(ex1))` and the equation `ex2` into an expression `x2:simplify(lhs(ex2)-rhs(ex2))`, and then simplify the ratio of the two numerators of `x1` and `x2`:, i.e. `num(x1)/num(x2)` (with some edge case detection of course).  If this is a number then we have cancelled algebraic factors precicely, and roots match (with multiplicity).  Notice we do not actually "solve" the equations during this process, thereby side-stepping the decidability question.  (We would need a separate test to ignore multiplicity of roots.)
+
+In calculating the ratio `x1/x2` we use Maxima's simplifer, which may be modified by commands like `assume`.  However, since we do not actually solve the equations we do not use `assume` to reject solutions themselves.  For example, in the following situation
+
+    assume(x>0);
+    eq1: a = (c*x^3)/x;
+    eq2: a*x = c*x^3;
+
+`eq1` does not have \(0\) as a solution, whereas `eq2` does have \(0\) as a solution, the ratio simplifes to `1/x` indicating that `eq2` has a zero solution which is not balanced by a corresponding solution in `eq`.   Since the equations are never solved, the `assume(x>0)` never comes into play here.  (We would need a separate test to use `assume` statements and reject roots.)
 
 Inequalities are turned into sets of real numbers they represent.  When this is done it is indicated by the answer note `ATInequality_solver.`  If you want `a>1` to be _not_ the same as `x>1` then you need to test in a more syntactic way, not using algebraic equivalence.