Contrib/equationReader

1 What is it?

equationReader is an extension to OpenFOAM that allows you to read equations from a dictionary file, and have them evaluated at every timestep. It works for scalars and dimensionedScalars. For example:

nu          nu [0 2 -1 0 0 0 0] "1.2 + 3 * alpha^sin(pi_/6)";
aScalar     "nu / max(5, alpha)";
alpha       1.3;

2 Features

• Order of operations - it is fully compliant with the conventional order of operations to an arbitrary parenthesis depth;
• Flexible data sources - equations can use data from any dictionary, scalar, or dimensionedScalar;
• Equation dependency tracking - equations can depend on one another to an arbitrary hierarchy depth;
• Circular-reference detection - it will halt computations when a circular reference is detected;
• On-the-fly equation mapping - it will automatically perform substitution on other equations when they are needed, even if they aren't specifically called for in the solver;
• Dimension-checking - fully utilizes OpenFOAM's built-in dimension-checking, or you can force the outcome to a specific dimension-set to quickly disable it (if you are lazy);
• three modes of operation - you can choose from three different modes of operation to suit your needs:

1. stand-alone - this one works "out of the box" with all OpenFOAM applications. You can only use literal constants in your equations;
2. passive mode - if you create an equationReader object, you can give it data sources. This allows you to use variables, and equation substitution; and
3. active mode - if you also give equationReader pointers to your output variables, it can automatically update the values at every timestep.

3 How do you use it?

3.1 Syntax

The general syntax is:

3.1.1 scalar or regular equation

An equation using this format determines has dimension-checking enabled (unless you turn off set dimensionSet::debug).

keyword    "equation";

e.g.:

endTime    "2*pi_/360*60";

3.1.2 dimensionedScalar or dimensioned equation

If you specify dimensions, it will disable the dimension-checking and force the outcome to the given dimensionSet.

keyword     name [dimensionSet] "equation";

e.g.:

nu    nu [0 2 -1 0 0 0 0] "1 / (1e-5 + 2.3/4000 + SMALL_)";

Note:

• A dimensioned equation will ignore the 'name' field;
• An abbreviated dimensioned equation format is also permitted:

keyword    [dimensionSet] "equation";

e.g.:

nu     [0 2 -1 0 0 0 0] "1 / (1e-5 + 2.3/4000 + SMALL_)";

The abbreviated format will not work in stand-alone mode.

3.1.3 Equation syntax

equationReader uses the conventional order of operations BEDMAS, then left to right:

• Brackets (and functions);
• Exponents;
• DM - division and multiplication; and
• AS - addition and subtraction.

Basically, if you can enter equations into Excel, you already know how to do this.

• you can use any amount of whitespace you want;
• exponents are ^, for example 2^3 is 8;
• multiplication is *, for example 2*3 is 6;
• there is no implied multiplication - you must explicitly use *. For example:

2 sin(theta) INCORRECT

2 * sin(theta) CORRECT

and

2(3 + 4) INCORRECT

2 * (3 + 4) CORRECT

NOTE: You cannot have numbers in your variable names.

3.1.4 Mathematical constants

equationReader recognizes all the mathematical constants I could find in the OpenFOAM library. To specify a mathematical constant, append the regular OpenFOAM format with an underscore '_'. The available constants are:

• e_ (Euler's number);
• pi_;
• twoPi_;
• piByTwo_;
• GREAT_;
• VGREAT_;
• ROOTVGREAT_;
• SMALL_;
• VSMALL_; and
• ROOTSMALL_.

3.2 Stand-alone mode

equationReader changes OpenFOAM's readScalar function, and therefore all existing applications can use equation input for scalars and dimensionedScalars read from dictionary. Using stand-alone mode:

• you do not have to recompile the solver or application;
• you can use [#<tt>scalar or regular equation|scalar]</tt> and [<tt>dimensionedScalar or dimensioned equation|dimensionedScalar]</tt> formats (above);
• you cannot use any variables