Contrib equationReader/Using equationReader

From OpenFOAMWiki

1 Dictionary syntax

Any of these formats are acceptable to equationReader:

1.1 Standard equation

keyword    "equation";
keyword    scalar;

e.g.:

endTime    "2*pi_/360*60";
gamma      1.58e-6;

The standard equation format performs dimension checking for every operation. Use this if you want OpenFOAM to be strict about the dimensions you use. This has may unexpected consequences. For example:

  • sin(time) is wrong because you can't have dimensions in any transcendental functions; and
  • max(deltaT, SMALL_) is wrong because SMALL is dimensionless.

If this is too troublesome, you can also use:

1.2 Dimensioned equation

keyword    [dimensionSet] "equation";
keyword    [dimensionSet] scalar;
keyword    ignoredWord [dimensionSet] "equation";
keyword    ignoredWord [dimensionSet] scalar;

e.g.:

nu      [0 2 -1 0 0 0 0] "1 / (1e-5 + 2.3/4000 + SMALL_)";
rho     [1 -3 0 0 0 0 0] 1.235;
delta   delta [0 1 0 0 0 0 0] "sin(pi_ * t)";
alhpa   alpha [0 1 0 0 0 0 0] 3.2;

The dimensioned equation format disables dimension checking, and forces the final result to a given dimensionSet. Also note the optional ignoredWord - this allows equationReader to be compatible with dimensionedScalar formats.

2 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.

It's just like Excel, except exponents 'a^b' don't work - use 'pow(a,b)' instead.

  • you can use any amount of whitespace you want (use a backslash for a line break);
  • 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

2.1 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_.

2.2 Functions

Click here for a complete list of functions.

All the scalar and dimensionedScalar functions I could find in the OpenFOAM library have been implemented.

3 Troubleshooting your equations

Your equations may cause you trouble, such as:

  • Giving you a SIGFPE; or
  • Failing dimension checks.

If this happens and you don't know why, equationReader has a detailed set of debug switches to help. To change the debug switch, edit the OpenFOAM/etc/controlDict file and add:

equationReader     integerValue;

to the DebugSwitches list.

The debug switches available are:

0. Silent mode;
1. scalar logging (light);
2. scalar logging (verbose);
3. dimension logging (light);
4. dimension logging (verbose);
5. scalar & dimension logging (light); or
6. scalar & dimension logging (verbose).

The scalar logging will report scalar-related operations to the console. The dimension logging, relates to dimensionSet operations. verbose reports operation-by-operation, so it can be overwhelming.