larvaworld.lib.sim.single_run

Classes

ExpRun

Basic Class for the Agent-based model

Module Contents

class larvaworld.lib.sim.single_run.ExpRun(experiment: str | None = None, parameters: dict | None = None, parameter_dict: dict = {}, **kwargs: Any)

Bases: larvaworld.lib.sim.base_run.BaseRun

Basic Class for the Agent-based model Extends the agentpy Model class

parameter_dict

setup() → None

Sets up the simulation environment and agents for a single run.

This method performs the following steps: 1. Initializes simulation epochs based on the provided trials. 2. Converts epoch age ranges to start and stop times in simulation steps. 3. Builds the simulation environment using the provided environment parameters. 4. Constructs agents based on the provided larva groups and parameter dictionary. 5. Sets up data collectors for the simulation. 6. Eliminates overlap between agents if larva collisions are not allowed. 7. Determines the termination condition for the simulation.

step() → None

Defines the models’ events per simulation step.

update() → None

Record a dynamic variable.

end() → None

Repord an evaluation measure.

simulate(**kwargs: Any)

Simulates the larva world environment and collects data.

This method initializes the simulation, runs it, collects the output data, and optionally enriches and stores the data.

Returns:

list: A list of datasets collected during the simulation.

build_agents(larva_groups: dict, parameter_dict: dict = {}) → None

Builds and places agent groups in the simulation.

Args:

larva_groups (dict): A dictionary containing larva group configurations. parameter_dict (dict, optional): A dictionary of parameters to be passed to each larva group. Defaults to an empty dictionary.

Returns:

None

eliminate_overlap() → None

Adjusts the positions of larva agents to eliminate overlaps.

This method iteratively checks for collisions among larva agents and adjusts their positions randomly until no collisions are detected. The scale parameter is used to determine the precision of collision detection and adjustment.

The process involves: 1. Checking for existing collisions at a given scale. 2. If collisions are detected, updating the positions of the larva agents. 3. Repeating the process until no collisions are found.

collisions_exist(scale: float = 1.0) → bool

Check if any collisions exist among the agents.

This method scales the larva bodies and checks each agent for collisions. If any agent has collisions, the method returns True, otherwise False.

Args:

scale (float, optional): The scale factor to apply to the larva bodies. Defaults to 1.0.

Returns:

bool: True if any collisions are detected, False otherwise.

detect_collisions(id: int)

Detects collisions between a given larva and other larvae in the simulation.

Args:

id (int): The identifier of the larva to check for collisions.

Returns:

list: A list of identifiers of larvae that are colliding with the given larva.

get_larva_bodies(scale: float = 1.0)

Retrieve the shapes of all larva agents in the simulation.

Args:

scale (float, optional): A scaling factor to apply to the shapes. Defaults to 1.0.

Returns:

dict: A dictionary where the keys are the unique IDs of the larva agents

and the values are Shapely geometries (scaled by the given factor) that support spatial predicates like intersects.

analyze(**kwargs: Any) → None

Analyzes the datasets based on the specified experiment type and generates plots or results accordingly.

Keyword Args:

**kwargs: Additional keyword arguments to be passed to the plotting functions.

Returns:

None

This method performs the following steps: 1. Creates the directory for storing plots if it does not exist. 2. Checks if the datasets are available and valid. 3. If the experiment type includes “PI” (odor preference), it extracts PI and PI2 values from the datasets and stores them in the results attribute. 4. If the experiment type includes “disp” (disperal), it loads reference datasets based on unique samples in the datasets. 5. Retrieves the analysis graph groups based on the experiment type and source coordinates. 6. Evaluates the graph groups and generates the corresponding figures, saving them to the plot directory.

property graphgroups

Retrieve the graph groups for the current experiment type.

Returns:

list: A list of graph groups corresponding to the experiment type.

store() → None

Stores the simulation output and datasets.

This method performs the following steps: 1. Attempts to save the simulation output using the parameters specified in self.p.agentpy_output_kws. 2. Creates the directory specified by self.data_dir if it does not already exist. 3. Iterates over the datasets in self.datasets, saving each one and storing their larva dictionaries.

Note:

If an exception occurs during the saving of the simulation output, it is silently ignored.

Raises:

Any exceptions raised during the creation of the directory or saving of datasets are not handled and will propagate.

load_agentpy_output()

Load and process the output from an AgentPy simulation.

This method loads the simulation output data using the parameters specified in self.p.agentpy_output_kws, concatenates the variables along the rows, and drops the second level of the index. The resulting DataFrame’s index is renamed to “Model”.

Returns:

pd.DataFrame: A DataFrame containing the processed simulation output data.

classmethod from_ID(id: str, simulate: bool = True, **kwargs: Any)

Create an instance of the class from a given experiment ID.

Args:

id (str): The experiment ID to create the instance from. simulate (bool, optional): Whether to run the simulation. Defaults to True. **kwargs: Additional keyword arguments to pass to the class constructor.

Returns:

object: An instance of the class initialized with the given experiment ID.

Raises:

AssertionError: If the provided ID is not in the list of valid experiment IDs.