org.ejml.equation

Class Equation

java.lang.Object

org.ejml.equation.Equation

public class Equation
extends java.lang.Object

Equation allows the user to manipulate matrices in a more compact symbolic way, similar to Matlab and Octave. Aliases are made to Matrices and scalar values which can then be manipulated by specifying an equation in a string. These equations can either be "pre-compiled" [1] into a sequence of operations or immediately executed. While the former is more verbose, when dealing with small matrices it significantly faster and runs close to the speed of normal hand written code.

Each string represents a single line and must have one and only one assignment '=' operator. Temporary variables are handled transparently to the user. Temporary variables are declared at compile time, but resized at runtime. If the inputs are not resized and the code is precompiled, then no new memory will be declared. When a matrix is assigned the results of an operation it is resized so that it can store the results.

The compiler currently produces simplistic code. For example, if it encounters the following equation "a = b*c' it will not invoke multTransB(b,c,a), but will explicitly transpose c and then call mult(). In the future it will recognize such short cuts.

Usage example:

 Equation eq = new Equation();
 eq.alias(x,"x", P,"P", Q,"Q");

 eq.process("x = F*x");
 eq.process("P = F*P*F' + Q");
 

Which will modify the matrices 'x' amd 'P'. Sub-matrices and inline matrix construction is also supported.

 eq.process("x = [2 1 0; 0 1 3;4 5 6]*x");
 eq.process("x(1:3,5:9) = [a ; b]*2");
 

To pre-compile one of the above lines, do the following instead:

 Sequence predictX = eq.compile("x = F*x");
 predictX.perform();
 

Then you can invoke it as much as you want without the "expensive" compilation step. If you are dealing with larger matrices (e.g. 100 by 100) then it is likely that the compilation step has an insignificant runtime cost.

Variables can also be lazily declared and their type inferred under certain conditions. For example:

 eq.alias(A,"A", B,"B");
 eq.process("C = A*B");
 DenseMatrix64F C = eq.lookupMatrix("C");
 

In this case 'C' was lazily declared. To access the variable, or any others, you can use one of the lookup*() functions.

Sometimes you don't get the results you expect and it can be helpful to print out the tokens and which operations the compiler selected. To do this set the second parameter to eq.compile() or eq.process() to true:

 Code:
 eq.process("C=2.1*B'*A",true);

 Output:
 Parsed tokens:
 ------------
 Word:C
 ASSIGN
 VarSCALAR
 TIMES
 VarMATRIX
 TRANSPOSE
 TIMES
 VarMATRIX

 Operations:
 ------------
 transpose-m
 multiply-ms
 multiply-mm
 copy-mm
 

Built in Constants

 pi = Math.PI
 e  = Math.E
 

Supported functions

 eye(N)       Create an identity matrix which is N by N.
 eye(A)       Create an identity matrix which is A.numRows by A.numCols
 normF(A)     Frobenius normal of the matrix.
 det(A)       Determinant of the matrix
 inv(A)       Inverse of a matrix
 pinv(A)      Pseudo-inverse of a matrix
 rref(A)      Reduced row echelon form of A
 trace(A)     Trace of the matrix
 zeros(r,c)   Matrix full of zeros with r rows and c columns.
 ones(r,c)    Matrix full of ones with r rows and c columns.
 diag(A)      If a vector then returns a square matrix with diagonal elements filled with vector
 diag(A)      If a matrix then it returns the diagonal elements as a column vector
 dot(A,B)     Returns the dot product of two vectors as a double.  Does not work on general matrices.
 solve(A,B)   Returns the solution X from A*X = B.
 kron(A,B)    Kronecker product
 abs(A)       Absolute value of A.
 max(A)       Element with the largest value in A.
 min(A)       Element with the smallest value in A.
 pow(a,b)     Computes a to the power of b.  Can also be invoked with "a^b" scalars only.
 sqrt(a)      Computes the square root of a.
 sin(a)       Math.sin(a) for scalars only
 cos(a)       Math.cos(a) for scalars only
 atan(a)      Math.atan(a) for scalars only
 atan2(a,b)   Math.atan2(a,b) for scalars only
 exp(a)       Math.exp(a) for scalars and element-wise matrices
 log(a)       Math.log(a) for scalars and element-wise matrices
 

Supported operations

 '*'        multiplication (Matrix-Matrix, Scalar-Matrix, Scalar-Scalar)
 '+'        addition (Matrix-Matrix, Scalar-Matrix, Scalar-Scalar)
 '-'        subtraction (Matrix-Matrix, Scalar-Matrix, Scalar-Scalar)
 '/'        divide (Matrix-Scalar, Scalar-Scalar)
 '/'        matrix solve "x=b/A" is equivalent to x=solve(A,b) (Matrix-Matrix)
 '^'        Scalar power.  a^b is a to the power of b.
 '\'        left-divide.  Same as divide but reversed.  e.g. x=A\b is x=solve(A,b)
 '.*'       element-wise multiplication (Matrix-Matrix)
 './'       element-wise division (Matrix-Matrix)
 '.^'       element-wise power. (scalar-scalar) (matrix-matrix) (scalar-matrix) (matrix-scalar)
 '''        matrix transpose
 '='        assignment by value (Matrix-Matrix, Scalar-Scalar)
 

Order of operations: [ ' ] precedes [ ^ .^ ] precedes [ * / .* ./ ] precedes [ + - ]

Specialized submatrix and matrix construction syntax

 Extracts a sub-matrix from A with rows 1 to 10 (inclusive) and column 3.
               A(1:10,3)
 Extracts a sub-matrix from A with rows 2 to numRows-1 (inclusive) and all the columns.
               A(2:,:)
 Will concat A and B along their columns and then concat the result with  C along their rows.
                [A,B;C]
 Defines a 3x2 matrix.
            [1 2; 3 4; 4 5]
 You can also perform operations inside:
            [[2 3 4]';[4 5 6]']
 Will assign B to the sub-matrix in A.
             A(1:3,4:8) = B
 

Footnotes:

 [1] It is not compiled into Java byte-code, but into a sequence of operations stored in a List.
 

Constructor Summary

Constructors

Constructor and Description
Equation()

Method Summary

Modifier and Type	Method and Description
void	alias(DenseMatrix64F variable, java.lang.String name) Adds a new Matrix variable.
void	alias(double value, java.lang.String name) Adds a new floating point variable.
void	alias(int value, java.lang.String name) Adds a new integer variable.
void	alias(java.lang.Object... args) Creates multiple aliases at once.
void	alias(SimpleMatrix variable, java.lang.String name)
Sequence	compile(java.lang.String equation)
Sequence	compile(java.lang.String equation, boolean debug) Parses the equation and compiles it into a sequence which can be executed later on
ManagerFunctions	getFunctions() Returns the functions manager
double	lookupDouble(java.lang.String token)
int	lookupInteger(java.lang.String token)
DenseMatrix64F	lookupMatrix(java.lang.String token)
<T extends Variable> T	lookupVariable(java.lang.String token) Looks up a variable given its name.
void	process(java.lang.String equation) Compiles and performs the provided equation.
void	process(java.lang.String equation, boolean debug) Compiles and performs the provided equation.

Methods inherited from class java.lang.Object

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

Constructor Detail

Equation

public Equation()

Method Detail

alias

public void alias(DenseMatrix64F variable,
                  java.lang.String name)

Adds a new Matrix variable. If one already has the same name it is written over. While more verbose for multiple variables, this function doesn't require new memory be declared each time it's called.

Parameters:

variable - Matrix which is to be assigned to name

name - The name of the variable

alias

public void alias(SimpleMatrix variable,
                  java.lang.String name)

alias

public void alias(double value,
                  java.lang.String name)

Adds a new floating point variable. If one already has the same name it is written over.

Parameters:

value - Value of the number

name - Name in code

alias

public void alias(int value,
                  java.lang.String name)

Adds a new integer variable. If one already has the same name it is written over.

Parameters:

value - Value of the number

name - Name in code

alias

public void alias(java.lang.Object... args)

Creates multiple aliases at once.

compile

public Sequence compile(java.lang.String equation)

compile

public Sequence compile(java.lang.String equation,
                        boolean debug)

Parses the equation and compiles it into a sequence which can be executed later on

Parameters:

equation - String in simple equation format.

debug - if true it will print out debugging information

Returns:

Sequence of operations on the variables

lookupVariable

public <T extends Variable> T lookupVariable(java.lang.String token)

Looks up a variable given its name. If none is found then return null.

lookupMatrix

public DenseMatrix64F lookupMatrix(java.lang.String token)

lookupInteger

public int lookupInteger(java.lang.String token)

lookupDouble

public double lookupDouble(java.lang.String token)

process

public void process(java.lang.String equation)

Compiles and performs the provided equation.

Parameters:

equation - String in simple equation format

process

public void process(java.lang.String equation,
                    boolean debug)

Compiles and performs the provided equation.

Parameters:

equation - String in simple equation format

getFunctions

public ManagerFunctions getFunctions()

Returns the functions manager