parserImplicitEquation.pl  An answer checker for implicit equations.
From WeBWorK
NAME
parserImplicitEquation.pl  An answer checker for implicit equations.
DESCRIPTION
This is a MathObject class that implements an answer checker for implicitly defined equations. The checker looks for the zeros of the equation and tests that the student and professor equations both have the same solutions.
This type of check is very subtle, and there are important issues that you may have to take into account. The solutions to the equations are found numerically, and so they will not be exact; that means that there are tolerances that may need to be adjusted for your particular equation. Also, it is always possible for the student to represent the function in a form that will exceed those tolerances, and so be marked as incorrect. The answer checker attempts to set the parameters based on the values of the functions involved, but this may not work perfectly.
The method used to locate the solutions of A=B is by finding zeros of AB, and it requires this function to take on both positive and negative values (that is, it can only find transverse intersections of the surface AB=0 and the plane at height 0). For example, even though the solutions of (x^2+y^11)^2=0 form a circle, the algorithm will fail to find any solutions for this equation.
In order to locate the zeros, you may need to change the limits so that they include regions where the function is both positive and negative (see below). The algorithm will avoid discontinuities, so you can specify things like xy=1/(x+y) rather than x^2y^2=1.
Because the solutions are found using a random search, it is possible the randomly chosen starting points don't locate enough zeros for the function, in which case the check will fail. This can happen for both the professor's function and the student's, since zeros are found for both. This means that a correct answer can sometimes be marked incorrect depending on the random points chosen initially. These points also affect the values selected for the tolerances used to determine when a function's value is zero, and so can affect whether the student's function is marked as correct or not.
If an equation has several components or branches, it is possible that the random location of solutions will not find zeros on some of the branches, and so might incorrectly mark as correct an equation that only is zero on one of the components. For example, x^2y^2=0 has solutions along the lines y=x and y=x, so it is possible that xy=0 or x+y=0 will be marked as correct if the random points are unluckily chosen. One way to reduce this problem is to increase the number of solutions that are required (by setting the ImplicitPoints flag in the Context). Another is to specify the solutions yourself, so that you are sure there are points on each component.
These problems should be rare, and the values for the various parameters have been set in an attempt to minimize the possibility of these errors, but they can occur, and you should be aware of them, and their possible solutions.
Usage examples:
Context("ImplicitEquation"); $f = ImplicitEquation("x^2 = cos(y)"); $f = ImplicitEquation("x^2  2y^2 = 5",limits=>[[3,3],[2,2]]); $f = ImplicitEquation("x=1/y",tolerance=>.0001);
Then use
ANS($f>cmp);
to get the answer checker for $f.
There are a number of Context flags that control the answer checker. These include:
ImplicitPoints => 7

the number of solutions to test.
ImplicitTolerance => 1E6

relative tolerance value for when the tested function is zero.
ImplicitAbsoluteMinTolerance => 1E3

the minimum tolerance allowed.
ImplicitAbsoluteMaxTolerance => 1

the maximum tolerance allowed.
ImplicitPointTolerance => 1E9

relative tolerance for how close the solution point must be to an actual solution.
BisectionTolerance => .01

extra factor used for the tolerance when finding the solutions.
BisectionCutoff => 40

maximum number of bisections to perform when looking for a solution.
You may set any of these using Context()>flags>set(...).
In addition to the Context flags, you can set some values within the ImplicitEquation itself:
tolerance

the absolute tolerance for zeros of the function.
bisect_tolerance

the tolerance used when searching for zeros.
point_tolerance

the absolute tolerance for how close to an actual solution the located solution must be.
limits

the domain to use for the function; see the documentation for the Formula object.
solutions

a reference to an array of references to arrays that contain the coordinates of the points that are the solutions of the equation.
These can be set in the in the ImplicitEquation()
call that creates
the object, as in the examples below:
For example:
$f = ImplicitEquation("x^2y^2=0", solutions => [[0,0],[1,1],[1,1],[1,1],[1,1]], tolerance => .001 );
$f = ImplicitEquation("xy=5",limits=>[3,3]);
The limits value can be set globally within the Context, if you wish, and the others can be controlled by the Context flags discussed above.