Merge pull request #106 from ChristopherChudzicki/matrix-docs

Version 1.2 documentation
mitodl · Aug 12, 2018 · d86f826 · d86f826
2 parents 85040df + 4d2eeae
commit d86f826
Show file tree

Hide file tree

Showing 36 changed files with 1,731 additions and 348 deletions.
diff --git a/course/course/course.xml b/course/course/course.xml
@@ -24,6 +24,18 @@
         <problem url_name="formula7"/>
         <problem url_name="formula8"/>
         <problem url_name="formula9"/>
+        <problem url_name="formula10"/>
+      </vertical>
+    </sequential>
+    <sequential url_name="matrixgrader" display_name="MatrixGrader">
+      <vertical url_name="v-matrixgrader" display_name="MatrixGrader">
+        <html url_name="matrixinfo"/>
+        <problem url_name="matrix1"/>
+        <problem url_name="matrix2"/>
+        <problem url_name="matrix3"/>
+        <problem url_name="matrix4"/>
+        <problem url_name="matrix5"/>
+        <problem url_name="matrix6"/>
       </vertical>
     </sequential>
     <sequential url_name="singlelistgrader" display_name="SingleListGrader">

diff --git a/course/html/matrixinfo.xml b/course/html/matrixinfo.xml
@@ -0,0 +1,9 @@
+<html display_name="MatrixGrader">
+
+<p>
+  <code>MatrixGrader</code> is an extended version of FormulaGrader used to grade mathematical expressions containing scalars, vectors, and matrices. Authors and students may enter matrix (or vector) expressions by using variables sampled from matrices, or by entering a matrix entry-by-entry.
+</p>
+
+<p>Examples below. See also the <a href="https://mitodl.github.io/mitx-grading-library/matrix_grader">full documetnation</a>.</p>
+
+</html>
diff --git a/course/problem/formula10.xml b/course/problem/formula10.xml
@@ -0,0 +1,78 @@
+<problem display_name="Sibling Variables" showanswer="always" weight="10" attempts="">
+
+<script type="loncapa/python">
+from mitxgraders import ListGrader, NumericalGrader
+
+initial_subgrader = NumericalGrader(tolerance=2)
+iteration_subgrader = NumericalGrader(
+    tolerance=1e-6,
+    user_functions={
+        # these are just for convenience when specifying answer above.
+        # Students could use them, but we will not announce their existence
+        'f' : lambda x: x**2 - 9,           # root is x = sqrt(9)
+        'df': lambda x: 2*x                 # derivative of f
+    }
+)
+
+grader = ListGrader(
+    ordered=True,
+    answers=[
+        '5', # anything between 4 and 6 accepted
+        'sibling_1 - f(sibling_1)/df(sibling_1)',
+        'sibling_2 - f(sibling_2)/df(sibling_2)',
+    ],
+    subgraders=[
+        initial_subgrader,
+        iteration_subgrader,
+        iteration_subgrader
+    ]
+)
+</script>
+
+  <p>
+    When a student submits several mathematical inputs as part of one problem, it is sometimes useful to grade these inputs in comparison to each other. This problem uses sibling variables to score subsequent answers based off of the previous one. Sibling variables are available to <code>FormulaGrader</code>s, <code>NumericalGrader</code>s, and <code>MatrixGrader</code>s when used inside an <strong>ordered</strong> <code>ListGrader</code>.
+  </p>
+
+  <p>
+    Use Newton's Method on \(f(x)=x^2 - 9\) to calculate the square root of 9. Use anything in the interval \( (4, 6) \) as your starting value. Round answers to no fewer than 6 decimal places.
+  </p>
+
+  <p>Suggested inputs:</p>
+  <ul>
+    <li><code>[5, 3.4, 3.0235294]</code> is a correct input</li>
+    <li><code>[4.5, 3.25, 3.0096154]</code> is a correct input</li>
+    <li>Try changing one or two values in the lists above.</li>
+  </ul>
+
+  <customresponse cfn="grader">
+    <table>
+      <tr>
+        <th></th>
+        <th>value</th>
+      </tr>
+      <tr>
+        <td>\(x_0\)</td>
+        <td><textline /></td>
+      </tr>
+      <tr>
+        <td>\(x_1\)</td>
+        <td><textline /></td>
+      </tr>
+      <tr>
+        <td>\(x_2\)</td>
+        <td><textline /></td>
+      </tr>
+    </table>
+  </customresponse>
+
+  <h3>Resources</h3>
+  <ul>
+    <li>
+      <a href="https://github.com/mitodl/mitx-grading-library/tree/master/course/problem/list6.xml" target="_blank">View source</a>
+    </li>
+    <li>
+      <a href="https://mitodl.github.io/mitx-grading-library/grading_math/formula_grader/#sibling-variables" target="_blank">Documentation for sibling variables</a>
+    </li>
+  </ul>
+
+</problem>
diff --git a/course/problem/list5.xml b/course/problem/list5.xml
@@ -1,44 +1,82 @@
 <problem display_name="Eigensystem Example" showanswer="always" weight="10" attempts="">
+<script type="text/python" system_path="python_lib">
+from mitxgraders import MatrixGrader, FormulaGrader, ListGrader
+from mitxgraders.comparers import eigenvector_comparer
 
-  <p>Here is the jewel in the crown of ListGrader: the ability to nest ListGraders.</p>
-
-  <p>Here is a matrix.</p>
-
-  \[M = \left[\begin{array}{cc}1 &amp; 0 \\ 0 &amp; -1\end{array}\right]\]
-
-  <p>Compute the eigenvalues and corresponding eigenvectors of this matrix. You may enter the eigenvalues in any order, but the eigenvectors must be corresponding to the appropriate eigenvalue. The eigenvectors should be normalized; the grader will accept either sign of the eigenvectors though. (Answers: Eigenvalue 1 = 1, Eigenvector 1 = (1, 0). Eigenvector 2 = -1, Eigenvector 2 = (0, 1))</p>
+# A simple answer that will be passed to FormulaGrader
+expect_value_0 = '-sqrt(1+x^2)'
+# A custom comparer that will be passed to MatrixGrader
+expect_vector_0 = {
+    'comparer_params': [
+        '[[1, x], [x, -1]]',
+        expect_value_0
+    ],
+    'comparer': eigenvector_comparer
+}
 
+expect_value_1 = 'sqrt(1+x^2)'
+expect_vector_1 = {
+    'comparer_params': [
+        '[[1, x], [x, -1]]',
+        expect_value_1
+    ],
+    'comparer': eigenvector_comparer
+}
 
-<script type="text/python" system_path="python_lib">
-from mitxgraders import *
 grader = ListGrader(
     answers=[
-        ['1', (['1', '0'], ['-1', '0'])],
-        ['-1', (['0', '1'], ['0', '-1'])],
+        [expect_value_0, expect_vector_0],
+        [expect_value_1, expect_vector_1]
     ],
+    # group the first two inputs together, and the last two inputs together
+    grouping=[1, 1, 2, 2],
+    # Each group wil be passed to the ListGrader below
     subgraders=ListGrader(
-        subgraders=[
-            NumericalGrader(),
-            ListGrader(
-                subgraders=NumericalGrader(),
-                ordered=True
-            )
-        ],
         ordered=True,
-        grouping=[1, 2, 2]
-    ),
-    grouping=[1, 1, 1, 2, 2, 2]
+        subgraders=[
+            FormulaGrader(variables=['x']),
+            MatrixGrader(variables=['x'])
+        ]
+    )
 )
 </script>
 
-<customresponse cfn="grader" inline="1">
-  <p style="display:inline">Eigenvalue 1: </p><textline inline="1" correct_answer="1"/>
-  <br/>
-  <p style="display:inline">Eigenvector 1: </p><textline inline="1" correct_answer="1"/><textline inline="1" correct_answer="0"/>
-  <br/>
-  <p style="display:inline">Eigenvalue 2: </p><textline inline="1" correct_answer="-1"/>
-  <br/>
-  <p style="display:inline">Eigenvector 2: </p><textline inline="1" correct_answer="0"/><textline inline="1" correct_answer="1"/>
+  <p>Here is the jewel in the crown of ListGrader: the ability to nest ListGraders.</p>
+
+  <p>Find the eigenvalues and eigenvectors of the matrix</p>
+
+  \[M =
+    \begin{bmatrix}
+      1 &amp; x \\
+      x &amp; -1
+    \end{bmatrix}
+  \]
+
+  <p>Answer: (pairs may be in any order, but correct vector must go with correct value)</p>
+  <ul>
+    <li>1st pair: <code>+sqrt(1+x^2)</code>, <code>[1+sqrt(1+x^2), x]</code></li>
+    <li>2nd pair: <code>-sqrt(1+x^2)</code>, <code>[1-sqrt(1+x^2), x]</code></li>
+  </ul>
+
+<customresponse cfn="grader">
+
+  <table>
+    <tr>
+      <th></th>
+      <th>Eigenvalue</th>
+      <th>Eigenvector</th>
+    </tr>
+    <tr>
+      <th>1st Eigenpair</th>
+      <td><textline math="true"/></td>
+      <td><textline math="true" size="40"/></td>
+    </tr>
+    <tr>
+      <th>2nd Eigenpair</th>
+      <td><textline math="true"/></td>
+      <td><textline math="true" size="40"/></td>
+    </tr>
+  </table>
 </customresponse>
 
 

diff --git a/course/problem/matrix1.xml b/course/problem/matrix1.xml
@@ -0,0 +1,42 @@
+<problem display_name="MatrixGrader: First Example" showanswer="always" weight="10" attempts="">
+
+<script type="text/python" system_path="python_lib">
+from mitxgraders import MatrixGrader, RealMatrices, RealVectors
+
+grader = MatrixGrader(
+  answers='4*A*B^2*v',
+  variables=['A', 'B', 'v'],
+  sample_from={
+     'A': RealMatrices(), # samples from 2 by 2 matrices by default
+     'B': RealMatrices(),
+     'v': RealVectors(shape=2)
+  },
+  identity_dim=2
+)
+</script>
+
+<p>This is a demo problem with 3 variables: <code>A</code> and <code>B</code> are 2 by 2 matrices, while <code>v</code> is a vector of length 2.</p>
+
+<p>Try inputting different forms of the correct answer, as well as different incorrect answers:</p>
+<ul>
+  <li><code>4*A*B^2*v</code> is correct</li>
+  <li><code>A*(2*B^2 + 2*B*I*B)*v</code> is also correct; here <code>I</code> is the 2 by 2 identity matrix.</li>
+  <li><code>4*B*A*B*v</code> is incorrect (non-commutative)</li>
+  <li>The following answers will raise interesting errors:
+    <ul>
+      <li><code>A + v</code></li>
+      <li><code>v^2</code></li>
+      <li><code>A^2.5</code></li>
+      <li><code>4*A*B^2</code></li>
+    </ul>
+  </li>
+</ul>
+
+<customresponse cfn="grader" expect="4*A*B^2*v">
+    <textline math="true" preprocessorClassName="MJxPrep" preprocessorSrc="/static/MJxPrep.js" />
+</customresponse>
+
+<a href="https://github.com/mitodl/mitx-grading-library/tree/master/course/problem/matrix1.xml" target="_blank">View source</a>
+
+
+</problem>
diff --git a/course/problem/matrix2.xml b/course/problem/matrix2.xml
@@ -0,0 +1,30 @@
+<problem display_name="MatrixGrader: Entry-by-entry input" showanswer="always" weight="10" attempts="">
+
+<script type="text/python" system_path="python_lib">
+from mitxgraders import MatrixGrader, RealMatrices, RealVectors
+
+grader = MatrixGrader(
+  answers='[[-cos(theta), -sin(theta)], [-sin(theta), cos(theta)]]',
+  variables=['theta'],
+  max_array_dim=2
+)
+</script>
+
+<p>A linear transformation \(\mathcal{T}: \mathbb{R}^2 \rightarrow \mathbb{R}^2\) rotates vectors counter-clockwise by angle \(\theta\) then reflects them over the \(y\)-axis. Enter the matrix representation of \(\mathcal{T}\).</p>
+
+<p>This problem requires entry-by-entry input of a matrix. Suggested inputs:</p>
+
+<ul>
+  <li><code>[[-cos(theta), -sin(theta)], [-sin(theta), cos(theta)]]</code>, correct answers</li>
+  <li><code>-[[cos(theta), sin(theta)], [sin(theta), -cos(theta)]]</code>, also correct</li>
+  <li>Try inputting ill-formed matrices such as <code>[[1, 2], [3]]</code></li>
+</ul>
+
+<customresponse cfn="grader" expect="[[-cos(theta), -sin(theta)], [-sin(theta), cos(theta)]]">
+    <textline math="true" preprocessorClassName="MJxPrep" preprocessorSrc="/static/MJxPrep.js" size="100" />
+</customresponse>
+
+<a href="https://github.com/mitodl/mitx-grading-library/tree/master/course/problem/matrix2.xml" target="_blank">View source</a>
+
+
+</problem>
diff --git a/course/problem/matrix3.xml b/course/problem/matrix3.xml
@@ -0,0 +1,45 @@
+<problem display_name="MatrixGrader: Cross Product Demo" showanswer="always" weight="10" attempts="">
+
+<script type="text/python" system_path="python_lib">
+from mitxgraders import MatrixGrader, RealMatrices, RealVectors
+
+grader = MatrixGrader(
+  answers='abs(cross(vecb-veca, vecc-veca))/abs(vecb-veca)',
+  variables=['veca', 'vecb', 'vecc'],
+  sample_from={
+     'veca': RealVectors(shape=3),
+     'vecb': RealVectors(shape=3),
+     'vecc': RealVectors(shape=3)
+  }
+)
+</script>
+
+<p>A line goes through points \( \vec{a}, \vec{b} \in \mathbb{R}^3 \). Give an expression for the minimum distance from this line to a third point \( \vec{c} \).</p>
+
+<ul>
+  <li>You may enter \(\vec{a}\), \(\vec{b}\), and \(\vec{c}\) as <code>veca</code>, <code>vecb</code>, and <code>vecc</code>.</li>
+  <li>Use <code>cross(a, b)</code> for \( \vec{a} \times \vec{b}\)</li>
+</ul>
+
+<p>This demo problem is primarily intended to show off the cross product. Some suggested inputs:</p>
+
+<ul>
+  <li>
+    <code>abs(cross(vecb-veca, vecc-veca))/abs(vecb-veca)</code> is correct,
+  </li>
+  <li>
+    <code>abs(cross(vecb-veca, vecc-vecb))/abs(vecb-veca)</code> is also correct
+  </li>
+  <li>
+    <code>cross(1, [1, 2, 3])</code> to see hepful error messages. All standard functions (<code>norm</code>, <code>trans</code>, <code>det</code>, ...) provided by the MatrixGrader class give similar error messages when something goes wrong.
+  </li>
+</ul>
+
+<customresponse cfn="grader" expect="abs(cross(vecb - veca, vecc - veca))/abs(vecb - veca)">
+    <textline math="true" preprocessorClassName="MJxPrep" preprocessorSrc="/static/MJxPrep.js" size="100" />
+</customresponse>
+
+<a href="https://github.com/mitodl/mitx-grading-library/tree/master/course/problem/matrix3.xml" target="_blank">View source</a>
+
+
+</problem>
diff --git a/course/problem/matrix4.xml b/course/problem/matrix4.xml
@@ -0,0 +1,59 @@
+<problem display_name="MatrixGrader: Vectors vs single-row/column matrix" showanswer="always" weight="10" attempts="">
+
+<script type="text/python" system_path="python_lib">
+from mitxgraders import MatrixGrader
+
+grader_1 = MatrixGrader(
+  answers='[1, 2]',
+  max_array_dim=1 # this is the default, so we did not really need to set it
+)
+
+grader_2 = MatrixGrader(
+  answers='[1, 2]',
+  max_array_dim=2 # students may enter vectors or matrices
+)
+</script>
+
+<p>This pair of graders is intended to display how MatrixGrader treats vectors, single-row matriecs, and single-column matrices as different objects.  The problems are identical, except that the second problem allows entry-by-entry matrix input.</p>
+
+<p>Suggested inputs:</p>
+
+<ul>
+  <li>
+    Correct answers:
+    <ul>
+      <li><code>[1, 2]</code></li>
+      <li><code>trans([1, 2])</code>, transpose does nothing to vectors</li>
+      <li><code>[[1, 0], [0, 1]] * [1, 2]</code></li>
+      <li><code>[1,2] * [[1, 0], [0, 1]]</code></li>
+    </ul>
+  </li>
+  <li><code>[[1, 2]]</code>, single-row matrix, incorrect</li>
+  <li><code>[[1], [2]]</code>, single-column matrix, incorrect</li>
+</ul>
+
+<table>
+  <tr>
+    <th style="width:40%">Only vector input is allowed</th>
+    <th style="width:40%">Vector and matrix input allowed</th>
+  </tr>
+  <tr>
+    <td>
+      <customresponse cfn="grader_1" expect="[1, 2]">
+        <textline math="true" preprocessorClassName="MJxPrep" preprocessorSrc="/static/MJxPrep.js" size="40" />
+      </customresponse>
+    </td>
+    <td>
+      <customresponse cfn="grader_2" expect="[1, 2]">
+        <textline math="true" preprocessorClassName="MJxPrep" preprocessorSrc="/static/MJxPrep.js" size="40" />
+      </customresponse>
+    </td>
+  </tr>
+</table>
+
+<h3>Avoiding Confusion</h3>
+<p>In "real" problems, we strongly recommend disallowing entry-by-entry matrix input (which is the default) unless it is needed, to avoid potential confusion between <code>[1, 2]</code> and <code>[[1, 2]]</code></p>
+
+<a href="https://github.com/mitodl/mitx-grading-library/tree/master/course/problem/matrix4.xml" target="_blank">View source</a>
+
+</problem>