# User Defined Features

Source: https://help.sim-flow.com/installation/configuration/user-defined-features
Last updated: 2026-10-14

## 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 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 a solver named *mySolverFoam* 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

A statement consists of a key-value pair ended with a semicolon. The 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

A block consists 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

The UDF file format allows for standard *C++* comments.

Example of single-line and multi-line comments

```
//Single line comment
someKey someValue;

/*
Multi line comment
*/
someOtherKey sameValue;
```

### Dimensions

Some inputs may require definition of the physical dimension associated with a property or field. The dimension specification follows the OpenFOAM convention. Dimensions are defined by a list of integers in square brackets 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 in:

- text field
- number field
- dropdown list
- check box
- time-value table editor

On the other hand, the input value provided in the GUI will be saved in the relevant OpenFOAM dictionary file using the same label as the input name.

![example bc result](https://help.sim-flow.com/installation/configuration/images/user-defined-features/example-bc-result.png)

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.

```
inputType <additional options>
```

For example, to define inputs presented in the [image above](https://help.sim-flow.com/installation/configuration/user-defined-features#exampleGUIOF) you will use the following statements:

```cpp
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 `referenceVelocity`.

### 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 the 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, which 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 the 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 a block named equations. Each equation should be defined in a block corresponding to the equation name. Equation definition requires two keywords:

- **matrix**
- **tensor**

The keyword matrix is to define a matrix type and should be followed by one of two words: **symmetric** or **asymmetric** . The keyword tensor has an identical meaning as in the case of fields.

Definition of temperature for the 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, the solution block can contain an 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 three 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-state 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 the 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 are:

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

The **dimensions** entry determines the physical dimensions of the property. The **value** entry should contain the default value of the property.

All other models require no additional options.

Diffusion coefficient for the Laplace equation

```
transport
{
    type simple;
    DT
    {
        dimensions [0 2 -1 0 0 0 0];
        value 1e-5;
    }
}
```

#### Thermophysical properties - optional

For compressible solvers, thermophysical properties can be enabled in a block named **thermo** . In this block, the 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 File](https://help.sim-flow.com/installation/configuration/user-defined-features#_user_defined_files), you can include this as a panel in your solver. This panel will allow specifying additional configuration parameters within the GUI and save them as an additional file before calculations begin. In order to include a **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 configuration 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](https://help.sim-flow.com/installation/configuration/user-defined-features#_boundary_conditions_specific_inputs).

Definition of simple vector field input

```
inputs
{
    value field vector;
}
```

#### Boundary Conditions Specific Inputs

Besides standard inputs, 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 accepts 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, the 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](https://help.sim-flow.com/installation/configuration/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 the keyword **typeConstraints** followed by a list of boundary types. This way, the 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 a block **fieldConstraints**, where you can define the following keywords:

- **names**
- **type**

Keyword **names** should be followed by a list of field names on which this boundary condition should be available. Use the 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 );

fieldConstraints
{
        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](https://help.sim-flow.com/installation/configuration/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](https://help.sim-flow.com/installation/configuration/user-defined-features#_standard_input_definitions) 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 the 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 a user input panel:

![advanceduser defined file example](https://help.sim-flow.com/installation/configuration/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 the optional keyword **symmetric** followed by a Boolean value `true`. Similarly, if the solver is to be used for asymmetric matrices, add the 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](https://help.sim-flow.com/installation/configuration/user-defined-features#_standard_input_definitions).

You do not have to include standard OpenFOAM inputs like **tolerance** and **relTol**. These 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 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.

Function 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](https://help.sim-flow.com/installation/configuration/user-defined-features#_standard_input_definitions).

Definition of simple scalar input

```
inputs
{
    someFunctionParameter  float;
}
```