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 Using is also possible. A simple example:
  -(3+4)^(2x)
Parsing is possible, too. A sub-string represents a list if the list entries are separated by commas and the whole list is enveloped by curly brackets, for example:
  {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?

Expression Conversion

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

To simplify an Expression doesn't include evaluation of constant sub-expressions or cancel down operation. See Tutorial - 1.6. Expression Conversions for details.

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 context. For example:
  //pseudo-code:
  expression=3+4i
  evaluationType=complex
  //mapping from expression-tree-hierarchy
  //to evaluator-tree-hierarchy
  evaluator=expression.getEvaluator()
  result=evaluator.evaluate
The user decides in what kind of context (evaluationType) the evaluation takes place. See Tutorial - Context for more detail.

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

What will be implemented in future releases?

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";
  Parser p=new Parser(new StringReader(s), ...);
  Expression expr=p.parse();
To evaluate that 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.