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

View of /trunk/pg/doc/MathObjects/UsingMathObjects.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: 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 
    6     loadMacros("Parser.pl");
    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 
   17 =head2 Working With Formulas
   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 
  106 =head2 Combining Formulas
  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 
  139 =head2 Special Syntax
  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 
  153 =head2 The Formula Types
  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 
  286 =head2 Specifying the Context
  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 
  334     $context->variables->add(y=>'Real');
  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 
  351     $context->constants->add(M=>1/log(10));
  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
  359 pg/lib/Value/Context/Data.pm file for more information on the methods
  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 
  365     $constant->strings->add(TRUE=>{},FALSE=>{});
  366 
  367 Note that strings are case-sensitive, so you might want to add
  368 
  369     $constant->strings->add(
  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 

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9