org.lsmp.djep.mrpe

Class MRpEval

java.lang.Object

org.lsmp.djep.mrpe.MRpEval

All Implemented Interfaces:

ParserVisitor

public final class MRpEval
extends Object
implements ParserVisitor

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

 MatrixJep j = ...;
 Node node = ...; 
 MRpEval rpe = new MRpEval(j);
 MRpCommandList list = rpe.compile(node);
 MRpRes rpRes = rpe.evaluate(list);
 System.out.println(rpRes.toString());
 MatrixValueI 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 differentation 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)
 Add scalers (adds 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 VecObj and MatObj optimised for speed. For instance a 2 by 2 matrix is an instance of Mat22Obj whose elements are represented by the fields a,b,c,d. This eliminates bound checking on arrays.
• Each possible vector and matrix operation has been hand coded, and there are a lot of methods (27 just for matrix multiplication!).
• The values of variables are kept on local arrays for fast access. These values are kept in sync with the main Jep Variables by using the java.util.Observer interface.

For each type of vector or matrix (i.e. 2D vecs, 3D vecs, 4D vecs, 2 by 2 matrices ... 4 by 4 matrices. there is a corresponding class V2Obj, M22Obj etc. which stores the values and another class V2Store, M22Store etc. 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. The operation is illustrated by the add method for 2 by 2 matrices.

 private final class M22Store
 {
  ....
  final void add(){
   M22Obj r = stack[--sp]; // pop from stack
   M22Obj l = stack[--sp]; // pop from stack
         M22Obj res = heap[hp++]; // result is next entry in heap
         res.a = l.a+r.a;       // add each componant
         res.b = l.b+r.b;
         res.c = l.c+r.c;
         res.d = l.d+r.d;
         stack[sp++]=res;       // push result onto stack
  }
 }
 

Constructor Summary

Constructors

Constructor and Description
MRpEval(MatrixJep mjep)

Method Summary

Modifier and Type	Method and Description
void	cleanUp() Removes observers and other cleanup needed when evaluator no longer used.
MRpCommandList	compile(MatrixVariableI var, Node node) compile an expression of the type var = node.
MRpCommandList	compile(Node node) Compile the expressions to produce a set of commands in reverse Polish notation.
MRpRes	evaluate(MRpCommandList comList) Evaluate the expression.
int	getVarRef(MatrixVariableI var) Finds the reference number used for this variable.
int	getVarRef(Variable var) Finds the reference number used for this variable.
void	setVarValue(int ref, double val) Sets value of rpe variable.
void	setVarValue(int ref, MatrixValueI val) Sets value of rpe variable.
Object	visit(ASTConstant node, Object data)
Object	visit(ASTFunNode node, Object data)
Object	visit(ASTStart node, Object data)
Object	visit(ASTVarNode node, Object data)
Object	visit(SimpleNode node, Object data)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MRpEval

public MRpEval(MatrixJep mjep)

Method Detail

compile

public final MRpCommandList compile(MatrixVariableI 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

getVarRef

public int getVarRef(Variable var)
              throws ParseException

Finds the reference number used for this variable.

Parameters:

var -

Returns:

an index used to refer to the variable

Throws:

ParseException

getVarRef

public int getVarRef(MatrixVariableI var)
              throws ParseException

Finds the reference number used for this variable.

Parameters:

var -

Returns:

an index used to refer to the variable

Throws:

ParseException

setVarValue

public final void setVarValue(int ref,
                              MatrixValueI val)
                       throws ParseException

Sets value of rpe variable.

Parameters:

ref - the reference number for the variable (found using getVarRef(org.lsmp.djep.matrixJep.MatrixVariableI))

val -

Throws:

ParseException

setVarValue

public final void setVarValue(int ref,
                              double val)

Sets value of rpe variable. Only applies to scaler (double variables).

Parameters:

ref - the reference number for the variable (found using getVarRef(org.lsmp.djep.matrixJep.MatrixVariableI))

val - the value

visit

public final Object visit(ASTStart node,
                          Object data)
                   throws ParseException

Specified by:

visit in interface ParserVisitor

Throws:

ParseException

visit

public final Object visit(SimpleNode node,
                          Object data)
                   throws ParseException

Specified by:

visit in interface ParserVisitor

Throws:

ParseException

visit

public final Object visit(ASTConstant node,
                          Object data)
                   throws ParseException

Specified by:

visit in interface ParserVisitor

Throws:

ParseException

visit

public final Object visit(ASTVarNode node,
                          Object data)
                   throws ParseException

Specified by:

visit in interface ParserVisitor

Throws:

ParseException

visit

public final Object visit(ASTFunNode node,
                          Object data)
                   throws ParseException

Specified by:

visit in interface ParserVisitor

Throws:

ParseException

evaluate

public final MRpRes evaluate(MRpCommandList comList)

Evaluate the expression.

Returns:

the value after evaluation

cleanUp

public void cleanUp()

Removes observers and other cleanup needed when evaluator no longer used.