Introduction to MathObjects

What are MathObjects?

MathObjects are a set of Perl objects that make the manipulation of mathematics within WeBWorK problems more intuitive. They make it possible to define variables in your problems that correspond to common mathematical objects, such as formulas, real number, complex numbers, intervals, vectors, points, and so on. For example:

   $f = Formula("sin(x^2+6)");
   $a = Real("sqrt(pi/6)");
   $z = Complex("1 + 5i");

These are useful (and powerful) because MathObjects "know" information about themselves; thus, you can add formulas to get new formulas, plug real objects into formulas to get formulas evaluated at those values, calculate derivatives of formulas, add and subtract intervals to form unions and intersections, and much more.

For several reasons it is usually preferable to write the MathObjects above using the Compute() function rather than the individual constructors for the various MathObject types.

   $f = Compute("sin(x^2+6)");
   $a = Compute("sqrt(pi/6)");
   $z = Compute("1 + 5i");

The Compute() function determines the kind of MathObject from the Context and from the syntax of its argument, which is usually a string value that is in the form that a student could type. The Compute function also sets the "correct answer" to be the exact string that it was given, so that if a student were asked to enter a number that matched $a from above and asked to see the correct answer (after the due date), then sqrt(pi/6) would be displayed rather than 0.723601. This gives you more control over the format of correct answers that are shown to students.

Why use MathObjects?

MathObjects are designed to be used in two ways. First, you can use them within your Perl code when writing problems as a means of making it easier to handle formulas and other mathematical items, and in particular to be able to produce numeric values, TeX output, and answer strings from a single formula object. This avoids having to type a function three different ways (as a Perl function, as a TeX string, and as an answer string), making it much easier to maintain a problem, or duplicate and modify it to use a different formula. Since MathObjects also includes vectors, points, matrices, intervals, complex numbers, and a variety of other object types, it is easier to work with these kinds of values as well.

More importantly, using MathObjects improves the processing of student input. This is accomplished through special answer checkers that are part of the MathObjects Parser package rather than the traditional WeBWorK answer checkers. Each of these checkers has error checking customized to the type of input expected from the student and can provide helpful feedback if the syntax of the student's entry is incorrect. Because the MathObject checkers are part of a unified library, students get consistent error messages regardless of the type of answer that is expected or that they provide. For example, if a student enters a formula in an answer blank where the correct answer is actually a number, she will receive a message indicating that what she typed was a formula but that a number was expected. Thus students are given guidance automatically about this type of semantic problem with their answers. Answer checkers for points and vectors can indicate that the number of coordinates are wrong, or can tell the student which coordinates are incorrect (at the problem-author's discretion).

MathObject Contexts

Although a problem may include several answer blanks, the problem generally has a collection of variables that it defines, values that it uses, and so on; these form the "context" of the problem. For example, if the problem is concerned with a function of [math]x[/math] and [math]y[/math] and its partial derivatives, then the context of the problem includes variables [math]x[/math] and [math]y[/math], and so all the answer blanks within the problem should recognize that x and y have meaning within the problem, even if the answer blank is only asking for a number. Suppose a student is asked to enter the value of a partial derivative at a particular point and, rather than giving a number, enters the formula for the derivative (not evaluated at the point). He should not be told "x is undefined", as would have been the case with WeBWorK's traditional answer checkers, since [math]x[/math] actually is defined as part of the problem. Such messages serve to confuse the student rather than help him resolve the problem.

MathObjects solves this issue by using a Context object to maintain the context of a problem. That way, all the answer blanks will know about all the variables and values defined within the problem, and can issue appropriate warning messages when a student uses them inappropriately. For example, in the situation described above where the student entered the unevaluated derivative where the value at a point was requested, he will get the message "Your answer is not a number (it seems to be a formula returning a number)", which should help him figure out what he has done wrong.

Thus one of the main purposes for the Context is to maintain the set of variables and values that are part of the problem as a whole. Another key function of the Context is to tell the answer checkers what functions and operations are available within a student answer, and what the various symbols the student can type will mean. For example, if you are asking a student to compute the value of 6 / 3, then you may want to restrict what the student can type so that she can't enter / in her answer, and must type an actual number (not an expression that is evaluated to a number). Or if you are asking a student to determine the value of sin(pi/6), you might want to restrict his answer so that he can't include sin(), but you do allow arithmetic operations. Such restrictions are also part of the context of the problem, and so are maintained by MathObjects as part of the Context.

In a similar way, some symbols mean different things in different problems. For example in a problem dealing with intervals, (4,5) means the interval between 4 and 5, while in a multi-variable calculus setting, it might mean a single point in the [math]xy[/math]-plane. Or in a problem on complex numbers, the value [math]i[/math] means [math]\sqrt{-1}[/math], while in vector calculus, it would mean the coordinate unit vector along the [math]x[/math]-axis. Or in a problem on inequalities, 5 < x would use < as the "less-than" sign, while in a vector calculus problem, <5,6,7> would mean the vector with coordinates 5, 6, and 7. The Context determines how these symbols will be interpreted by the MathObjects library.

The MathObjects library comes with a collection of predefined Contexts that you can call on to set the meanings of symbols like these to be what you need for your problems. The default Context is the Numeric Context, which is sufficient for most first-semester calculus problems. There are Contexts for complex numbers, intervals, vectors, and so forth; see the Common Contexts list and the links at the bottom of this document for further information. The pg/macros/ directory includes a number of specialized Contexts as well; the files beginning with context define these, and are described on the Specialized contexts page.

Use $context = Context(); to obtain a reference to the current context. See the Introduction to contexts for information about how to use this to modify an existing context (e.g., to add variables to it, or to restrict the functions that can be used).

It is possible to use more than one context within the same problem. This is discussed (link needed).

Further Reading

• Introduction to Contexts
• Common Contexts
• Specialized contexts
• pg/macros -- files starting with context define new Contexts

How to create a MathObject

In order to use MathObjects in a problem you are writing, include MathObjects.pl in your loadMacros() call. For example:

   loadMacros(
     "PGstandard.pl",
     "MathObjects.pl",
     "PGcourse.pl",
   );

Once this is done, there are several ways to create MathObjects in your problem:

• By calling a constructor function for the type of object you want (e.g., Real(3.5) or Complex("3+4i"))
• By calling Compute() to parse a string and return the resulting object (e.g., Compute("3+4i"))
• By calling a method of an existing MathObject that returns another object (e.g., Formula("sin(x)")->eval(x => pi/2))
• By combining existing MathObjects via mathematical operations (e.g., $x = Formula("x"); $f = $x**2 + 2*$x + 1)

Some examples:

   $a = Real(3.5);   or
   $a = Compute(3.5);   or
   $a = Compute("3.5");

   $b = Complex(3, 4);   or
   $b = Complex("3 + 4i");   or 
   $b = Compute("3 + 4i");

   $v = Vector(4,5,8);   or
   $v = Vector([4,5,8]);   or
   $v = Vector("<4,5,8>");  or
   $v = Compute("<4,5,8>");

   $f = Formula("sin(x^2) + 6");  or
   $f = Compute("sin(x^2) + 6");

Here, $a (defined any of the three ways) represents a real number and $b (defined by any of the three) represents a complex number; $v will be a vector, and $f is a formula.

In general, the Compute() variant is preferred because you enter what you want the student to type, and Compute() generates the proper MathObject to handle that (just as it will when it processes the student answer). Another important feature of Compute() is that the input string also serves as the correct answer when a student requests answers after the due date, which lets you put the correct answer in exactly the form you want it to appear. For example if you use

   Compute("<cos(pi/6),sin(pi/6), pi/6>")->cmp

the correct answer will be presented to the student as <cos(pi/6),sin(pi/6), pi/6>, while

   Vector("<cos(pi/6),sin(pi/6), pi/6>")->cmp

would show <0.866025,0.5,0.523599> as the correct answer.

In addition, Compute() can be used to compute the result of a formula at a given value of its inputs. For example,

   $a = Compute("x+3",x => 2);
   $a = Compute("x^2+y^2",x => 1, y => 2);

both are equivalent to $a = Real(5).

The MathObjects library defines classes for a variety of common mathematical concepts, including real numbers, complex numbers, intervals, points, vectors, matrices, and formulas. These are described in more detail in the MathObject Class documentation.

The pg/macros directory contains a number of extensions to MathObjects, including files that define specialized MathObject types. The ones that begin with parser typically define a new object class. For example, parserParametricLine.pl defines a constructor ParametricLine() for creating a special object that checks if a student's answer is a given parametric line or not, even if it is parameterized differently. These files usually contain documentation within them; see the POD pages for versions that you can read on line, and Specialized parsers for a list of most of the MathObject extensions.

Further Reading

• MathObject Class documentation
• Specialized parsers
• pg/macros -- files starting with parser define new MathObejcts

How to display a MathObject

MathObject can be inserted into the text of your problem just as any other variable can be. When this is done, the MathObject will insert its string version (as generated by its string() method). Frequently, however, you want to include the MathObject within a mathematical expression, and would prefer to use its [math]\rm\TeX[/math] form (as generated by its TeX() method). One way to do this is to call the TeX() method directly, as in

   $f = Formula("(x+1)/(x-1)");
   BEGIN_TEXT
     \[f(x) = \{$f->TeX\}\]
   END_TEXT

but this requires \{...\} and the explicit use of ->TeX to get the desired output. There is an easier way, however, that involves telling the Context to produce [math]\rm\TeX[/math] format rather than string format via the texStrings() method of the Context object.

   $f = Formula("(x+1)/(x-1)");
   Context()->texStrings;
   BEGIN_TEXT
     \[f(x) = $f\]
   END_TEXT
   Context()->normalStrings;

In this case, you just use $f within the text of the problem, which is easier to type and easier to read, especially if you have several MathObjects to insert. It is good practice to return the setting to normal using normalStrings(), as is done here, so that if you use MathObjects withing strings later on (e.g., $g = Compute("3*$f + 1")), you will not be inserting [math]\rm\TeX[/math] into those strings inadvertently.

MathObject Answer Checkers

Each MathObject type has a corresponding answer checker that can be used to process student responses. You obtain the checker by using the cmp() method of the MathObject.

   ANS($mathObject->cmp);

There is no need to select the right kind of answer checker, as the MathObject library handles that for you.

Many of the answer checkers include options that you can specify. For example, the tolerances to use, or the limits to use for the variables, or whether to provide certain kinds of hints to students as they enter incorrect answers. These are passed as name=>value to the cmp() method, separated by commas if there is more than one option to set, as in the following example:

   ANS(Real(sqrt(2))->cmp(tolerance => .0001));           # requires answer with roughly four decimal places.
   ANS(Formula("sqrt(x-10)")->cmp(limits => [10,12]));    # use x in the interval [10,12] so that the square root is defined.

See the Answer Checkers in MathObjects page for details about the MathObject Answer checkers, and the Answer Checker Options page for more on the options you can set for the different MathObject classes.

Further Reading

• Answer Checkers in MathObjects
• Answer Checker Options
• Custom Answer Checkers

MathObject Methods and Properties

Since MathObjects are Perl objects, you call a method on a MathObject as you would a method for any Perl object, using the -> operator with the MathObject on the left and the method name and its arguments (if any) on the right. E.g.,

   $mathObject->method;              # when there are no arguments
   $mathObject->method($arg);        # for one argument
   $mathObject->method($arg1,$arg2); # for two arguments
   # and so on

Similarly, you access the properties of an object just as you would for a Perl hash, via the -> operator with the MathObject on the left and the property name in braces on the right. E.g.,

   $mathObject->{property-name}

There are a number of methods and properties that are common to all MathObjects, which are described in the documentation for Common MathObject Methods and Common MathObject Properties. Some classes have additional methods and properties, and many of these are described in the MathObject Class documentation under the individual class links.

Further Reading

• Common MathObject Methods
• Common MathObject Properties
• MathObject Classes

Experimenting with MathObejcts

One way to experiment with MathObjects is to use the on-line PG labs to write example code and see what it produces. You can copy any of the examples above (or elsewhere in the WIki) and paste them into the lab to check the results. This makes it easy to test code without having to write complete problem files and save them in a course. One lab lets you get the output from a line of PG code, while another lets you try out full problems to see how they work.

See also

• Using Math Objects POD documentation

• MathObject Classes
• Common MathObject Methods
• Common MathObject Properties

• Answer Checkers
• Answer Checker Options
• Custom Answer Checkers
• Custom Answer Checkers for Lists

• Introduction to contexts
• Common Contexts
• Context flags
• Specialized contexts
• Modifying contexts (advanced)

• Specialized parsers