larvaworld.lib.sim.genetic_algorithm

Classes

`GAevaluation`	Genetic algorithm evaluation configuration.
`GAselector`	Genetic algorithm selection and evolution configuration.
`GAlauncher`	Genetic algorithm launcher for model optimization.

Functions

optimize_mID(mID0, ks, evaluator[, mID1, experiment, ...])

Optimize model configuration using genetic algorithm.

Module Contents

class larvaworld.lib.sim.genetic_algorithm.GAevaluation(**kwargs: Any)

Bases: larvaworld.lib.process.Evaluation

Genetic algorithm evaluation configuration.

Extends Evaluation with GA-specific fitness functions, exclusion criteria, and optimization operators for evolutionary search.

Attributes:

exclusion_mode: If True, apply exclusion criteria instead of fitness. exclude_func_name: Name of exclusion function from exclusion_funcs. fitness_func_name: Name of fitness function from fitness_funcs. fit_kws: Keyword arguments passed to fitness function.

Example:

>>> ga_eval = GAevaluation(
...     fitness_func_name='dst2source',
...     exclusion_mode=False,
...     fit_kws={'target_xy': (0, 0)}
... )

exclusion_mode

exclude_func_name

fitness_func_name

fit_kws

exclude_func

class larvaworld.lib.sim.genetic_algorithm.GAselector(**kwargs: Any)

Bases: larvaworld.lib.model.SpaceDict

Genetic algorithm selection and evolution configuration.

Manages population size, selection strategy, and evolutionary parameters for GA optimization process.

Attributes:

Ngenerations: Number of generations to evolve (None = infinite). Nagents: Population size per generation. Nelits: Number of elite agents preserved each generation. selection_ratio: Fraction of population selected for breeding. bestConfID: Configuration ID for storing best model.

Example:

>>> selector = GAselector(
...     Ngenerations=50,
...     Nagents=20,
...     Nelits=3,
...     selection_ratio=0.3
... )

Ngenerations

Nagents

Nelits

selection_ratio

bestConfID

Nagents_min

new_genome(gConf: dict, mConf0: larvaworld.lib.util.AttrDict) → larvaworld.lib.util.AttrDict

Create a new genome with the given genetic and mutation configurations.

Args:

gConf (dict): Genetic configuration dictionary. mConf0 (AttrDict): Initial mutation configuration as an AttrDict.

Returns:

AttrDict: A dictionary-like object containing the new genome’s fitness,: fitness dictionary, genetic configuration, and updated mutation configuration.

create_new_generation(sorted_gs: list) → list

Create a new generation of genomes using elitism and crossover.

Args:

sorted_gs (list): A list of sorted genomes from the previous generation.

Returns:

list: A new list of genomes for the next generation.

Raises:

ValueError: If the number of genomes is lower than the minimum required to breed a new generation.

Notes:

The best genomes are preserved through elitism.
New genomes are created by randomly selecting and combining attributes from two parent genomes.
The new genomes are then mutated before being added to the new generation.

create_generation(sorted_gs: list | None = None) → dict

Creates a new generation of genomes.

If sorted_gs is provided, it creates a new generation based on the sorted genomes. Otherwise, it creates the first generation with a specified number of agents.

Args:: sorted_gs (list, optional): A list of sorted genomes to base the new generation on. Defaults to None.
Returns:: dict: A dictionary where keys are indices and values are new genomes generated from the configuration.

class larvaworld.lib.sim.genetic_algorithm.GAlauncher(dataset: larvaworld.lib.process.dataset.LarvaDataset | None = None, evaluator: GAevaluation | None = None, **kwargs: Any)

Bases: larvaworld.lib.sim.base_run.BaseRun

Genetic algorithm launcher for model optimization.

Runs evolutionary optimization to evolve agent models toward target behaviors specified by evaluation criteria.

Attributes:

evaluator: GAevaluation instance defining fitness function. selector: GAselector instance managing evolution parameters. genome_dict: Current generation genome configurations. best_genome: Best genome found across all generations. best_fitness: Fitness value of best genome.

Example:

>>> launcher = GAlauncher(
...     dataset=ref_dataset,
...     evaluator=ga_eval,
...     ga_select_kws={'Ngenerations': 50}
... )
>>> launcher.simulate()

evaluator = None

selector

setup() → None

Initializes the genetic algorithm setup.

This method sets up the initial parameters and configurations for the genetic algorithm, including initializing genome-related attributes, setting up the progress bar, and building the environment and the first generation.

Attributes:: genome_dict (dict): Dictionary to store genome information. best_genome (Any): Stores the best genome found. best_fitness (Any): Stores the fitness value of the best genome. sorted_genomes (Any): Stores sorted genomes. all_genomes_dic (list): List to store all genomes. generation_num (int): Counter for the number of generations. progress_bar (progressbar.ProgressBar or None): Progress bar for tracking generations. p.collections (list): List of parameter collections to be recorded.
Prints:: Initialization message and the number of generations to be launched.

simulate()

Simulates the genetic algorithm process.

This method sets up the simulation, runs it in a loop until the simulation is no longer running, and then returns the best genome found during the simulation.

Returns:: Genome: The best genome found during the simulation.

build_generation(sorted_genomes: dict | None = None) → None

Builds a new generation of genomes for the genetic algorithm.

Args:: sorted_genomes (dict, optional): A dictionary of genomes sorted by fitness. Defaults to None.

This method performs the following steps: 1. Records the current time as the pre-start generation time. 2. Increments the generation number. 3. Creates a new generation of genomes using the selector. 4. Prepares configuration dictionaries for each genome, including parameters, unique ID, genome object, and a random bright color. 5. Places agents in the simulation based on the configurations. 6. Sets up data collectors. 7. Initializes threads for agents if multicore processing is enabled. 8. Updates the progress bar if it is enabled. 9. Records the current time as the start generation time. 10. Calculates and prints the duration taken to load the generation.

eval_robots(ds: List[larvaworld.lib.process.dataset.LarvaDataset], Ngen: int, genome_dict: dict) → list

Evaluate the fitness of robots for a given generation.

Parameters: ds (list): A list of LarvaDataset objects to be enriched and evaluated. Ngen (int): The current generation number. genome_dict (dict): A dictionary where keys are genome identifiers and values are genome objects.

Returns: list: A sorted list of valid genome objects based on their fitness, in descending order.

store(sorted_gs: list, Ngen: int) → None

Stores the best genome from the current generation and updates the best fitness value. Optionally, stores data for all genomes in the current generation.

Args:: sorted_gs (list): A list of genomes sorted by their fitness in descending order. Ngen (int): The current generation number.
Returns:: None

property generation_completed: bool

Check if the current generation is completed.

A generation is considered completed if the number of steps taken (self.t) is greater than or equal to the maximum number of steps allowed (self.Nsteps), or if the number of agents is less than or equal to the minimum number of agents required by the selector (self.selector.Nagents_min).

Returns:: bool: True if the generation is completed, False otherwise.

property max_generation_completed: bool

Check if the maximum number of generations has been completed.

Returns:

bool: True if the current generation number is greater than or equal to the: maximum number of generations specified by the selector, otherwise False.

sim_step() → None

Advances the simulation by one step.

This method increments the simulation time, performs a simulation step, updates the screen manager, and updates the simulation state. If the current generation is completed, it either builds a new generation or finalizes the simulation if the maximum number of generations is reached.

step() → None

Executes a single step of the genetic algorithm simulation.

If threads are available, each thread will perform a step. Otherwise, the agents will perform a step.

Additionally, if an exclusion function is defined in the evaluator, it will be applied to each agent. If an agent is excluded by the function, its genome’s fitness will be set to negative infinity.

end() → None

Finalizes the current generation by performing the following steps: 1. Records the end time of the generation and calculates its duration. 2. Logs the completion of the generation. 3. Records the agents’ final states. 4. Creates output data for the generation. 5. Collects and processes the data into a LarvaDatasetCollection. 6. Evaluates the robots based on the collected data and sorts their genomes. 7. Deletes the agents for the current generation. 8. Resets internal logs and time counters. 9. Records the end time of the evaluation and calculates its duration. 10. Logs the completion of the evaluation.

This method is typically called at the end of each generation in a genetic algorithm simulation.

update() → None

Updates the state of the genetic algorithm simulation.

This method performs the following actions: 1. Records the current state of the agents using the step collector. 2. (Commented out) Updates the progress bar for the genetic algorithm generation.

Note: The progress bar update is currently commented out.

finalize() → None

Finalizes the genetic algorithm simulation.

This method performs the following actions: - Sets the running flag to False, indicating the simulation has ended. - Calls the finalize method on the screen manager to clean up any resources. - If a progress bar is being used, it finishes the progress bar. - Prints the best fitness value found during the simulation. - If data storage is enabled, stores all genomes to the specified directory.

Returns:: None

store_genomes(dic: dict, save_to: str) → None

Stores the genomes in a DataFrame, sorts them by fitness, and saves the results to a CSV file. Additionally, generates a correlation DataFrame and a difference DataFrame if possible.

Parameters: dic (dict): Dictionary containing genome data. save_to (str): Path to the directory where the results will be saved.

Returns: None

build_threads(robots: list) → list

Distributes the given robots among multiple threads for parallel processing.

This method divides the list of robots into sublists, each assigned to a separate thread. The number of threads created is equal to the number of CPU cores available. Each thread processes a subset of the robots list.

Args:: robots (list): A list of robot instances to be processed.
Returns:: list: A list of threads that were created and executed.

larvaworld.lib.sim.genetic_algorithm.optimize_mID(mID0: str, ks: list[str], evaluator: GAevaluation, mID1: str | None = None, experiment: str = 'exploration', Nagents: int = 10, Nelits: int = 2, Ngenerations: int = 3, duration: float = 0.5, **kwargs: Any)

Optimize model configuration using genetic algorithm.

Evolves agent model parameters through evolutionary search to optimize fitness according to evaluator criteria.

Args:

mID0: Initial model configuration ID. ks: List of parameter keys defining search space. evaluator: GAevaluation instance for fitness computation. mID1: Model ID for storing optimized configuration (default: mID0). experiment: Experiment type for simulations (default: ‘exploration’). Nagents: Population size per generation (default: 10). Nelits: Number of elite agents preserved (default: 2). Ngenerations: Number of evolution generations (default: 3). duration: Simulation duration per agent (default: 0.5). **kwargs: Additional arguments passed to GAlauncher.

Returns:

GAlauncher instance with optimization results.

Example:

>>> launcher = optimize_mID(
...     mID0='explorer',
...     ks=['crawler.f', 'turner.ang_v'],
...     evaluator=ga_eval,
...     Ngenerations=50
... )