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 options added to custom versions of 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 options can be defined using simple text configuration files - no programming is required. This configuration files use standard OpenFOAM syntax, so it should be easy to use for those already familiar with OpenFOAM.
Defining UDFs
User Defined Features configuration files should be located in dedicated profile subdirectory . Every type of UDF has its own associated file extension:
- Solver - *.solver
- Boundary Condition - *.bc
- File - *.file
- Linear Solver - *.sles
- Motion Function - *.sbmf
File defining solver named mySolverFoam for profile myProfile should be placed under:
<HOME>/.simflow/profiles/myProfile/mySolverFoam.solver
UDF File Syntax
UDFs use standard OpenFOAM file format. This is 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 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 physical dimensions of property or field that they correspond to. 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 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
Inputs are defined as statements in definition file.
inputName <input definition>;
Input definition contains input type and zero or more options.
intpuType <additional options>
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 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 file named "data.txt"
someFileInput file "data.txt";
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.
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
amplitude transient scalar;
- Velocity field name:
U
Define name of 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;
User Defined Solvers
User who created their own OpenFOAM solvers can access them by defining configuration files .
Solver Definition
Field Definition - required
Solver fields should be defined in a block named fields . Each field should be defined in a block with 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 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 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 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 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 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 determines the physical dimensions of the property. Entry value should contain 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 special cofinguration files .
Containing Library - optional
If your boundary conditions is located in a library that your solver is not linked against, you can include optional keyword inLibrary . This keyword should be followed by the name of your library. The name can optionally be in quotes and optionally contain 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 label keyword followed by a short text in quotes. This options allows to add 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 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 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;
}
User Defined Files
SimFlow allows you to define additional setup files for simulations with your custom solver. To do so you have to create configuration file containing standard inputs .
Inputs defined in such a way can be nested up to two levels by placing them inside blocks. Additionally, each such configuration file requires 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:
that with default settings will generate 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 optional keyword inLibrary . This keyword should be followed by the name of your library. The name can optionally be in quotes and optionally contain 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 label keyword followed by a short text in quotes. This options allows to add 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 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 options 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 optional keyword inLibrary . This keyword should be followed by the name of your library. The name can optionally be in quotes and optionally contain 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 label keyword followed by a short text in quotes. This options 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 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;
}