Introduction
Many OpenFOAM users require custom models and other features that were not implemented in the official version. For those users, SimFlow offers functionality called User Defined Features (UDF). This functionality allows users to define graphical user interface elements for user extensions of the OpenFOAM. Currently, the following additional options can be added to the SimFlow interface:
- Solvers
- Boundary Conditions
- Files
- Linear Equation Systems Solvers
- Solid Body Motion Functions
This option can be defined using simple text configuration files. The configuration file uses the standard OpenFOAM syntax, making it easy to use for those already familiar with OpenFOAM.
Defining UDFs
User Defined Features configuration files should be located in the dedicated configuration subdirectory:
<HOME>/.simflow/5.0/udf
Every type of UDF has its own associated file extension:
- Solver - *.solver
- Boundary Condition - *.bc
- File - *.file
- Linear Solver - *.sles
- Motion Function - *.sbmf
For example, a file defining solver named mySolverFoam for should be placed under:
<HOME>/.simflow/5.0/udf/mySolverFoam.solver
UDF File Syntax
UDFs use the standard OpenFOAM file format. This is a nested dictionary format consisting of statements and blocks which is essentially a tree-like structure.
Statements
Statement consists of a key-value pair ended with semicolon. Value could be of any type (string, integer, float, list) or even left empty.
Simple entry with key myKey and value myValue .
myKey myValue;
Blocks
Block consist of a name and content enclosed in curly braces. The content of a block could be any number of statements and/or nested blocks.
Block myBlock with entry someKey and nested block myNestedBlock .
myBlock
{
someKey someValue;
myNestedBlock
{
someOtherKey someOtherValue;
}
}
Comments
UDF file format allows for standard C++ comments.
Example of single
//Single line comment
someKey someValue;
/*
Multi line comment
*/
someOtherKey sameValue;
Dimensions
Some inputs may require definition of the physical dimension associated with property or field. The dimension specification follows the OpenFOAM convention. Dimensions are defined by a list of integers in a square bracket corresponding to the dimensions of its units in the following order: kg , m , s , K , kgmol , A , cd .
Definition of velocity (m/s) dimensions
dimensions [0 1 -1 0 0 0 0]
Tensor Type
It may be required to define a tensor type of field or property. This can be done using one of two keywords scalar or vector . Currently, no higher rank tensors are supported.
Vector input named someVectorInput
someVectorInput vector;
UDF Input Definition
Any input defined in the UDF file will be translated into a GUI input field, depending on the type, it might result as:
- text field
- number field
- dropdown list
- check box
- time-value table editor
On the other hand, the input value, provided by in GUI will be saved in the relevant OpenFOAM dictionary file using the same label as the input name.
![example bc result](images/user-defined-features/example-bc-result.png)
Inputs are defined as statements in the definition file.
inputName <input definition>;
Input definition contains an input type and zero or more options.
intpuType <additional options>
For example, to define inputs presented in the image above you will use the following statements:
direction vector (1 0 0);
referenceVelocity float 5.0;
This will define inputs with default values [1, 0, 0] for the direction
and 5.0 for the refrenceVelocity
Standard Input Definitions
Integer: int <initialValue>
Integer input with default value of 5
someIntInput int 5;
Float: float <initialValue> <dimensionsDefinition>
Float input with default value 0.5 and dimension of length
someFloatInput float 0.5 [0 1 0 0 0];
Vector: vector <initialValue> <dimensionsDefinition>
Dimensionless vector input pointing in Z direction by default
someVectorInput vector (0 0 1);
Switch (boolean input): switch <initialValue>
Boolean input is disabled by default
someSwitchInput switch false;
List: list (element1 element2 …)
List with three options
someListInput list (firstOption secondOption someOtherOption);
Since version 2.2
File locations: file <initialValue>
Use a file named "data.txt"
someFileInput file "data.txt";
User Defined Solvers
Users who created their own OpenFOAM solvers can access them by defining the *.solver file, that should be located under the UDF directory: <HOME>/.simflow/5.0/udf/mySolverFoam.solver
Solver Definition
Field Definition - required
Solver fields should be defined in a block named fields . Each field should be defined in a block with a name corresponding to the name of the field. Field definition requires two keywords to be present:
- dimensions
- tensor
followed respectively by dimensions and tensor rank definition.
Additionally, you can include optional keyword special if your block has one of the following names:
- U
- T
- p
- p_rgh
This keyword will cause SimFlow to use one of the predefined fields and make all the necessary boundary conditions and options available. For p and p_rgh fields you need to define dimensions to differentiate between pressure and kinematic pressure.
Definition of kinematic pressure and velocity
fields
{
p
{
dimensions [0 2 -2 0 0 0 0];
tensor scalar;
}
U
{
dimensions [0 1 -1 0 0 0 0];
tensor vector;
}
}
Equations definition - required
Equations solved by the solver should be defined in block-named equations. Each equation should be defined in a block corresponding to the equation name. Equation definition requires two keywords:
- matrix
- tensor
Keyword matrix is to define a matrix type and should be followed by one of two words: symmetric or asymmetric . Keyword tensor has identical meaning as in the case of fields.
Definition of temperature for Laplace equation
equations
{
T
{
matrix symmetric;
tensor scalar;
}
}
Solution controls definition - required
Solution control should be defined inside a block named solution . Inside this block one of three blocks: SIMPLE, PISO, PIMPLE is required. Inside this block options required by each of these schemes can be placed. Additionally, solution block can contain additional block relaxationFactors where default values of relaxation factors for each equation can be defined.
Standard SIMPLE solution control
solution
{
SIMPLE
{
nNonOrthogonalCorrectors 2;
pRefCell 0;
pRefValue 0;
}
relaxationFactors
{
p 0.3;
U 0.7;
}
}
Discretization definition - required
Discretization options should be defined in a block named discretization . The discretization block can contain four sub-blocks:
- time
- convection
- fluxRequired
The time block can contain three keywords transient , steadyState and LTS . Each of these keywords enables a respectively transient, steady-state or local time stepping approach to steady stat simulations.
The convection block should contain all convection fields. Fields that were not mentioned in the fields block will be ignored.
The fluxRequired block should contain all equations for which the solver requires flux to be computed.
Discretization definition for simpleFoam solver
discretization
{
time
{
steadyState;
}
convection
{
U;
}
fluxRequired
{
p;
}
}
Transport properties - optional
Transport properties can be defined in a block named transport . This block has an obligatory entry type . Currently supported transport properties ar:
- simple - for custom transport properties
- laplacian - Laplace transport (laplacianFoam)
- incompressible - incompressible transport (icoFoam)
- singlePhase - single phase transport (simpleFoam)
- Boussinesq - Boussinesq transport (buoyantBoussinesqSimpleFoam)
- twoPhaseVOF - two phase volume of fluid transport (interFoam)
Simple transport properties should be defined in blocks with names corresponding to the property name. Each property block should contain two entries:
- dimensions
- value
Entry dimensions determine the physical dimensions of the property. Entry value should contain the default value of the property.
All other models require no additional options.
Diffusion coefficient for Laplace equation
transport
{
type simple;
DT
{
dimensions [0 2 -1 0 0 0 0];
value 1e-5;
}
}
Thermophysical properties - optional
For compressible solvers thermo-physical properties can be enabled in block named thermo . In this block entry type is required, this entry should contain one of two values: psi
or rho
, to determine if compressibility or density based formulation should be used.
Thermophysical properties for compressibility based solver like sonicFoam
thermo
{
type psi;
}
Turbulence - optional
To enable turbulence models a block named turbulence should be created. Currently, this block has no options.
turbulence
{
}
Gravity - optional
To allow specifying gravity you need to add an empty block named gravity. Currently, this block has no options.
gravity
{
}
Radiation - optional
To enable radiation models a block named radiation should be created. Currently, this block has no options.
radiation
{
}
Dynamic Mesh - optional
To enable dynamic mesh a block named dynamicMesh should be created. Currently, this block has no options.
dynamicMesh
{
}
Custom File - optional
If you have already prepared a User Defined Files you can include this as a panel in your solver. This panel will allow specifying additional configuration parameters within GUI and save them as an additional file before calculations begin. In order to include User Defined File in the solver, you need to place the file name under the extensions block in the list of files:
extensions
{
files ("user-defined-file-name");
}
User Defined Boundary Conditions
SimFlow allows you to access custom types of OpenFOAM finite volume patch fields. To do so, you have to create a cofinguration file and place it under:
<HOME>/.simflow/5.0/udf/myBoundaryCondition.bc
Containing Library - optional
If your boundary condition is located in a library that your solver is not linked against, you can include an optional keyword inLibrary. This keyword should be followed by the name of your library. The name can optionally be in quotes and optionally contain an extension.
This will cause libmyLibrary.dll
to be dynamically loaded to make your boundary condition available
inLibrary "libmyLibrary.dll";
Label - optional
You can optionally include a label keyword followed by a short text in quotes. This option allows adding user-friendly names to your custom boundary conditions.
Boundary condition with this entry will be displayed as My Fancy BC
label "My Fancy BC";
Inputs - required
All inputs for a given boundary condition have to be defined in a block named inputs . This block should contain only boundary inputs.
Definition of simple vector field input
inputs
{
value field vector;
}
Boundary Conditions Specific Inputs
Besides standard intputs, definitions of boundary conditions can include dedicated inputs
General: general <defaultValue>
General input field that can accept any value. The value provided by the user as a text will be directly copied into the OpenFOAM dictionary file. This option might be useful when SimFlow standard inputs do not offer a suitable input type that would match the expected dictionary entry.
Example of input that excepts expressions
expression general myDefaultValue;
Field (nonuniform value): field <tensorType> <dimensionsDefinition>
Currently, there are two possibilities of defining the tensor type of the field: scalar and vector . If no type is specified type is taken from the field on which this boundary condition is defined.
Reference pressure for Total Pressure boundary condition
p0 field;
Transient value: transient <tensorType> <dimensionsDefinition>
Amplitude that can change in time. The GUI element representing this input will be presented as a table input. Any table input can accept either a constant or tabular value.
![example transient](images/user-defined-features/example-transient.png)
amplitude transient scalar;
Velocity field name: U
Define the name of the velocity field
UName U;
Temperature field name: T
Name of temperature field
TName T;
Density field name: rho
Name of density field
rhoName rho;
Hidden input: hidden <value>
This entry will not be available in the user interface but still will be written to the setup file.
Hidden input definition
myHiddenInput hidden myHiddenValue;
Since version 2.2
Flux field name: phi
Name of the flux field
phiName phi;
Boundary Type Constraints - optional
If you want to make this boundary condition available only for certain boundary types (patch, wall, symmetry, etc.), you can put keyword typeConstraints followed by a list of boundary types. This way given boundary condition will be available in SimFlow only where it is needed and will not clutter the user interface.
This boundary condition will be available only on boundaries with type wall .
typeConstraints ( wall );
Field Type Constraints - optional
You can make your custom boundary condition available only on selected fields. To do so create block fieldConstraints where you can define following keywords:
- names
- type
Keyword names should be followed by a list of field names on which this boundary condition should be available. Use keyword type to make this boundary condition available for scalar
or vector
fields.
Make boundary condition available only for pressure field
fieldConstraints
{
names (p p_rgh);
type scalar;
}
Example of UDF Boundary Condition File
inputs
{
direction vector (1 0 0);
referenceVelocity transient scalar;
}
typeConstraint ( patch );
filedConstraints
{
name (U);
type vector;
}
label "Velocity Custom Profile";
inLibrary "libuserBC.so";
The above configuration file will be interpreted into the following GUI and OpenFOAM file:
![example custom bc](images/user-defined-features/example-custom-bc.png)
User Defined Files
SimFlow allows you to define additional setup files for simulations with your custom solver. To do so you have to create a configuration file containing standard inputs and place it under:
<HOME>/.simflow/5.0/udf/myFile.file
Inputs defined in such a way can be nested up to two levels by placing them inside blocks. Additionally, each such configuration file requires a standard FoamFile to determine its location in case directory structure.
Configuration file:
FoamFile
{
version 2.0;
format ascii;
class dictionary;
location "constant";
object myModelProperties;
}
activateModel switch;
someModelConstant float 0.5;
someOptions list (firstOption secondOption thirdOption);
will generate user input panel:
![advanceduser defined file example](images/user-defined-features/advanceduser-defined-file-example.png)
that with default settings will generate the following OpenFOAM file:
FoamFile
{
version 2.0;
format ascii;
class dictionary;
location "constant";
object myModelProperties;
}
activateModel true;
someModelConstant 0.5;
someOptions firstOption;
User Defined Linear Solvers
With this feature you can access third party linear equation system solvers, for example, you can use GPU accelerated solvers.
Containing Library - optional
Usually your custom solver will be located in a library that your application is not linked against. To access this solver, you need to include an optional keyword inLibrary . This keyword should be followed by the name of your library. The name can optionally be in quotes and optionally contain an extension.
This will cause libmySolverLibrary.dll
to be dynamically loaded to make your solver available at run time
inLibrary "libmySolverLibrary.dll";
Label - optional
You can optionally include a label keyword followed by a short text in quotes. This option allows adding user-friendly names to your custom solver.
Solver with this entry will be displayed as My Super Fast Solver
label "My Super Fast Solver";
Symmetric/Asymmetric - required
If this custom solver is to be used for symmetric matrices add optional keyword symmetric followed by a Boolean value true
, similarly if the solver is to be used for asymmetric matrices add optional keyword asymmetric followed by true
.
At least one of the keywords symmetric and asymmetric must be set to true
Definition of solver for both symmetric and asymmetric matrices.
symmetric true;
asymmetric true;
Inputs - required
All inputs for a given solver have to be defined in a block named inputs . This block should contain only valid inputs.
You do not have to include standard OpenFOAM inputs like tolerance and relTol. This option will be included automatically.
Definition of simple scalar input
inputs
{
someSolverParameter float;
}
User Defined Motion Functions
These options allow you to access your custom solid body motion functions.
Containing Library - optional
Usually your custom motion function will be located in a library that your application is not linked against. To access the function, you need to include an optional keyword inLibrary . This keyword should be followed by the name of your library. The name can optionally be in quotes and optionally contain an extension.
This will cause libmyLibrary.dll
to be dynamically loaded to make your function available at run time
inLibrary "libmyLibrary.dll";
Label - optional
You can optionally include a label keyword followed by a short text in quotes. This option allows you to add user-friendly names to your custom function.
Solver with this entry will be displayed as My Complex Motion
label "My Complex Motion";
Inputs - required
All inputs for a given function have to be defined in a block named inputs. This block should contain only valid inputs.
Definition of simple scalar input
inputs
{
someFunctionParameter float;
}