Reference ========= Data structures --------------- dyn_pset_state_t ~~~~~~~~~~~~~~~~ .. code-block:: c typedef struct{ void * dyn_pset_data; // Library internal data. Should not be accessed by users void * user_pointer; // User data pointer passed at init bool is_dynamic; // True if the process was added dynamically MPI_Comm mpicomm; // Current MPI communicator int mpirank; // Rank in mpicomm int mpisize; // Size of mpicomm MPI_Group group_add; // Group added during last reconfiguration MPI_Group group_sub; // Group removed during last reconfiguration } dyn_pset_state_t; Fields ------ - ``dyn_pset_data``: Opaque, internal library state. Users must not access this directly. - ``user_pointer``: Opaque pointer provided by the application at initialization; forwarded to redistribution callbacks to enable application-specific data movement. - ``is_dynamic``: Indicates whether this process was added during a dynamic expansion. - ``mpicomm``/``mpirank``/``mpisize``: Current MPI communicator and rank/size; these may change as a direct result of reconfiguration operations. - ``group_add``/``group_sub``: MPI groups reflecting the last reconfiguration; useful for identifying which ranks were added or removed. Notes ----- Fields in ``dyn_pset_state_t`` may change after calls to ``dyn_pset_adapt`` or ``dyn_pset_adapt_nb``; callers should re-read the structure after reconfiguration completes. Notes ----- This reference is a concise summary extracted from the project's README. For more in-depth details see the in-source comments and the implementation in ``src/``. .. function:: int dyn_pset_finalize(dyn_pset_state_t ** state, char *final_pset) Finalize the Dyn_PSet state and optionally write the final PSet name into ``final_pset`` (must be a buffer of length ``MPI_MAX_PSET_NAME_LEN`` if non-NULL). .. function:: int dyn_pset_set_info(dyn_pset_state_t * state, MPI_Info info) Set optimization information (see the info keys table below). .. function:: 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) Initialize the Dyn_PSets library and return a ``dyn_pset_state_t`` pointer on success or ``NULL`` if the initialization was canceled (e.g., an expansion was aborted and the calling process should terminate). The parameters are the same as described in the Usage section; notable behaviors: - ``info``: Use an ``MPI_Info`` object to provide optimization/hint keys (see the "Optimization Information Keys" table). - Redistribution callbacks (``exp_send``, ``exp_recv``, ``shr_send``, ``shr_recv``) are invoked by the library during reconfiguration to move application data between processes. .. function:: int dyn_pset_adapt(dyn_pset_state_t * state, int *terminate, int *reconfigured) Blocking call that attempts to reconfigure the DynPSet state according to the policy and any optimization information previously specified. On return, ``terminate`` is set to 1 if the calling process must terminate (it was removed by shrinkage); ``reconfigured`` is set to 1 if a reconfiguration occurred. .. function:: int dyn_pset_adapt_nb(dyn_pset_state_t * state, int *terminate, int *reconfigured) Non-blocking variant of ``dyn_pset_adapt``. Returns promptly and sets ``reconfigured`` to 0 or 1 to indicate whether a reconfiguration occurred. If ``reconfigured`` is 0, callers should call this function again to check for completion. Optimization Information Keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The library accepts optimization information via the ``MPI_Info`` passed to ``dyn_pset_init`` or ``dyn_pset_set_info``. Common keys include (at least one of ``generator_key`` or ``output_space_generator`` should be provided; ``model`` is recommended): .. csv-table:: Optimization Information Keys :header: "Key", "Value", "Description" :widths: 30, 20, 50 "generator_key","","Task attribute key used in the batch script." "output_space_generator","","Python expression that evaluates to an output-space generator function." "output_space_generator_def","","Full function definition for the output-space generator." "model","","Evaluates to an instance of a PSet model (e.g. DefaultReplaceModel())." "model_params","","Comma-separated parameter triples for the model." "input_pset_model_[index]","","PSet model class name for the input PSet at the given index." "input_pset_model_params_[index]","","Comma-separated params for the corresponding input-pset model." .. function:: void dyn_pset_set_output(char * filename, int verbosity_level) Configure debug output file and verbosity. .. function:: int dyn_pset_config(dyn_pset_state_t * state, const char * config_param, void * value) Set runtime configuration parameters (see supported configure parameters below). Supported configure parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The current implementation supports the following configure parameter: .. csv-table:: Configure Parameters :header: "Parameter", "Type", "Description" :widths: 20, 10, 70 "garbage_collection", "bool", "Default: true. If set to false, MPI communicators will not be garbage collected during reconfiguration; the user is responsible for disconnecting and cleaning up communicators." "col_update", "bool", "Default: false. If set to true, calls to ``dyn_pset_set_info`` will trigger updates of currently pending psetop." Callback typedefs ----------------- .. code-block:: c typedef int (*dyn_psets_expand_send_func_t) (dyn_pset_state_t * state); typedef int (*dyn_psets_expand_recv_func_t) (dyn_pset_state_t * state); typedef int (*dyn_psets_shrink_send_func_t) (dyn_pset_state_t * state); typedef int (*dyn_psets_shrink_recv_func_t) (dyn_pset_state_t * state); Notes ----- This reference is a concise summary extracted from the project's README. For more in-depth details see the in-source comments and the implementation in `src/`.