3.6 Coupling

Nektar++ Solvers can be run in parallel with third party applications and other Nektar++ solvers, where run-time data exchange is enabled by the coupling interface. The interface is configured in the COUPLING tag as

1<COUPLING TYPE="[type]" NAME="[name]"> 
2    <I PROPERTY="SendSteps"         VALUE="1" /> 
3    <I PROPERTY="SendVariables"     VALUE="u0S,v0S" /> 
4    <I PROPERTY="ReceiveSteps"      VALUE="1" /> 
5    <I PROPERTY="ReceiveVariables"  VALUE="u0R,v0R" /> 
6    ... 

The coupling type may be any of the types described later in this section, while the name can be chosen arbitrarily. Inside each coupling block, the send and receive frequencies are defined by the SendSteps and ReceiveSteps parameters, respectively. Which variables are to be sent or received is specified by the SendVariables and ReceiveVariables. By default, the send and receive frequencies is set to zero, which disables the corresponding exchange in this coupling. An empty SendVariables or ReceiveVariables list has the same effect.

Option name Required Default


SendSteps 0

Frequency (in steps) at which fields are sent. Sending is disabled if set to zero.

SendVariables <empty>

Comma-separated list of sent variables. Sending is disabled if the list is empty.

ReceiveSteps 0

Frequency (in steps) at which fields are received. Receiving is disabled if set to zero.

ReceiveVariables <empty>

Comma-separated list of received variables. Receiving is disabled if the list is empty.

3.6.1 File

This coupling type allows the user to exchange fields at run time by reading from and writing to files. Besides the basic parameters which define the exchanged variables and the exchange frequency, the file coupling type requires the SendFileName and ReceiveFunction parameters to be set. The Coupling name is not used for this type and can be ignored.

1<COUPLING NAME="coupling1" TYPE="File"> 
2    <I PROPERTY="SendSteps"         VALUE="1" /> 
3    <I PROPERTY="SendVariables"     VALUE="u0S,v0S" /> 
4    <I PROPERTY="SendFileName"      VALUE="Dummy0out_%14.8E.pts" /> 
5    <I PROPERTY="ReceiveSteps"      VALUE="1" /> 
6    <I PROPERTY="ReceiveVariables"  VALUE="u0R,v0R" /> 
7    <I PROPERTY="ReceiveFunction"   VALUE="CouplingIn" /> 

SendFileName specifies a file name template to write the field data to. Currently, only .pts files are supported and the file is only created once fully written, avoiding race conditions between sender and receiver. Receiving is implemented by evaluating a session function specified in the ReceiveFunction parameter. The coupling waits for the file given in the receive function to appear.

Option name Required Default


SendFileName (✓) -

File name where the sent fields should be written to. Required if sending is enabled. Time dependent file names are supported.

ReceiveFunction (✓) -

Function to evaluate to obtain the received fields.Required if receiving is enabled.

3.6.2 Cwipi

Note: The Cwipi coupling is only available when Nektar++ is compiled with OpenMPI and CWIPI
The Cwipi coupling uses CWIPI1 to facilitate real time data exchange over MPI. See [24] for details. All data transfers are non-blocking to minimize the computational overhead. The interface must be enabled with the command line option –cwipi and a unique application name, e.g:
DummySolver --cwipi ’Dummy1’ Dummy_3DCubeCwipi_1.xml

CWIPI uses the names of the current application and the coupling to identify two peers in cosimulation setups. The name of the remote application must be provided by the RemoteName parameter. Unlike the File-type coupling, a linear interpolation in time is applied to the received fields if non-unity values are set for ReceiveSteps.

1<COUPLING NAME="coupling1" TYPE="Cwipi"> 
2    <I PROPERTY="RemoteName"        VALUE="Dummy1" /> 
3    <I PROPERTY="SendSteps"         VALUE="1" /> 
4    <I PROPERTY="SendVariables"     VALUE="u0S,v0S" /> 
5    <I PROPERTY="SendMethod"        VALUE="Evaluate" /> 
6    <I PROPERTY="ReceiveSteps"      VALUE="1" /> 
7    <I PROPERTY="ReceiveVariables"  VALUE="u0R,v0R" /> 
8    <I PROPERTY="Oversample"        VALUE="5" /> 
9    <I PROPERTY="FilterWidth"       VALUE="10E-3" /> 
10    <I PROPERTY="NotLocMethod"      VALUE="Extrapolate" /> 

Additional options which define the coupling include SendMethod, the method used to retrieve the physical values at the locations requested by the remote application. Available options are NearestNeighbour, Shepard and the default Evaluate. The last option directly evaluates the expansions using a backward transform, giving superior accuracy at acceptable computational cost.

When using non-conforming domains, the current application might request values outside of the computational domain of the remote application. How to handle these not-located points is specified by the NotLocMethod parameter. When set to keep, the point value is not altered. With Extrapolate, the nearest neighbor value of the current application is used. Note that this can be very inefficient when using many MPI ranks.

Option name Required Default


RemoteName -

Name of the remote application.

SendMethod Evaluate

Specifies how to evaluate fields before sending. Available options are NearestNeighbour, Shepard and Evaluate.

Oversample 0

Receive fields at a higher (or lower) number of quadrature points before filtering to avoid aliasing.

FilterWidth 0

Apply a spatial filter of a given filter width to the received fields. Disabled when set to zero.

NotLocMethod keep

Specifies how not located points in non-conformal domains are handled. Possible values are keep and Extrapolate.