Skip to content

Commit 62e7f67

Browse files
KarlLundengaardKarlLundengaard
committed
Updated user documentation
1 parent 62df654 commit 62e7f67

File tree

1 file changed

+185
-7
lines changed

1 file changed

+185
-7
lines changed

‎app/docs/user.md‎

Lines changed: 185 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Note that this function is designed to handle comparisons of mathematical expres
88

99
### Optional parameters
1010

11-
There are eight optional parameters that can be set: `complexNumbers`, `convention`, `criteria`, `multiple_answers_criteria`, `elementary_functions`, `physical_quantity`, `plus_minus`/`minus_plus` `specialFunctions`, `strict_syntax`, `symbol_assumptions`.
11+
There are twelve optional parameters that can be set: `complexNumbers`, `convention`, `criteria`, `elementary_functions`, `feedback_for_incorrect_response`, `multiple_answers_criteria`, `physical_quantity`, `plus_minus`/`minus_plus`, `specialFunctions`, `strict_syntax`, `strictness`, `symbol_assumptions`.
1212

1313
## `complexNumbers`
1414

@@ -36,10 +36,13 @@ The `criteria` parameter reserves `response` and `answer` as keywords that will
3636

3737
## `elementary_functions`
3838

39-
When using implicit multiplication function names with mulitple characters are sometimes split and not interpreted properly. Setting `elementary_functions` to true will reserve the function names listed below and prevent them from being split. If a name is said to have one or more alternatives this means that it will accept the alternative names but the reserved name is what will be shown in the preview.
39+
When using implicit multiplication function names with multiple characters are sometimes split and not interpreted properly. Setting `elementary_functions` to true will reserve the function names listed below and prevent them from being split. If a name is said to have one or more alternatives this means that it will accept the alternative names but the reserved name is what will be shown in the preview.
4040

4141
`sin`, `sinc`, `csc` (alternative `cosec`), `cos`, `sec`, `tan`, `cot` (alternative `cotan`), `asin` (alternative `arcsin`), `acsc` (alternatives `arccsc`, `arccosec`), `acos` (alternative `arccos`), `asec` (alternative `arcsec`), `atan` (alternative `arctan`), `acot` (alternatives `arccot`, `arccotan`), `atan2` (alternative `arctan2`), `sinh`, `cosh`, `tanh`, `csch` (alternative `cosech`), `sech`, `asinh` (alternative `arcsinh`), `acosh` (alternative `arccosh`), `atanh` (alternative `arctanh`), `acsch` (alternatives `arccsch`, `arcosech`), `asech` (alternative `arcsech`), `exp` (alternative `Exp`), `E` (equivalent to `exp(1)`, alternative `e`), `log`, `sqrt`, `sign`, `Abs` (alternative `abs`), `Max` (alternative `max`), `Min` (alternative `min`), `arg`, `ceiling` (alternative `ceil`), `floor`
4242

43+
## `feedback_for_incorrect_response`
44+
All feedback for all incorrect responses will be replaced with the string that this parameter is set to.
45+
4346
## `multiple_answers_criteria`
4447

4548
The $\pm$ and $\mp$ symbols can be represented in the answer or response by `plus_minus` and `minus_plus` respectively.
@@ -59,6 +62,147 @@ When `physical_quantity` the evaluation function will generate feedback based on
5962

6063
**TODO:** Generate new flowchart for updated physical quantity feedback generation procedure.
6164

65+
## `strictness`
66+
67+
Constrols the conventions used when parsing physical quantities.
68+
69+
**Remark:** If `physical_quantity` is set to `false`, this parameter will be ignored.
70+
71+
There are three possible values: `strict`, `natural` and `legacy`. If `strict` is chosen then quantities will be parsed according to the conventions described in 5.1, 5.2, 5.3.2, 5.3.3 in https://www.bipm.org/documents/20126/41483022/si_brochure_8.pdf and 5.2, 5.3, 5.4.2 and 5.4.3 in https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf. If `natural` is chosen then less restrictive conventions are used.
72+
73+
**Remark:** The default setting is `natural`.
74+
75+
**Remark:** The `legacy` setting should not be used and is only there to allow compatibility with content designed for use with older versions of the evaluation function. If you encounter a question using the `legacy` setting is recommended that it is changed to another setting and the answer is redefined to match the chosen conventions.
76+
77+
## `units_string`
78+
79+
Controls what sets of units are used. There are three values `SI`, `common` and `imperial`.
80+
81+
If `SI` is chosen then only units from the tables `Base SI units` and `Derived SI units` (below) are allowed (in combinations with prefixes). If `common` is chosen then all the units allowed by `SI` as well as those listed in the tables for `Common non-SI units`. If `imperial` is chosen the base SI units and the units listed in the `Imperial units` table are allowed.
82+
83+
**Remark:** The different settings can also be combine, e.g. `SI common imperial` will allow all units.
84+
85+
### Notation and definition of units
86+
87+
#### Table: Base SI units
88+
89+
SI base units based on Table 2 in https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf
90+
91+
Note that gram is used as a base unit instead of kilogram.
92+
93+
| SI base unit | Symbol | Dimension name |
94+
|--------------|:-------|:--------------------|
95+
| metre | m | length |
96+
| gram | g | mass |
97+
| second | s | time |
98+
| ampere | A | electriccurrent |
99+
| kelvin | k | temperature |
100+
| mole | mol | amountofsubstance |
101+
| candela | cd | luminousintensity |
102+
103+
#### Table: SI prefixes
104+
105+
SI prefixes based on Table 7 in https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf
106+
107+
| SI Prefix | Symbol | Factor | | SI Prefix | Symbol | Factor |
108+
|-----------|:-------|:-----------|-|-----------|:-------|:-----------|
109+
| yotta | Y | $10^{24}$ | | deci | d | $10^{-1}$ |
110+
| zetta | Z | $10^{21}$ | | centi | c | $10^{-2}$ |
111+
| exa | E | $10^{18}$ | | milli | m | $10^{-3}$ |
112+
| peta | P | $10^{15}$ | | micro | mu | $10^{-6}$ |
113+
| tera | T | $10^{12}$ | | nano | n | $10^{-9}$ |
114+
| giga | G | $10^{9}$ | | pico | p | $10^{-12}$ |
115+
| mega | M | $10^{6}$ | | femto | f | $10^{-15}$ |
116+
| kilo | k | $10^{3}$ | | atto | a | $10^{-18}$ |
117+
| hecto | h | $10^{2}$ | | zepto | z | $10^{-21}$ |
118+
| deka | da | $10^{1}$ | | yocto | y | $10^{-24}$ |
119+
120+
#### Table: Derived SI units
121+
122+
Derived SI based on Table 4 in https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf
123+
124+
Note that the function treats radians and steradians as dimensionless values.
125+
126+
| Unit name | Symbol | Expressed in base SI units |
127+
|-----------|:-------|:---------------------------------------------------------------------------------|
128+
| radian | r | $(2\pi)^{-1}$ |
129+
| steradian | sr | $(4\pi)^{-1}$ |
130+
| hertz | Hz | $\mathrm{second}^{-1}$ |
131+
| newton | N | $\mathrm{metre}~\mathrm{kilogram}~\mathrm{second}^{-2}$ |
132+
| pascal | Pa | $\mathrm{metre}^{-1}~\mathrm{kilogram}~\mathrm{second}^{-2}$ |
133+
| joule | J | $\mathrm{metre}^2~\mathrm{kilogram~second}^{-2}$ |
134+
| watt | W | $\mathrm{metre}^2~\mathrm{kilogram~second}^{-3}$ |
135+
| coulomb | C | $\mathrm{second~ampere}$ |
136+
| volt | V | $\mathrm{metre}^2~\mathrm{kilogram second}^{-3}~\mathrm{ampere}^{-1}$ |
137+
| farad | F | $\mathrm{metre}^{-2}~\mathrm{kilogram}^{-1}~\mathrm{second}^4~\mathrm{ampere}^2$ |
138+
| ohm | O | $\mathrm{metre}^2~\mathrm{kilogram second}^{-3}~\mathrm{ampere}^{-2}$ |
139+
| siemens | S | $\mathrm{metre}^{-2}~\mathrm{kilogram}^{-1}~\mathrm{second}^3~\mathrm{ampere}^2$ |
140+
| weber | Wb | $\mathrm{metre}^2~\mathrm{kilogram~second}^{-2}~\mathrm{ampere}^{-1}$ |
141+
| tesla | T | $\mathrm{kilogram~second}^{-2} \mathrm{ampere}^{-1}$ |
142+
| henry | H | $\mathrm{metre}^2~\mathrm{kilogram~second}^{-2}~\mathrm{ampere}^{-2}$ |
143+
| lumen | lm | $\mathrm{candela}$ |
144+
| lux | lx | $\mathrm{metre}^{-2}~\mathrm{candela}$ |
145+
| becquerel | Bq | $\mathrm{second}^{-1}$ |
146+
| gray | Gy | $\mathrm{metre}^2~\mathrm{second}^{-2}$ |
147+
| sievert | Sv | $\mathrm{metre}^2~\mathrm{second}^{-2}$ |
148+
| katal | kat | $\mathrm{mole~second}^{-1}$ |
149+
150+
#### Table: Common non-SI units
151+
152+
Commonly used non-SI units based on Table 8 in https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf and Tables 7 and 8 in https://www.bipm.org/documents/20126/41483022/si_brochure_8.pdf
153+
Note that the function treats angles, neper and bel as dimensionless values.
154+
155+
Note that only the first table in this section has short form symbols defined, the second table does not, this is done to minimize ambiguities when writing units.
156+
157+
| Unit name | Symbol | Expressed in SI units |
158+
|-------------------|:-------|:-------------------------------------------|
159+
| minute | min | $60~\mathrm{second}$ |
160+
| hour | h | $3600~\mathrm{second}$ |
161+
| degree | deg | $\frac{1}{360}$ |
162+
| liter | l | $10^{-3}~\mathrm{metre}^3$ |
163+
| metric_ton | t | $10^3~\mathrm{kilogram}$ |
164+
| neper | Np | $1$ |
165+
| bel | B | $\frac{1}{2}~\ln(10)$ |
166+
| electronvolt | eV | $1.60218 \cdot 10^{-19}~\mathrm{joule}$ |
167+
| atomic_mass_unit | u | $1.66054 \cdot 10^{-27}~\mathrm{kilogram}$ |
168+
| angstrom | å | $10^{-10}~\mathrm{metre}$ |
169+
170+
| Unit name | Expressed in SI units |
171+
|------------------|:-----------------------------------------------------|
172+
| day | $86400~\mathrm{second}$ |
173+
| angleminute | $\frac{\pi}{10800}$ |
174+
| anglesecond | $\frac{\pi}{648000}$ |
175+
| astronomicalunit | $149597870700~\mathrm{metre}$ |
176+
| nauticalmile | $1852~\mathrm{metre}$ |
177+
| knot | $\frac{1852}{3600}~\mathrm{metre~second}^{-1}$ |
178+
| are | $10^2~\mathrm{metre}^2$ |
179+
| hectare | $10^4~\mathrm{metre}^2$ |
180+
| bar | $10^5~\mathrm{pascal}$ |
181+
| barn | $10^{-28}~\mathrm{metre}$ |
182+
| curie | $3.7 \cdot 10^{10}~\mathrm{becquerel} |
183+
| roentgen | $2.58 \cdot 10^{-4}~\mathrm{kelvin~(kilogram)}^{-1}$ |
184+
| rad | $10^{-2}~\mathrm{gray}$ |
185+
| rem | $10^{-2}~\mathrm{sievert}$ |
186+
187+
#### Table: Imperial units
188+
189+
Commonly imperial units taken from https://en.wikipedia.org/wiki/Imperial_units
190+
191+
| Unit name | Symbol | Expressed in SI units |
192+
|-------------------|:-------|:----------------------------------------------|
193+
| inch | in | $0.0254~\mathrm{metre}$ |
194+
| foot | ft | $0.3048~\mathrm{metre}$ |
195+
| yard | yd | $0.9144~\mathrm{metre}$ |
196+
| mile | mi | $1609.344~\mathrm{metre}$ |
197+
| fluid ounce | fl oz | $28.4130625~\mathrm{millilitre}$ |
198+
| gill | gi | $142.0653125~\mathrm{millilitre}$ |
199+
| pint | pt | $568.26125~\mathrm{millilitre}$ |
200+
| quart | qt | $1.1365225~\mathrm{litre}$ |
201+
| gallon | gal | $4546.09~\mathrm{litre}$ |
202+
| ounce | oz | $28.349523125~\mathrm{gram}$ |
203+
| pound | lb | $0.45359237~\mathrm{kilogram}$ |
204+
| stone | st | $6.35029318~\mathrm{kilogram}$ |
205+
62206
## `plus_minus` and `minus_plus`
63207

64208
The $\pm$ and $\mp$ symbols can be represented in the answer or response by `plus_minus` and `minus_plus` respectively.
@@ -81,14 +225,16 @@ By default `strict_syntax` is set to true.
81225

82226
This input parameter allows the author to set an extra assumption each symbol. Each assumption should be written on the form `('symbol','assumption name')` and all pairs concatenated into a single string.
83227

84-
The possible assumption names can be found in this list:
228+
The possible assumptions are: `constant`, `function` as well as those listed here:
85229
[`SymPy Assumption Predicates`](https://docs.sympy.org/latest/guides/assumptions.html#predicates)
86230

231+
**Note:** Writing a symbol which denotes a function without its arguments, e.g. `T` instead of `T(x,t)`, is prone to cause errors.
232+
87233
## Examples
88234

89235
Implemented versions of these examples can be found in the module 'Examples: Evaluation Functions'.
90236

91-
### 1 Setting input symbols to be assumed positive to avoid issues with fractional powers
237+
### Setting input symbols to be assumed positive to avoid issues with fractional powers
92238

93239
In general $\frac{\sqrt{a}}{\sqrt{b}} \neq \sqrt{\frac{a}{b}}$ but if $a > 0$ and $b > 0$ then $\frac{\sqrt{a}}{\sqrt{b}} = \sqrt{\frac{a}{b}}$. The same is true for other fractional powers.
94240

@@ -97,7 +243,7 @@ So if expressions like these are expected in the answer and/or response then it
97243
The example given in the example problem set uses two EXPRESSION response areas. Both response areas uses `compareExpression` with answer `sqrt(a/b)`, `strict_syntax` set to false, `elementary_functions` set to true. One response area leaves `symbol_assumptions` unset and the other sets the parameter as described in the previous paragraph. Some examples of expressions that are accepted as correct when positivity is assumed:
98244
`sqrt(a)/sqrt(b)`, `(a/b)**(1/2)`, `a**(1/2)/b**(1/2)`, `(a/b)^(0.5)`, `a^(0.5)/b^(0.5)`
99245

100-
### 2 Using plus/minus symbols
246+
### Using plus/minus symbols
101247

102248
The $\pm$ and $\mp$ symbols can be represented in the answer or response by `plus_minus` and `minus_plus` respectively. To use other symbols for $\pm$ and $\mp$ set the grading parameters `plus_minus` and `minus_plus` to the desired symbol. **Remark:** symbol replacement is brittle and can have unintended consequences.
103249

@@ -106,14 +252,14 @@ It is considered good practice to make sure that the appropriate notation for $\
106252
The example given in the example problem set uses an EXPRESSION response area that uses `compareExpression` with answer `plus_minus x**2 + minus_plus y**2`, `strict_syntax` set to false and `elementary_function` set to true. Some examples of expressions that are accepted as correct:
107253
`plus_minus x**2 + minus_plus y**2`, `- minus_plus x**2 + minus_plus y**2`, `- minus_plus x^2 minus_plus y^2`, `- minus_plus x^2 - plus_minus y^2`
108254

109-
### 3 Equalities in the answer and response
255+
### Equalities in the answer and response
110256

111257
There is (limited) support for using equalities in the response and answer.
112258

113259
The example given in the example problem set uses an EXPRESSION response area that uses `compareExpression` with answer `x**2-5*y**2-7=0`. Some examples of expressions that are accepted as correct:
114260
`x**2-5*y**2-7=0`, `x^2 = 5y^2+7`, `2x^2 = 10y^2+14`
115261

116-
### 4 Checking the value of an expression or a physical quantity
262+
### Checking the value of an expression or a physical quantity
117263

118264
If the parameter `physical_quantity` is set to true, the evaluation function can handle expressions that describe physical quantities. Which units are permitted and how they should be written depends on the `units_string` and `strictness` parameters respectively.
119265

@@ -130,3 +276,35 @@ Here the answer is `2.00 km/h`. To restrict the answers to SI units `strictness`
130276
#### Example (c)
131277

132278
Here the answer is `2.00 km/h`. To restrict the answers to imperial units `strictness` is set to `strict` and `units_string` is set to `imperial common`. Accepted response: `1.24 mile/hour`
279+
280+
### Changing convention for precedence for implicit and explicit multiplication
281+
282+
You can change what convention is used for precedence for explicit and implicit multiplication by setting the `convention` parameter.
283+
284+
There are two supported conventions:
285+
286+
`equal_precedence` Implicit multiplication have the same precedence as explicit multiplication, i.e. both `1/ab` and `1/a*b` will be equal to `(1/a)*b`.
287+
288+
`implicit_higher_precedence` Implicit multiplication have higher precedence than explicit multiplication, i.e. `1/ab` will be equal to `1/(ab)` and `1/a*b` will be equal to `(1/a)*b`.
289+
290+
In the examples set there is one response area for each of the two conventions, both with answer `1/ab`. Try `1/ab`, `(1/a)*b` and `1/(a*b)` in both response areas and note the differences in behaviour.
291+
292+
### Setting absolute or relative tolerances for numerical comparison
293+
294+
`compareExpressions` can be used both for symbolic and numerical comparisons. The default is symbolic comparisons.
295+
296+
The evaluation function can be configured to do numerical comparisons in the following ways:
297+
298+
- Setting the absolute error tolerance: This is done by setting the parameter `atol`. When `atol` is set to any positive value, then `response` will be considered correct if $|$`answer`$-$`response`$| < $`atol`.
299+
300+
- Setting the relative error tolerance: This is done by setting the parameter `rtol`. When `rtol` is set to any positive value, then `response` will be considered correct if $|$`answer`$-$`response`$|/|$`answer`$| < $`rtol`.
301+
302+
**Note:** If the response area is used to compare physical quantities (i.e. the parameter `physical_quantity` is set to `true`) comparisons will be numerical be default (since unit conversion has finite precision).
303+
304+
#### Setting the absolute tolerance
305+
306+
In the following response area the absolute tolerance (`atol`) has been set to $5$. There are three correct answers: $\sqrt{47}+\pi$ (approx. 9.9997), $\frac{13}{3}^{\pi}$ (approx. 99.228) and $9^{e+\ln(1.5305)}$ (approx. 1000.05). Any answer within the set absolute tolerance (i.e. $5<$`response`$<15$, $95<$`response`$<105$ or $995<$`response`$<1005$) of either answer will be considered correct.
307+
308+
#### Setting the relative tolerance
309+
310+
In the following response area the absolute tolerance (`atol`) has been set to $0.5$. There are three correct answers: $\sqrt{47}+\pi$ (approx. 9.9997), $\frac{13}{3}^{\pi}$ (approx. 99.228) and $9^{e+\ln(1.5305)}$ (approx. 1000.05). Any answer within the set absolute tolerance (i.e. $5<$`response`$<15$, $95<$`response`$<105$ or $995<$`response`$<1005$) of either answer will be considered correct.

0 commit comments

Comments
 (0)