Contrib/equationReader
Contents
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:
- stand-alone - this one works "out of the box" with all OpenFOAM applications. You can only use literal constants in your equations;
- passive mode - if you create an equationReader object, you can give it data sources. This allows you to use variables, and equation substitution; and
- 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[1], 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
4 Notes
- ↑ Excel is copyright Microsoft