./precice-tools md > reference.md

precice-configuration

Main tag containing preCICE configuration.

Example:

<precice-configuration experimental="false" allow-remeshing="false" wait-in-finalize="false">
  <log enabled="true">
    ...
  </log>
  <profiling mode="fundamental" flush-every="50" directory="." synchronize="false"/>
  <data:scalar name="{string}" waveform-degree="1"/>
  <mesh name="{string}" dimensions="{integer}">
    ...
  </mesh>
  <m2n:sockets port="0" network="lo" exchange-directory="." acceptor="{string}" connector="{string}" enforce-gather-scatter="false" use-two-level-initialization="false"/>
  <participant name="{string}">
    ...
  </participant>
  <coupling-scheme:serial-explicit>
    ...
  </coupling-scheme:serial-explicit>
</precice-configuration>

Valid Subtags:

• log 0..1
• profiling 0..1
• mesh 1..*
• participant 1..*
• coupling-scheme
  • serial-explicit 0..*
  • parallel-explicit 0..*
  • serial-implicit 0..*
  • parallel-implicit 0..*
  • multi 0..*
• data
  • scalar 0..*
  • vector 0..*
• m2n
  • sockets 0..*
  • mpi-multiple-ports 0..*
  • mpi 0..*

log

Configures logging sinks based on Boost log.

Example:

<log enabled="true">
  <sink type="stream" output="stdout" format="(%Rank%) %TimeStamp(format="%H:%M:%S")% [%Module%]:%Line% in %Function%: %ColorizedSeverity%%Message%" filter="(%Severity% > debug) and not ((%Severity% = info) and (%Rank% != 0))" enabled="true"/>
</log>

Valid Subtags:

• sink 0..*

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 %TimeStamp%, %Runtime%, %Severity%, %ColorizedSeverity%, %File%, %Line%, %Function%, %Module%, %Rank%, and %Participant%. The boolean attribute %preCICE% is true for all log entries originating from preCICE.

Example:

<sink type="stream" output="stdout" format="(%Rank%) %TimeStamp(format="%H:%M:%S")% [%Module%]:%Line% in %Function%: %ColorizedSeverity%%Message%" filter="(%Severity% > debug) and not ((%Severity% = info) and (%Rank% != 0))" enabled="true"/>

profiling

Allows configuring the profiling functionality of preCICE.

Example:

<profiling mode="fundamental" flush-every="50" directory="." synchronize="false"/>

data:scalar

Defines a scalar data set to be assigned to meshes.

Example:

<data:scalar name="{string}" waveform-degree="1"/>

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 of the mesh.

Example:

<data:vector name="{string}" waveform-degree="1"/>

mesh

Surface mesh consisting of vertices and optional connectivity information. The vertices of a mesh can carry data, configured by tags . The mesh coordinates have to be defined by a participant (see tag ).

Example:

<mesh name="{string}" dimensions="{integer}">
  <use-data name="{string}"/>
</mesh>

Valid Subtags:

• use-data 0..*

use-data

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

Example:

<use-data name="{string}"/>

m2n:sockets

Communication via Sockets.

Example:

<m2n:sockets port="0" network="lo" exchange-directory="." acceptor="{string}" connector="{string}" enforce-gather-scatter="false" use-two-level-initialization="false"/>

m2n:mpi-multiple-ports

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

Example:

<m2n:mpi-multiple-ports exchange-directory="." acceptor="{string}" connector="{string}" enforce-gather-scatter="false" use-two-level-initialization="false"/>

m2n:mpi

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

Example:

<m2n:mpi exchange-directory="." acceptor="{string}" connector="{string}" enforce-gather-scatter="false" use-two-level-initialization="false"/>

participant

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

Example:

<participant name="{string}">
  <write-data name="{string}" mesh="{string}"/>
  <read-data name="{string}" mesh="{string}"/>
  <mapping:nearest-neighbor from="" to="" direction="{string}" constraint="{string}"/>
  <action:multiply-by-area timing="{string}" mesh="{string}">
    ...
  </action:multiply-by-area>
  <export:vtk directory="." every-n-time-windows="1" every-iteration="false"/>
  <watch-point name="{string}" mesh="{string}" coordinate="{vector}"/>
  <watch-integral name="{string}" mesh="{string}" scale-with-connectivity="{boolean}"/>
  <provide-mesh name="{string}"/>
  <receive-mesh name="{string}" api-access="false" direct-access="false" geometric-filter="on-secondary-ranks" from="{string}" safety-factor="0.5"/>
  <intra-comm:sockets port="0" network="lo" exchange-directory="."/>
</participant>

Valid Subtags:

• write-data 0..*
• read-data 0..*
• watch-point 0..*
• watch-integral 0..*
• provide-mesh 0..*
• receive-mesh 0..*
• action
  • multiply-by-area 0..*
  • divide-by-area 0..*
  • summation 0..*
  • recorder 0..*
  • python 0..*
• export
  • vtk 0..*
  • vtu 0..*
  • vtp 0..*
  • csv 0..*
• intra-comm
  • sockets 0..1
  • mpi 0..1
• mapping
  • nearest-neighbor 0..*
  • nearest-projection 0..*
  • nearest-neighbor-gradient 0..*
  • linear-cell-interpolation 0..*
  • rbf-global-iterative 0..*
  • rbf-global-direct 0..*
  • rbf-pum-direct 0..*
  • rbf 0..*
  • axial-geometric-multiscale 0..*
  • radial-geometric-multiscale 0..*

write-data

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

Example:

<write-data name="{string}" mesh="{string}"/>

read-data

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

Example:

<read-data name="{string}" mesh="{string}"/>

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 from="" to="" direction="{string}" constraint="{string}"/>

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 from="" to="" direction="{string}" constraint="{string}"/>

mapping:nearest-neighbor-gradient

Nearest-neighbor-gradient mapping which uses nearest-neighbor mapping with an additional linear approximation using gradient data.

Example:

<mapping:nearest-neighbor-gradient from="" to="" direction="{string}" constraint="{string}"/>

mapping:linear-cell-interpolation

Linear cell interpolation mapping which uses a rstar-spacial index tree to index meshes and locate the nearest cell. Only supports 2D meshes.

Example:

<mapping:linear-cell-interpolation from="" to="" direction="{string}" constraint="{string}"/>

mapping:rbf-global-iterative

Radial-basis-function mapping using an iterative solver with a distributed parallelism.

Example:

<mapping:rbf-global-iterative from="" to="" direction="{string}" constraint="{string}" polynomial="separate" x-dead="false" y-dead="false" z-dead="false" solver-rtol="1e-09">
  <executor:cpu/>
  <basis-function:compact-polynomial-c0 support-radius="{float}"/>
</mapping:rbf-global-iterative>

Valid Subtags:

• basis-function
  • compact-polynomial-c0 0..1
  • compact-polynomial-c2 0..1
  • compact-polynomial-c4 0..1
  • compact-polynomial-c6 0..1
  • compact-polynomial-c8 0..1
  • compact-tps-c2 0..1
  • multiquadrics 0..1
  • inverse-multiquadrics 0..1
  • gaussian 0..1
  • thin-plate-splines 0..1
  • volume-splines 0..1
• executor
  • cpu 0..1
  • cuda 0..1
  • hip 0..1
  • openmp 0..1

executor:cpu

The default executor relying on PETSc, which uses CPUs and distributed memory parallelism via MPI.

Example:

<executor:cpu/>

executor:cuda

Cuda (Nvidia) executor, which uses Ginkgo with a gather-scatter parallelism.

Example:

<executor:cuda gpu-device-id="0"/>

executor:hip

Hip (AMD/Nvidia) executor, which uses hipSolver with a gather-scatter parallelism.

Example:

<executor:hip gpu-device-id="0"/>

executor:openmp

OpenMP executor, which uses Ginkgo with a gather-scatter parallelism.

Example:

<executor:openmp n-threads="0"/>

basis-function:compact-polynomial-c0

Wendland C0 function

Example:

<basis-function:compact-polynomial-c0 support-radius="{float}"/>

basis-function:compact-polynomial-c2

Wendland C2 function

Example:

<basis-function:compact-polynomial-c2 support-radius="{float}"/>

basis-function:compact-polynomial-c4

Wendland C4 function

Example:

<basis-function:compact-polynomial-c4 support-radius="{float}"/>

basis-function:compact-polynomial-c6

Wendland C6 function

Example:

<basis-function:compact-polynomial-c6 support-radius="{float}"/>

basis-function:compact-polynomial-c8

Wendland C8 function

Example:

<basis-function:compact-polynomial-c8 support-radius="{float}"/>

basis-function:compact-tps-c2

Compact thin-plate-spline C2

Example:

<basis-function:compact-tps-c2 support-radius="{float}"/>

basis-function:multiquadrics

Multiquadrics

Example:

<basis-function:multiquadrics shape-parameter="{float}"/>

basis-function:inverse-multiquadrics

Inverse multiquadrics

Example:

<basis-function:inverse-multiquadrics shape-parameter="{float}"/>

basis-function:gaussian

Gaussian basis function accepting a support radius or a shape parameter.

Example:

<basis-function:gaussian shape-parameter="nan" support-radius="nan"/>

basis-function:thin-plate-splines

Thin-plate-splines

Example:

<basis-function:thin-plate-splines/>

basis-function:volume-splines

Volume splines

Example:

<basis-function:volume-splines/>

mapping:rbf-global-direct

Radial-basis-function mapping using a direct solver with a gather-scatter parallelism.

Example:

<mapping:rbf-global-direct from="" to="" direction="{string}" constraint="{string}" polynomial="separate" x-dead="false" y-dead="false" z-dead="false">
  <executor:cpu/>
  <basis-function:compact-polynomial-c0 support-radius="{float}"/>
</mapping:rbf-global-direct>

Valid Subtags:

• basis-function
  • compact-polynomial-c0 0..1
  • compact-polynomial-c2 0..1
  • compact-polynomial-c4 0..1
  • compact-polynomial-c6 0..1
  • compact-polynomial-c8 0..1
  • compact-tps-c2 0..1
  • multiquadrics 0..1
  • inverse-multiquadrics 0..1
  • gaussian 0..1
  • thin-plate-splines 0..1
  • volume-splines 0..1
• executor
  • cpu 0..1
  • cuda 0..1
  • hip 0..1

executor:cpu

The default executor, which uses a single-core CPU with a gather-scatter parallelism.

Example:

<executor:cpu/>

executor:cuda

Cuda (Nvidia) executor, which uses cuSolver/Ginkgo and a direct QR decomposition with a gather-scatter parallelism.

Example:

<executor:cuda gpu-device-id="0"/>

executor:hip

Hip (AMD/Nvidia) executor, which uses hipSolver/Ginkgo and a direct QR decomposition with a gather-scatter parallelism.

Example:

<executor:hip gpu-device-id="0"/>

basis-function:compact-polynomial-c0

Wendland C0 function

Example:

<basis-function:compact-polynomial-c0 support-radius="{float}"/>

basis-function:compact-polynomial-c2

Wendland C2 function

Example:

<basis-function:compact-polynomial-c2 support-radius="{float}"/>

basis-function:compact-polynomial-c4

Wendland C4 function

Example:

<basis-function:compact-polynomial-c4 support-radius="{float}"/>

basis-function:compact-polynomial-c6

Wendland C6 function

Example:

<basis-function:compact-polynomial-c6 support-radius="{float}"/>

basis-function:compact-polynomial-c8

Wendland C8 function

Example:

<basis-function:compact-polynomial-c8 support-radius="{float}"/>

basis-function:compact-tps-c2

Compact thin-plate-spline C2

Example:

<basis-function:compact-tps-c2 support-radius="{float}"/>

basis-function:multiquadrics

Multiquadrics

Example:

<basis-function:multiquadrics shape-parameter="{float}"/>

basis-function:inverse-multiquadrics

Inverse multiquadrics

Example:

<basis-function:inverse-multiquadrics shape-parameter="{float}"/>

basis-function:gaussian

Gaussian basis function accepting a support radius or a shape parameter.

Example:

<basis-function:gaussian shape-parameter="nan" support-radius="nan"/>

basis-function:thin-plate-splines

Thin-plate-splines

Example:

<basis-function:thin-plate-splines/>

basis-function:volume-splines

Volume splines

Example:

<basis-function:volume-splines/>

mapping:rbf-pum-direct

Radial-basis-function mapping using a partition of unity method, which supports a distributed parallelism.

Example:

<mapping:rbf-pum-direct from="" to="" direction="{string}" constraint="{string}" polynomial="separate" vertices-per-cluster="50" relative-overlap="0.15" project-to-input="true">
  <executor:cpu/>
  <basis-function:compact-polynomial-c0 support-radius="{float}"/>
</mapping:rbf-pum-direct>

Valid Subtags:

• basis-function
  • compact-polynomial-c0 0..1
  • compact-polynomial-c2 0..1
  • compact-polynomial-c4 0..1
  • compact-polynomial-c6 0..1
  • compact-polynomial-c8 0..1
  • compact-tps-c2 0..1
  • multiquadrics 0..1
  • inverse-multiquadrics 0..1
  • gaussian 0..1
  • thin-plate-splines 0..1
  • volume-splines 0..1
• executor
  • cpu 0..1

executor:cpu

The default (and currently only) executor using a CPU and a distributed memory parallelism via MPI.

Example:

<executor:cpu/>

basis-function:compact-polynomial-c0

Wendland C0 function

Example:

<basis-function:compact-polynomial-c0 support-radius="{float}"/>

basis-function:compact-polynomial-c2

Wendland C2 function

Example:

<basis-function:compact-polynomial-c2 support-radius="{float}"/>

basis-function:compact-polynomial-c4

Wendland C4 function

Example:

<basis-function:compact-polynomial-c4 support-radius="{float}"/>

basis-function:compact-polynomial-c6

Wendland C6 function

Example:

<basis-function:compact-polynomial-c6 support-radius="{float}"/>

basis-function:compact-polynomial-c8

Wendland C8 function

Example:

<basis-function:compact-polynomial-c8 support-radius="{float}"/>

basis-function:compact-tps-c2

Compact thin-plate-spline C2

Example:

<basis-function:compact-tps-c2 support-radius="{float}"/>

basis-function:multiquadrics

Multiquadrics

Example:

<basis-function:multiquadrics shape-parameter="{float}"/>

basis-function:inverse-multiquadrics

Inverse multiquadrics

Example:

<basis-function:inverse-multiquadrics shape-parameter="{float}"/>

basis-function:gaussian

Gaussian basis function accepting a support radius or a shape parameter.

Example:

<basis-function:gaussian shape-parameter="nan" support-radius="nan"/>

basis-function:thin-plate-splines

Thin-plate-splines

Example:

<basis-function:thin-plate-splines/>

basis-function:volume-splines

Volume splines

Example:

<basis-function:volume-splines/>

mapping:rbf

Alias tag, which auto-selects a radial-basis-function mapping depending on the simulation parameter,

Example:

<mapping:rbf from="" to="" direction="{string}" constraint="{string}" x-dead="false" y-dead="false" z-dead="false">
  <basis-function:compact-polynomial-c0 support-radius="{float}"/>
</mapping:rbf>

Valid Subtags:

• basis-function
  • compact-polynomial-c0 0..1
  • compact-polynomial-c2 0..1
  • compact-polynomial-c4 0..1
  • compact-polynomial-c6 0..1
  • compact-polynomial-c8 0..1
  • compact-tps-c2 0..1
  • multiquadrics 0..1
  • inverse-multiquadrics 0..1
  • gaussian 0..1
  • thin-plate-splines 0..1
  • volume-splines 0..1

basis-function:compact-polynomial-c0

Wendland C0 function

Example:

<basis-function:compact-polynomial-c0 support-radius="{float}"/>

basis-function:compact-polynomial-c2

Wendland C2 function

Example:

<basis-function:compact-polynomial-c2 support-radius="{float}"/>

basis-function:compact-polynomial-c4

Wendland C4 function

Example:

<basis-function:compact-polynomial-c4 support-radius="{float}"/>

basis-function:compact-polynomial-c6

Wendland C6 function

Example:

<basis-function:compact-polynomial-c6 support-radius="{float}"/>

basis-function:compact-polynomial-c8

Wendland C8 function

Example:

<basis-function:compact-polynomial-c8 support-radius="{float}"/>

basis-function:compact-tps-c2

Compact thin-plate-spline C2

Example:

<basis-function:compact-tps-c2 support-radius="{float}"/>

basis-function:multiquadrics

Multiquadrics

Example:

<basis-function:multiquadrics shape-parameter="{float}"/>

basis-function:inverse-multiquadrics

Inverse multiquadrics

Example:

<basis-function:inverse-multiquadrics shape-parameter="{float}"/>

basis-function:gaussian

Gaussian basis function accepting a support radius or a shape parameter.

Example:

<basis-function:gaussian shape-parameter="nan" support-radius="nan"/>

basis-function:thin-plate-splines

Thin-plate-splines

Example:

<basis-function:thin-plate-splines/>

basis-function:volume-splines

Volume splines

Example:

<basis-function:volume-splines/>

mapping:axial-geometric-multiscale

Axial geometric multiscale mapping between one 1D and multiple 3D vertices.

Example:

<mapping:axial-geometric-multiscale from="" to="" direction="{string}" constraint="{string}" multiscale-type="{string}" multiscale-axis="{string}" multiscale-radius="{float}"/>

mapping:radial-geometric-multiscale

Radial geometric multiscale mapping between multiple 1D and multiple 3D vertices, distributed along a principle axis.

Example:

<mapping:radial-geometric-multiscale from="" to="" direction="{string}" constraint="{string}" multiscale-type="{string}" multiscale-axis="{string}" multiscale-radius="{float}"/>

action:multiply-by-area

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

Example:

<action:multiply-by-area timing="{string}" mesh="{string}">
  <target-data name="{string}"/>
</action:multiply-by-area>

Valid Subtags:

• target-data 1

target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>

action:divide-by-area

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

Example:

<action:divide-by-area timing="{string}" mesh="{string}">
  <target-data name="{string}"/>
</action:divide-by-area>

Valid Subtags:

• target-data 1

target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>

action:summation

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

Example:

<action:summation timing="{string}" mesh="{string}">
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:summation>

Valid Subtags:

• source-data 1..*
• target-data 1

source-data

Multiple data to read from.

Example:

<source-data name="{string}"/>

target-data

Data to read from and write to.

Example:

<target-data name="{string}"/>

action:recorder

Records action invocations for testing purposes.

Example:

<action:recorder timing="{string}" mesh="{string}"/>

action:python

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

Example:

<action:python timing="{string}" mesh="{string}">
  <path name=""/>
  <module name="{string}"/>
  <source-data name="{string}"/>
  <target-data name="{string}"/>
</action:python>

Valid Subtags:

• path 0..1
• module 1
• source-data 0..1
• target-data 0..1

path

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

Example:

<path name=""/>

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}"/>

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}"/>

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}"/>

export:vtk

Exports meshes to VTK legacy format files. Parallel participants will use the VTU exporter instead.

Example:

<export:vtk directory="." every-n-time-windows="1" every-iteration="false"/>

export:vtu

Exports meshes to VTU files in serial or PVTU files with VTU piece files in parallel.

Example:

<export:vtu directory="." every-n-time-windows="1" every-iteration="false"/>

export:vtp

Exports meshes to VTP files in serial or PVTP files with VTP piece files in parallel.

Example:

<export:vtp directory="." every-n-time-windows="1" every-iteration="false"/>

export:csv

Exports vertex coordinates and data to CSV files.

Example:

<export:csv directory="." every-n-time-windows="1" every-iteration="false"/>

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 name="{string}" mesh="{string}" coordinate="{vector}"/>

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 name="{string}" mesh="{string}" scale-with-connectivity="{boolean}"/>

provide-mesh

Provide a mesh (see tag <mesh>) to other participants.

Example:

<provide-mesh name="{string}"/>

receive-mesh

Makes a remote mesh (see tag <mesh>) available to this participant.

Example:

<receive-mesh name="{string}" api-access="false" direct-access="false" geometric-filter="on-secondary-ranks" from="{string}" safety-factor="0.5"/>

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

<intra-comm:sockets port="0" network="lo" exchange-directory="."/>

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

<intra-comm:mpi exchange-directory="."/>

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" method="fixed"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="false"/>
</coupling-scheme:serial-explicit>

Valid Subtags:

• max-time 0..1
• max-time-windows 0..1
• time-window-size 1
• participants 1
• exchange 1..*

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>

max-time-windows

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

Example:

<max-time-windows value="{integer}"/>

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" method="fixed"/>

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="false"/>

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"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="false"/>
</coupling-scheme:parallel-explicit>

Valid Subtags:

• max-time 0..1
• max-time-windows 0..1
• time-window-size 1
• participants 1
• exchange 1..*

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>

max-time-windows

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

Example:

<max-time-windows value="{integer}"/>

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1"/>

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="false"/>

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" method="fixed"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="true"/>
  <acceleration:constant>
    ...
  </acceleration:constant>
  <absolute-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>
  <absolute-or-relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" abs-limit="{float}" rel-limit="{float}"/>
  <relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>
  <residual-relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>
  <min-iterations value="{integer}"/>
  <max-iterations value="{integer}"/>
</coupling-scheme:serial-implicit>

Valid Subtags:

• max-time 0..1
• max-time-windows 0..1
• time-window-size 1
• participants 1
• exchange 1..*
• absolute-convergence-measure 0..*
• absolute-or-relative-convergence-measure 0..*
• relative-convergence-measure 0..*
• residual-relative-convergence-measure 0..*
• min-iterations 0..1
• max-iterations 0..1
• acceleration
  • constant 0..1
  • aitken 0..1
  • IQN-ILS 0..1
  • IQN-IMVJ 0..1

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>

max-time-windows

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

Example:

<max-time-windows value="{integer}"/>

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1" method="fixed"/>

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="true"/>

acceleration:constant

Accelerates coupling data with constant underrelaxation.

Example:

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

Valid Subtags:

• relaxation 1

relaxation

Example:

<relaxation value="{float}"/>

acceleration:aitken

Accelerates coupling data with dynamic Aitken under-relaxation.

Example:

<acceleration:aitken>
  <initial-relaxation value="{float}"/>
  <data scaling="1" name="{string}" mesh="{string}"/>
  <preconditioner type="{string}" freeze-after="-1"/>
</acceleration:aitken>

Valid Subtags:

• initial-relaxation 0..1
• data 1..*
• preconditioner 0..1

initial-relaxation

Initial relaxation factor. If this tag is not provided, an initial relaxation of 0.5 is used.

Example:

<initial-relaxation value="{float}"/>

data

The data used to compute the acceleration.

Example:

<data scaling="1" name="{string}" mesh="{string}"/>

preconditioner

To improve the numerical stability of multiple data vectors 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 type="{string}" freeze-after="-1"/>

acceleration:IQN-ILS

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

Example:

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

Valid Subtags:

• initial-relaxation 0..1
• max-used-iterations 0..1
• time-windows-reused 0..1
• data 1..*
• filter 0..1
• preconditioner 0..1

initial-relaxation

Initial relaxation factor. If this tag is not provided, an initial relaxation of 0.1 is used.

Example:

<initial-relaxation value="{float}" enforce="false"/>

max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian. If this tag is not provided, the attribute value of 100 is used.

Example:

<max-used-iterations value="{integer}"/>

time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian. If this tag is not provided, the default attribute value of 10 is used.

Example:

<time-windows-reused value="{integer}"/>

data

The data used to compute the acceleration.

Example:

<data scaling="1" name="{string}" mesh="{string}"/>

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. When this tag is not provided, the QR2-filter with the limit value 1e-2 is used.

Example:

<filter limit="1e-16" type="{string}"/>

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. If this tag is not provided, the residual-sum preconditioner is employed.

Example:

<preconditioner type="{string}" update-on-threshold="true" freeze-after="-1"/>

acceleration:IQN-IMVJ

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

Example:

<acceleration:IQN-IMVJ always-build-jacobian="false" reduced-time-grid="true">
  <initial-relaxation value="{float}" enforce="false"/>
  <imvj-restart-mode type="RS-SVD" chunk-size="8" reused-time-windows-at-restart="8" truncation-threshold="0.0001"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" name="{string}" mesh="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner type="{string}" update-on-threshold="true" freeze-after="-1"/>
</acceleration:IQN-IMVJ>

Valid Subtags:

• initial-relaxation 0..1
• imvj-restart-mode 0..1
• max-used-iterations 0..1
• time-windows-reused 0..1
• data 1..*
• filter 0..1
• preconditioner 0..1

initial-relaxation

Initial relaxation factor. If this tag is not provided, an initial relaxation of 0.1 is used.

Example:

<initial-relaxation value="{float}" enforce="false"/>

imvj-restart-mode

Type of IMVJ restart mode that is used:

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

Example:

<imvj-restart-mode type="RS-SVD" chunk-size="8" reused-time-windows-at-restart="8" truncation-threshold="0.0001"/>

max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian. If this tag is not provided, the default attribute value of 20 is used.

Example:

<max-used-iterations value="{integer}"/>

time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian. If this tag is not provided, the attribute value of 0 is used.

Example:

<time-windows-reused value="{integer}"/>

data

The data used to compute the acceleration.

Example:

<data scaling="1" name="{string}" mesh="{string}"/>

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. When this tag is not provided, the QR2-filter with the limit value 1e-2 is used.

Example:

<filter limit="1e-16" type="{string}"/>

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. If this tag is not provided, the residual-sum preconditioner is employed.

Example:

<preconditioner type="{string}" update-on-threshold="true" freeze-after="-1"/>

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 data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>

absolute-or-relative-convergence-measure

Absolute or relative convergence, which is the disjunction of an absolute criterion based on the two-norm difference of data values between iterations and a relative criterion based on the relative two-norm difference of data values between iterations,i.e. convergence is reached as soon as one of the both criteria is fulfilled.$$\left\lVert H(x^k) - x^k \right\rVert_2 < \text{abs-limit}\quad\text{or}\quad\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^k) \right\rVert_2} < \text{rel-limit}$$

Example:

<absolute-or-relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" abs-limit="{float}" rel-limit="{float}"/>

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 data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>

residual-relative-convergence-measure

Relative convergence criterion comparing the currently measured residual to the residual of the first iteration in the time window. $$\frac{\left\lVert H(x^k) - x^k \right\rVert_2}{\left\lVert H(x^0) - x^0 \right\rVert_2} < \text{limit}$$

Example:

<residual-relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>

min-iterations

Allows to specify a minimum amount of iterations that must be performed per time window.

Example:

<min-iterations value="{integer}"/>

max-iterations

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

Example:

<max-iterations value="{integer}"/>

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"/>
  <participants first="{string}" second="{string}"/>
  <exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="true"/>
  <acceleration:constant>
    ...
  </acceleration:constant>
  <absolute-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>
  <absolute-or-relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" abs-limit="{float}" rel-limit="{float}"/>
  <relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>
  <residual-relative-convergence-measure data="{string}" mesh="{string}" suffices="false" strict="false" limit="{float}"/>
  <min-iterations value="{integer}"/>
  <max-iterations value="{integer}"/>
</coupling-scheme:parallel-implicit>

Valid Subtags:

• max-time 0..1
• max-time-windows 0..1
• time-window-size 1
• participants 1
• exchange 1..*
• absolute-convergence-measure 0..*
• absolute-or-relative-convergence-measure 0..*
• relative-convergence-measure 0..*
• residual-relative-convergence-measure 0..*
• min-iterations 0..1
• max-iterations 0..1
• acceleration
  • constant 0..1
  • aitken 0..1
  • IQN-ILS 0..1
  • IQN-IMVJ 0..1

max-time

Defined the end of the simulation as total time.

Example:

<max-time value="{float}"/>

max-time-windows

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

Example:

<max-time-windows value="{integer}"/>

time-window-size

Defines the size of the time window.

Example:

<time-window-size value="-1"/>

participants

Defines the participants of the coupling scheme.

Example:

<participants first="{string}" second="{string}"/>

exchange

Defines the flow of data between meshes of participants.

Example:

<exchange data="{string}" mesh="{string}" from="{string}" to="{string}" initialize="false" substeps="true"/>

acceleration:constant

Accelerates coupling data with constant underrelaxation.

Example:

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

Valid Subtags:

• relaxation 1

relaxation

Example:

<relaxation value="{float}"/>

acceleration:aitken

Accelerates coupling data with dynamic Aitken under-relaxation.

Example:

<acceleration:aitken>
  <initial-relaxation value="{float}"/>
  <data scaling="1" name="{string}" mesh="{string}"/>
  <preconditioner type="{string}" freeze-after="-1"/>
</acceleration:aitken>

Valid Subtags:

• initial-relaxation 0..1
• data 1..*
• preconditioner 0..1

initial-relaxation

Initial relaxation factor. If this tag is not provided, an initial relaxation of 0.5 is used.

Example:

<initial-relaxation value="{float}"/>

data

The data used to compute the acceleration.

Example:

<data scaling="1" name="{string}" mesh="{string}"/>

preconditioner

To improve the numerical stability of multiple data vectors 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 type="{string}" freeze-after="-1"/>

acceleration:IQN-ILS

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

Example:

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

Valid Subtags:

• initial-relaxation 0..1
• max-used-iterations 0..1
• time-windows-reused 0..1
• data 1..*
• filter 0..1
• preconditioner 0..1

initial-relaxation

Initial relaxation factor. If this tag is not provided, an initial relaxation of 0.1 is used.

Example:

<initial-relaxation value="{float}" enforce="false"/>

max-used-iterations

Maximum number of columns used in low-rank approximation of Jacobian. If this tag is not provided, the attribute value of 100 is used.

Example:

<max-used-iterations value="{integer}"/>

time-windows-reused

Number of past time windows from which columns are used to approximate Jacobian. If this tag is not provided, the default attribute value of 10 is used.

Example:

<time-windows-reused value="{integer}"/>

data

The data used to compute the acceleration.

Example:

<data scaling="1" name="{string}" mesh="{string}"/>

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. When this tag is not provided, the QR2-filter with the limit value 1e-2 is used.

Example:

<filter limit="1e-16" type="{string}"/>

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. If this tag is not provided, the residual-sum preconditioner is employed.

Example:

<preconditioner type="{string}" update-on-threshold="true" freeze-after="-1"/>

acceleration:IQN-IMVJ

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

Example:

<acceleration:IQN-IMVJ always-build-jacobian="false" reduced-time-grid="true">
  <initial-relaxation value="{float}" enforce="false"/>
  <imvj-restart-mode type="RS-SVD" chunk-size="8" reused-time-windows-at-restart="8" truncation-threshold="0.0001"/>
  <max-used-iterations value="{integer}"/>
  <time-windows-reused value="{integer}"/>
  <data scaling="1" name="{string}" mesh="{string}"/>
  <filter limit="1e-16" type="{string}"/>
  <preconditioner type="{string}" update-on-threshold="true" freeze-after="-1"/>
</acceleration:IQN-IMVJ>