[system] / trunk / pg / doc / MathObjects / MathObjectsAnswerCheckers.pod Repository: Repository Listing bbplugincoursesdistsnplrochestersystemwww 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
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
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
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
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
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
189 (default: 'Value::Real')
190
191 =back
192
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
206 which coordinates are right.
207 (default: 1)
208
209 =back
210
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
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
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
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
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.
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).
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.
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
323 (default:  0)
324
325 =item S<C<< entry_type=>'a (name)' >>>
326
327 The string to use in error messages
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
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
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
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.5],];
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
```