.. _usage:

Usage
=====

Initialization
--------------

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

.. code-block:: c

    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:

.. code-block:: c

    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:

.. code-block:: c

    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:

.. code-block:: c

    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
-------

.. toctree::
    :maxdepth: 1

    example