.. _physics-evolveForestsWorkShare:

Evolve Forests Work Share
=========================

Class providing work sharing strategies for the evolve forests task---the algorithm that assigns merger tree forests to individual MPI processes and OpenMP threads for parallel execution. Implementations return the index of the next forest to be processed by the calling worker, a unique worker identifier, and the total worker count. Strategies include first-come-first-served (FCFS) dynamic scheduling and static pre-assignment, with load balancing optionally guided by tree processing time estimates from :galacticus-class:`metaTreeProcessingTimeClass`.

**Default implementation:** ``evolveForestsWorkShareFCFS``

Methods
-------

``forestNumber`` → ``integer(c_size_t)``
   Return the number of the forest to process.

   * ``logical, intent(in ) :: utilizeOpenMPThreads``

``workerID`` → ``integer``
   Return a unique worker ID.

   * ``logical, intent(in ) :: utilizeOpenMPThreads``

``workerCount`` → ``integer``
   Return the count of workers.

   * ``logical, intent(in ) :: utilizeOpenMPThreads``

.. _physics-evolveForestsWorkShareCyclic:

``evolveForestsWorkShareCyclic``
--------------------------------

A forest evolution work sharing class implementing static cyclic assignment, where each worker (MPI rank or OpenMP thread) is pre-assigned a contiguous block of forests offset by the worker index and strided by the total worker count. This gives deterministic, reproducible forest-to-worker mapping at the cost of potentially uneven load balancing.

.. _physics-evolveForestsWorkShareFCFS:

``evolveForestsWorkShareFCFS``
------------------------------

A forest evolution work sharing class implementing dynamic first-come-first-served (FCFS) scheduling, in which each worker atomically increments a shared MPI counter to claim the next available forest. This provides good load balancing across variable-cost forests at the expense of MPI synchronization overhead. Optionally, a subset of active MPI process ranks can be specified.

**(Default implementation)**

**Parameters**

* ``[doPing]`` (default ``.false.``) — If true, the master MPI process will attach to the ``calculationReset`` event and ping the MPI counter. This can help to ensure that the counter updates regularly.
* ``[reportWaitTime]`` (default ``.false.``) — If true, the time spent waiting to increment the counter will be reported.
* ``[activeProcessRanks]`` — A list of MPI process ranks which will be allowed to process trees---all other ranks are given no work.

.. _physics-evolveForestsWorkShareStride:

``evolveForestsWorkShareStride``
--------------------------------

A forest evolution work sharing class that wraps another work sharing strategy and applies a stride and offset to the resulting forest indices, so that only every :math:`N`-th forest (offset by a given amount) is processed. This enables subsampling of forests or splitting a forest set across independent runs without modifying the underlying assignment algorithm.

**Parameters**

* ``[stride]`` — The size of the stride to take over forests.
* ``[offset]`` — The offset of the stride to take over forests.