[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 5539 - (download) (annotate)
Fri Sep 28 00:23:44 2007 UTC (12 years, 4 months ago) by sh002i
File size: 11819 byte(s)
converted basic mathobjects docs to POD

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

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9