User Defined Features

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
Figure 1. Example UDF Boundary Condition (GUI vs. generated OpenFOAM file)

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

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

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;
}