# mathExpr

The`mathExpr`

library provides classes to parse and evaluate
mathematical expressions.
You can use this library whenever the following problem has to be solved: The input is a mathematical expression. The next step of processing uses the evaluation result of that expression. In other words: This library provides a front end between a certain input and further processing. For example, it can be used to convert editor inputs - representing mathematical expressions in any case - into constant values. See the tutorial for more detail and examples.

__Concept__

The most important fact is that parser and evaluator are strictly separated and independent from each other. Thus the highest possible performance is achieved if the same expression is evaluated repeatedly (e.g. a function which arguments are changing).

A mathematical expression is parsed unique with an arbitrary overhead. A successful parsing result an expression-tree-hierarchy which has to be maped on an evaluator-tree-hierarchy. So the expression is kept in a tree-structure which can be executed recursively again and again without parsing anymore. Further more any evaluation executes with very low overhead because all objects were already created during the parsing and mapping. That's why even a lot of reiterations of evaluation are relatively performant.

Beside the win of performance the independence between parser and evaluator is also important to evaluate in different contexts (e.g. real or complex). Example: If you decide to evaluate in a complex context, the symbol "i" is defined as the square root of -1. But if you want to evaluate in a real context, "i" is just another variable. The evaluator has to decide how to deal with "i" but for the parser "i" is just a symbol which meaning is not known.

__The Parser__

One of the component of the mathExpr library is a parser which is able to analyse Strings representing mathematical expressions and building up an expression-tree.

#### What's implemented till now?

The parser is able to create sub-expressions for all possible- binary operations (+, -, *, /, ^),
- unary operations (+, -),
- function calls ("f(2)") and
- symbols (constants or variables).

- brackets and
- implicit multiplication

-(3+4)^(2x)Parsing

- lists

{1,2,3}A parameter list of a function call is not need to be enveloped by curly brackets. Example:

f(3,4)The example shows a function call with two constant arguments (3 and 4).

**Attention:**Because the exception-handling is not fully developed yet, be careful with your expression-Strings. Wrong syntax can cause misleading exceptions or even a process hang-up.

#### What will be implemented in future releases?

- scientific notation will be supported ("3,45e-10")

__Expression Conversion__

The mathExpr library also provides to convert successfully parsed expressions. Possible kinds of conversion are

- simplify an Expression
- differentiate an Expression

__The Evaluator__

Another library component is the evaluator. It provides evaluation of an expression in different contexts.

#### What's implemented till now?

It's possible to evaluate an expression in a- Real or a
- Complex

//pseudo-code:The user decides in what kind of context (evaluationType) the evaluation takes place. See Tutorial - Context for more detail.

expression=3+4i

evaluationType=complex

//mapping from expression-tree-hierarchy

//to evaluator-tree-hierarchy

evaluator=expression.getEvaluator()

result=evaluator.evaluate

It's also possible to evaluate lists representing vectors but not matrices yet.

#### What will be implemented in future releases?

- matrice evaluation will be supported
- Quaternions will be implemented as a new value-type and an alternative evaluation context

__Rough Functionality__ *Tutorial content*

An expression comes as a simple `String`

by the user.
That `String`

must be parsed by a `Parser`

to create
an `Expression`

object representing the
expression-tree-hierarchy. Example:

String s="1+2*3";To evaluate that

Parser p=new Parser(new StringReader(s), ...);

Expression expr=p.parse();

`Expression`

an evaluator-tree-hierarchy must be
created. That's why the abstract class `Expression`

provides
the method `getEvaluator()`

. It returns an `Evaluator`

object representing the evaluator-tree-hierarchy.Evaluator eval=expr.getEvaluator(RealType.TYPE, ...);If you call the getEvaluator() method, every sub-expression of the tree will be mapped to a sub-evaluator. The evaluation itself will be started by calling the method evaluate() on the Evaluator. It works recursively.

The first step (parsing and getEvaluator()) has a big overhead. All neccessary objects will be created. The second step (evaluate()) works very fast without creating any object. That's very important if you want to parse once and evaluate the same expression again and again with different variable values.

__Usage__

To get the easiest introduction into practicing with the `mathExpr`

library you should read the tutorial.
Further more the tutorial contains a simple description how the
`mathExpr`

components are working (incl. UML-diagrams)
and some examples.

It's **recommended** to start reading the api documentation of `mathExpr`

with the
documentation of the class ** de.jtem.mathExpr.ExpressionConfiguration**.