# Mexpr

Mexpr is a library supporting writing mathematical expressions and their evaluation.

Scientific applications sometimes need to enter some formulas and evaluate them or show them in a graph. The formula is not a part of the application but user usually wishes to enter own formula and evaluate it.

## ExpressionParser

### Simplest expression

Main class to use is `ExpressionParser` Example of use:

```ExpressionParser expressionParser = new ExpressionParser("100 * 10 + 25");
double result = expressionParser.evaluateDouble();
```

### Variables

More complex use may contain variables (which can be considered to be some constants):

#### Easy Variables

Passing a value into variable, like 'x':

```ExpressionParser expressionParser = new ExpressionParser("100 * x + 25", Map.of("x", 20));
double result = expressionParser.evaluateDouble();
```
Note: the number 20 in this case can't be changed so it's in fact a constant unless using settable instance like DoubleHolder

#### Settable Variables

Variables can be set without need to recompile expression which would be slow for scientific calculations, like using in equations or drawing a graph.

```DoubleHolder xHolder = new DoubleHolder(); // DoubleHolder is a Supplier<Double> with possibility to dynamically change the value
ExpressionParser expressionParser = new ExpressionParser("x + 1", Map.of("x", xHolder));
xHolder.accept(10);
expressionParser.evaluateDouble(); // 11
xHolder.accept(20);
expressionParser.evaluateDouble(); // 21
```

#### Typical Use Case

An exception should be expected for the parsing. Depending on exception the input should be changed:

```ExpressionParser expressionParser = null;
try {
expressionParser = new ExpressionParser("100 * x + 25");
} catch (ParseExpressionException e) {
if (e instanceof UndefinedVariableException) {
expressionParser = new ExpressionParser("100 * x + 25", Map.of(e.getVariableName(), 10)); // setting value for missing x variable
}
}
...
double result = expressionParser.evaluateDouble();
```

### Constants

Also constants like `pi` are supported:

```ExpressionParser expressionParser = new ExpressionParser("pi * r ^ 2", Map.of("r", 20));
double result = expressionParser.evaluateDouble();
```

### Functions

#### Expressed Functions

They can be made easily directly by user using a declaring and defining string present in the map.

```new ExpressionParser("sin(0.5) + quadr(11)", Map.of("quadr(x)", "11 * x ^ 2 + 21 * x + 31"));
```

Invalid example:

```new ExpressionParser("f(11)", Map.of("f(x)", "x + a"));
```
Variable from outside of function is valid:
```new ExpressionParser("f(11)", Map.of("f(x)", "x + a", "a", 20));
```
This is valid but argument variable wins:
```new ExpressionParser("f(10, 20)", Map.of("f(x, a)", "x + a",
"a", 40)); // 30
```

#### Java Functions

Functions can be made by a java class annotated with `@FunctionalSupplier`. All such classes with such annotation are ready to use in expression. There are some prepared basic math functions, like `sin`, `log`, ... Prepared functions are all functions found on classpath and their package starts with `cz.jmare.mexpr.func` but another custom functions with own package may be also added. Prepared functions can be disabled by `new Config().withPredefinedClasses(false);`, config is passed as an argument int ExpressionParser constructor.

List of available java functions:

```SupplierInfos supplierInfos = SuppliersClassesProvider.getSupplierInfosEmbedded(true);
System.out.println(supplierInfos.funcInfos);
```

Example of use:

```ExpressionParser expressionParser = new ExpressionParser("sin(2 *  pi)");
double result = expressionParser.evaluateDouble();
```

They can be used, for example, in graphs.

```DoubleHolder xHolder = new DoubleHolder();
ExpressionParser expressionParser = new ExpressionParser("sin(x * 2 * pi)", Map.of("x", xHolder));
for (double x = 0; x < 10; x += 0.01) {
xHolder.accept(x);
double y = expressionParser.evaluateDouble();
plot(x, y);
}
```

Note: We are creating a DoubleHolder instance which is a Supplier providing a value and it's also a Consumer to set the value. The expression needn't be compiled for each evaluation but rather we only set the value and get a new result.

##### Useful functions

I often use functions, like `sin`, `rand`. For example to generate a sine wave with standard deviation of 0.05 such formula may be used:

```sin(x * 2 * pi) + rand(-0.1, 0.1)
```

Or to generate one curve with two frequencies where `x = 1` is a border:

```sin(x * 2 * pi) * less(x, 1) + sin(x * 2 * pi * 2) * greater(x, 1)
```
This was an example of use discrete functions like less or greater. Inclusion (less or equals, greater or equals) of the second parameter can be enabled by third parameter with value 1, otherwise the second parameter means exclusion (less or greater). There is also the `between` function to define a range.

Also functions like `log` are often used. Note they can contain various number of parameters and some functions like `log` may contain one or two parameters. The second parameter is the base. For `base=10` the `log10` function can be also used as shortcut.

## Application configuration

Use following Maven configuration before start:

```<dependency>
<groupId>io.bitbucket.janmaren</groupId>
<artifactId>mexpr</artifactId>
<version>1.1</version>
</dependency>
```