On this page you find the complete configuration references of preCICE API.

precice-configuration

Main tag containing preCICE configuration.

Example:

<precice-configuration sync-mode="0">
  <log enabled="1">
    ...
  </log>
  <solver-interface dimensions="2">
    ...
  </solver-interface>
</precice-configuration>
Attribute Type Description Default Options
sync-mode boolean sync-mode enabled additional inter- and intra-participant synchronizations 0 none

Valid Subtags:

log

Configures logging sinks based on Boost log.

Example:

<log enabled="1">
  <sink filter="(%Severity% > debug) and not ((%Severity% = info) and (%Rank% != 0))" format="(%Rank%) %TimeStamp(format="%H:%M:%S")% [%Module%]:%Line% in %Function%: %ColorizedSeverity%%Message%" output="stdout" type="stream" enabled="1"/>
</log>
Attribute Type Description Default Options
enabled boolean Enables logging 1 none

Valid Subtags:

sink

Contains the configuration of a single log sink, which allows fine grained control of what to log where. Available attributes in filter and format strings are %Severity%, %ColorizedSeverity%, %File%, %Line%, %Function%, %Module%, %Rank%, and %Participant%

Example:

<sink filter="(%Severity% > debug) and not ((%Severity% = info) and (%Rank% != 0))" format="(%Rank%) %TimeStamp(format="%H:%M:%S")% [%Module%]:%Line% in %Function%: %ColorizedSeverity%%Message%" output="stdout" type="stream" enabled="1"/>
Attribute Type Description Default Options
filter string Boost Log Filter String (%Severity% > debug) and not ((%Severity% = info) and (%Rank% != 0)) none
format string Boost Log Format String (%Rank%) %TimeStamp(format="%H:%M:%S")% [%Module%]:%Line% in %Function%: %ColorizedSeverity%%Message% none
output string Depends on the type of the sink. For streams, this can be stdout or stderr. For files, this is the filename. stdout none
type string The type of sink. stream stream, file
enabled boolean Enables the sink 1 none

solver-interface

Configuration of simulation relevant features.

Example:

<solver-interface dimensions="2">
  <data:scalar name="{string}"/>
  <mesh name="{string}" flip-normals="0">
    ...
  </mesh>
  <m2n:sockets port="0" exchange-directory="" from="{string}" network="lo" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>
  <participant name="{string}">
    ...
  </participant>
  <coupling-scheme:serial-explicit>
    ...
  </coupling-scheme:serial-explicit>
</solver-interface>
Attribute Type Description Default Options
dimensions integer Determines the spatial dimensionality of the configuration 2 2, 3

Valid Subtags:

data:scalar

Defines a scalar data set to be assigned to meshes.

Example:

<data:scalar name="{string}"/>
Attribute Type Description Default Options
name string Unique name for the data set. none none

data:vector

Defines a vector data set to be assigned to meshes. The number of components of each data entry depends on the spatial dimensions set in tag .

Example:

<data:vector name="{string}"/>
Attribute Type Description Default Options
name string Unique name for the data set. none none

mesh

Surface mesh consisting of vertices and (optional) of edges and triangles (only in 3D). The vertices of a mesh can carry data, configured by tag . The mesh coordinates have to be defined by a participant (see tag ).

Example:

<mesh name="{string}" flip-normals="0">
  <use-data name="{string}"/>
</mesh>
Attribute Type Description Default Options
name string Unique name for the mesh. none none
flip-normals boolean Flips mesh normal vector directions. 0 none

Valid Subtags:

use-data

Assigns a before defined data set (see tag ) to the mesh.

Example:

<use-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data set. none none

m2n:sockets

Communication via Sockets.

Example:

<m2n:sockets port="0" exchange-directory="" from="{string}" network="lo" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>
Attribute Type Description Default Options
port integer Port number (16-bit unsigned integer) to be used for socket communication. The default is “0”, what means that the OS will dynamically search for a free port (if at least one exists) and bind it automatically. 0 none
exchange-directory string Directory where connection information is exchanged. By default, the directory of startup is chosen, and both solvers have to be started in the same directory. `` none
from string First participant name involved in communication. For performance reasons, we recommend to use the participant with less ranks at the coupling interface as “from” in the m2n communication. none none
network string Interface name to be used for socket communiation. Default is the cannonical name of the loopback interface of your platform. Might be different on supercomputing systems, e.g. “ib0” for the InfiniBand on SuperMUC. lo none
to string Second participant name involved in communication. none none
enforce-gather-scatter boolean Enforce the distributed communication to a gather-scatter scheme. Only recommended for trouble shooting. 0 none
use-two-level-initialization boolean Use a two-level initialization scheme. Recommended for large parallel runs (>5000 MPI ranks). 0 none

m2n:mpi

Communication via MPI with startup in separated communication spaces, using multiple communicators.

Example:

<m2n:mpi exchange-directory="" from="{string}" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>
Attribute Type Description Default Options
exchange-directory string Directory where connection information is exchanged. By default, the directory of startup is chosen, and both solvers have to be started in the same directory. `` none
from string First participant name involved in communication. For performance reasons, we recommend to use the participant with less ranks at the coupling interface as “from” in the m2n communication. none none
to string Second participant name involved in communication. none none
enforce-gather-scatter boolean Enforce the distributed communication to a gather-scatter scheme. Only recommended for trouble shooting. 0 none
use-two-level-initialization boolean Use a two-level initialization scheme. Recommended for large parallel runs (>5000 MPI ranks). 0 none

m2n:mpi-singleports

Communication via MPI with startup in separated communication spaces, using a single communicator

Example:

<m2n:mpi-singleports exchange-directory="" from="{string}" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>
Attribute Type Description Default Options
exchange-directory string Directory where connection information is exchanged. By default, the directory of startup is chosen, and both solvers have to be started in the same directory. `` none
from string First participant name involved in communication. For performance reasons, we recommend to use the participant with less ranks at the coupling interface as “from” in the m2n communication. none none
to string Second participant name involved in communication. none none
enforce-gather-scatter boolean Enforce the distributed communication to a gather-scatter scheme. Only recommended for trouble shooting. 0 none
use-two-level-initialization boolean Use a two-level initialization scheme. Recommended for large parallel runs (>5000 MPI ranks). 0 none

participant

Represents one solver using preCICE. At least two participants have to be defined.

Example:

<participant name="{string}">
  <write-data mesh="{string}" name="{string}"/>
  <read-data mesh="{string}" name="{string}"/>
  <mapping:rbf-thin-plate-splines solver-rtol="1e-09" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
  <action:multiply-by-area mesh="{string}" timing="{string}">
    ...
  </action:multiply-by-area>
  <export:vtk every-n-time-windows="1" directory="" every-iteration="0" normals="1"/>
  <watch-point mesh="{string}" name="{string}" coordinate="{vector}"/>
  <watch-integral mesh="{string}" name="{string}" scale-with-connectivity="{boolean}"/>
  <use-mesh safety-factor="0.5" from="" geometric-filter="on-slaves" name="{string}" provide="0"/>
  <master:sockets port="0" exchange-directory="" network="lo"/>
</participant>
Attribute Type Description Default Options
name string Name of the participant. Has to match the name given on construction of the precice::SolverInterface object used by the participant. none none

Valid Subtags:

write-data

Sets data to be written by the participant to preCICE. Data is defined by using the tag.

Example:

<write-data mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
mesh string Mesh the data belongs to. If data should be read/written to several meshes, this has to be specified separately for each mesh. none none
name string Name of the data. none none

read-data

Sets data to be read by the participant from preCICE. Data is defined by using the tag.

Example:

<read-data mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
mesh string Mesh the data belongs to. If data should be read/written to several meshes, this has to be specified separately for each mesh. none none
name string Name of the data. none none

mapping:rbf-thin-plate-splines

Global radial-basis-function mapping based on the thin plate splines.

Example:

<mapping:rbf-thin-plate-splines solver-rtol="1e-09" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
solver-rtol float Solver relative tolerance for convergence 1e-09 none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-multiquadrics

Global radial-basis-function mapping based on the multiquadrics RBF.

Example:

<mapping:rbf-multiquadrics shape-parameter="{float}" solver-rtol="1e-09" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
shape-parameter float Specific shape parameter for RBF basis function. none none
solver-rtol float Solver relative tolerance for convergence 1e-09 none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-inverse-multiquadrics

Global radial-basis-function mapping based on the inverse multiquadrics RBF.

Example:

<mapping:rbf-inverse-multiquadrics shape-parameter="{float}" solver-rtol="1e-09" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
shape-parameter float Specific shape parameter for RBF basis function. none none
solver-rtol float Solver relative tolerance for convergence 1e-09 none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-volume-splines

Global radial-basis-function mapping based on the volume-splines RBF.

Example:

<mapping:rbf-volume-splines solver-rtol="1e-09" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
solver-rtol float Solver relative tolerance for convergence 1e-09 none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-gaussian

Local radial-basis-function mapping based on the Gaussian RBF with a cut-off threshold.

Example:

<mapping:rbf-gaussian shape-parameter="{float}" solver-rtol="1e-09" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
shape-parameter float Specific shape parameter for RBF basis function. none none
solver-rtol float Solver relative tolerance for convergence 1e-09 none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-compact-tps-c2

Local radial-basis-function mapping based on the C2-polynomial RBF.

Example:

<mapping:rbf-compact-tps-c2 solver-rtol="1e-09" support-radius="{float}" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
solver-rtol float Solver relative tolerance for convergence 1e-09 none
support-radius float Support radius of each RBF basis function (global choice). none none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-compact-polynomial-c0

Local radial-basis-function mapping based on the C0-polynomial RBF.

Example:

<mapping:rbf-compact-polynomial-c0 solver-rtol="1e-09" support-radius="{float}" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
solver-rtol float Solver relative tolerance for convergence 1e-09 none
support-radius float Support radius of each RBF basis function (global choice). none none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:rbf-compact-polynomial-c6

Local radial-basis-function mapping based on the C6-polynomial RBF.

Example:

<mapping:rbf-compact-polynomial-c6 solver-rtol="1e-09" support-radius="{float}" constraint="{string}" direction="{string}" from="{string}" polynomial="separate" preallocation="tree" timing="initial" to="{string}" use-qr-decomposition="0" x-dead="0" y-dead="0" z-dead="0"/>
Attribute Type Description Default Options
solver-rtol float Solver relative tolerance for convergence 1e-09 none
support-radius float Support radius of each RBF basis function (global choice). none none
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
polynomial string Toggles use of the global polynomial separate on, off, separate
preallocation string Sets kind of preallocation for PETSc RBF implementation tree estimate, compute, off, save, tree
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none
use-qr-decomposition boolean If set to true, QR decomposition is used to solve the RBF system 0 none
x-dead boolean If set to true, the x axis will be ignored for the mapping 0 none
y-dead boolean If set to true, the y axis will be ignored for the mapping 0 none
z-dead boolean If set to true, the z axis will be ignored for the mapping 0 none

mapping:nearest-neighbor

Nearest-neighbour mapping which uses a rstar-spacial index tree to index meshes and run nearest-neighbour queries.

Example:

<mapping:nearest-neighbor constraint="{string}" direction="{string}" from="{string}" timing="initial" to="{string}"/>
Attribute Type Description Default Options
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none

mapping:nearest-projection

Nearest-projection mapping which uses a rstar-spacial index tree to index meshes and locate the nearest projections.

Example:

<mapping:nearest-projection constraint="{string}" direction="{string}" from="{string}" timing="initial" to="{string}"/>
Attribute Type Description Default Options
constraint string Use conservative to conserve the quantity of the data over the interface such as force or mass. Use consistent for normalized quantities such as temperature or pressure. none conservative, consistent
direction string Write mappings map written data prior to communication, thus in the same participant who writes the data. Read mappings map received data after communication, thus in the same participant who reads the data. none write, read
from string The mesh to map the data from. none none
timing string This allows to defer the mapping of the data to advance or to a manual call to mapReadDataTo and mapWriteDataFrom. initial initial, onadvance, ondemand
to string The mesh to map the data to. none none

action:multiply-by-area

Multiplies data values with mesh area associated to vertex holding the value.

Example:

<action:multiply-by-area mesh="{string}" timing="{string}">
  <target-data name="{string}"/>
</action:multiply-by-area>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:divide-by-area

Divides data values by mesh area associated to vertex holding the value.

Example:

<action:divide-by-area mesh="{string}" timing="{string}">
  <target-data name="{string}"/>
</action:divide-by-area>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:scale-by-computed-dt-ratio

Multiplies source data values by ratio of full dt / last computed dt, and writes the result into target data.

Example:

<action:scale-by-computed-dt-ratio mesh="{string}" timing="{string}">
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:scale-by-computed-dt-ratio>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

source-data

Single data to read from.

Example:

<source-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none
target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:scale-by-computed-dt-part-ratio

Multiplies source data values by ratio of full dt / computed dt part, and writes the result into target data.

Example:

<action:scale-by-computed-dt-part-ratio mesh="{string}" timing="{string}">
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:scale-by-computed-dt-part-ratio>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

source-data

Single data to read from.

Example:

<source-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none
target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:scale-by-dt

Multiplies source data values by last computed dt, and writes the result into target data.

Example:

<action:scale-by-dt mesh="{string}" timing="{string}">
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:scale-by-dt>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

source-data

Single data to read from.

Example:

<source-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none
target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:summation

Sums up multiple source data values and writes the result into target data.

Example:

<action:summation mesh="{string}" timing="{string}">
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:summation>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

source-data

Multiple data to read from.

Example:

<source-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none
target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:compute-curvature

Computes curvature values at mesh vertices.

Example:

<action:compute-curvature mesh="{string}" timing="{string}">
  <target-data name="{string}"/>
</action:compute-curvature>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

action:recorder

Records action invocations for testing purposes.

Example:

<action:recorder mesh="{string}" timing="{string}"/>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

action:python

Calls Python script to execute action. See preCICE file “src/action/PythonAction.py” for an overview.

Example:

<action:python mesh="{string}" timing="{string}">
  <path name=""/>
  <module name="{string}"/>
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:python>
Attribute Type Description Default Options
mesh string Determines mesh used in action. none none
timing string Determines when (relative to advancing the coupling scheme) the action is executed. none regular-prior, regular-post, on-exchange-prior, on-exchange-post, on-time-window-complete-post, write-mapping-prior, write-mapping-post, read-mapping-prior, read-mapping-post

Valid Subtags:

path

Directory path to Python module, i.e. script file. If it doesn’t occur, the current path is used

Example:

<path name=""/>
Attribute Type Description Default Options
name string The path to the directory of the module. `` none
module

Name of Python module, i.e. Python script file without file ending. The module name has to differ from existing (library) modules, otherwise, the existing module will be loaded instead of the user script.

Example:

<module name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none
source-data

Source data to be read is handed to the Python module. Can be omitted, if only a target data is needed.

Example:

<source-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none
target-data

Target data to be read and written to is handed to the Python module. Can be omitted, if only source data is needed.

Example:

<target-data name="{string}"/>
Attribute Type Description Default Options
name string Name of the data. none none

export:vtk

Exports meshes to VTK text files.

Example:

<export:vtk every-n-time-windows="1" directory="" every-iteration="0" normals="1"/>
Attribute Type Description Default Options
every-n-time-windows integer preCICE does an export every X time windows. Choose -1 for no exports. 1 none
directory string Directory to export the files to. `` none
every-iteration boolean Exports in every coupling (sub)iteration. For debug purposes. 0 none
normals boolean If set to on/yes, mesh normals (if available) are added to the export. 1 none

watch-point

A watch point can be used to follow the transient changes of data and mesh vertex coordinates at a given point

Example:

<watch-point mesh="{string}" name="{string}" coordinate="{vector}"/>
Attribute Type Description Default Options
mesh string Mesh to be watched. none none
name string Name of the watch point. Is taken in combination with the participant name to construct the filename the watch point data is written to. none none
coordinate vector The coordinates of the watch point. If the watch point is not put exactly on the mesh to observe, the closest projection of the point onto the mesh is considered instead, and values/coordinates are interpolated linearly to that point. none none

watch-integral

A watch integral can be used to follow the transient change of integral data and surface area for a given coupling mesh.

Example:

<watch-integral mesh="{string}" name="{string}" scale-with-connectivity="{boolean}"/>
Attribute Type Description Default Options
mesh string Mesh to be watched. none none
name string Name of the watch integral. Is taken in combination with the participant name to construct the filename the watch integral data is written to. none none
scale-with-connectivity boolean Whether the vertex data is scaled with the element area before summing up or not. In 2D, vertex data is scaled with the average length of neighboring edges. In 3D, vertex data is scaled with the average surface of neighboring triangles. If false, vertex data is directly summed up. none none

use-mesh

Makes a mesh (see tag available to a participant.

Example:

<use-mesh safety-factor="0.5" from="" geometric-filter="on-slaves" name="{string}" provide="0"/>
Attribute Type Description Default Options
safety-factor float If a mesh is received from another partipant (see tag ), it needs to bedecomposed at the receiving participant. To speed up this process, a geometric filter (see tag ), i.e. filtering by bounding boxes around the local mesh, can be used. This safety factor defines by which factor this local information is increased. An example: 0.5 means that the bounding box is 150% of its original size. 0.5 none
from string If a created mesh should be used by another solver, this attribute has to specify the creating participant’s name. The creator has to use the attribute “provide” to signal he is providing the mesh geometry. `` none
geometric-filter string If a mesh is received from another partipant (see tag ), it needs to bedecomposed at the receiving participant. To speed up this process, a geometric filter, i.e. filtering by bounding boxes around the local mesh, can be used. Two different variants are implemented: a filter "on-master" strategy, which is beneficial for a huge mesh and a low number of processors, and a filter "on-slaves" strategy, which performs better for a very high number of processors. Both result in the same distribution (if the safety factor is sufficiently large). "on-master" is not supported if you use two-level initialization. For very asymmetric cases, the filter can also be switched off completely ("no-filter"). on-slaves on-master, on-slaves, no-filter
name string Name of the mesh. none none
provide boolean If this attribute is set to “on”, the participant has to create the mesh geometry before initializing preCICE. 0 none

master:sockets

A solver in parallel needs a communication between its ranks. By default, the participant’s MPI_COM_WORLD is reused.Use this tag to use TCP/IP sockets instead.

Example:

<master:sockets port="0" exchange-directory="" network="lo"/>
Attribute Type Description Default Options
port integer Port number (16-bit unsigned integer) to be used for socket communiation. The default is “0”, what means that OS will dynamically search for a free port (if at least one exists) and bind it automatically. 0 none
exchange-directory string Directory where connection information is exchanged. By default, the directory of startup is chosen. `` none
network string Interface name to be used for socket communiation. Default is the cannonical name of the loopback interface of your platform. Might be different on supercomputing systems, e.g. “ib0” for the InfiniBand on SuperMUC. lo none

master:mpi

A solver in parallel needs a communication between its ranks. By default, the participant’s MPI_COM_WORLD is reused.Use this tag to use MPI with separated communication spaces instead instead.

Example:

<master:mpi exchange-directory=""/>
Attribute Type Description Default Options
exchange-directory string Directory where connection information is exchanged. By default, the directory of startup is chosen. `` none

master:mpi-single

A solver in parallel needs a communication between its ranks. By default (which is this option), the participant’s MPI_COM_WORLD is reused.This tag is only used to ensure backwards compatibility.

Example:

<master:mpi-single/>

coupling-scheme:serial-explicit

Explicit coupling scheme according to conventional serial staggered procedure (CSS).

Example:

<coupling-scheme:serial-explicit>
  <max-time value="{float}"/>
  <max-time-windows value="{integer}"/>
  <time-window-size value="-1" valid-digits="10" method="fixed"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
</coupling-scheme:serial-explicit>

Valid Subtags:

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>
Attribute Type Description Default Options
value float The value of the maximum simulation time. none none

max-time-windows

Defined the end of the simulation as a total count of time windows.

Example:

<max-time-windows value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum count of time windows. none none

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" valid-digits="10" method="fixed"/>
Attribute Type Description Default Options
value float The maximum time window size. -1 none
valid-digits integer Precision to use when checking for end of time windows used this many digits. \(\phi = 10^{-validDigits}\) 10 none
method string The method used to determine the time window size. Use fixed to fix the time window size for the participants. fixed fixed, first-participant

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>
Attribute Type Description Default Options
first string First participant to run the solver. none none
second string Second participant to run the solver. none none

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
Attribute Type Description Default Options
data string The data to exchange. none none
from string The participant sending the data. none none
mesh string The mesh which uses the data. none none
to string The participant receiving the data. none none
initialize boolean Should this data be initialized during initializeData? 0 none

coupling-scheme:parallel-explicit

Explicit coupling scheme according to conventional parallel staggered procedure (CPS).

Example:

<coupling-scheme:parallel-explicit>
  <max-time value="{float}"/>
  <max-time-windows value="{integer}"/>
  <time-window-size value="-1" valid-digits="10" method="fixed"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
</coupling-scheme:parallel-explicit>

Valid Subtags:

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>
Attribute Type Description Default Options
value float The value of the maximum simulation time. none none

max-time-windows

Defined the end of the simulation as a total count of time windows.

Example:

<max-time-windows value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum count of time windows. none none

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" valid-digits="10" method="fixed"/>
Attribute Type Description Default Options
value float The maximum time window size. -1 none
valid-digits integer Precision to use when checking for end of time windows used this many digits. \(\phi = 10^{-validDigits}\) 10 none
method string The method used to determine the time window size. Use fixed to fix the time window size for the participants. fixed fixed

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>
Attribute Type Description Default Options
first string First participant to run the solver. none none
second string Second participant to run the solver. none none

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
Attribute Type Description Default Options
data string The data to exchange. none none
from string The participant sending the data. none none
mesh string The mesh which uses the data. none none
to string The participant receiving the data. none none
initialize boolean Should this data be initialized during initializeData? 0 none

coupling-scheme:serial-implicit

Implicit coupling scheme according to block Gauss-Seidel iterations (S-System). Improved implicit iterations are achieved by using a acceleration (recommended!).

Example:

<coupling-scheme:serial-implicit>
  <max-time value="{float}"/>
  <max-time-windows value="{integer}"/>
  <time-window-size value="-1" valid-digits="10" method="fixed"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
  <acceleration:constant>
    ...
  </acceleration:constant>
  <absolute-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <residual-relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <min-iteration-convergence-measure min-iterations="{integer}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <max-iterations value="{integer}"/>
  <extrapolation-order value="{integer}"/>
</coupling-scheme:serial-implicit>

Valid Subtags:

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>
Attribute Type Description Default Options
value float The value of the maximum simulation time. none none

max-time-windows

Defined the end of the simulation as a total count of time windows.

Example:

<max-time-windows value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum count of time windows. none none

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" valid-digits="10" method="fixed"/>
Attribute Type Description Default Options
value float The maximum time window size. -1 none
valid-digits integer Precision to use when checking for end of time windows used this many digits. \(\phi = 10^{-validDigits}\) 10 none
method string The method used to determine the time window size. Use fixed to fix the time window size for the participants. fixed fixed, first-participant

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>
Attribute Type Description Default Options
first string First participant to run the solver. none none
second string Second participant to run the solver. none none

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
Attribute Type Description Default Options
data string The data to exchange. none none
from string The participant sending the data. none none
mesh string The mesh which uses the data. none none
to string The participant receiving the data. none none
initialize boolean Should this data be initialized during initializeData? 0 none

acceleration:constant

Accelerates coupling data with constant underrelaxation.

Example:

<acceleration:constant>
  <relaxation value="{float}"/>
</acceleration:constant>

Valid Subtags:

relaxation

Example:

<relaxation value="{float}"/>
Attribute Type Description Default Options
value float Constant relaxation factor. none none

acceleration:aitken

Accelerates coupling data with dynamic Aitken under-relaxation.

Example:

<acceleration:aitken>
  <initial-relaxation value="{float}"/>
  <data mesh="{string}" name="{string}"/>
</acceleration:aitken>

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
data

The data used to compute the acceleration.

Example:

<data mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none

acceleration:IQN-ILS

Accelerates coupling data with the interface quasi-Newton inverse least-squares method.

Example:

<acceleration:IQN-ILS>
  <initial-relaxation value="{float}" enforce="0"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner freeze-after="-1" type="{string}"/>
</acceleration:IQN-ILS>

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
enforce boolean Enforce initial relaxation in every time window. 0 none
max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian.

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian.

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer The number of time windows. none none
data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none
filter

Type of filtering technique that is used to maintain good conditioning in the least-squares system. Possible filters:

  • QR1-filter: updateQR-dec with (relative) test \(R(i,i) < \epsilon *\lVert R\rVert_F\)
  • QR1_absolute-filter: updateQR-dec with (absolute) test \(R(i, i) < \epsilon\)
  • QR2-filter: en-block QR-dec with test \(\lVert v_\text{orth} \rVert_2 < \epsilon * \lVert v \rVert_2\)

Please note that a QR1 is based on Given’s rotations whereas QR2 uses modified Gram-Schmidt. This can give different results even when no columns are filtered out.

Example:

<filter limit="1e-16" type="{string}"/>
Attribute Type Description Default Options
limit float Limit eps of the filter. 1e-16 none
type string Type of the filter. none QR1, QR1-absolute, QR2
preconditioner

To improve the performance of a parallel or a multi coupling schemes a preconditioner can be applied. A constant preconditioner scales every acceleration data by a constant value, which you can define as an attribute of data. A value preconditioner scales every acceleration data by the norm of the data in the previous time window. A residual preconditioner scales every acceleration data by the current residual. A residual-sum preconditioner scales every acceleration data by the sum of the residuals from the current time window.

Example:

<preconditioner freeze-after="-1" type="{string}"/>
Attribute Type Description Default Options
freeze-after integer After the given number of time steps, the preconditioner weights are frozen and the preconditioner acts like a constant preconditioner. -1 none
type string The type of the preconditioner. none constant, value, residual, residual-sum

acceleration:IQN-IMVJ

Accelerates coupling data with the interface quasi-Newton inverse multi-vector Jacobian method.

Example:

<acceleration:IQN-IMVJ always-build-jacobian="0">
  <initial-relaxation value="{float}" enforce="0"/>
  <imvj-restart-mode truncation-threshold="0.0001" chunk-size="8" reused-time-windows-at-restart="8" type="RS-SVD"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner freeze-after="-1" type="{string}"/>
</acceleration:IQN-IMVJ>
Attribute Type Description Default Options
always-build-jacobian boolean If set to true, the IMVJ will set up the Jacobian matrix in each coupling iteration, which is inefficient. If set to false (or not set) the Jacobian is only build in the last iteration and the updates are computed using (relatively) cheap MATVEC products. 0 none

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
enforce boolean Enforce initial relaxation in every time window. 0 none
imvj-restart-mode

Type of IMVJ restart mode that is used:

  • no-restart: IMVJ runs in normal mode with explicit representation of Jacobian
  • RS-ZERO: IMVJ runs in restart mode. After M time steps all Jacobain information is dropped, restart with no information
  • RS-LS: IMVJ runs in restart mode. After M time steps a IQN-LS like approximation for the initial guess of the Jacobian is computed.
  • RS-SVD: IMVJ runs in restart mode. After M time steps a truncated SVD of the Jacobian is updated.
  • RS-SLIDE: IMVJ runs in sliding window restart mode.

Example:

<imvj-restart-mode truncation-threshold="0.0001" chunk-size="8" reused-time-windows-at-restart="8" type="RS-SVD"/>
Attribute Type Description Default Options
truncation-threshold float If IMVJ restart-mode=RS-SVD, the truncation threshold for the updated SVD can be set. 0.0001 none
chunk-size integer Specifies the number of time steps M after which the IMVJ restarts, if run in restart-mode. Defaul value is M=8. 8 none
reused-time-windows-at-restart integer If IMVJ restart-mode=RS-LS, the number of reused time steps at restart can be specified. 8 none
type string Type of the restart mode. RS-SVD no-restart, RS-0, RS-LS, RS-SVD, RS-SLIDE
max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian.

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian.

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none
filter

Type of filtering technique that is used to maintain good conditioning in the least-squares system. Possible filters:

  • QR1-filter: updateQR-dec with (relative) test \(R(i,i) < \epsilon *\lVert R\rVert_F\)
  • QR1_absolute-filter: updateQR-dec with (absolute) test \(R(i, i) < \epsilon\)
  • QR2-filter: en-block QR-dec with test \(\lVert v_\text{orth} \rVert_2 < \epsilon * \lVert v \rVert_2\)

Please note that a QR1 is based on Given’s rotations whereas QR2 uses modified Gram-Schmidt. This can give different results even when no columns are filtered out.

Example:

<filter limit="1e-16" type="{string}"/>
Attribute Type Description Default Options
limit float Limit eps of the filter. 1e-16 none
type string Type of the filter. none QR1, QR1-absolute, QR2
preconditioner

To improve the performance of a parallel or a multi coupling schemes a preconditioner can be applied. A constant preconditioner scales every acceleration data by a constant value, which you can define as an attribute of data.

  • A value preconditioner scales every acceleration data by the norm of the data in the previous time window.
  • A residual preconditioner scales every acceleration data by the current residual.
  • A residual-sum preconditioner scales every acceleration data by the sum of the residuals from the current time window.

Example:

<preconditioner freeze-after="-1" type="{string}"/>
Attribute Type Description Default Options
freeze-after integer After the given number of time steps, the preconditioner weights are frozen and the preconditioner acts like a constant preconditioner. -1 none
type string Type of the preconditioner. none constant, value, residual, residual-sum

acceleration:broyden

Accelerates coupling data with the (single-vector) Broyden method.

Example:

<acceleration:broyden>
  <initial-relaxation value="{float}" enforce="0"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
</acceleration:broyden>

Valid Subtags:

initial-relaxation

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float   none none
enforce boolean   0 none
max-used-iterations

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer   none none
time-windows-reused

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer   none none
data

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string   none none
name string   none none

absolute-convergence-measure

Absolute convergence criterion based on the two-norm difference of data values between iterations. $$\left\lVert H(x^k) - x^k \right\rVert_2 < \text{limit}$$

Example:

<absolute-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in ((0, 1]). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

relative-convergence-measure

Relative convergence criterion based on the relative two-norm difference of data values between iterations. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^k) \right\rVert_2} < \text{limit} $$

Example:

<relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in \((0, 1]\). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

residual-relative-convergence-measure

Residual relative convergence criterion based on the relative two-norm differences of data values between iterations. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^{k-1}) - x^{k-1} \right\rVert_2} < \text{limit}$$

Example:

<residual-relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in ((0, 1]). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

min-iteration-convergence-measure

Convergence criterion used to ensure a miminimal amount of iterations. Specifying a mesh and data is required for technical reasons and does not influence the measure.

Example:

<min-iteration-convergence-measure min-iterations="{integer}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
min-iterations integer The minimal amount of iterations. none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

max-iterations

Allows to specify a maximum amount of iterations per time window.

Example:

<max-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum value of iterations. none none

extrapolation-order

Sets order of predictor of interface values for first participant.

Example:

<extrapolation-order value="{integer}"/>
Attribute Type Description Default Options
value integer The extrapolation order to use. none none

coupling-scheme:parallel-implicit

Parallel Implicit coupling scheme according to block Jacobi iterations (V-System). Improved implicit iterations are achieved by using a acceleration (recommended!).

Example:

<coupling-scheme:parallel-implicit>
  <max-time value="{float}"/>
  <max-time-windows value="{integer}"/>
  <time-window-size value="-1" valid-digits="10" method="fixed"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
  <acceleration:constant>
    ...
  </acceleration:constant>
  <absolute-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <residual-relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <min-iteration-convergence-measure min-iterations="{integer}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <max-iterations value="{integer}"/>
  <extrapolation-order value="{integer}"/>
</coupling-scheme:parallel-implicit>

Valid Subtags:

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>
Attribute Type Description Default Options
value float The value of the maximum simulation time. none none

max-time-windows

Defined the end of the simulation as a total count of time windows.

Example:

<max-time-windows value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum count of time windows. none none

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" valid-digits="10" method="fixed"/>
Attribute Type Description Default Options
value float The maximum time window size. -1 none
valid-digits integer Precision to use when checking for end of time windows used this many digits. \(\phi = 10^{-validDigits}\) 10 none
method string The method used to determine the time window size. Use fixed to fix the time window size for the participants. fixed fixed

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>
Attribute Type Description Default Options
first string First participant to run the solver. none none
second string Second participant to run the solver. none none

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
Attribute Type Description Default Options
data string The data to exchange. none none
from string The participant sending the data. none none
mesh string The mesh which uses the data. none none
to string The participant receiving the data. none none
initialize boolean Should this data be initialized during initializeData? 0 none

acceleration:constant

Accelerates coupling data with constant underrelaxation.

Example:

<acceleration:constant>
  <relaxation value="{float}"/>
</acceleration:constant>

Valid Subtags:

relaxation

Example:

<relaxation value="{float}"/>
Attribute Type Description Default Options
value float Constant relaxation factor. none none

acceleration:aitken

Accelerates coupling data with dynamic Aitken under-relaxation.

Example:

<acceleration:aitken>
  <initial-relaxation value="{float}"/>
  <data mesh="{string}" name="{string}"/>
</acceleration:aitken>

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
data

The data used to compute the acceleration.

Example:

<data mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none

acceleration:IQN-ILS

Accelerates coupling data with the interface quasi-Newton inverse least-squares method.

Example:

<acceleration:IQN-ILS>
  <initial-relaxation value="{float}" enforce="0"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner freeze-after="-1" type="{string}"/>
</acceleration:IQN-ILS>

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
enforce boolean Enforce initial relaxation in every time window. 0 none
max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian.

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian.

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer The number of time windows. none none
data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none
filter

Type of filtering technique that is used to maintain good conditioning in the least-squares system. Possible filters:

  • QR1-filter: updateQR-dec with (relative) test \(R(i,i) < \epsilon *\lVert R\rVert_F\)
  • QR1_absolute-filter: updateQR-dec with (absolute) test \(R(i, i) < \epsilon\)
  • QR2-filter: en-block QR-dec with test \(\lVert v_\text{orth} \rVert_2 < \epsilon * \lVert v \rVert_2\)

Please note that a QR1 is based on Given’s rotations whereas QR2 uses modified Gram-Schmidt. This can give different results even when no columns are filtered out.

Example:

<filter limit="1e-16" type="{string}"/>
Attribute Type Description Default Options
limit float Limit eps of the filter. 1e-16 none
type string Type of the filter. none QR1, QR1-absolute, QR2
preconditioner

To improve the performance of a parallel or a multi coupling schemes a preconditioner can be applied. A constant preconditioner scales every acceleration data by a constant value, which you can define as an attribute of data. A value preconditioner scales every acceleration data by the norm of the data in the previous time window. A residual preconditioner scales every acceleration data by the current residual. A residual-sum preconditioner scales every acceleration data by the sum of the residuals from the current time window.

Example:

<preconditioner freeze-after="-1" type="{string}"/>
Attribute Type Description Default Options
freeze-after integer After the given number of time steps, the preconditioner weights are frozen and the preconditioner acts like a constant preconditioner. -1 none
type string The type of the preconditioner. none constant, value, residual, residual-sum

acceleration:IQN-IMVJ

Accelerates coupling data with the interface quasi-Newton inverse multi-vector Jacobian method.

Example:

<acceleration:IQN-IMVJ always-build-jacobian="0">
  <initial-relaxation value="{float}" enforce="0"/>
  <imvj-restart-mode truncation-threshold="0.0001" chunk-size="8" reused-time-windows-at-restart="8" type="RS-SVD"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner freeze-after="-1" type="{string}"/>
</acceleration:IQN-IMVJ>
Attribute Type Description Default Options
always-build-jacobian boolean If set to true, the IMVJ will set up the Jacobian matrix in each coupling iteration, which is inefficient. If set to false (or not set) the Jacobian is only build in the last iteration and the updates are computed using (relatively) cheap MATVEC products. 0 none

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
enforce boolean Enforce initial relaxation in every time window. 0 none
imvj-restart-mode

Type of IMVJ restart mode that is used:

  • no-restart: IMVJ runs in normal mode with explicit representation of Jacobian
  • RS-ZERO: IMVJ runs in restart mode. After M time steps all Jacobain information is dropped, restart with no information
  • RS-LS: IMVJ runs in restart mode. After M time steps a IQN-LS like approximation for the initial guess of the Jacobian is computed.
  • RS-SVD: IMVJ runs in restart mode. After M time steps a truncated SVD of the Jacobian is updated.
  • RS-SLIDE: IMVJ runs in sliding window restart mode.

Example:

<imvj-restart-mode truncation-threshold="0.0001" chunk-size="8" reused-time-windows-at-restart="8" type="RS-SVD"/>
Attribute Type Description Default Options
truncation-threshold float If IMVJ restart-mode=RS-SVD, the truncation threshold for the updated SVD can be set. 0.0001 none
chunk-size integer Specifies the number of time steps M after which the IMVJ restarts, if run in restart-mode. Defaul value is M=8. 8 none
reused-time-windows-at-restart integer If IMVJ restart-mode=RS-LS, the number of reused time steps at restart can be specified. 8 none
type string Type of the restart mode. RS-SVD no-restart, RS-0, RS-LS, RS-SVD, RS-SLIDE
max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian.

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian.

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none
filter

Type of filtering technique that is used to maintain good conditioning in the least-squares system. Possible filters:

  • QR1-filter: updateQR-dec with (relative) test \(R(i,i) < \epsilon *\lVert R\rVert_F\)
  • QR1_absolute-filter: updateQR-dec with (absolute) test \(R(i, i) < \epsilon\)
  • QR2-filter: en-block QR-dec with test \(\lVert v_\text{orth} \rVert_2 < \epsilon * \lVert v \rVert_2\)

Please note that a QR1 is based on Given’s rotations whereas QR2 uses modified Gram-Schmidt. This can give different results even when no columns are filtered out.

Example:

<filter limit="1e-16" type="{string}"/>
Attribute Type Description Default Options
limit float Limit eps of the filter. 1e-16 none
type string Type of the filter. none QR1, QR1-absolute, QR2
preconditioner

To improve the performance of a parallel or a multi coupling schemes a preconditioner can be applied. A constant preconditioner scales every acceleration data by a constant value, which you can define as an attribute of data.

  • A value preconditioner scales every acceleration data by the norm of the data in the previous time window.
  • A residual preconditioner scales every acceleration data by the current residual.
  • A residual-sum preconditioner scales every acceleration data by the sum of the residuals from the current time window.

Example:

<preconditioner freeze-after="-1" type="{string}"/>
Attribute Type Description Default Options
freeze-after integer After the given number of time steps, the preconditioner weights are frozen and the preconditioner acts like a constant preconditioner. -1 none
type string Type of the preconditioner. none constant, value, residual, residual-sum

acceleration:broyden

Accelerates coupling data with the (single-vector) Broyden method.

Example:

<acceleration:broyden>
  <initial-relaxation value="{float}" enforce="0"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
</acceleration:broyden>

Valid Subtags:

initial-relaxation

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float   none none
enforce boolean   0 none
max-used-iterations

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer   none none
time-windows-reused

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer   none none
data

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string   none none
name string   none none

absolute-convergence-measure

Absolute convergence criterion based on the two-norm difference of data values between iterations. $$\left\lVert H(x^k) - x^k \right\rVert_2 < \text{limit}$$

Example:

<absolute-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in ((0, 1]). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

relative-convergence-measure

Relative convergence criterion based on the relative two-norm difference of data values between iterations. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^k) \right\rVert_2} < \text{limit} $$

Example:

<relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in \((0, 1]\). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

residual-relative-convergence-measure

Residual relative convergence criterion based on the relative two-norm differences of data values between iterations. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^{k-1}) - x^{k-1} \right\rVert_2} < \text{limit}$$

Example:

<residual-relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in ((0, 1]). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

min-iteration-convergence-measure

Convergence criterion used to ensure a miminimal amount of iterations. Specifying a mesh and data is required for technical reasons and does not influence the measure.

Example:

<min-iteration-convergence-measure min-iterations="{integer}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
min-iterations integer The minimal amount of iterations. none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

max-iterations

Allows to specify a maximum amount of iterations per time window.

Example:

<max-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum value of iterations. none none

extrapolation-order

Sets order of predictor of interface values for first participant.

Example:

<extrapolation-order value="{integer}"/>
Attribute Type Description Default Options
value integer The extrapolation order to use. none none

coupling-scheme:multi

Multi coupling scheme according to block Jacobi iterations. Improved implicit iterations are achieved by using a acceleration (recommended!).

Example:

<coupling-scheme:multi>
  <max-time value="{float}"/>
  <max-time-windows value="{integer}"/>
  <time-window-size value="-1" valid-digits="10" method="fixed"/>
  <participant name="{string}" control="0"/>
  <exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
  <acceleration:constant>
    ...
  </acceleration:constant>
  <absolute-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <residual-relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <min-iteration-convergence-measure min-iterations="{integer}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
  <max-iterations value="{integer}"/>
  <extrapolation-order value="{integer}"/>
</coupling-scheme:multi>

Valid Subtags:

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>
Attribute Type Description Default Options
value float The value of the maximum simulation time. none none

max-time-windows

Defined the end of the simulation as a total count of time windows.

Example:

<max-time-windows value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum count of time windows. none none

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" valid-digits="10" method="fixed"/>
Attribute Type Description Default Options
value float The maximum time window size. -1 none
valid-digits integer Precision to use when checking for end of time windows used this many digits. \(\phi = 10^{-validDigits}\) 10 none
method string The method used to determine the time window size. Use fixed to fix the time window size for the participants. fixed fixed

participant

Example:

<participant name="{string}" control="0"/>
Attribute Type Description Default Options
name string Name of the participant. none none
control boolean Does this participant control the coupling? 0 none

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>
Attribute Type Description Default Options
data string The data to exchange. none none
from string The participant sending the data. none none
mesh string The mesh which uses the data. none none
to string The participant receiving the data. none none
initialize boolean Should this data be initialized during initializeData? 0 none

acceleration:constant

Accelerates coupling data with constant underrelaxation.

Example:

<acceleration:constant>
  <relaxation value="{float}"/>
</acceleration:constant>

Valid Subtags:

relaxation

Example:

<relaxation value="{float}"/>
Attribute Type Description Default Options
value float Constant relaxation factor. none none

acceleration:aitken

Accelerates coupling data with dynamic Aitken under-relaxation.

Example:

<acceleration:aitken>
  <initial-relaxation value="{float}"/>
  <data mesh="{string}" name="{string}"/>
</acceleration:aitken>

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
data

The data used to compute the acceleration.

Example:

<data mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none

acceleration:IQN-ILS

Accelerates coupling data with the interface quasi-Newton inverse least-squares method.

Example:

<acceleration:IQN-ILS>
  <initial-relaxation value="{float}" enforce="0"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner freeze-after="-1" type="{string}"/>
</acceleration:IQN-ILS>

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
enforce boolean Enforce initial relaxation in every time window. 0 none
max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian.

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian.

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer The number of time windows. none none
data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none
filter

Type of filtering technique that is used to maintain good conditioning in the least-squares system. Possible filters:

  • QR1-filter: updateQR-dec with (relative) test \(R(i,i) < \epsilon *\lVert R\rVert_F\)
  • QR1_absolute-filter: updateQR-dec with (absolute) test \(R(i, i) < \epsilon\)
  • QR2-filter: en-block QR-dec with test \(\lVert v_\text{orth} \rVert_2 < \epsilon * \lVert v \rVert_2\)

Please note that a QR1 is based on Given’s rotations whereas QR2 uses modified Gram-Schmidt. This can give different results even when no columns are filtered out.

Example:

<filter limit="1e-16" type="{string}"/>
Attribute Type Description Default Options
limit float Limit eps of the filter. 1e-16 none
type string Type of the filter. none QR1, QR1-absolute, QR2
preconditioner

To improve the performance of a parallel or a multi coupling schemes a preconditioner can be applied. A constant preconditioner scales every acceleration data by a constant value, which you can define as an attribute of data. A value preconditioner scales every acceleration data by the norm of the data in the previous time window. A residual preconditioner scales every acceleration data by the current residual. A residual-sum preconditioner scales every acceleration data by the sum of the residuals from the current time window.

Example:

<preconditioner freeze-after="-1" type="{string}"/>
Attribute Type Description Default Options
freeze-after integer After the given number of time steps, the preconditioner weights are frozen and the preconditioner acts like a constant preconditioner. -1 none
type string The type of the preconditioner. none constant, value, residual, residual-sum

acceleration:IQN-IMVJ

Accelerates coupling data with the interface quasi-Newton inverse multi-vector Jacobian method.

Example:

<acceleration:IQN-IMVJ always-build-jacobian="0">
  <initial-relaxation value="{float}" enforce="0"/>
  <imvj-restart-mode truncation-threshold="0.0001" chunk-size="8" reused-time-windows-at-restart="8" type="RS-SVD"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner freeze-after="-1" type="{string}"/>
</acceleration:IQN-IMVJ>
Attribute Type Description Default Options
always-build-jacobian boolean If set to true, the IMVJ will set up the Jacobian matrix in each coupling iteration, which is inefficient. If set to false (or not set) the Jacobian is only build in the last iteration and the updates are computed using (relatively) cheap MATVEC products. 0 none

Valid Subtags:

initial-relaxation

Initial relaxation factor.

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float Initial relaxation factor. none none
enforce boolean Enforce initial relaxation in every time window. 0 none
imvj-restart-mode

Type of IMVJ restart mode that is used:

  • no-restart: IMVJ runs in normal mode with explicit representation of Jacobian
  • RS-ZERO: IMVJ runs in restart mode. After M time steps all Jacobain information is dropped, restart with no information
  • RS-LS: IMVJ runs in restart mode. After M time steps a IQN-LS like approximation for the initial guess of the Jacobian is computed.
  • RS-SVD: IMVJ runs in restart mode. After M time steps a truncated SVD of the Jacobian is updated.
  • RS-SLIDE: IMVJ runs in sliding window restart mode.

Example:

<imvj-restart-mode truncation-threshold="0.0001" chunk-size="8" reused-time-windows-at-restart="8" type="RS-SVD"/>
Attribute Type Description Default Options
truncation-threshold float If IMVJ restart-mode=RS-SVD, the truncation threshold for the updated SVD can be set. 0.0001 none
chunk-size integer Specifies the number of time steps M after which the IMVJ restarts, if run in restart-mode. Defaul value is M=8. 8 none
reused-time-windows-at-restart integer If IMVJ restart-mode=RS-LS, the number of reused time steps at restart can be specified. 8 none
type string Type of the restart mode. RS-SVD no-restart, RS-0, RS-LS, RS-SVD, RS-SLIDE
max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian.

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian.

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer The number of columns. none none
data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string The name of the mesh which holds the data. none none
name string The name of the data. none none
filter

Type of filtering technique that is used to maintain good conditioning in the least-squares system. Possible filters:

  • QR1-filter: updateQR-dec with (relative) test \(R(i,i) < \epsilon *\lVert R\rVert_F\)
  • QR1_absolute-filter: updateQR-dec with (absolute) test \(R(i, i) < \epsilon\)
  • QR2-filter: en-block QR-dec with test \(\lVert v_\text{orth} \rVert_2 < \epsilon * \lVert v \rVert_2\)

Please note that a QR1 is based on Given’s rotations whereas QR2 uses modified Gram-Schmidt. This can give different results even when no columns are filtered out.

Example:

<filter limit="1e-16" type="{string}"/>
Attribute Type Description Default Options
limit float Limit eps of the filter. 1e-16 none
type string Type of the filter. none QR1, QR1-absolute, QR2
preconditioner

To improve the performance of a parallel or a multi coupling schemes a preconditioner can be applied. A constant preconditioner scales every acceleration data by a constant value, which you can define as an attribute of data.

  • A value preconditioner scales every acceleration data by the norm of the data in the previous time window.
  • A residual preconditioner scales every acceleration data by the current residual.
  • A residual-sum preconditioner scales every acceleration data by the sum of the residuals from the current time window.

Example:

<preconditioner freeze-after="-1" type="{string}"/>
Attribute Type Description Default Options
freeze-after integer After the given number of time steps, the preconditioner weights are frozen and the preconditioner acts like a constant preconditioner. -1 none
type string Type of the preconditioner. none constant, value, residual, residual-sum

acceleration:broyden

Accelerates coupling data with the (single-vector) Broyden method.

Example:

<acceleration:broyden>
  <initial-relaxation value="{float}" enforce="0"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" mesh="{string}" name="{string}"/>
</acceleration:broyden>

Valid Subtags:

initial-relaxation

Example:

<initial-relaxation value="{float}" enforce="0"/>
Attribute Type Description Default Options
value float   none none
enforce boolean   0 none
max-used-iterations

Example:

<max-used-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer   none none
time-windows-reused

Example:

<time-windows-reused value="{integer}"/>
Attribute Type Description Default Options
value integer   none none
data

Example:

<data scaling="1" mesh="{string}" name="{string}"/>
Attribute Type Description Default Options
scaling float To improve the performance of a parallel or a multi coupling schemes, data values can be manually scaled. We recommend, however, to use an automatic scaling via a preconditioner. 1 none
mesh string   none none
name string   none none

absolute-convergence-measure

Absolute convergence criterion based on the two-norm difference of data values between iterations. $$\left\lVert H(x^k) - x^k \right\rVert_2 < \text{limit}$$

Example:

<absolute-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in ((0, 1]). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

relative-convergence-measure

Relative convergence criterion based on the relative two-norm difference of data values between iterations. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^k) \right\rVert_2} < \text{limit} $$

Example:

<relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in \((0, 1]\). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

residual-relative-convergence-measure

Residual relative convergence criterion based on the relative two-norm differences of data values between iterations. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^{k-1}) - x^{k-1} \right\rVert_2} < \text{limit}$$

Example:

<residual-relative-convergence-measure limit="{float}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
limit float Limit under which the measure is considered to have converged. Must be in ((0, 1]). none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

min-iteration-convergence-measure

Convergence criterion used to ensure a miminimal amount of iterations. Specifying a mesh and data is required for technical reasons and does not influence the measure.

Example:

<min-iteration-convergence-measure min-iterations="{integer}" data="{string}" mesh="{string}" strict="0" suffices="0"/>
Attribute Type Description Default Options
min-iterations integer The minimal amount of iterations. none none
data string Data to be measured. none none
mesh string Mesh holding the data. none none
strict boolean If true, non-convergence of this measure ends the simulation. “strict” overrules “suffices”. 0 none
suffices boolean If true, convergence of this measure is sufficient for overall convergence. 0 none

max-iterations

Allows to specify a maximum amount of iterations per time window.

Example:

<max-iterations value="{integer}"/>
Attribute Type Description Default Options
value integer The maximum value of iterations. none none

extrapolation-order

Sets order of predictor of interface values for first participant.

Example:

<extrapolation-order value="{integer}"/>
Attribute Type Description Default Options
value integer The extrapolation order to use. none none