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

# View of /trunk/pg/doc/MathObjects/UsingMathObjects.pod

Fri Sep 28 00:23:44 2007 UTC (12 years, 4 months ago) by sh002i
File size: 13976 byte(s)
```converted basic mathobjects docs to POD
```

```    1 =head1 Using MathObjects
2
3 To use MathObjects in your own problems, you need to load the
4 "MathObjects.pl" macro file:
5
7
8 which defines the commands you need to interact with MathObjects.
9 Once you have done that, you can call the MathObjects functions to create
10 formulas for you.  The main call is Formula(), which takes a string and
11 returns a parsed version of the string.  For example:
12
13     \$f = Formula("x^2 + 3x + 1");
14
15 will set \$f to a reference to the parsed version of the formula.
16
18
19 A formula has a number of methods that you can call.  These include:
20
21 =over
22
23 =item \$f->eval(x=>5)
24
25 Evaluate the formula when x is 5.
26 If \$f has more variables than that, then
27 you must provide additional values, as in
28 \$f->eval(x=>3,y=>1/2);
29
30 =item \$f->reduce
31
32 Tries to remove redundent items from your
33 formula.  For example, Formula("1x+0") returns "x".
34 Reduce tries to factor out negatives and do
35 some other adjustments as well.  (There still
36 needs to be more work done on this.  What it does
37 is correct, but not always smart, and there need
38 to be many more situations covered.)  All the
39 reduction rules can be individually enabled
40 or disabled using the Context()->reduction->set()
41 method, but the documentation for the various
42 rules is not yet ready.
43
44 =item \$f->substitute(x=>5)
45
46 Replace x by the value 5 throughout (you may want
47 to reduce the result afterword, as this is not
48 done automatically).  Note that you can replace a
49 variable by another formula, if you wish.  To make
50 this easier, substitute will apply Formula() to
51 any string values automatically.  E.g.,
52     Formula("x-1")->substitute(x=>"y")
53 returns "y-1" as a formula.
54
55 =item \$f->string
56
57 returns a string representation of the formula
58 (should be equivalent to the original, though not
59 necessarily equal to it).
60
61 =item \$f->TeX
62
63 returns a LaTeX representation of the formula.
64 You can use this in BEGIN_TEXT...END_TEXT blocks
65 as follows:
66
67     BEGIN_TEXT
68     Suppose \(f(x) = \{\$f->TeX}\). ...
69     END_TEXT
70
71 =item \$f->perl
72
73 returns a representation of the formula that could
74 be evaluated by perl's eval() function.
75
76 =item \$f->perlFunction
77
78 returns a perl code block that can be called to
79 evaluate the function.  For example:
80
81     \$f = Formula('x^2 + 3')->perlFunction;
82     \$y = &\$f(5);
83
84 will assign the value 28 to \$y.
85 You can also pass a function name to perlFunction
86 to get a named function to call:
87
88     Formula('x^2 + 3')->perlFunction('f');
89     \$y = f(5);
90
91 If the formula involves more than one variable,
92 then the paramaters should be given in
93 alphabetical order.
94
95     Formula('x^2 + y')->perlFunction('f');
96     \$z = f(5,3);  # \$z is 28.
97
98 Alternatively, you can tell the order for the
99 parameters:
100
101     Formula('x^2 + y')->perlFunction('f',['y','x']);
102     \$z = f(5,3); \$ now \$z is 14.
103
104 =back
105
107
108 There is a second way to create formulas.  Once you have a formula, you can
109 create additional formulas simply by using perls' built-in operations and
110 functions, which have been overloaded to handle formulas.  For example,
111
112     \$x = Formula('x');
113     \$f = 3*x**2 + 2*\$x - 1;
114
115 makes \$f be a formula, and is equivalent to having done
116
117     \$f = Formula("3x^2 + 2x - 1");
118
119 This can be very convenient, but also has some pitfalls.  First, you
120 need to include '*' for multiplication, since perl doesn't do implied
121 multiplication, and you must remember to use '**' not '^'.  (If you use '^'
122 on a formula, the parser will remind you to use '**'.)  Second, the
123 precedences of the operators in perl are fixed, and so changes you make to
124 the precedence table for the parser are not reflected in formulas produced
125 in this way.  (The reason '^' is not overloaded to do exponentiation is
126 that the precedence of '^' is wrong for that in perl, and can't be
127 changed.)  As long as you leave the default precedences, however, things
128 should work as you expect.
129
130 Note that the standard functions, like sin, cos, etc, are overloaded to
131 generate appropriate formulas when their values are formulas.  For example,
132
133     \$x = Formula('x');
134     \$f = cos(3*\$x + 1);
135
136 produces the same result as \$f = Formula("cos(3x+1)"); and you can then go
137 on to output its TeX form, etc.
138
140
141 This parser has support for some things that are missing from the current
142 one, like absolute values.  You can say  |1+x|  rather than  abs(1+x)
143 (though both are allowed), and even |1 - |x|| works.
144
145 Also, you can use  sin^2(x)  (or even sin^2 x) to get  (sin(x))^2.
146
147 Finally, you can use  sin^-1(x)  to get  arcsin(x).
148
149 There is an experimental set of operator precedences that make it possible
150 to write  sin 2x + 3 and get  sin(2x) + 3.  See examples/7-precedence.pg
151 for some details.
152
154
155 The parser understands a wide range of data types, including real and
156 complex numbers, points, vectors, matrices, arbitrary lists, intervals,
157 unions of intervals, and predefined words.  Each has a syntax for use
158 within formulas, as described below:
159
160     numbers        the usual form:  153, 233.5, -2.456E-3, etc.
161
162     complex        a + b i  where a and b are numbers:  1+i, -5i, 6-7i, etc.
163
164     infinitites    the words 'infinity' or '-infinity' (or several
165                    equivalents).
166
167     point          (a,b,c)  where a, b and c are real or complex numbers.
168                    any number of coordinates are allowed.  Eg, (1,2),
169                    (1,0,0,0), (-1,2,-3).  Points are promoted to vectors
170                    automatically, when necessary.
171
172     vector         <a,b,c>  or  a i + b j + c k  (when used in vector context).
173                    As with points, vectors can have any number of
174                    coordinates.  For example, <1,0,0>, <-1,3>, <x,1-x>, etc.
175
176     matrix         [[a11,...,a1n],...[am1,...amn]], i.e., use [..] around
177                    each row, and around the matrix itself.  The elements
178                    are separated by commas (not spaces).  e.g,
179                         [[1,2],[3,4]]     (a 2x2 matrix)
180                         [1,2]             (a 1x2 matrix, really a vector)
181                         [[1],[2]]         (a 2x1 matrix, ie. column vector)
182                    Points and vectors are promoted to matrices when
183                    appropriate.  Vectors are converted to column vectors
184                    when needed for matrix-vector multiplication.  Matrices
185                    can be 3-dimensional or higher by repeated nesting of
186                    matrices.  (In this way, a 2-dimensional matrix is really
187                    thought of as a vector of vectors, and n-dimensional
188                    ones as vectors of (n-1)-dimensional ones.)
189
190    list            (a,b,c)  where a,b,c are arbitrary elements.
191                    For example, (1+i, -3, <1,2,3>, Infinity).
192                    The empty list () is allowed, and the parentheses are
193                    optional if there is only one list.  (This makes it
194                    possible to make list-based answer checkers that
195                    really know where the separations occur.)
196
197    interval        (a,b), (a,b], [a,b), [a,b], or [a,a]  where a and b are
198                    numbers or appropriate forms of infinity.
199                    For example, (-INF,3], [4,4], [2,INF), (-INF,INF).
200
201    union           represented by 'U'.  For example  [-1,0) U (0,1].
202
203    string          special predefined strings like NONE and DNE.
204
205 These forms are what are used in the strings passed to Formula().
206 If you want to create versions of these in perl, there are several
207 ways to do it.  One way is to use the Compute() command, which takes a
208 string parses it and then evaluates the result (it is equivalent to
209 Formula(...)->eval).  If the formula produces a vector, the result
210 will be a Vector constant that you can use in perl formulas by hand.
211
212 For example:
213
214     \$v = Compute("<1,1,0> >< <-1,4,-2>");
215
216 would compute the dot product of the two vectors and assign the
217 resulting vector object to \$v.
218
219 Another way to generate constants of the various types is to use the
220 following routines.  If their inputs are constant, they produce a
221 constant of the appropriate type.  If an input is a formula, they
222 produce corresponding formula objects.
223
224     Real(a)            create a real number with "fuzzy"
225                        comparisons (so that 1.0000001 == Real(1) is true).
226
227     Complex(a,b)       create a complex number a + b i
228
229     Infinity           creates the +infinity object
230     -(Infinity)        creates -infinity
231
232     Point(x1,...xn) or Point([x1,...,xn])      produces (x1,...,xn)
233
234     Vector(x1,...,xn) or Vector([x1,...,xn])   produces <x1,...,xn>
235
236     Matrix([a11,...,a1m],...,[am1,...,amn]) or
237     Matrix([[a11,...,a1m],...,[am1,...,amn]])  produces an n x m matrix
238
239     List(a,...,b)   produces a list with the given elements
240
241     Interval('(',a,b,']')   produces (a,b], (the other endpoints work as
242                             expected.  Use 'INF' and '-INF' for infinities.)
243
244     Union(I1,...,In)  takes the union of the n intervals. (where I1 to In
245                       are intervals.)
246
247     String(word)  Produces a string object for the given word (if it
248                   is a known word).  This is mostly to be able to
249           call the ->cmp and ->TeX methods.
250
251 For example,
252
253     \$a = random(-5,5,1)
254     \$V = Vector(\$a,1-\$a,\$a**2+1);
255
256 produces a vector with some random coordinates.
257
258 Objects of these types also have TeX, string and perl methods, so you can
259 use:
260
261     Vector(1,2,3)->TeX
262
263 to produce a TeX version of the vector, just as you can with formulas.
264
265 There are several "constant" functions that generate common constant
266 values.  These include pi, i, j, k and Infininty.  you can use these
267 in perl expressions as though they were their actual values:
268
269     \$z = \$a + \$b * i;
270     \$v = \$a*i + \$b*j + \$c*k;
271     \$I = Infinity;
272
273 Note that because of a peculiarity of perl, you need to use -(pi)
274 or - pi (with a space) rather than -pi, and similary for the other
275 functions.  Without this, you will get an error message about an
276 ambiguity being resolved.  (This is not a problem if you process your
277 expressions through the parser itself, only if you are writing
278 expressions in perl directly.  Note that since student answers are
279 processed by the parser, not perl directly, they can write -pi without
280 problems.)
281
282 Another useful command is Compute(), which evaluates a formula and
283 returns its value.  This is one way to create point or vector-valued
284 constants, but there is an easier way discussed below.
285
287
288 You may have noticed that "i" was used in two different ways in the
289 examples above.  In the first example, it was treated as a complex
290 number and the second as a coordinate unit vector.  To control which
291 interpretation is used, you specify a parser "context".
292
293 The context controls what operations and functions are defined in the
294 parser, what variables and constants to allow, how to interpret
295 various paretheses, and so on.  Changing the context can completely
296 change the way a formula is interpreted.
297
298 There are several predefined contexts:  Numeric, Complex, Vector,
299 Interval and Full.  (You can also define your own contexts, but that
300 will be described elsewhere.)  To select a context, use the Context()
301 function, e.g.
302
303     Context("Numeric");
304
305 selects the numeric context, where i, j and k have no special meaning,
306 points and vectors can't be used, and the only predefined variable is
307 'x'.
308
309 On the other hand, Context("Vector") makes i, j and k represent the
310 unit coordinate vectors, and defines variables 'x', 'y' and 'z'.
311
312 Context("Interval") is like numeric context, but it also defines the
313 parentheses so that they will form intervals (rather than points or
314 lists).
315
316 Once you have selected a context, you can modify it to suit the
317 particular needs of your problem.  The command
318
319     \$context = Context();
320
321 gets you a reference to the current context object (you can also use
322 something like
323
324     \$context = Context("Numeric");
325
326 to set the context and get its reference at the same time).  Once you
327 have this reference, you can call the Context methods to change values
328 in the context.  These are discussed in more detail in the
329 documentation of the Context object [not yet written], but some of the
330 more common actions are described here.
331
332 To add a variable, use, for example,
333
335
336 To delete any existing variables and replace them with new ones, use
337
338     \$context->variables->are(t=>'Real');
339
340 To remove a variable, use
341
342     \$context->variables->remove('t');
343
344 To get the names of the defind variables, use
345
346     @names = \$context->variables->names;
347
348
349 Similarly, you can add a named constant via
350
352
353 and can change, remove or list the constants via methods like those
354 used for variables above.  The command
355
356     \$M = \$constant->constants->get('M');
357
358 will return the value of the consant M.  (See the
360 you can call for the various types of context data.)
361
362 To add new predefined words (like 'NONE' and 'DNE'), use something
363 like
364
366
367 Note that strings are case-sensitive, so you might want to add
368
370         true => {alias=>'TRUE'},
371         false => {alias=>'FALSE'},
372     );
373
374 so that either "TRUE" or "true" will be interpreted as TRUE.
375
376 There are a number of values stored in the context that control things
377 like the tolerance used when comparing numbers, and so on.  You
378 control these via commands like:
379
380     \$context->flags->set(tolerance=>.00001);
381
382 For example,
383
384     \$context->flags->set(ijk=>1);
385
386 will cause the output of all vectors to be written in ijk format
387 rather than <...> format.
388
389 Finally, you can add or modify the operators and functions that are
390 available in the parser via calls to \$context->operators and
391 \$context->functions.  See the files in webwork2/docs/parser/extensions
392 for examples of how to do this.
393
```