Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.lsmp.djep.mrpe
Class MRpEval

    java.lang.Object
      org.lsmp.djep.mrpe.MRpEval

All Implemented Interfaces:
  ParserVisitor

    public final class MRpEval

extends java.lang.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
      }
     }

Author:
  Rich Morris Created on 14-Apr-2004

Constructor Summary
`MRpEval(MatrixJep mjep)`

Method Summary
`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.
`java.lang.Object` | `visit(ASTConstant node, java.lang.Object data)`
`java.lang.Object` | `visit(ASTFunNode node, java.lang.Object data)`
`java.lang.Object` | `visit(ASTStart node, java.lang.Object data)`
`java.lang.Object` | `visit(ASTVarNode node, java.lang.Object data)`
`java.lang.Object` | `visit(SimpleNode node, java.lang.Object data)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, 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 java.lang.Object visit(ASTStart node,
                                        java.lang.Object data)
                                 throws ParseException

  Specified by:
    `visit` in interface `ParserVisitor`
  Throws:
    `ParseException`

### visit

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

  Specified by:
    `visit` in interface `ParserVisitor`
  Throws:
    `ParseException`

### visit

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

  Specified by:
    `visit` in interface `ParserVisitor`
  Throws:
    `ParseException`

### visit

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

  Specified by:
    `visit` in interface `ParserVisitor`
  Throws:
    `ParseException`

### visit

    public final java.lang.Object visit(ASTFunNode node,
                                        java.lang.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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

http://www.singularsys.com/jep Copyright © 2007 Singular Systems