Usage

Initialization

Initialize the dyn_psets library and a new MPI Session. This function is usually placed early in the program:

dyn_pset_state_t * dyn_pset_init(const char *initial_pset, void *user_pointer, MPI_Info info,
        dyn_psets_expand_send_func_t exp_send, dyn_psets_expand_recv_func_t exp_recv,
        dyn_psets_shrink_send_func_t shr_send, dyn_psets_shrink_recv_func_t shr_recv);

Parameters

  • initial_pset: name of the initial PSet (e.g., mpi://WORLD).

  • user_pointer: pointer to user-defined state; useful during redistribution callbacks.

  • info: MPI_Info object with optimization hints (use MPI_INFO_NULL to delay reconfiguration).

  • exp_send/exp_recv: callbacks executed by outgoing and incoming processes during expansion.

  • shr_send/shr_recv: callbacks executed by leaving and staying processes during shrinkage.

Return

Returns dyn_pset_state_t * describing the current state. NULL is returned if the initialization was canceled (for example, if an expansion was canceled and this process should terminate).

Process Reconfiguration

The library provides blocking and non-blocking reconfiguration calls. These are usually placed at the beginning or end of the main loop of a program:

int dyn_pset_adapt(dyn_pset_state_t * state, int *terminate, int *reconfigured);
int dyn_pset_adapt_nb(dyn_pset_state_t * state, int *terminate, int *reconfigured);

Parameters

  • state: the Dyn_PSet state to adapt.

  • terminate: pointer to an int set to 1 if the calling process must terminate due to shrinkage.

  • reconfigured: pointer to an int set to 1 if the Dyn_PSet state was changed by this call.

Notes

dyn_pset_adapt may block until a reconfiguration takes place; dyn_pset_adapt_nb is non-blocking and returns promptly, setting reconfigured to 0 or 1.

Finalization

Use dyn_pset_finalize to finalize the state. This is placed at the end of a program:

int dyn_pset_finalize(dyn_pset_state_t ** state, char *final_pset);

Parameters

  • state: pointer to the Dyn_PSet state pointer to be finalized (it will be set to NULL).

  • final_pset: optional buffer to receive the current main PSet name (must be of length MPI_MAX_PSET_NAME_LEN if non-NULL).

State structure

The returned dyn_pset_state_t object holds the current dynamic PSet state and includes the following commonly-used fields:

  • user_pointer: the opaque pointer passed by the application at initialization (useful inside redistribution callbacks).

  • is_dynamic: if true, the calling process was added dynamically and will generally execute the ‘new process’ code path.

  • mpicomm, mpirank, mpisize: the communicator and rank/size of the current PSet; these values may change after reconfiguration.

  • group_add / group_sub: MPI groups describing processes added or removed in the most recent reconfiguration.

Callers should not assume these values are stable across reconfiguration operations and should re-read them after calls to dyn_pset_adapt / dyn_pset_adapt_nb.

Optimization information

Use MPI_Info to convey optimization hints to the library with dyn_pset_set_info.

Parameters for dyn_pset_set_info

This call accepts the optimization keys described in the Reference section. Typical keys include generator_key, output_space_generator (a Python expression), model, and parameter sets such as model_params. See the Reference’s “Optimization Information Keys” table for full details.

Debug output

Control debug output via:

void dyn_pset_set_output(char * filename, int verbosity_level);

Configuration

Use dyn_pset_config to set runtime configuration parameters such as garbage collection behavior.

Parameters for dyn_pset_config

  • config_param: the configuration parameter name (e.g., "garbage_collection").

  • value: pointer to the value to set (type depends on parameter; e.g., pointer to bool for garbage_collection).

See the Reference section ‘Supported configure parameters’ for details and defaults.

Example