./binprecice md > reference.md

precice-configuration

Main tag containing preCICE configuration.

Example:

<precice-configuration sync-mode="0">
  <log enabled="1">
    ...
  </log>
  <solver-interface dimensions="2" experimental="0">
    ...
  </solver-interface>
</precice-configuration>

Valid Subtags:

• log 0..1
• solver-interface 1

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>

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

solver-interface

Configuration of simulation relevant features.

Example:

<solver-interface dimensions="2" experimental="0">
  <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>

Valid Subtags:

• 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..*
  • mpi-singleports 0..*

data:scalar

Defines a scalar data set to be assigned to meshes.

Example:

<data:scalar name="{string}"/>

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

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>

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" exchange-directory="" from="{string}" network="lo" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>

m2n:mpi-multiple-ports

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

Example:

<m2n:mpi-multiple-ports exchange-directory="" from="{string}" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>

m2n:mpi

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

Example:

<m2n:mpi exchange-directory="" from="{string}" to="{string}" enforce-gather-scatter="0" use-two-level-initialization="0"/>

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

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 waveform-order="0" 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="0"/>
  <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-secondary-ranks" name="{string}" direct-access="0" provide="0"/>
  <master:sockets port="0" exchange-directory="" network="lo"/>
  <intra-comm:sockets port="0" exchange-directory="" network="lo"/>
</participant>

Valid Subtags:

• write-data 0..*
• read-data 0..*
• watch-point 0..*
• watch-integral 0..*
• use-mesh 0..*
• action
  • multiply-by-area 0..*
  • divide-by-area 0..*
  • scale-by-computed-dt-ratio 0..*
  • scale-by-computed-dt-part-ratio 0..*
  • scale-by-dt 0..*
  • summation 0..*
  • compute-curvature 0..*
  • recorder 0..*
  • python 0..*
• export
  • vtk 0..*
  • vtu 0..*
  • vtp 0..*
  • csv 0..*
• intra-comm
  • sockets 0..1
  • mpi 0..1
  • mpi-single 0..1
• mapping
  • rbf-thin-plate-splines 0..*
  • rbf-multiquadrics 0..*
  • rbf-inverse-multiquadrics 0..*
  • rbf-volume-splines 0..*
  • rbf-gaussian 0..*
  • rbf-compact-tps-c2 0..*
  • rbf-compact-polynomial-c0 0..*
  • rbf-compact-polynomial-c6 0..*
  • nearest-neighbor 0..*
  • nearest-projection 0..*
  • nearest-neighbor-gradient 0..*
  • linear-cell-interpolation 0..*
• master
  • sockets 0..1
  • mpi 0..1
  • mpi-single 0..1
  • sockets 0..1
  • mpi 0..1
  • mpi-single 0..1

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

read-data

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

Example:

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

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

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

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

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

mapping:rbf-gaussian

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

Example:

<mapping:rbf-gaussian shape-parameter="nan" solver-rtol="1e-09" support-radius="nan" 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"/>

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

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

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

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

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

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

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>

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 mesh="{string}" timing="{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:scale-by-computed-dt-ratio

Multiplies source data values by ratio of last time step size / time window size, 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>

Valid Subtags:

• source-data 1
• target-data 1

source-data

Single data to read from.

Example:

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

target-data

Data to read from and write to.

Example:

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

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

Multiplies source data values by ratio of computed time window part / time window size, 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>

Valid Subtags:

• source-data 1
• target-data 1

source-data

Single data to read from.

Example:

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

target-data

Data to read from and write to.

Example:

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

action:scale-by-dt

Multiplies source data values by the time window size, 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>

Valid Subtags:

• source-data 1
• target-data 1

source-data

Single data to read from.

Example:

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

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 mesh="{string}" timing="{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:compute-curvature

Computes curvature values at mesh vertices.

Example:

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

Valid Subtags:

• target-data 1

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 mesh="{string}" timing="{string}"/>

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>

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 every-n-time-windows="1" directory="" every-iteration="0" normals="0"/>

export:vtu

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

Example:

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

export:vtp

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

Example:

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

export:csv

Exports vertex coordinates and data to CSV files.

Example:

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

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

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

use-mesh

Makes a mesh (see tag available to a participant.

Example:

<use-mesh safety-factor="0.5" from="" geometric-filter="on-secondary-ranks" name="{string}" direct-access="0" provide="0"/>

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

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

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

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

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

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

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" exchange-directory="" network="lo"/>

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

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

<intra-comm: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 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" valid-digits="10" 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}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>

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 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" valid-digits="10" 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}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>

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 0..1
• max-time-windows 0..1
• time-window-size 1
• participants 1
• exchange 1..*
• absolute-convergence-measure 0..*
• relative-convergence-measure 0..*
• residual-relative-convergence-measure 0..*
• min-iteration-convergence-measure 0..*
• max-iterations 1
• extrapolation-order 0..1
• acceleration
  • constant 0..1
  • aitken 0..1
  • IQN-ILS 0..1
  • IQN-IMVJ 0..1
  • broyden 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" valid-digits="10" 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}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>

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 mesh="{string}" name="{string}"/>
</acceleration:aitken>

Valid Subtags:

• initial-relaxation 1
• data 1..*

initial-relaxation

Initial relaxation factor.

Example:

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

data

The data used to compute the acceleration.

Example:

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

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 1
• max-used-iterations 1
• time-windows-reused 1
• data 1..*
• filter 0..1
• preconditioner 0..1

initial-relaxation

Initial relaxation factor.

Example:

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

max-used-iterations

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

Example:

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

time-windows-reused

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

Example:

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

data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{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.

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.

Example:

<preconditioner freeze-after="-1" type="{string}"/>

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>

Valid Subtags:

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

initial-relaxation

Initial relaxation factor.

Example:

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

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

Example:

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

max-used-iterations

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

Example:

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

time-windows-reused

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

Example:

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

data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{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.

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.

Example:

<preconditioner freeze-after="-1" type="{string}"/>

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 1
• max-used-iterations 1
• time-windows-reused 1
• data 1..*

initial-relaxation

Example:

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

max-used-iterations

Example:

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

time-windows-reused

Example:

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

data

Example:

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

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

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

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

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

max-iterations

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

Example:

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

extrapolation-order

Sets order of predictor of interface values for first participant.

Example:

<extrapolation-order 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" 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 0..1
• max-time-windows 0..1
• time-window-size 1
• participants 1
• exchange 1..*
• absolute-convergence-measure 0..*
• relative-convergence-measure 0..*
• residual-relative-convergence-measure 0..*
• min-iteration-convergence-measure 0..*
• max-iterations 1
• extrapolation-order 0..1
• acceleration
  • constant 0..1
  • aitken 0..1
  • IQN-ILS 0..1
  • IQN-IMVJ 0..1
  • broyden 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" valid-digits="10" 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}" from="{string}" mesh="{string}" to="{string}" initialize="0"/>

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 mesh="{string}" name="{string}"/>
</acceleration:aitken>

Valid Subtags:

• initial-relaxation 1
• data 1..*

initial-relaxation

Initial relaxation factor.

Example:

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

data

The data used to compute the acceleration.

Example:

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

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 1
• max-used-iterations 1
• time-windows-reused 1
• data 1..*
• filter 0..1
• preconditioner 0..1

initial-relaxation

Initial relaxation factor.

Example:

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

max-used-iterations

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

Example:

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

time-windows-reused

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

Example:

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

data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{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.

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.

Example:

<preconditioner freeze-after="-1" type="{string}"/>

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>

Valid Subtags:

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

initial-relaxation

Initial relaxation factor.

Example:

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

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

Example:

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

max-used-iterations

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

Example:

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

time-windows-reused

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

Example:

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

data

The data used to compute the acceleration.

Example:

<data scaling="1" mesh="{string}" name="{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.

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.

Example:

<preconditioner freeze-after="-1" type="{string}"/>

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 1
• max-used-iterations 1
• time-windows-reused 1
• data 1..*

initial-relaxation

Example:

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

max-used-iterations

Example: