In order to run a coupled simulation, you need to:
- prepare a preCICE configuration file (described in the preCICE configuration),
- prepare an adapter’s configuration file,
- set the coupling boundaries in the OpenFOAM case,
- load the adapter, and
- start all the solvers normally, from the same directory, e.g., in two different terminals.
You may skip the section “Advanced configuration” in the beginning, as it only concerns special cases.
The adapter’s configuration file
The adapter is configured via the file system/preciceDict
. This file is an OpenFOAM dictionary with the following form:
FoamFile
{
version 2.0;
format ascii;
class dictionary;
location "system";
object preciceDict;
}
preciceConfig "precice-config.xml";
participant Fluid;
modules (CHT);
interfaces
{
Interface1
{
mesh Fluid-Mesh;
patches (interface);
locations faceCenters;
readData
(
Heat-Flux
);
writeData
(
Temperature
);
};
};
The participant
needs to be the same as the one specified in the preciceConfig
,
which is the main preCICE configuration file. The preciceConfig
can be a path and needs to be wrapped with quotation marks.
The list modules
can contain CHT
, FSI
, or/and FF
(separated by space).
Each module provides some data fields common in the respective type of simulation, and data fields from different modules can be combined by selecting multiple modules.
For example, this is a valid combination: modules (CHT FF);
.
In the interfaces
, we specify the coupling interfaces (here only one).
The mesh
needs to be the same as the one specified in the preciceConfig
.
The patches
specifies a list of the names of the OpenFOAM boundary patches that are
participating in the coupled simulation. These need to be defined in the files
included in the 0/
directory. The names of the interfaces (e.g., Interface1
) are arbitrary and are not used.
The locations
field is optional and its default value is faceCenters
(with faceCentres
also accepted), signifying that the interface mesh is defined on the cell face centers. The alternative option is faceNodes
, which defines the mesh on the face nodes and is needed, e.g., for reading displacements in an FSI scenario.
The values for readData
and writeData
for conjugate heat transfer
can be Temperature
, Heat-Flux
, Sink-Temperature
,
or Heat-Transfer-Coefficient
. Postfixed names like Sink-Temperature-Domain1
are also allowed (e.g., in order to distinguish multiple data sets of the same type).
For a Dirichlet-Neumann coupling, the writeData
and readData
can be
either:
readData
(
Heat-Flux
);
writeData
(
Temperature
);
or:
readData
(
Temperature
);
writeData
(
Heat-Flux
);
For a Robin-Robin coupling, we need to write and read both of Sink-Temperature
and Heat-Transfer-Coefficient
:
readData
(
Sink-Temperature // e.g., Sink-Temperature-Solid
Heat-Transfer-Coefficient // e.g., Heat-Transfer-Coefficient-Solid
);
writeData
(
Sink-Temperature // e.g., Sink-Temperature-Fluid
Heat-Transfer-Coefficient // e.g., Heat-Transfer-Coefficient-Fluid
);
For fluid-structure interaction, coupled quantities can be:
writeData
:- fluid participants:
Force
,Stress
(force over area, consistent) - solid participants:
Displacement
- fluid participants:
readData
:- fluid participants:
Displacement
,DisplacementDelta
(difference to the displacement at the last coupling time window) - solid participants:
Force
,Stress
- fluid participants:
Displacement(Delta)
as write data set and execute RBF mappings in parallel. This would affect users who use OpenFOAM and the adapter as the Solid participant in order to compute solid mechanics with OpenFOAM (currently not officially supported at all). Have a look at this issue on GitHub for details.
Configuration of the OpenFOAM case
A few changes are required in the configuration of an OpenFOAM case, in order to specify the interfaces and load the adapter. For some solvers, additional parameters may be needed (see “advanced configuration”).
Boundary conditions
The type of the readData
needs to be compatible with the respective boundary
conditions set for each field in the 0/
directory of the case.
Read the OpenFOAM User Guide for more on boundary conditions.
CHT
- For
readData(Temperature)
, usetype fixedValue
for theinterface
in0/T
. OpenFOAM requires that you also give a (redundant)value
, but the adapter will overwrite it. ParaView uses this value for the initial time. As a placeholder, you can, e.g., use the value from theinternalField
.
interface
{
type fixedValue;
value $internalField;
}
- For
readData(Heat-Flux)
, usetype fixedGradient
for theinterface
in0/T
. OpenFOAM requires that you also give a (redundant)gradient
, but the adapter will overwrite it.
interface
{
type fixedGradient;
gradient 0;
}
- For
readData(Sink-Temperature)
orHeat-Transfer-Coefficient
, usetype mixed
for theinterface
in0/T
. OpenFOAM requires that you also give (redundant) values forrefValue
,refGradient
, andvalueFraction
, but the adapter will overwrite them.
interface
{
type mixed;
refValue uniform 293;
valueFraction uniform 0.5;
refGradient uniform 0;
}
FSI
- For
readData(Displacement)
orDisplacementDelta
, you need the following:type movingWallVelocity
for the interface (e.g.,flap
) in0/U
,type fixedValue
for the interface (e.g.,flap
) in the0/pointDisplacement
, andsolver displacementLaplacian
in theconstant/dynamicMeshDict
. The solverRBFMeshMotionSolver
from solids4foam is also known to work, since the OpenFOAM adapter v1.2.0 and the solids4foam v2.0.
// File 0/U
interface
{
type movingWallVelocity;
value uniform (0 0 0);
}
// File 0/pointDisplacement
interface
{
type fixedValue;
value $internalField;
}
// File constant/dynamicMeshDict
dynamicFvMesh dynamicMotionSolverFvMesh;
motionSolverLibs ("libfvMotionSolvers.so");
solver displacementLaplacian;
FF
The fluid-fluid coupling module supports reading and writing Pressure
, Velocity
, PressureGradient
, and VelocityGradient
.
Similarly to the CHT module, you need a fixedValue
boundary condition of the respective primary field in order to read and apply values, and a fixedGradient
boundary condition of the respective gradient field in order to read and apply gradients.
fixedGradient
can have side-effects and may not lead to completely accurate results.
Load the adapter
To load this adapter, you must include the following in
the system/controlDict
configuration file of the case:
functions
{
preCICE_Adapter
{
type preciceAdapterFunctionObject;
libs ("libpreciceAdapterFunctionObject.so");
}
}
This directs the solver to use the preciceAdapterFunctionObject
function object,
which is part of the libpreciceAdapterFunctionObject.so
shared library.
The name preCICE_Adapter
can be arbitrary.
If you are using other function objects in your simulation, add the preCICE adapter to the end of the list. The adapter will then be executed last, which is important, as the adapter also controls the end of the simulation. When the end of the simulation is detected, the adapter also triggers the end()
method method of all function objects.
Advanced configuration
These additional parameters may only concern some users in special cases. Keep reading if you want to use the nearest-projection mapping, an incompressible or basic (e.g., laplacianFoam) solver, if you are using a solver with different variable names (e.g., a multiphase solver) or if you are trying to debug a simulation.
Nearest-projection mapping
An example for for nearest-projection mapping is provided in the nearest-projection tutorial case. The preCICE documentation contains a detailed description of nearest-projection mappings in preCICE. In summary, we need to explicitly enable the connectivity
option to create edges between the interface mesh points and give them to preCICE:
interfaces
{
Interface1
{
mesh Fluid-Mesh-Centers;
locations faceCenters;
connectivity false;
patches (interface);
// ... writeData, readData ...
};
Interface2
{
mesh Fluid-Mesh-Nodes;
locations faceNodes;
connectivity true;
patches (interface);
// ... writeData, readData ...
};
};
This connectivity
boolean is optional and defaults to false
. Note that connectivity true
can only be used with locations faceNodes
.
Even if the coupling data is associated to faceCenters
in the solver, we can select faceNodes
as locations type: the respective data will be interpolated from faces to nodes. Also, connectivity is only needed and supported for writeData
. Therefore, we need to split the interface in a “read” and a “write” part, as shown above.
More details about the rationale are given in the following section.
Adapter Implementation
Since OpenFOAM is a finite-volume based solver, data is located in the middle of the cell, or on the cell face centers for a coupling interface. Mesh connectivity can be given to preCICE using the methods setMeshTriangle
and setMeshEdge
. Using the face centers as arguments for these methods is cumbersome. The main reason is that, although OpenFOAM decomposes the mesh for parallel simulations and distributes the subdomains to different processes, mesh connectivity needs to be defined over the partitioned mesh boundaries. This problem vanishes if we define mesh connectivity based on the face nodes, since boundary nodes can be shared among processors. Therefore, mesh connectivity can only be provided on the face nodes (not on the face centers).
As described already, the data is not stored on the face nodes, but on the face centers. Therefore, we use OpenFOAM functions to interpolate from face centers to face nodes. The following image illustrates the workflow:
Data is obtained at the face centers, then interpolated to face nodes. Here, we have provided mesh connectivity and finally, preCICE performs the nearest-projection mapping. It is important to notice that the target data location is again the face center mesh of the coupling partner. In the standard CHT case, where both data sets are exchanged by a nearest-projection mapping, this leads to two interface meshes (centers and nodes) per participant. Having both the centers and nodes defined, we can skip one interpolation step and read data directly to the centers (cf. picture solver B).
consistent
constraint, but it is not implemented for the FSI
and FF
modules.
Additional properties for some solvers
Some solvers may not read all the material properties that are required for a coupled simulation. These parameters need to be added in the preciceDict
.
Conjugate heat transfer
For conjugate heat transfer, the adapter assumes that a solver belongs to one of the following categories: compressible, incompressible, or basic. Most of the solvers belong in the compressible category and do not need any additional information. The other two need one or two extra parameters, in order to compute the heat flux.
For incompressible solvers (like the buoyantBoussinesqPimpleFoam), you need to add the density and the specific heat in a CHT
subdictionary of preciceDict
. For example:
CHT
{
rho [ 1 -3 0 0 0 0 0 ] 50;
Cp [ 0 2 -2 -1 0 0 0 ] 5;
};
For basic solvers (like the laplacianFoam), you need to add a constant conductivity:
CHT
{
k [ 1 1 -3 -1 0 0 0 ] 100;
};
The value of k
is connected to the one of DT
(set in constant/transportProperties
)
and depends on the density (rho [ 1 -3 0 0 0 0 0 ]
) and heat capacity (Cp [ 0 2 -2 -1 0 0 0 ]
). The relation between them is DT = k / rho / Cp
.
Fluid-structure interaction
The adapter’s FSI functionality supports both compressible and incompressible solvers, as well as solid (e.g., solids4Foam) solvers.
For incompressible solvers, it tries to read uniform values for the density and kinematic viscosity (if it is not already available) from the FSI
subdictionary of preciceDict
:
nu nu [ 0 2 -1 0 0 0 0 ] 1e-03;
rho rho [1 -3 0 0 0 0 0] 1;
Notice that here, in contrast to the CHT
subdict, we need to provide both the keyword (first nu
) and the word name (second nu
). We are working on bringing consistency on this.
Additional parameters in the adapter’s configuration file
Some optional parameters can allow the adapter to work with more solvers, whose type is not determined automatically, their fields have different names, or they do not work well with some features of the adapter.
User-defined solver type
The adapter tries to automatically determine the solver type,
based on the dictionaries that the solver uses.
However, you may manually specify the solver type to be basic
,
incompressible
or compressible
for a CHT simulation:
CHT
{
solverType incompressible;
};
or the incompressible
, compressible
, or solid
(e.g., for solids4Foam) for an FSI simulation:
FSI
{
solverType solid;
}
Note that the adapter does not currently adapt the name of the pressure used in the computations for compressible solvers.
For an FF simulation, known types are incompressible
and compressible
:
FF
{
solverType incompressible;
}
This will force the adapter to use the boundary condition implementations for the respective type.
Parameters and fields with different names
The names of the parameters and fields that the adapter looks for can be changed, in order to support a wider variety of solvers. You may specify the following parameters in the adapter’s configuration file (the values correspond to the default values):
CHT
{
// Temperature field
nameT T1;
// Thermal conductivity
nameKappa k1;
// Density
nameRho rho1;
// Heat capacity for constant pressure
nameCp Cp1;
// Prandtl number
namePr Pr1;
// Turbulent thermal diffusivity
nameAlphat alphat1;
};
Similarly for FSI simulations:
FSI
{
// Displacement fields
namePointDisplacement pointD;
nameCellDisplacement D;
// Force field
nameForce Force; // For solids4Foam: solidForce
}
Use the option namePointDisplacement unused;
for solvers that do not create a pointDisplacement field, such as the RBFMeshMotionSolver.
For FF simulations:
FF
{
// Velocity
nameU U;
// Pressure
nameP p;
}
Note that the adapter does not automatically adapt the pressure name for solvers that account for hydrostatic pressure effects. In these cases, you may want to set nameP p_rgh
to couple p_rgh
, as p
is a derived quantity for these solvers.
Restarting FSI simulations
Restarting a coupled simulation using the OpenFOAM adapter works in principle in the same way as restarting a standalone OpenFOAM solver. However, the adapter and preCICE define the coupling interface and the interface node locations based on the mesh at the particular time. In case of FSI simulations, the interface deforms over time, which leads to the definition of a deformed interface during the restart. The boolean variable restartFromDeformed
(true
by default) allows to account for the previously accumulated interface deformation such that the initial interface configuration (t = 0
) is completely recovered. The setting here needs to agree with the behavior of the selected solid solver.
FSI
{
// Account for previous displacement during a restart
restartFromDeformed true;
}
Debugging
The user can toggle debug messages at build time.
Coupling OpenFOAM with 2D solvers
The adapter asks preCICE for the dimensions of the coupling data defined in the precice-config.xml
(2D or 3D). It then automatically operates in either 3D (normal) or 2D (reduced) mode, with z-axis being the out-of-plane dimension. Read more. In 2D mode, the adapter also supports axisymmetric cases.
Porting your older cases to the current configuration format
In earlier versions of the adapter, we were using a yaml-based configuration format,
with the adapter configuration file usually named as precice-adapter-config.yml
.
We moved to a OpenFOAM dictionary format in #105,
to reduce the dependencies. You may also find the tutorials #69
to be a useful reference (file changes).