PLE
Parallel Location and Exchange
Loading...
Searching...
No Matches
ple_coupling.h File Reference
#include "ple_config.h"
#include <mpi.h>
#include "ple_defs.h"

Go to the source code of this file.

Data Structures

struct  ple_coupling_mpi_set_info_t

Macros

#define PLE_COUPLING_INIT   (1 << 0)
#define PLE_COUPLING_NO_SYNC   (1 << 1)
#define PLE_COUPLING_STOP   (1 << 2)
#define PLE_COUPLING_LAST   (1 << 3)
#define PLE_COUPLING_NEW_ITERATION   (1 << 4)
#define PLE_COUPLING_REDO_ITERATION   (1 << 5)
#define PLE_COUPLING_TS_MIN   (1 << 6)
#define PLE_COUPLING_TS_LEADER   (1 << 7)
#define PLE_COUPLING_TS_FOLLOWER   (1 << 15)
#define PLE_COUPLING_TS_INDEPENDENT   (1 << 16)
#define PLE_COUPLING_UNSTEADY   (1 << 8)
#define PLE_COUPLING_STEADY   (1 << 9)
#define PLE_COUPLING_CONVERGED   (1 << 10)
#define PLE_COUPLING_USER_1   (1 << 11)
#define PLE_COUPLING_USER_2   (1 << 12)
#define PLE_COUPLING_USER_3   (1 << 13)
#define PLE_COUPLING_USER_4   (1 << 14)

Functions

int ple_coupling_mpi_name_to_id (MPI_Comm comm, const char *group_name)
 Build a group id within a communicator based on its name.
ple_coupling_mpi_set_t * ple_coupling_mpi_set_create (int sync_flag, const char *app_type, const char *app_name, MPI_Comm base_comm, MPI_Comm app_comm)
 Discover other applications in a set with a common communicator.
void ple_coupling_mpi_set_destroy (ple_coupling_mpi_set_t **s)
 Free an PLE coupling MPI set info structure.
int ple_coupling_mpi_set_n_apps (const ple_coupling_mpi_set_t *s)
 Return the number of applications in a coupled set.
int ple_coupling_mpi_set_get_app_id (const ple_coupling_mpi_set_t *s)
 Return the id of the local application in a coupled set.
ple_coupling_mpi_set_info_t ple_coupling_mpi_set_get_info (const ple_coupling_mpi_set_t *s, int app_id)
 Return application information in set's common communicator.
void ple_coupling_mpi_set_synchronize (ple_coupling_mpi_set_t *s, int sync_flag, double time_step)
 Synchronize applications in a set.
const int * ple_coupling_mpi_set_get_status (const ple_coupling_mpi_set_t *s)
 Get status of applications in a set.
const double * ple_coupling_mpi_set_get_timestep (const ple_coupling_mpi_set_t *s)
 Get time steps in a set.
double ple_coupling_mpi_set_compute_timestep (const ple_coupling_mpi_set_t *s)
 Compute recommended time step for the current application based on provided flags and values of applications in a set.
void ple_coupling_mpi_intracomm_create (MPI_Comm base_comm, MPI_Comm app_comm, int distant_root, MPI_Comm *new_comm, int local_range[2], int distant_range[2])
 Create an intracommunicator from a local and distant communicator within a base communicator.
MPI_Comm ple_coupling_mpi_set_get_base_comm (const ple_coupling_mpi_set_t *s)
 Get base communicator of an PLE coupling MPI set.
void ple_coupling_mpi_set_dump (const ple_coupling_mpi_set_t *s)
 Dump printout of an PLE coupling MPI set info structure.

Macro Definition Documentation

◆ PLE_COUPLING_CONVERGED

#define PLE_COUPLING_CONVERGED   (1 << 10)

◆ PLE_COUPLING_INIT

#define PLE_COUPLING_INIT   (1 << 0)

Not yet synchronized

◆ PLE_COUPLING_LAST

#define PLE_COUPLING_LAST   (1 << 3)

Last synchronization

◆ PLE_COUPLING_NEW_ITERATION

#define PLE_COUPLING_NEW_ITERATION   (1 << 4)

◆ PLE_COUPLING_NO_SYNC

#define PLE_COUPLING_NO_SYNC   (1 << 1)

Not synchronized

◆ PLE_COUPLING_REDO_ITERATION

#define PLE_COUPLING_REDO_ITERATION   (1 << 5)

◆ PLE_COUPLING_STEADY

#define PLE_COUPLING_STEADY   (1 << 9)

◆ PLE_COUPLING_STOP

#define PLE_COUPLING_STOP   (1 << 2)

Will stop immediately

◆ PLE_COUPLING_TS_FOLLOWER

#define PLE_COUPLING_TS_FOLLOWER   (1 << 15)

Follow time step of other members only; other members should ignore this one

◆ PLE_COUPLING_TS_INDEPENDENT

#define PLE_COUPLING_TS_INDEPENDENT   (1 << 16)

Other members should ignore this one when checking for smallest time step

◆ PLE_COUPLING_TS_LEADER

#define PLE_COUPLING_TS_LEADER   (1 << 7)

Prescribe time step for all members of group (only one member may set this flag)

◆ PLE_COUPLING_TS_MIN

#define PLE_COUPLING_TS_MIN   (1 << 6)

Time step value handling bits

By default, no specific time step handling is done, though all members of a set may observe the values used by other members.

If an application sets the PLE_COUPLING_TS_LEADER bit, this implies all synchronized applications should use the same time step, unless they have set the PLE_COUPLING_TS_INDEPENDENT bit.

This specific case is deprecated: it is recommended that all applications following a time-step leader set the PLE_COUPLING_TS_FOLLOWER bit. In the future, all application not marked explicitely as followers may ignore the time-step of a leader.

If an application sets the PLE_COUPLING_TS_MIN bit, this implies it will align its time step with the smallest value of all synchronized applications, except those who also set the PLE_COUPLING_TS_FOLLOWER bit.

Note that PLE_COUPLING_TS_LEADER should have priority over PLE_COUPLING_TS_MIN when both are set.

If an application uses (PLE_COUPLING_TS_MIN | PLE_COUPLING_TS_FOLLOWER), this implies it will use the smallest time step of other non-"follower" applications, but other applications should ignore it when determining the minimum time step.

At most one one application may set PLE_COUPLING_TS_LEADER, and it should not also set PLE_COUPLING_TS_FOLLOWER. Use smallest time step

◆ PLE_COUPLING_UNSTEADY

#define PLE_COUPLING_UNSTEADY   (1 << 8)

◆ PLE_COUPLING_USER_1

#define PLE_COUPLING_USER_1   (1 << 11)

◆ PLE_COUPLING_USER_2

#define PLE_COUPLING_USER_2   (1 << 12)

◆ PLE_COUPLING_USER_3

#define PLE_COUPLING_USER_3   (1 << 13)

◆ PLE_COUPLING_USER_4

#define PLE_COUPLING_USER_4   (1 << 14)

Function Documentation

◆ ple_coupling_mpi_intracomm_create()

void ple_coupling_mpi_intracomm_create ( MPI_Comm base_comm,
MPI_Comm app_comm,
int distant_root,
MPI_Comm * new_comm,
int local_range[2],
int distant_range[2] )

Create an intracommunicator from a local and distant communicator within a base communicator.

Parameters
[in]base_commcommunicator associated with both applications
[in]app_commcommunicator associated with local application
[in]distant_rootrank of distant group leader in base_comm
[in]new_commpointer to new communicator
[in]local_rangefirst and past-the last ranks of local application in new communicator
[in]distant_rangefirst and past-the last ranks of distant application in new communicator

◆ ple_coupling_mpi_name_to_id()

int ple_coupling_mpi_name_to_id ( MPI_Comm comm,
const char * group_name )

Build a group id within a communicator based on its name.

If multiple groups are present, ids are number from 0 to n_groups - 1, based on the odering of group names. If all processes have the same group name, the returned value is -1.

The returned id may typically be used as a "color" argument for MPI_Comm_split().

As this function requires communication between applications, it is a collective function in comm.

Parameters
[in]commMPI communicator.
[in]group_namename associated with current group.
Returns
id associated with local name.

◆ ple_coupling_mpi_set_compute_timestep()

double ple_coupling_mpi_set_compute_timestep ( const ple_coupling_mpi_set_t * s)

Compute recommended time step for the current application based on provided flags and values of applications in a set.

The flags and values used to compute this recommended time step value are update at each call to ple_coupling_mpi_set_synchronize().

Parameters
[in]spointer to PLE coupling MPI set info structure.
Returns
computed application time step

◆ ple_coupling_mpi_set_create()

ple_coupling_mpi_set_t * ple_coupling_mpi_set_create ( int sync_flag,
const char * app_type,
const char * app_name,
MPI_Comm base_comm,
MPI_Comm app_comm )

Discover other applications in a set with a common communicator.

In most cases, the base communicator is MPI_COMM_WORLD, and the local application communicator app_comm is usually obtained from it using MPI_Comm_split, but other combinations may be possible using MPI-2 process management functions.

As this function requires communication between applications, it is a collective function in base_comm.

Parameters
[in]sync_flag1 if application is to be synchronized at each time step, 0 if independent from others.
[in]app_typename of current application type (software name).
[in]app_namename of current application (data/case name).
[in]base_commcommunicator associated with all applications.
[in]app_commcommunicator associated with local application.
Returns
PLE coupling MPI set info structure.

◆ ple_coupling_mpi_set_destroy()

void ple_coupling_mpi_set_destroy ( ple_coupling_mpi_set_t ** s)

Free an PLE coupling MPI set info structure.

Parameters
[in,out]spointer to structure that should be freed.

◆ ple_coupling_mpi_set_dump()

void ple_coupling_mpi_set_dump ( const ple_coupling_mpi_set_t * s)

Dump printout of an PLE coupling MPI set info structure.

Parameters
[in]spointer to PLE coupling MPI set info structure.

◆ ple_coupling_mpi_set_get_app_id()

int ple_coupling_mpi_set_get_app_id ( const ple_coupling_mpi_set_t * s)

Return the id of the local application in a coupled set.

Parameters
[in]spointer to PLE coupling MPI set info structure.
Returns
id of the local application in set's common communicator.

◆ ple_coupling_mpi_set_get_base_comm()

MPI_Comm ple_coupling_mpi_set_get_base_comm ( const ple_coupling_mpi_set_t * s)

Get base communicator of an PLE coupling MPI set.

Parameters
[in]spointer to PLE coupling MPI set info structure.

◆ ple_coupling_mpi_set_get_info()

ple_coupling_mpi_set_info_t ple_coupling_mpi_set_get_info ( const ple_coupling_mpi_set_t * s,
int app_id )

Return application information in set's common communicator.

Parameters
[in]spointer to PLE coupling MPI set info structure.
[in]app_idapplication id
Returns
application information structure.

◆ ple_coupling_mpi_set_get_status()

const int * ple_coupling_mpi_set_get_status ( const ple_coupling_mpi_set_t * s)

Get status of applications in a set.

This function allows access to the status flag of each synchronized application in the set. It may be used immediately after ple_coupling_mpi_set_create(), and flags are updated after each call to ple_coupling_mpi_set_synchronize().

param[in] s pointer to PLE coupling MPI set info structure.

Returns
a pointer to the set's array of status flags

◆ ple_coupling_mpi_set_get_timestep()

const double * ple_coupling_mpi_set_get_timestep ( const ple_coupling_mpi_set_t * s)

Get time steps in a set.

This function may be called after ple_coupling_mpi_set_synchronize() to query the time step values of each synchronized application in the set.

Parameters
[in]spointer to PLE coupling MPI set info structure.
Returns
a pointer to the set's array of time steps

◆ ple_coupling_mpi_set_n_apps()

int ple_coupling_mpi_set_n_apps ( const ple_coupling_mpi_set_t * s)

Return the number of applications in a coupled set.

Parameters
[in]spointer to PLE coupling MPI set info structure.
Returns
number of application in set's common communicator.

◆ ple_coupling_mpi_set_synchronize()

void ple_coupling_mpi_set_synchronize ( ple_coupling_mpi_set_t * s,
int sync_flag,
double time_step )

Synchronize applications in a set.

Note that if a member of the set has used a PLE_COUPLING_STOP or PLE_COUPLING_LAST flag when calling ple_coupling_mpi_set_create() or or at the previous call to this function, it will not be synchronized anymore (i.e. the PLE_COUPLING_NO_SYNC flag will be added).

param[in] s pointer to PLE coupling MPI set info structure. param[in] sync_flag synchronization info for current application. param[in] time_step time step for current application.