Equation editor - Part 2¶

We have looked at the basics of the equation editor in a previous issue, so now it is the time to look a bit deeper. In this section we will see how we can get the most out of our equations to get the most functional calculators possible.

Ensuring multi-directional solutions: Systems of equations¶

If you have enough experience creating complicated calculators, you might have noticed that not all variables get computed as you would expect. This is due to a limitation in the interconnection between different equations in the editor. In fact, equations cannot be combined to calculate the value of a variable that couldn’t be computed with one unique equation.

Our engine cannot do symbolic calculations, so a variable will get a value if, and only if, it is the only unknown in the equation. Let’s take a look at a practical example using the recently updated “Schwarzschild radius calculator”.

The equations in this calculator can be reduced to:

R = k * M
g = k’ * M / R^2

where k and k’ are fixed constants. From this simplification one can easily see that either R, M, or g alone are to obtain the other two values. However, implemented like this, if the user inputs g nothing else gets computed. The engine put R in terms of a placeholder M to solve the equations.

To fix an issue like this, we simply need to re-write the equations so that, for any input, there will always be at least one equation with only one unknown. Here is an example:

R = k * M
g = k’ * M / (k*M)^2

Now, when the user inputs g there is only one unknown in the second equation, so M can be computed, which allows R to be computed as well. The same thing happens for any other input, just in different order.

[Trick/Hack] Defining two-way custom function¶

As great as defining our own functions is, doing that limits the usability of our calculator. This is because custom functions make variables “output-only” which… sub-optimal. There are workarounds that use value selects and selectively hiding/showing variables can restore some of that functionality, but we all wish there was a better way.

And there is! …kind of. There is one special function called erf that keeps the input-output behaviour of variables. To do this, it has an inverse function erfinv that allows the engine to calculate the input from the output and the output from the input as required.

Warning

The erf and erfinv functions should not be used as the standard way to define a custom function to get two-way calculations. The use desribe here is not the intended one and this should, therefore, be considered only a hack/trick to get out of a sticky situation.

However, it too has some limitations, so let’s see a list of important things to know about this pair:

Definition: a = erf(b) where a and b are variables.
[Optional] Defining the inverse function b = erfinv(a) for the same a and b as above.
When implementing erf and erfinv using omni.define make sure that erf(erfinv(a)) == a.
Names MUST BE only erf and erfinv other names will not enable “two-way” calculations.
Both erf and erfinv must have one and only one input.
Like other omni.define functions the return type must be a number or a decimaljs object.

Let’s look at a very simple example, where we can convert the pow function into a “two-way” function as long as we fix the exponent. We will take the simplest root of defining only one equation:

result = erf(base)

Our cJS code will look like this (fixed exponent being 3.4):

omni.define('erf', function(base) {
  return mathjs.pow (base.toNumber(), 3.4);
});

omni.define('erfinv', function(base) {
  return mathjs.pow (base.toNumber(), 1/3.4);
});

We need to define erfinv in cJS even if we haven’t explicitly done so in the equations tab. If we fail to define erfinv in cJS all variables will be shown as “input-output” but calculations will only work in one way.