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

advanceduser defined file example

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