Equation (equation 0.28 API)

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.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class Equation.TokenType

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`Equation.TokenType`

Constructor Summary

Constructors
Constructor and Description

Equation()

Constructors
Constructor and Description
`Equation()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`alias(org.ejml.data.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(org.ejml.simple.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
`protected org.ejml.equation.TokenList.Token`	`createFunction(org.ejml.equation.TokenList.Token name, java.util.List<org.ejml.equation.TokenList.Token> inputs, org.ejml.equation.TokenList tokens, Sequence sequence)` Adds a new operation to the list from the operation and two variables.
`protected org.ejml.equation.TokenList.Token`	`createOp(org.ejml.equation.TokenList.Token left, org.ejml.equation.TokenList.Token op, org.ejml.equation.TokenList.Token right, org.ejml.equation.TokenList tokens, Sequence sequence)` Adds a new operation to the list from the operation and two variables.
`protected org.ejml.equation.TokenList`	`extractTokens(java.lang.String equation, ManagerTempVariables managerTemp)` Parses the text string to extract tokens.
`ManagerFunctions`	`getFunctions()` Returns the functions manager
`protected void`	`handleParentheses(org.ejml.equation.TokenList tokens, Sequence sequence)` Searches for pairs of parentheses and processes blocks inside of them.
`protected org.ejml.equation.TokenList.Token`	`insertTranspose(org.ejml.equation.TokenList.Token variable, org.ejml.equation.TokenList tokens, Sequence sequence)` Adds a new operation to the list from the operation and two variables.
`protected static boolean`	`isLetter(char c)` Returns true if the character is a valid letter for use in a variable name
`protected static boolean`	`isOperatorLR(Symbol s)` Operators which affect the variables to its left and right
`protected boolean`	`isReserved(java.lang.String name)` Returns true if the specified name is NOT allowed.
`protected static boolean`	`isSymbol(char c)`
`protected static boolean`	`isTargetOp(org.ejml.equation.TokenList.Token token, Symbol[] ops)` Checks to see if the token is in the list of allowed character operations.
`double`	`lookupDouble(java.lang.String token)`
`int`	`lookupInteger(java.lang.String token)`
`org.ejml.data.DenseMatrix64F`	`lookupMatrix(java.lang.String token)`
`<T extends Variable> T`	`lookupVariable(java.lang.String token)` Looks up a variable given its name.
`protected org.ejml.equation.TokenList.Token`	`parseBlockNoParentheses(org.ejml.equation.TokenList tokens, Sequence sequence)` Parses a code block with no parentheses and no commas.
`protected void`	`parseBracketCreateMatrix(org.ejml.equation.TokenList tokens, Sequence sequence)` Searches for brackets which are only used to construct new matrices by concatenating 1 or more matrices together
`protected void`	`parseNegOp(org.ejml.equation.TokenList tokens, Sequence sequence)` Searches for cases where a minus sign means negative operator.
`protected void`	`parseOperationsL(org.ejml.equation.TokenList tokens, Sequence sequence)` Parses operations where the input comes from variables to its left only.
`protected void`	`parseOperationsLR(Symbol[] ops, org.ejml.equation.TokenList tokens, Sequence sequence)` Parses operations where the input comes from variables to its left and right
`protected java.util.List<org.ejml.equation.TokenList.Token>`	`parseParameterCommaBlock(org.ejml.equation.TokenList tokens, Sequence sequence)` Searches for commas in the set of tokens.
`protected org.ejml.equation.TokenList.Token`	`parseSubmatrixToExtract(org.ejml.equation.TokenList.Token variableTarget, org.ejml.equation.TokenList tokens, Sequence sequence)` Converts a submatrix into an extract matrix operation.
`protected void`	`parseValueRange(org.ejml.equation.TokenList tokens, Sequence sequence, java.util.List<Variable> variables)` Parse a range written like 0:10 in which two numbers are separated by a colon.
`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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- Equation
```
public Equation()
```

Method Detail

alias
```
public void alias(org.ejml.data.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(org.ejml.simple.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

handleParentheses
```
protected void handleParentheses(org.ejml.equation.TokenList tokens,
                                 Sequence sequence)
```
Searches for pairs of parentheses and processes blocks inside of them. Embedded parentheses are handled with no problem. On output only a single token should be in tokens.

Parameters:

tokens - List of parsed tokens

sequence - Sequence of operators

parseParameterCommaBlock

protected java.util.List<org.ejml.equation.TokenList.Token> parseParameterCommaBlock(org.ejml.equation.TokenList tokens,
                                                                                     Sequence sequence)

Searches for commas in the set of tokens. Used for inputs to functions

Returns:: List of output tokens between the commas

parseSubmatrixToExtract

protected org.ejml.equation.TokenList.Token parseSubmatrixToExtract(org.ejml.equation.TokenList.Token variableTarget,
                                                                    org.ejml.equation.TokenList tokens,
                                                                    Sequence sequence)

Converts a submatrix into an extract matrix operation.

Parameters:: variableTarget - The variable in which the submatrix is extracted from

parseValueRange

protected void parseValueRange(org.ejml.equation.TokenList tokens,
                               Sequence sequence,
                               java.util.List<Variable> variables)

Parse a range written like 0:10 in which two numbers are separated by a colon.

parseBlockNoParentheses

protected org.ejml.equation.TokenList.Token parseBlockNoParentheses(org.ejml.equation.TokenList tokens,
                                                                    Sequence sequence)

Parses a code block with no parentheses and no commas. After it is done there should be a single token left, which is returned.

parseBracketCreateMatrix

protected void parseBracketCreateMatrix(org.ejml.equation.TokenList tokens,
                                        Sequence sequence)

Searches for brackets which are only used to construct new matrices by concatenating 1 or more matrices together

parseNegOp
```
protected void parseNegOp(org.ejml.equation.TokenList tokens,
                          Sequence sequence)
```
Searches for cases where a minus sign means negative operator. That happens when there is a minus sign with a variable to its right and no variable to its left

parseOperationsL
```
protected void parseOperationsL(org.ejml.equation.TokenList tokens,
                                Sequence sequence)
```
Parses operations where the input comes from variables to its left only. Hard coded to only look for transpose for now

Parameters:

tokens - List of all the tokens

sequence - List of operation sequence

parseOperationsLR
```
protected void parseOperationsLR(Symbol[] ops,
                                 org.ejml.equation.TokenList tokens,
                                 Sequence sequence)
```
Parses operations where the input comes from variables to its left and right

Parameters:

ops - List of operations which should be parsed

tokens - List of all the tokens

sequence - List of operation sequence

insertTranspose

protected org.ejml.equation.TokenList.Token insertTranspose(org.ejml.equation.TokenList.Token variable,
                                                            org.ejml.equation.TokenList tokens,
                                                            Sequence sequence)

Adds a new operation to the list from the operation and two variables. The inputs are removed from the token list and replaced by their output.

createOp

protected org.ejml.equation.TokenList.Token createOp(org.ejml.equation.TokenList.Token left,
                                                     org.ejml.equation.TokenList.Token op,
                                                     org.ejml.equation.TokenList.Token right,
                                                     org.ejml.equation.TokenList tokens,
                                                     Sequence sequence)

Adds a new operation to the list from the operation and two variables. The inputs are removed from the token list and replaced by their output.

createFunction

protected org.ejml.equation.TokenList.Token createFunction(org.ejml.equation.TokenList.Token name,
                                                           java.util.List<org.ejml.equation.TokenList.Token> inputs,
                                                           org.ejml.equation.TokenList tokens,
                                                           Sequence sequence)

Adds a new operation to the list from the operation and two variables. The inputs are removed from the token list and replaced by their output.

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 org.ejml.data.DenseMatrix64F lookupMatrix(java.lang.String token)

lookupInteger

public int lookupInteger(java.lang.String token)

lookupDouble

public double lookupDouble(java.lang.String token)

extractTokens

protected org.ejml.equation.TokenList extractTokens(java.lang.String equation,
                                                    ManagerTempVariables managerTemp)

Parses the text string to extract tokens.

isTargetOp
```
protected static boolean isTargetOp(org.ejml.equation.TokenList.Token token,
                                    Symbol[] ops)
```
Checks to see if the token is in the list of allowed character operations. Used to apply order of operations

Parameters:

token - Token being checked

ops - List of allowed character operations

Returns:

true for it being in the list and false for it not being in the list

isSymbol

protected static boolean isSymbol(char c)

isOperatorLR
```
protected static boolean isOperatorLR(Symbol s)
```
Operators which affect the variables to its left and right

isLetter
```
protected static boolean isLetter(char c)
```
Returns true if the character is a valid letter for use in a variable name

isReserved
```
protected boolean isReserved(java.lang.String name)
```
Returns true if the specified name is NOT allowed. It isn't allowed if it matches a built in operator or if it contains a restricted character.

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

Class Equation

Built in Constants

Supported functions

Supported operations

Specialized submatrix and matrix construction syntax

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Equation

Method Detail

alias

alias

alias

alias

alias

compile

compile

handleParentheses

parseParameterCommaBlock

parseSubmatrixToExtract

parseValueRange

parseBlockNoParentheses

parseBracketCreateMatrix

parseNegOp

parseOperationsL

parseOperationsLR

insertTranspose

createOp

createFunction

lookupVariable

lookupMatrix

lookupInteger

lookupDouble

extractTokens

isTargetOp

isSymbol

isOperatorLR

isLetter

isReserved

process

process

getFunctions