Merge pull request #1416 from maths/iss1403

Documentation, updated files, and example questions for the linear algebra libraries

Author: sangwinc

doc/en/Authoring/Inclusions.md

@@ -1,25 +1,25 @@
 # Inclusions
 
-This is an expert level topic, please avoid this feature unless you feel that you understand the implications and consequences of it. Note that using this feature goes against the self-contained material principle present in [the future proof guidelines](../STACK_question_admin/Future_proof.md).
+STACK provides a mechanism for sharing code between questions.  For example, you can include small libraries of Maxima functions, dedicated to specific topics, in the question variables.
 
-That being said, a common request on the wish-list has been to provide some means of sharing code between questions. The inclusion-feature is the first step towards such a feature, however, it is not perfect nor do we expect it to be the solution that will finally be selected. But we provide it now that the back-end has the tools to provide it, for those adventurous enough.
+There is a tension between (i) reusing libraries of functions between questions and (ii) the self-contained material principle present in [the future proof guidelines](../STACK_question_admin/Future_proof.md).
+
+This is an expert level topic, please avoid this feature unless you feel that you understand the implications and consequences of it. 
 
 Technical note: Currently, inclusions within inclusions are not supported, due to loop detection and security validation reasons.
 
 ## Inclusions life-cycle
 
-For all current types of inclusions the inclusion happens at the time of compilation,
-which means that the source will be fetched when the question gets compiled and will
-stay in the cached compilation product. Compilation happens during the first use of
-the question after it has been saved or the cache has been purged.
+For all current types of inclusions the inclusion happens at the time of question compilation,
+which means that the source will be fetched when the question gets compiled and will stay in the cached compilation product. 
+Compilation happens during _the first use_ of the question after it has been saved or the cache has been purged.
 
-The logic will not track changes to the source material, if one wants to fetch it
-again one must re-compile the question, either by purging the caches or by editing
+The inclusion logic will not track changes to the source material. 
+If one wants to fetch it again one must re-compile the question, either by purging the caches or by editing
 the question.
 
-Note that in the current solution during export we export only the source address
-and the exported material will only work if the address is accessible at the end
-that imports it.
+Note that in the current solution during export we export only the _source address_
+and the exported material will only work if the address is accessible at the end that imports it.
 
 
 ## Inclusions within text
@@ -58,7 +58,8 @@ math-mode is not quite ready to understand all of these context switches.
 ## Inclusions within CAS-logic
 
 You can also include code into keyvals, i.e. question-variables or into feedback-variables.
-This type of an inclusion will again act just as if written directly by the question author at that place in the code. If one writes this type of an inclusion within an if-statement it will simply get written open within
+This type of an inclusion will act just as if written directly by the question author at that place in the code.
+If one writes this type of an inclusion within an if-statement it will simply get written open within
 an if-statement, the `if` will only decide if it executes, but it will still take that space and bandwidth.
 
 The included material must follow all the rules of normal STACK keyvals.
@@ -70,7 +71,7 @@ The included material must follow all the rules of normal STACK keyvals.
 
 Note that we do not do "tree-shaking" at this point to remove unnecessary code.  If you include a massive library of functions that you do not use the question will still have to load those functions into the CAS and that may take some time.  If you have libraries, used in many questions, please consider contributing these to the core of STACK.
 
-To include external CAS code call the `stack_include()`-function with a string  argument.  The argument must be a raw string, containing the URL of the code.  You cannot reference a variable containing such a string. For example,
+To include external CAS code call the `stack_include()` - function with a string argument.  The argument must be a raw string, containing the URL of the code.  You cannot reference a variable containing such a string. For example,
 
 ```
 a: rand(3)+2;
@@ -99,6 +100,7 @@ Notes.
 1. We will try to keep files in the contrib folder small, and stable.
 2. We intend to move commonly used contributed code into the core in due course.  At that point we will localise language strings for automatic translation.
 3. Please contact the developers about naming conventions.  For example, external validators should start the function name with `validator_`.
+4. If you wish to use the libraries locally, on your server, prepend the file name with `contribl://`, e.g. `stack_include_contrib("matchlib.mac");` will load the local file, not the file on github.  This is mostly for local development, before code is pushed to the master branch.  We advise against this for live questions.
 
 ### Sandbox testing
 

doc/en/CAS/Matrix.md

@@ -1,13 +1,14 @@
 # Matrices and vectors in STACK
 
-This page documents the use of matrices in STACK.  There is a topics page for setting [linear algebra](../Topics/Linear_algebra.md) STACK questions.
+This page documents the use of matrices in STACK.  There is a topics page for setting [linear algebra](../Topics/Linear_algebra/index.md) STACK questions.
 
 ## Matrices ##
 
-Note that in Maxima, the operator `.` represents noncommutative multiplication and scalar product. The star `A*B` gives element-wise multiplication.
+The operator `.` represents noncommutative multiplication and scalar product. The star `A*B` gives element-wise multiplication.
 
+Maxima functions `addrow` and `addcol` appends rows/columns onto the matrix.
 
-The following functions are part of Maxima, but are very useful for us.
+Maxima functions perform row operations
 
     rowswap(m,i,j)
     rowadd(m,i,j,k)
@@ -17,13 +18,10 @@ Where ` m[i]: m[i] + k * m[j]`.
     rowmul(m,i,k)
 
 Where `m[i]: k * m[i]`.
-And a function to compute reduced row echelon form
 
-    rref(m)
-
-(Note the Maxima functions `addrow` and `addcol` appends rows/columns onto the matrix.)
+STACK provides a function to compute reduced row echelon form
 
-STACK has a library for creating [structured random matrices](Random.md).
+    rref(m)
 
 ## Assigning individual elements ##
 
@@ -82,41 +80,6 @@ Now it makes no sense to include the point wise multiplication of elements as a
 
 There must be a more elegant way to do this!
 
-## Matrices and answer tests
-
-Some answer tests accept matrices as arguments. E.g. algebraic equivalence (`ATAlgEquiv`) will accept matrices, even of different sizes, and return feedback underlining which elements are different.  This is a rather blunt tool, since it is all or nothing.  And, it's often necessary to apply other answer tests to corresponding elements of matrices.
-
-1. Every answer test in STACK has a corresponding function in Maxima.  The Maxima function name of AlgEquiv is `ATAlgEquiv`, et.
-2. The Maxima code for every answer in STACK returns a list of four elements.  The _second_ element is the result of the test.  See the [documentation](../Authoring/Answer_Tests/index.md) for details of the other elements.  For example `second(ATComAss(x+y,y+x))` is `true` because \(x+y=y+x\) up to commutativity etc (using `ATComAss`).
-3. Some answer tests take an optional agument, e.g. numerical accuracy.  to use `zip_with_matrix` we need to create an un-named (lambda) function of two arguments.  E.g. `lambda([ex1,ex2], ATNumAbsolute(ex1,ex2,0.01)` can be used to test corresponding matrix elements are within \(0.01\) of each other.
-
-Once you have a matrix `M` of boolean values, you could count the number which are false.
-
-    n:length(sublist(flatten(args(M)),lambda([ex],not(ex))));
-
-Or you could locate the false elements and give specific feedback.
-
-#### Example 1. ####
-
-Here we test two matrices with elements with `ATEqualComAss`.  This returns a matrix `M` of boolean values.
-
-````
-M1:matrix([x*(x+1),sqrt(x^2)],[2/3,1/2]);
-M2:matrix([x^2+x,abs(x)],[0.666,0.5]);
-M:matrixmap(second,zip_with_matrix(ATEqualComAss, M1, M2));
-````
-
-#### Example 2. ####
-
-Here we test two matrices with elements with `ATNumAbsolute`, and argument \(0.01\).  This returns a matrix `M` of boolean values.
-
-````
-M1:matrix([3.1415,10.0]);
-M2:matrix([%pi,%pi^2]);
-M:matrixmap(second,zip_with_matrix(lambda([ex1,ex2], ATNumAbsolute(ex1,ex2,0.01)), M1, M2));
-````
-
-
 ## Display of matrices ## {#matrixparens}
 
 You can set the type of parentheses used to surround matrices in a number of ways.  Firstly, the admin user should set the site default in the qtype_stack options page.
@@ -151,74 +114,3 @@ To change to right aligned columns, switch `"c"` to `"r"`.  This function takes
 
 For this function to take effect in the whole question, including validation of students' input, place the redefinition before `%_stack_preamble_end;` in the question variables.
 
-## Vectors ## {#vectors}
-
-If you are trying to use the vector notation such as \(3i+4j\) you will probably want to redefine \(i\) to be an abstract symbol, not a complex number.
-More information on this is given under [Numbers](Numbers.md).  In particular, use the question level option "Meaning and display of sqrt(-1)" value `symi` to stop interpreting `i` with `i^2=-1` and return it to being an abstract symbol.
-
-Another way to do this is to create matrices as follows:
-
-    ordergreat(i,j,k);
-    %_stack_preamble_end;
-    p:matrix([-7],[2],[-3]);
-    q:matrix([i],[j],[k]);
-
-Now we can use the dot product to create the vector.  The STACK function `texboldatoms` wraps all atomic variable names in the ephemeral function `stackvector`, which is typeset in bold.
-
-    v:texboldatoms(dotproduct(p,q));
-
-If you turn the option "Multiplication sign" to none, this should display as
-\[-7\,{\bf{i}}+2\,{\bf{j}}-3\,{\bf{k}}\]
-Notice the use of the function `ordergreat`.  `ordergreat` can only be used once at the beginning of the question.
-
-If you use the special constant `%_stack_preamble_end;` then anything before this constant will be available everywhere in the question, including the inputs.
-
-The vector `stackvector(a)` and the atom `a` are different, and are not considered algebraically equivalent.  While students may type in `stackvector(a)` as an answer, they are likely to type in `a`.  The teacher can either (1) add in `stackvector` ephemeral forms to the student's answer in the feedback variables using `texboldatoms` or (2) remove all `stackvector` forms from the teacher's answer by using the `destackvector(ex)` function on their answer.  In the future we may have an option in the input to apply texboldatoms to student's expressions.
-
-The display of the ephemeral form of `stackvector` is controlled by the function `stackvectortex`, e.g. you can display vectors differently using the following examples.
-
-    stackvectortex(ex):= block(sconcat("{\\bf \\vec{", tex1(first(args(ex))), "}}"));
-    stackvectortex(ex):= block(sconcat("{\\bf \\underline{", tex1(first(args(ex))), "}}"));
-
-which should go in the question variables.
-
-Any `texput` commands in the question variables now become "context variables" and will be available to the inputs. So, if in the context of your question you would like a variable such as `x` to be considered as a vector and displayed as a vector you can add one of the following to the question variables.
-
-    texput(x, "\\mathbf{\\vec{x}}");
-    texput(x, "\\mathbf{\\underline{x}}");
-
-Whenever `x` is then displayed in any part of the question, including the student's input validation or feedback generated by the answer tests, we will have the updated tex for this atom.  E.g.
-
-    texput(x, "\\mathbf{\\vec{x}}");
-    texput(y, "\\mathbf{\\vec{y}}");
-
-and a student types in `a*x+b*y` then the tex output will be \(a\cdot \mathbf{\vec{x}}+b\cdot \mathbf{\vec{y}}\).
-
-### Vector cross product ###
-
-The wedge product operator is denoted by the tilde `~`.  This is the `itensor` package.  This package is not normally loaded by STACK, and in any case the package takes lists and not matrices.  For convenience, the following function has been added which requires `3*1` matrices.
-
-    crossproduct(a,b);
-
-Another advantage of this function is the ability to return an un-simplified version with `simp:false`.
-
-## Student input ##
-
-Students do find typing in matrices very tedious.  Some teachers have asked for a convenient notation such as
-
-    c(1,2,3)
-
-for column vectors and
-
-    v(1,2,3,4)
-
-For row vectors.  This is not a core part of STACK currently, but in individual questions you can convert such notation easily into mainstream Maxima using code such as the following.
-
-    ta1:c(1,2,3);
-    ta2:v(1,2,3);
-    vec_convert(sa) := if op(sa)=c then transpose(matrix(args(sa))) elseif op(sa)=v then matrix(args(sa));
-    vec_convert(ta1);
-    vec_convert(ta2);
-
-Once converted into Matrices, the student's answer will be evaluated by PRTs as matrices.   Of course, this will not be reflected in the valuation.  If there is sufficient demand for this contact the developers.
-

doc/en/CAS/Maxima_background.md

@@ -92,7 +92,6 @@ By default, the list does not contain multiplicities. If the list should contain
 | `comp_square(ex,v)`             | Returns a quadratic `ex` in the variable `v` in completed square form.
 | `degree(ex,v)`                  | Returns the degree of the expanded form of `ex` in the variable `v`. See also Maxima's `hipow` command.
 | `unary_minus_sort(ex)`          | Tidies up the way unary minus is represented within expressions when `simp:false`.  See also [simplification](Simplification.md).
-| `texboldatoms(ex)`              | Displays all non-numeric atoms in bold.  Useful for vector questions.
 
 ## Assignment ## {#assignment}
 

doc/en/Developer/Development_track.md

@@ -7,13 +7,13 @@ We use the [github issue tracker](https://github.com/maths/moodle-qtype_stack/is
 
 ## Version 4.9.0
 
-Done.
 1. Introduce `ta` as the default teacher's answer in the question variables, and use this in the input and default prt.  Allow addition of multiple nodes in a PRT with one click.
-2. Support `allowrmpty` for dropdown, radio and checkbox inputs.
-3. Include the `rand_matrix.mac` contributed library, a collection of matrix randomisation functions for use in linear algebra, with the local STACK source code.  See the [random](../CAS/Random.md) documentation for details.
+2. Support `allowempty` for dropdown, radio and checkbox inputs.
+3. Add in the `space` option, i.e. `make_multsgn("space")` in the [options](../Authoring/Question_options.md).
 4. Convert input "syntax hint" to castext.
-5. Add in the `space` option, i.e. `make_multsgn("space")` in the [options](../Authoring/Question_options.md).
-
+5. Include the `rand_matrix.mac` contributed library, a collection of matrix randomisation functions for use in linear algebra, with the local STACK source code.  See the [random](../Topics/Linear_algebra/Random_Matrices.md) documentation for details.
+6. Add in a substantial library for dealing with [linear algebra problems](../Topics/Linear_algebra/index.md).
+7. Load Maxima's `eigen` library.
 
 Issues with [github milestone 4.9.0](https://github.com/maths/moodle-qtype_stack/issues?q=is%3Aissue+milestone%3A4.9.0) include
 

doc/en/Developer/Releasing.md

@@ -30,8 +30,10 @@ Unless you want to discuss something confidential with the developers, please do
 * Run `php cli/ast_test_generator.php` to confirm if auto-generated tests have not changed.
 * Run Maxima unit tests of contributed packages by re-defining `stacklocation` and running `s_test_case.mac` in the sandbox.  E.g.
 
+````
     stacklocation:"/var/www/html/m40/question/type/stack"$
     load("s_test_case.mac");
+````
 
 * Run PHP [unit tests](Unit_tests.md).
 * Run code checker.

doc/en/Specialist_tools/Drag_and_drop/Grid.md

@@ -36,7 +36,7 @@ You will use the `"<ID>"` string to write solutions and assess student inputs; t
 For our example, the _Question variables_ field looks as follows.
 
 ```
-stack_include("contribl://matchlib.mac");
+stack_include_contrib("matchlib.mac");
 
 steps : [
   ["f", "\\(y = x^2\\)"],
@@ -128,8 +128,9 @@ This item should appear in the index and not in the header.
 ### Question variables 
 
 The question variables with an index is as follows.
+
 ```
-stack_include("contribl://matchlib.mac");
+stack_include_contrib("matchlib.mac");
 
 steps : [
   ["dfdx", "\\(y' = 2x\\)"],

doc/en/Specialist_tools/Drag_and_drop/Grouping.md

@@ -105,8 +105,9 @@ You will use the `"<ID>"` string to write solutions and assess student inputs; t
 This should be column grouped.
 
 For our example, the _Question variables_ field looks as follows.
+
 ```
-stack_include("contribl://matchlib.mac");
+stack_include_contrib("matchlib.mac");
 
 steps : [
     ["sq", "\\(f(x) = x^2\\)"],

doc/en/Specialist_tools/Drag_and_drop/Parsons.md

@@ -54,7 +54,7 @@ It shows the proof that _\(\log_2(3)\) is irrational_.
 Define the following question variables:
 
 ````
-stack_include("contribl://prooflib.mac");
+stack_include_contrib("prooflib.mac");
 
 proof_steps: [
     ["assume", "Assume, for a contradiction, that \\(\\log_2(3)\\) is rational."],
@@ -143,7 +143,7 @@ The following Parson's question is an _if and only if_ proof, containing two blo
 ### Question variables
 
 ````
-stack_include("contribl://prooflib.mac");
+stack_include_contrib("prooflib.mac");
 
 ta: proof_iff(proof("assodd","defn_odd","alg_odd","def_M_odd","conc_odd"), proof("contrapos","assnotodd","even","alg_even","def_M_even","conc_even"));
 

doc/en/Specialist_tools/Drag_and_drop/Question_block.md

@@ -19,7 +19,7 @@ The question author should write all steps to be shown to the student as a list
 the steps. Note the `\` character needs to be protected within strings, so for example we have to type `\\(n=2m+1\\)` rather than just `\(n=2m+1\)`.
 
 ```
-stack_include("contribl://prooflib.mac");
+stack_include_contrib("prooflib.mac");
 
 proof_steps: [
     ["assume", "Assume that \\(n\\) is odd."],