com.singularsys.extensions.fastmatrix

## Class MrpEval

• All Implemented Interfaces:
JepComponent, ParserVisitor, java.io.Serializable

```public final class MrpEval
extends AbstractEval```
A fast evaluation algorithm for equations using Vectors and Matrix over the Doubles. This is based around reverse polish notation (hence the name M Rp Eval) and is optimised for speed at every opportunity.

To use do

``` Jep jep = new Jep();
MRpEval rpe = new MRpEval(j);
DimensionVisitor       dimV = new DimensionVisitor(jep);

Node node = jep.parse(...);
dimV.visit(node);
MRpCommandList list = rpe.compile(node);
MRpRes rpRes = rpe.evaluate(list);
System.out.println(rpRes.toString());
MatrixI mat = rpRes.toVecMat();
rpe.cleanUp();
```

The real use of this class is when an equation (or set of equations) need to be repeatedly evaluated with different values for the variables. MRpEval use an internal store for variable values different from those used in the main Jep classes. Changes in the Jep variable values, say by calling `Jep.setVarValue`, are reflected in changes in MRpEval variables, (the converse does not hold). A more efficient way is to use `int ref=getVarRef(var)` to return an index number of the variable and then calling `setVarVal(ref,value)` to set its value. For example

``` MRpCommandList list = rpe.compile(node);
int ref = rpe.getVarRef(j.getVar("x"));
for(double x=-1.;x<1.001;x+=0.1) {
rpe.setVarVal(ref,x);
rpe.evaluate(list);
}
```

Combining mrpe with Differentiation requires special techniques to cope with that fact that internal equations are used

The compile methods converts the expression represented by node into a string of commands. For example the expression "1+2*3" will be converted into the sequence of commands

``` Constant no 1 (pushes constant onto stack)
Constant no 2
Constant no 3
Multiply scalers (multiplies last two entries on stack)
```
The evaluate method executes these methods sequentially using a stack (actually a set of stacks) and returns the last object on the stack.

A few cautionary notes: the values returned by evaluate are references to internal variables, their values will change at the next call to compile or evaluate. Its very unlikely to be thread safe. It only works over doubles; expressions with complex numbers or strings will cause problems. It is tuned to work best for expressions involving scalers and 2, 3 and 4 dimensional vectors and matricies, larger vectors and matrices will be noticeably slower. The cleanUp function should be used when you no longer need the evaluator, this stops the evaluator listening to Variable through the java.util.Observer interface.

Implementation notes A lot of things have been done to make it as fast as possible:

• Everything is final which maximises the possibility for in-lining.
• All object creation happens during compile.
• All calculations done using double values.
• Vectors and Matrices are instances of VnObj and MatObj optimised for speed.
• The values of variables are kept on local arrays for fast access.

Scalers, Vectors and matrices used during evaluation are kept in three store classes. Each Store class contains a stack, a heap and a array of variable values. During evaluation objects are pushed and popped from the stack when a new object is needed it is taken from the heap.

Serialized Form

• ### Fields inherited from class com.singularsys.extensions.fastreal.AbstractEval

`customFunctionCommands, functionHash, jep, ls, opSet`
• ### Constructor Summary

Constructors
Constructor and Description
```MrpEval(Jep mjep, MatrixFactoryI mfac)```
Constructor using a supplied function table
• ### Method Summary

All Methods
Modifier and Type Method and Description
`MrpCommandList` `compile(Node node)`
Compile the expressions to produce a set of commands in reverse Polish notation.
`MrpCommandList` ```compile(Variable var, Node node)```
compile an expression of the type var = node.
`java.lang.Object` `convertResult(MrpRes res)`
Converts the results from the evaluate method into a more useful Double, VectorI or MatrixI type.
`MatrixI` `convertToMatrix(MrpRes res)`
Converts the results from the evaluate method into a MatrixI type.
`VectorI` `convertToVector(MrpRes res)`
Converts the results from the evaluate method into a VectorI type.
`MrpRes` `evaluate(MrpCommandList comList)`
Evaluate the expression.
`protected java.lang.Object` `getConstantValue(short ref)`
`Variable` `getVariable(MrpVarRef ref)`
Gets the Jep Variable associated with a particular reference
`MrpVarRef` `getVarRef(java.lang.String name)`
Finds the reference used for this variable.
`MrpVarRef` `getVarRef(Variable uVar)`
Finds the reference used for this variable.
`MrpRes` `getVarValue(MrpVarRef ref)`
Return the value of a variable.
`void` `reset()`
Clear all internal data.
`void` ```setVarValue(MrpVarRef varRef, double... vals)```
Sets the value of a scaler or vector variable
`void` ```setVarValue(MrpVarRef ref, double d)```
Sets the value of a variable
`void` ```setVarValue(MrpVarRef varRef, MatrixI val)```
Sets the value of a matrix variable
`void` ```setVarValue(MrpVarRef varRef, VectorI val)```
Sets the value of a vector variable
`java.lang.String` `toString()`
`java.lang.String` `toString(MrpCommandList.MrpCommand com)`
`void` `updateFromJepVariables()`
If the variables used by Jep have changed the values
`void` `updateToJepVariables()`
`java.lang.Object` ```visit(ASTConstant node, java.lang.Object data)```
`java.lang.Object` ```visit(ASTFunNode node, java.lang.Object data)```
`java.lang.Object` ```visit(ASTOpNode node, java.lang.Object data)```
`java.lang.Object` ```visit(ASTVarNode node, java.lang.Object data)```
`java.lang.Object` `visitAssign(ASTOpNode node)`
`java.lang.Object` `visitSetEle(ASTOpNode node)`
Givens a expression like ele(var,index) = value Produce sequence of commands ...
• ### Methods inherited from class com.singularsys.extensions.fastreal.AbstractEval

`getFunction, getLightWeightInstance, getUserFunction, init, staticGetFunction`
• ### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`
• ### Constructor Detail

• #### MrpEval

```public MrpEval(Jep mjep,
MatrixFactoryI mfac)```
Constructor using a supplied function table
Parameters:
`mjep` -
`mfac` -
• ### Method Detail

• #### compile

```public final MrpCommandList compile(Variable var,
Node node)
throws ParseException```
compile an expression of the type var = node.
Throws:
`ParseException`
• #### compile

```public final MrpCommandList compile(Node node)
throws ParseException```
Compile the expressions to produce a set of commands in reverse Polish notation.
Throws:
`ParseException`
• #### visit

```public final java.lang.Object visit(ASTConstant node,
java.lang.Object data)
throws ParseException```
Throws:
`ParseException`
• #### visit

```public final java.lang.Object visit(ASTVarNode node,
java.lang.Object data)
throws ParseException```
Throws:
`ParseException`
• #### visitAssign

```public java.lang.Object visitAssign(ASTOpNode node)
throws JepException,
ParseException```
Throws:
`JepException`
`ParseException`
• #### visitSetEle

```public java.lang.Object visitSetEle(ASTOpNode node)
throws JepException,
ParseException```
Givens a expression like ele(var,index) = value Produce sequence of commands
``` ...
value = pop()
index = pop()
addCommand(VAR,dimType,vRef);  // pops the var value
addCommand(SETELE,dimType,index) // sets top of stacks the index's element
```
Parameters:
`node` -
Returns:
Throws:
`JepException`
`ParseException`
• #### visit

```public final java.lang.Object visit(ASTOpNode node,
java.lang.Object data)
throws JepException```
Throws:
`JepException`
• #### visit

```public final java.lang.Object visit(ASTFunNode node,
java.lang.Object data)
throws JepException```
Throws:
`JepException`
• #### evaluate

`public final MrpRes evaluate(MrpCommandList comList)`
Evaluate the expression.
Returns:
the value after evaluation
• #### getConstantValue

`protected java.lang.Object getConstantValue(short ref)`
Specified by:
`getConstantValue` in class `AbstractEval`
• #### getVarRef

```public MrpVarRef getVarRef(Variable uVar)
throws ParseException```
Finds the reference used for this variable. The variable should have a known dimensions. This can be set either by using the `DimensionVisitor` by setting it to a explicit value or by setting the dimensions explicitly using `var.setHook(DimensionVisitor.DIM_KEY,Dimensions.ONE)`.
Parameters:
`uVar` - the variable
Returns:
an index used to refer to the variable
Throws:
`ParseException` - if the dimensions for the variable cannot be found.
• #### getVarRef

```public MrpVarRef getVarRef(java.lang.String name)
throws ParseException```
Finds the reference used for this variable.
Parameters:
`name` - variable name
Returns:
the reference
Throws:
`ParseException` - if the dimensions for the variable cannot be found.
• #### setVarValue

```public void setVarValue(MrpVarRef ref,
double d)
throws EvaluationException```
Sets the value of a variable
Parameters:
`ref` - reference to the variable
`d` - value
Throws:
`EvaluationException` - if the reference is not a scaler variable
• #### setVarValue

```public void setVarValue(MrpVarRef varRef,
double... vals)
throws EvaluationException```
Sets the value of a scaler or vector variable
Parameters:
`varRef` - reference to the variable
`vals` - either an array of doubles, or a set of values
Throws:
`EvaluationException`
• #### setVarValue

```public void setVarValue(MrpVarRef varRef,
VectorI val)
throws EvaluationException```
Sets the value of a vector variable
Parameters:
`varRef` - reference to the variable
`val` - vector value
Throws:
`EvaluationException` - if the dimensions do not match
• #### setVarValue

```public void setVarValue(MrpVarRef varRef,
MatrixI val)
throws EvaluationException```
Sets the value of a matrix variable
Parameters:
`varRef` - reference to the variable
`val` - a matrix vlaue
Throws:
`EvaluationException` - if the dimensions do not match
• #### getVarValue

`public MrpRes getVarValue(MrpVarRef ref)`
Return the value of a variable. It returns a subtype of `MrpRes` which can be converted using `convertResult(MrpRes)`.
Parameters:
`ref` - a reference to the variable
Returns:
the value of that variable or null if the reference is no longer current (happens when the dimensions of the variable changes)
• #### getVariable

```public Variable getVariable(MrpVarRef ref)
throws ParseException```
Gets the Jep Variable associated with a particular reference
Parameters:
`ref` - reference to variable
Returns:
the Jep Variable
Throws:
`ParseException`
• #### updateFromJepVariables

```public void updateFromJepVariables()
throws EvaluationException```
If the variables used by Jep have changed the values
Throws:
`EvaluationException`
• #### updateToJepVariables

```public void updateToJepVariables()
throws EvaluationException```
Throws:
`EvaluationException`
• #### convertResult

```public java.lang.Object convertResult(MrpRes res)
throws EvaluationException```
Converts the results from the evaluate method into a more useful Double, VectorI or MatrixI type.
Parameters:
`res` - the value returned by `evaluate(MrpCommandList)`
Returns:
a Double, VectorI or MatrixI type.
Throws:
`EvaluationException`
• #### convertToMatrix

```public MatrixI convertToMatrix(MrpRes res)
throws EvaluationException```
Converts the results from the evaluate method into a MatrixI type.
Parameters:
`res` - the value returned by `evaluate(MrpCommandList)`
Returns:
a MatrixI type, uses the MatrixFactory suppled to MatrixFunctionTable
Throws:
`EvaluationException` - if the res is a scalar or vector
• #### convertToVector

```public VectorI convertToVector(MrpRes res)
throws EvaluationException```
Converts the results from the evaluate method into a VectorI type.
Parameters:
`res` - the value returned by `evaluate(MrpCommandList)`
Returns:
a VectorI type,
Throws:
`EvaluationException` - if the res is a scalar or matrix
• #### reset

`public void reset()`
Clear all internal data.
• #### toString

`public java.lang.String toString()`
Overrides:
`toString` in class `java.lang.Object`
• #### toString

`public java.lang.String toString(MrpCommandList.MrpCommand com)`