Difference between revisions of "Contrib/equationReader"

Revision as of 02:18, 22 July 2010

An equation reader for your dictionary files.
Valid versions:

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?

First install it. Out of the box, it will work with all existing solvers.

3.1 Syntax

The general syntax is:

3.1.1 scalar or regular equation

An equation using this format 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;

3.1.3 Abbreviated dimensioned equation

Since a dimensioned equation does not need the name field, an abbreviated format is acceptable:

keyword    [dimensionSet] "equation";

e.g.:

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

This format will not work in stand-alone mode.

3.1.4 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.5 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.1.6 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.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 scalar and dimensionedScalar formats (above);
• you can use mathematical constants; and
• you can use functions; but
• you cannot use any variables.

Since you cannot use variables, there is no equation substitution available in stand-alone mode.

3.3 Passive and active mode

To use passive mode and active mode your solver or application has to be specifically written to use equationReader. See Programming with equationReader.

3.4 Debugging your equations

If you enter an incorrect equation equationReader should throw an error that explains exactly what is wrong with it. If you encounter a floating point exception, try using a debug flag. Add equationReader to the debug flag list in [OpenFOAM root folder]/etc/controlDict. There are two debug levels:

1. Show when equations are read, parsed, and evaluated; and
2. Show every operation as it is calculated.

4 Programming with equationReader

Have a look at the demo application that equationReader comes with.

To enable the use of variables, you have to create an equationReader object, and tell it where to find its data.

#include "equationReader.H"
// ...
equationReader eqns;

To give it data, use the addDataSource functions. There are three data sources equationReader will accept:

• scalars;
• dimensionedScalars; and
• dictionaries.

NOTE: I've provided access methods directly to the data storage members, so if you know what you are doing, you can direclty modify everything this way.

4.1 Data source and output warnings

WARNING - KEEP YOUR DATA SOURCES AND OUTPUTS ON THE FREESTORE
You will notice the addDataSource methods only accept pointers. This is deliberate because the data sources must be on the freestore. I've had a heck of a time with the debugging you can see, and this is necessary for stability^[2].

WARNING - DATA SOURCES AND OUTPUTS MUST NOT GO OUT-OF-SCOPE
Ensure that anytime equationReader is in use, all of its data is available to it. There is no way of telling when the object at the end of a pointer has been deleted. However, it is safe to let the equationReader go out-of-scope without impacting the data.

4.2 Reading equations

One you've defined the data sources, you can use the readEquation method to read and parse the equations in the dictionary. This does not immediately evaluate them... use the evaluate or update methods for that.

4.2.1 On-the-fly equation reading

If you have a dictionary source, equationReader will search the dictionary recursively for any unknown variables. If the variable happens to be an equation, equationReader will automatically read this equation as well. This can continue to an indefinite equation substitution depth.

4.3 Passive mode

To use an equation in passive mode, when you read the equation with readEquation, you do not have to specify an output variable. To get output from and equation in this manner, use evaluate. This returns a dimensionedScalar that you can assign to whatever variable you want.

Passive mode requires an evaluate command for each equation you're using.

4.4 Active mode

To use an equation in active mode, when you read the equation with readEquation, you must specify an output variable. Again, use the freestore, and give a pointer. When you you update, equationReader will cycle through all your equations, and evaluate those with output pointers, changing the output variables in the process. If you only want to update one equation, that is also available.

NOTE: You can still use this equation passively with evaluate.

5 Installation

To install equationReader:

0. If you are running precompiled binaries, first ensure that you can compile your copy of OpenFOAM.

1. Download the code from here.

http://openfoam-extend.svn.sourceforge.net/viewvc/openfoam-extend/trunk/Breeder_1.5/libraries/equationReaderExtension/?view=tar

2. Edit the src/OpenFOAM/Make/files file.

3. Around line 123 you will find "$(entry)/entryIO.C". Add this after it:

equation = $(dictionary)/equation
$(equation)/equationReader/equationReader.C
$(equation)/equation/equation.C
$(equation)/equationOperation/equationOperation.C

4. Save and close the file.

5. Open a terminal window, and browse to the directory with your download.

6. Execute the following commands. You should be able to copy and paste all 9 lines at once into you terminal window.

tar --transform='s,equationReaderExtension,'$WM_PROJECT_DIR',' \
-x -v -z -P -f openfoam-extend-equationReaderExtension.tar.gz
cd $WM_PROJECT_DIR/src/OpenFOAM
rmdepall
wmake libso
cd $FOAM_APP/test/equationReader/equationReaderDemo
wmake
cd $FOAM_APP/test/equationReader/equationReaderTester
wmake

Equation reader should now be installed.

5.1 Testing the installation

The code comes with two applications: a simple demo, and a more complex test program. Once equationReader is installed, there should be a new folder: $WM_PROJECT_DIR/tutorials/equationReader. Copy this into your run directory:

cp -rf $WM_PROJECT_DIR/tutorials/equationReader $FOAM_RUN/tutorials

To run the demo:

cd $FOAM_RUN/tutorials/equationReader/equationReaderDemo
equationReaderDemo

You can compare the output with the expectedOutput file.

To run the tester:

cd $FOAM_RUN/tutorials/equationReader/equationReaderTester
blockMesh
equationReaderTester

The tester runs equationReader in an environment that might be expected in a regular simulation. It shouldn't throw any errors here, but as it is beta code, please me know: Marupio.

6 Notes

runTime modification not supported

equationReader is not a regIOobject, and therefore is not capable of runTime modification (i.e. if you edit the dictionary equation while the simulation is running, nothing will happen). However, it will keep up with the change undergone by its data sources.

No plans for vector or label implementation

There are no plans to implement vectors, labels, or any other data type. You can get around this limitation if you must, albeit in a cumbersome manner: you can break the vectors down and reassemble them; you can cast to label, etc..

7 Foot notes

1. ↑ Excel is copyright Microsoft
2. ↑ Stability - I've tested equationReader with 200 data sources, embedded parenthesis depth and equation substitution depth both up to 100, using icoFoam's cavity tutorial as a back bone. I hope it works for you!