larvaworld.lib.sim.batch_run

Classes

`OptimizationOps`	Configuration for optimization-guided parameter space search.
`BatchRun`	Batch execution of parameter space search experiments.

Functions

space_search_sample(space_dict[, n])

Convert parameter space dictionary to agentpy Sample object.

Module Contents

class larvaworld.lib.sim.batch_run.OptimizationOps

Bases: 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.

fit_par

minimize

absolute

max_Nsims

threshold

operator

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.

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.

class larvaworld.lib.sim.batch_run.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: larvaworld.lib.reg.generators.SimConfiguration, 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)

optimization

df_path

exp_conf

datasets

results = None

figs

default_processing(d: Any | None = None)

end() → None: Defines the experiment’s actions after the last simulation. Can be overwritten for final calculations and reporting.

simulate(**kwargs: Any)

plot_results() → None

PI_heatmap(**kwargs: Any) → None

larvaworld.lib.sim.batch_run.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)