[LON-CAPA-cvs] cvs: doc /help/developers LC2_student_equation_syntax.txt

[damieng]

damieng		Tue Sep 23 20:11:47 2014 EDT

  Added files:                 
    /doc/help/developers	LC2_student_equation_syntax.txt 
  Log:
  added developers directory and a doc for student equation syntax
  
  

Index: doc/help/developers/LC2_student_equation_syntax.txt
+++ doc/help/developers/LC2_student_equation_syntax.txt
STUDENT EQUATION SYNTAX FOR MATHRESPONSE AND FORMULARESPONSE

* mathresponse or formularesponse with a CAS:

Note: by default, formularesponse uses Maxima. mathresponse requires the specification of the CAS.

Processing of the response:
1) separation of the string using the comma separator
2) addition of the implicit operators
  a b -> a*b
  3 b -> 3*b
  3 4 -> 3*4
  )( -> )*(
  ) ( -> )*(
  3a -> 3*a
  3( -> 3*(
  3 ( -> 3*(
  a ( -> a*(
  )a -> )*a
  )3 -> )*3
  ) 3 -> )*3
3) in the case of Maxima, tranformation of pi into %pi
4) run of the CAS with the script and the arguments
5) interpretation of the result: true -> EXACT_ANS, false -> INCORRECT, other -> BAD_FORMULA

Consequences:
- the general syntax is the one of the chosen CAS (Maxima or R), with implicit operators
- students can use all the CAS functions in the active libraries, except the blacklisted ones and the ones using more than one argument. For instance, "mod(9,5)" will not work because the string is separated into 2 arguments. Some other important Maxima functions that cannot be used: diff, integrate, sum, product, limit, binomial, atan2. With R %% can be used for the modulo.
- vectors can only be entered with a comma separated string which has then to be reconstructed with the arguments in the CAS script. A vector with the CAS syntax will not be recognized.
- matrices cannot be entered
- with Maxima, constants such as inf, minf, und, %e, %i, %pi and pi are recognized. Other constants than pi needing a percent sign, such as e and i, are not recognized.
- R recognizes pi, Inf and NaN, but not i or e. Due to the preprocessing, complex numbers cannot be entered.
- sometimes the result will be incorrect even though it's a syntax error (for instance when a function name is unknown with Maxima)


* formularesponse with samples:
- parenthesis
- implicit operator: *
- known operators: + - * / ^ % (modulo)
- known constants: only the ones that are explicitely used in the expected answer.
- some unknown operators: !
- known functions: abs, exp, log (log e), sqrt, factorial, sgn, ceil, floor, erf, erfc, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asin, acosh, atanh
- some unknown functions: ln, log10, pow, atan2, min, max
Other functions that should not be used by students seem to be recognized, like duration() and problem().
It looks like functions with more than one argument (like pow) and functions with digits in the name (like log10) are not recognized, even though CAPA knows about them. Probably because of a preprocessing similar to the one used with CAS.


* Summary: common features (for formularesponse and mathresponse, Maxima, R or samples):
- parenthesis
- implicit operator: *
- operators: + - * / ^
- functions: abs, exp, log (log e), sqrt, factorial, floor, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asin, acosh, atanh
- constants: pi, inf (assuming they are expected to be used when samples are used)


* Advice for authors
- Avoid asking students for expressions that require the use of a feature that does not work with all cases, such as constants other than pi. It makes it easier to switch later from CAS to samples or the other way around. It also keeps the syntax compatible with other LON-CAPA problems.
- Add some problems at the beginning of the course to train students to the syntax. In particular, make sure they will not use an expression like "xy" to mean "x*y". For example:
/res/msu/kortemey/physicsprecourse/inputpractice/algebraic.problem