[system] / trunk / pg / doc / MathObjects / MathObjectsAnswerCheckers.pod Repository: Repository Listing bbplugincoursesdistsnplrochestersystemwww

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
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
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
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
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
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
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
193 (default: 'Value::Real')
194
195 =back
196
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
210 which coordinates are right.
211 (default: 1)
212
213 =back
214
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
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
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
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
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.
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).
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.
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
327 (default:  0)
328
329 =item S<C<< entry_type=>'a (name)' >>>
330
331 The string to use in error messages
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
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
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
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
```