3.7 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    ... 
7</COUPLING>

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.

3.7.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" /> 
8</COUPLING>

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.

3.7.2 Cwipi

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

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.