[system] / trunk / pg / doc / MathObjects / MathObjectsAnswerCheckers.pod Repository:
ViewVC logotype

View of /trunk/pg/doc/MathObjects/MathObjectsAnswerCheckers.pod

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5634 - (download) (annotate)
Tue Apr 15 04:41:17 2008 UTC (11 years, 10 months ago) by gage
File size: 12019 byte(s)
Edited the first three paragraphs describing why math objects are used.
(I also copied these paragraphs into the wiki itself in the "introduction to math objects" page.)

    1 =head1 MathObjects-based Answer Checkers
    2 
    3 MathObjects are designed to be used in two ways. First, you can use it
    4 within your perl code when writing problems as a means of making it
    5 easier to handle formulas, and in particular, to be able to use a single
    6 object to produce numeric values, TeX output and answer strings from a
    7 single formula entry. This avoids having to type a function three
    8 different ways (which makes maintaining a problem much harder). Since
    9 MathObjects also included vector and complex arthimetic, it is easier to
   10 work with these types of values as well.
   11 
   12 Secondly using MathObjects improves the processing of student input.
   13 This is accomplished through special answer checkers that are part of
   14 the Parser package (rather than the traditional WeBWorK answer
   15 checkers). Each of these checkers has error checking customized to the
   16 type of input expected from the student and can provide helpful feedback
   17 if the syntax of the student's entry is incorrect.
   18 
   19 Checkers are available for each of the types of values that the parser
   20 can produce (numbers, complex numbers, infinities, points, vectors,
   21 intervals, unions, formulas, lists of numbers, lists of points, lists of
   22 intervals, lists of formulas returning numbers, lists of formulas
   23 returning points, and so on).
   24 
   25 To use one of these checkers, simply call the ->cmp method of the
   26 object that represents the correct answer.  For example:
   27 
   28     $n = Real(sqrt(2));
   29     ANS($n->cmp);
   30 
   31 will produce an answer checker that matches the square root of two.
   32 Similarly,
   33 
   34     ANS(Vector(1,2,3)->cmp);
   35 
   36 matches the vector <1,2,3> (or any computation that produces it, e.g.,
   37 i+2j+3k, or <4,4,4>-<3,2,1>), while
   38 
   39     ANS(Interval("(-inf,3]")->cmp);
   40 
   41 matches the given interval.  Other examples include:
   42 
   43     ANS(Infinity->cmp);
   44     ANS(String('NONE')->cmp);
   45     ANS(Union("(-inf,$a) U ($a,inf)")->cmp);
   46 
   47 and so on.
   48 
   49 Formulas are handled in the same way:
   50 
   51     ANS(Formula("x+1")->cmp);
   52 
   53     $a = random(-5,5,1); $b = random(-5,5,1); $x = random(-5,5,1);
   54     $f = Formula("x^2 + $a x + $b")->reduce;
   55     ANS($f->cmp);
   56     ANS($f->eval(x=>$x)->cmp);
   57 
   58     $x = Formula('x');
   59     ANS((1+$a*$x)->cmp);
   60 
   61     Context("Vector")->variables->are(t=>'Real');
   62     $v = Formula("<t,t^2,t^3>"); $t = random(-5,5,1);
   63     ANS($v->cmp);
   64     ANS($v->eval(t=>$t)->cmp);
   65 
   66 and so on.
   67 
   68 Lists of items can be checked as easily:
   69 
   70     ANS(List(1,-1,0)->cmp);
   71     ANS(List(Point($a,$b),Point($a,-$b))->cmp);
   72     ANS(List(Vector(1,0,0),Vector(0,1,1))->cmp);
   73     ANS(Compute("(-inf,2),(4,5)")->cmp); # easy way to get list of intervals
   74     ANS(Formula("x, x+1, x^2-1")->cmp);
   75     ANS(Formula("<x,2x>,<x,-2x>,<0,x>")->cmp);
   76     ANS(List('NONE')->cmp);
   77 
   78 and so on.  The last example may seem strange, as you could have used
   79 ANS(String('NONE')->cmp), but there is a reason for using this type
   80 of construction.  You might be asking for one or more numbers (or
   81 points, or whatever) or the word 'NONE' of there are no numbers (or
   82 points).  If you used String('NONE')->cmp, the student would get an
   83 error message about a type mismatch if he entered a list of numbers,
   84 but with List('NONE')->cmp, he will get appropriate error messages for
   85 the wrong entries in the list.
   86 
   87 It is often appropriate to use the list checker in this way even when
   88 the correct answer is a single value, if the student might type a list
   89 of answers.
   90 
   91 On the other hand, using the list checker has its disadvantages.  For
   92 example, if you use
   93 
   94     ANS(Interval("(-inf,3]")->cmp);
   95 
   96 and the student enters (-inf,3), she will get a message indicating
   97 that the type of interval is incorrect, while that would not be the
   98 case if
   99 
  100     ANS(List(Interval("(-inf,3]"))->cmp);
  101 
  102 were used.  (This is because the student doesn't know how many
  103 intervals there are, so saying that the type of interval is wrong
  104 would inform her that there is only one.)
  105 
  106 The rule of thumb is:  the individual checkers can give more detailed
  107 information about what is wrong with the student's answer; the list
  108 checker allows a wider range of answers to be given without giving
  109 away how many answers there are.  If the student knows there's only
  110 one, use the individual checker; if there may or may not be more than
  111 one, use the list checker.
  112 
  113 Note that you can form lists of formulas as well.  The following all
  114 produce the same answer checker:
  115 
  116     ANS(List(Formula("x+1"),Formula("x-1"))->cmp);
  117 
  118     ANS(Formula("x+1,x-1")->cmp); # easier
  119 
  120     $f = Formula("x+1"); $g = Formula("x-1");
  121     ANS(List($f,$g)->cmp);
  122 
  123     $x = Formula('x');
  124     ANS(List($x+1,$x-1)->cmp);
  125 
  126 See the files in webwork2/doc/parser/problems for more
  127 examples of using the parser's answer checkers.
  128 
  129 =head2 Controlling the Details of the Answer Checkers
  130 
  131 The action of the answer checkers can be modified by passing flags to
  132 the cmp() method.  For example:
  133 
  134     ANS(Real(pi)->cmp(showTypeWarnings=>0));
  135 
  136 will prevent the answer checker from reporting errors due to the
  137 student entering in the wrong type of answer (say a vector rather than
  138 a number).
  139 
  140 =head3 Flags common to all answer checkers
  141 
  142 There are a number of flags common to all the checkers:
  143 
  144 =over
  145 
  146 =item S<C<< showTypeWarnings=>1 or 0 >>>
  147 
  148 show/don't show messages about student
  149 answers not being of the right type.
  150 (default: 1)
  151 
  152 =item S<C<< showEqualErrors=>1 or 0 >>>
  153 
  154 show/don't show messages produced by
  155 trying to compare the professor and
  156 student values for equality, e.g.,
  157 conversion errors between types.
  158 (default: 1)
  159 
  160 =item S<C<< ignoreStrings=>1 or 0 >>>
  161 
  162 show/don't show type mismatch errors
  163 produced by strings (so that 'NONE' will
  164 not cause a type mismatch in a checker
  165 looking for a list of numbers, for example).
  166 (default: 1)
  167 
  168 =back
  169 
  170 In addition to these, the individual types have their own flags:
  171 
  172 =head3 Flags for Real()->cmp
  173 
  174 =over
  175 
  176 =item S<C<< ignoreInfinity=>1 or 0 >>>
  177 
  178 Don't report type mismatches if the
  179 student enters an infinity.
  180 (default: 1)
  181 
  182 =back
  183 
  184 =head3 Flags for String()->cmp
  185 
  186 =over
  187 
  188 =item S<C<< typeMatch=>value >>>
  189 
  190 Specifies the type of object that
  191 the student should be allowed to enter
  192 (in addition the string).
  193 (default: 'Value::Real')
  194 
  195 =back
  196 
  197 =head3 Flags for Point()->cmp
  198 
  199 =over
  200 
  201 =item S<C<< showDimensionHints=>1 or 0 >>>
  202 
  203 show/don't show messages about the
  204 wrong number of coordinates.
  205 (default: 1)
  206 
  207 =item S<C<< showCoordinateHints=>1 or 0 >>>
  208 
  209 show/don't show message about
  210 which coordinates are right.
  211 (default: 1)
  212 
  213 =back
  214 
  215 =head3 Flags for Vector()->cmp
  216 
  217 =over
  218 
  219 =item S<C<< showDimensionHints=>1 or 0 >>>
  220 
  221 show/don't show messages about the
  222 wrong number of coordinates.
  223 (default: 1)
  224 
  225 =item S<C<< showCoordinateHints=>1 or 0 >>>
  226 
  227 show/don't show message about
  228 which coordinates are right.
  229 (default: 1)
  230 
  231 =item S<C<< promotePoints=>1 or 0 >>>
  232 
  233 do/don't allow the student to
  234 enter a point rather than a vector.
  235 (default: 1)
  236 
  237 =item S<C<< parallel=>1 or 0 >>>
  238 
  239 Mark the answer as correct if it
  240 is parallel to the professor's answer.
  241 Note that a value of 1 forces
  242 showCoordinateHints to be 0.
  243 (default: 0)
  244 
  245 =item S<C<< sameDirection=>1 or 0 >>>
  246 
  247 During a parallel check, mark the
  248 answer as correct only if it is in
  249 the same (not the opposite)
  250 direction as the professor's answer.
  251 (default: 0)
  252 
  253 =back
  254 
  255 =head3 Flags for Matrix()->cmp
  256 
  257 =over
  258 
  259 =item S<C<< showDimensionHints=>1 or 0 >>>
  260 
  261 show/don't show messages about the
  262 wrong number of coordinates.
  263 (default: 1)
  264 
  265 =back
  266 
  267 The default for showEqualErrors is set to 0 for Matrices, since
  268 these errors usually are dimension errors, and that is handled
  269 separately (and after the equality check).
  270 
  271 =head3 Flags for Interval()->cmp
  272 
  273 =over
  274 
  275 =item S<C<< showEndpointHints=>1 or 0 >>>
  276 
  277 do/don't show messages about which
  278 endpoints are correct.
  279 (default: 1)
  280 
  281 =item S<C<< showEndTypeHints=>1 or 0 >>>
  282 
  283 do/don't show messages about
  284 whether the open/closed status of
  285 the enpoints are correct (only
  286 shown when the endpoints themselves
  287 are correct).
  288 (default: 1)
  289 
  290 =back
  291 
  292 =head3 Flags for Union()->cmp and List()->cmp
  293 
  294 all the flags from the Real()->cmp, plus:
  295 
  296 =over
  297 
  298 =item S<C<< showHints=>1 or 0 >>>
  299 
  300 do/don't show messages about which
  301 entries are incorrect.
  302 (default:  $showPartialCorrectAnswers)
  303 
  304 =item S<C<< showLengthHints=>1 or 0 >>>
  305 
  306 do/don't show messages about having the
  307 correct number of entries (only shown
  308 when all the student answers are
  309 correct but there are more needed, or
  310 all the correct answsers are among the
  311 ones given, but some extras were given).
  312 (default:  $showPartialCorrectAnswers)
  313 
  314 =item S<C<< partialCredit=>1 or 0 >>>
  315 
  316 do/don't give partial credit for when
  317 some answers are right, but not all.
  318 (default:  $showPartialCorrectAnswers)
  319 (currently the default is 0 since WW
  320 can't handle partial credit properly).
  321 
  322 =item S<C<< ordered=>1 or 0 >>>
  323 
  324 give credit only if the student answers
  325 are in the same order as the
  326 professor's answers.
  327 (default:  0)
  328 
  329 =item S<C<< entry_type=>'a (name)' >>>
  330 
  331 The string to use in error messages
  332 about type mismatches.
  333 (default:  dynamically determined from list)
  334 
  335 =item S<C<< list_type=>'a (name)' >>>
  336 
  337 The string to use in error messages
  338 about numbers of entries in the list.
  339 (default:  dynamically determined from list)
  340 
  341 =item S<C<< typeMatch=>value >>>
  342 
  343 Specifies the type of object that
  344 the student should be allowed to enter
  345 in the list (determines what
  346 constitutes a type mismatch error).
  347 (default: dynamically determined from list)
  348 
  349 =item S<C<< requireParenMatch=>1 or 0 >>>
  350 
  351 Do/don't require the parentheses in the
  352 student's answer to match those in the
  353 professor's answer exactly.
  354 (default: 1)
  355 
  356 =item S<C<< removeParens=>1 or 0 >>>
  357 
  358 Do/don't remove the parentheses from the
  359 professor's list as part of the correct
  360 answer string.  This is so that if you
  361 use List() to create the list (which
  362 doesn't allow you to control the parens
  363 directly), you can still get a list
  364 with no parentheses.
  365 (default: 0 for List() and 1 for Formula())
  366 
  367 =back
  368 
  369 =head3 Flags for Formula()->cmp
  370 
  371 The flags for formulas are dependent on the type of the result of
  372 the formula.  If the result is a list or union, it gets the flags
  373 for that type above, otherwise it gets that flags of the Real
  374 type above.
  375 
  376 More flags need to be added in order to allow more control over the
  377 answer checkers to give the full flexibility of the traditional
  378 WeBWorK answer checkers.  Note that some things, like whether trig
  379 functions are allowed in the answer, are controlled through the
  380 Context() rather than the answer checker itself.  For example,
  381 
  382     Context()->functions->undefine('sin','cos','tan');
  383 
  384 would remove those three functions from use.  (One would need to remove
  385 cot, sec, csc, arcsin, asin, etc., to do this properly; there could be
  386 a function call to do this.)
  387 
  388 Similarly, which arithmetic operations are available is controlled
  389 through Context()->operations.
  390 
  391 The tolerances used in comparing numbers are part of the Context as
  392 well.  You can set these via:
  393 
  394     Context()->flags->set(
  395         tolerance    => .0001,       # the relative or absolute tolerance
  396         tolType      => 'relative',  # or 'absolute'
  397         zeroLevel    => 1E-14,       # when to use zeroLevelTol
  398         zeroLevelTol => 1E-12,       # smaller than this matches zero
  399                                      #  when one of the two is less
  400                                      #  than zeroLevel
  401         limits       => [-2,2],      # limits for variables in formulas
  402         num_points   => 5,           # the number of test points
  403     );
  404 
  405 [These need to be handled better.]
  406 
  407 Note that for testing formulas, you can override the limits and
  408 num_points settings by setting these fields of the formula itself:
  409 
  410     $f = Formula("sqrt(x-10)");
  411     $f->{limits} = [10,12];
  412 
  413     $f = Formula("log(xy)");
  414     $f->{limits} = [[.1,2],[.1,2]]; # x and y limits
  415 
  416 You can also specify the test points explicitly:
  417 
  418     $f = Formula("sqrt(x-10)");
  419     $f->{test_points} = [[11],[11.5],[12]];
  420 
  421     $f = Formula("log(xy)");
  422     $f->{test_points} = [[.1,.1],[.1,.5],[.1,.75],
  423                          [.5,.1],[.5,.5],[.5,.75]];
  424 
  425 [There still needs to be a means of handling the tolerances similarly,
  426 and through the ->cmp() call itself.]
  427 

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9