larvaworld.lib.sim.batch_run
============================

.. py:module:: larvaworld.lib.sim.batch_run


Classes
-------

.. autoapisummary::

   larvaworld.lib.sim.batch_run.OptimizationOps
   larvaworld.lib.sim.batch_run.BatchRun


Functions
---------

.. autoapisummary::

   larvaworld.lib.sim.batch_run.space_search_sample


Module Contents
---------------

.. py:class:: OptimizationOps

   Bases: :py:obj:`larvaworld.lib.param.NestedConf`


   Configuration for optimization-guided parameter space search.

   Defines stopping criteria and optimization goals for batch runs
   that use optimization instead of grid search to explore parameter space.

   Attributes:
       fit_par: Fitness parameter name to optimize.
       minimize: If True, minimize fitness; if False, maximize.
       absolute: If True, use absolute values of fitness parameter.
       max_Nsims: Maximum number of simulations before halting.
       threshold: Target fitness value to reach.
       operator: Aggregation operator ('mean' or 'std') across agents.


   .. py:attribute:: fit_par


   .. py:attribute:: minimize


   .. py:attribute:: absolute


   .. py:attribute:: max_Nsims


   .. py:attribute:: threshold


   .. py:attribute:: operator


   .. py:method:: check(fits: numpy.ndarray) -> None

      Check optimization stopping criteria and log status.

      Evaluates whether to halt optimization based on maximum
      simulations reached or threshold achieved.

      Args:
          fits: Array of fitness values from completed simulations.

      Side Effects:
          Prints status message via vprint.



   .. py:method:: threshold_reached(fits: numpy.ndarray) -> bool

      Check if fitness threshold has been reached.

      Compares best fitness value (min or max based on optimization
      direction) against the target threshold.

      Args:
          fits: Array of fitness values from completed simulations.

      Returns:
          True if threshold reached, False otherwise.



.. py:class:: BatchRun(experiment: str, space_search: dict[str, Any], id: str | None = None, space_kws: dict[str, Any] = {}, exp: Any = None, exp_kws: dict[str, Any] = {}, store_data: bool = False, **kwargs: Any)

   Bases: :py:obj:`larvaworld.lib.reg.generators.SimConfiguration`, :py:obj:`agentpy.Experiment`


   Batch execution of parameter space search experiments.

   Runs multiple simulations with varying parameters to explore
   parameter space either via grid search or optimization-guided search.
   Extends agentpy.Experiment for parallel execution and result aggregation.

   Attributes:
       optimization: OptimizationOps configuration for guided search.

   Example:
       >>> batch_conf = reg.conf.Batch.getID('chemorbit')
       >>> batch = BatchRun(experiment='chemorbit', **batch_conf)
       >>> batch.simulate(n_jobs=4)


   .. py:attribute:: optimization


   .. py:attribute:: df_path


   .. py:attribute:: exp_conf


   .. py:attribute:: datasets


   .. py:attribute:: results
      :value: None



   .. py:attribute:: figs


   .. py:method:: default_processing(d: Any | None = None)


   .. py:method:: end() -> None

      Defines the experiment's actions after the last simulation.
      Can be overwritten for final calculations and reporting.



   .. py:method:: simulate(**kwargs: Any)


   .. py:method:: plot_results() -> None


   .. py:method:: PI_heatmap(**kwargs: Any) -> None


.. py:function:: space_search_sample(space_dict: dict[str, Any], n: int = 1, **kwargs: Any)

   Convert parameter space dictionary to agentpy Sample object.

   Transforms user-friendly parameter space specification into
   agentpy sampling objects (Values, Range, IntRange) for batch execution.

   Args:
       space_dict: Parameter space specification with structure:
                  - Direct value: param_name: value
                  - Discrete values: param_name: {'values': [v1, v2, ...]}
                  - Continuous range: param_name: {'range': (min, max)}
                  - Grid range: param_name: {'range': (min, max), 'Ngrid': N}
       n: Number of samples to generate (default: 1 for grid search).
       **kwargs: Additional args passed to ap.Sample constructor.

   Returns:
       agentpy.Sample object for batch parameter iteration.

   Example:
       >>> space = {
       >>>     'N': 50,
       >>>     'food_grid': {'values': [5, 10, 15]},
       >>>     'duration': {'range': (1.0, 10.0), 'Ngrid': 10}
       >>> }
       >>> sample = space_search_sample(space)