acds.evolutionary package

Submodules

acds.evolutionary.environment module

class acds.evolutionary.environment.SwarmForagingEnv(*args: Any, **kwargs: Any)

Bases: Env

Gymnasium environment for multi-agent colored-block foraging.

Agents move in a square arena with three omniwheel velocity commands, observe nearby walls, robots, and blocks, and receive reward for retrieving blocks whose color matches the current seasonal target.

Parameters:

• target_color – Color id that currently defines the rewarded block.

• size – Side length of the simulated square arena.

• n_agents – Number of robots in the swarm.

• n_blocks – Number of blocks placed in the arena.

• n_neighbors – Number of nearest sensed entities reported per robot.

• sensor_range – Maximum sensing distance in simulation units.

• max_wheel_velocity – Maximum velocity for each omniwheel command.

• sensitivity – Interaction radius for picking up blocks.

• time_step – Duration of one simulation step in seconds.

• duration – Maximum number of steps in one episode.

• max_retrieves – Number of correct retrieves that terminates an episode.

• colors – Available block color ids.

• rate_target_block – Fraction of blocks using target_color.

• repositioning – If True, retrieved blocks are respawned.

• efficency_reward – If True, add a completion-time reward.

• see_other_agents – If True, include nearby robots in observations.

• blocks_in_line – If True, initialize blocks along one line.

• season_colors – Active subset of colors for the current season.

change_season(new_season_colors, new_target_color)

Switch the active block colors and target color.

Parameters:

• new_season_colors – Color ids available in the new season.

• new_target_color – Target color id rewarded in the new season.

Raises:

ValueError – If a color is outside the configured color set or the target is not in new_season_colors.

close()

Close the environment.

The environment does not currently allocate external rendering resources, so this method is a no-op kept for Gymnasium compatibility.

create_initial_state()

Create randomized starting positions, headings, and block colors.

Returns:

Dictionary with agents, headings, blocks, and colors arrays used by reset().

Raises:

ValueError – If blocks_in_line is requested with too many blocks for the arena size.

print_observations(verbose=True)

Format the latest per-agent sensor readings as text.

Parameters:

verbose – If True, print the formatted observations.

Returns:

Human-readable multiline observation summary.

process_observation(obs, one_hot=True)

Convert raw environment observations into neural-network features.

Parameters:

• obs – Observation list returned by reset() or step().

• one_hot – If True, one-hot encode entity, carrying, and task labels.

Returns:

Feature matrix with one row per agent.

render(show_info=False, verbose=True)

Render the current arena state as a PIL image.

Parameters:

• show_info – If True, include retrieve counts in the image.

• verbose – If True, print the text grid to stdout.

Returns:

PIL image representing agents, blocks, and optional counts.

reset(seed=None)

Reset the episode state and compute the initial observations.

Parameters:

seed – Optional seed for the NumPy random generator.

Returns:

Pair (observations, info) following the Gymnasium API.

step(action)

Advance the swarm simulation by one time step.

Parameters:

action – Sequence of per-agent (v1, v2, v3) wheel velocities.

Returns:

Tuple (observations, reward, done, truncated, info).

acds.evolutionary.experiment module

class acds.evolutionary.experiment.LifelongEvoSwarmExperiment(name: str = None, population_size: int = None, env: SwarmForagingEnv = None, config_neat: neat.config.Config = None, seed: int = None, n_envs: int = 1, n_workers: int = 1)

Bases: object

Coordinate lifelong NEAT optimization across changing swarm tasks.

The experiment owns a swarm environment, a NEAT population, and the retained environments/models used to evaluate behavior after seasonal drifts.

Parameters:

• name – User-facing experiment name used in result paths.

• population_size – Number of genomes in the NEAT population.

• env – Swarm-foraging environment evaluated by the controllers.

• config_neat – NEAT configuration object.

• seed – Random seed for Python and NumPy generators.

• n_envs – Number of seeded environments used per fitness estimate.

• n_workers – Number of worker processes for genome evaluation.

drift(new_colors, new_target)

Apply a seasonal task drift and retain the previous task state.

Parameters:

• new_colors – Color ids available in the next season.

• new_target – Target color id for the next season.

run(generations: int, eval_retention: str = None, n_prev_eval_retention: int = 1, regularization_type: str = None, regularization_coefficient=None, n_prev_models=1)

Run NEAT for the current task and persist experiment artifacts.

Parameters:

• generations – Number of NEAT generations to execute.

• eval_retention – Optional retention metrics, such as top or population.

• n_prev_eval_retention – Number of previous environments used for retention evaluation.

• regularization_type – Optional regularization strategy for post-drift training.

• regularization_coefficient – Coefficient or coefficients for the selected regularizer.

• n_prev_models – Number of retained models used by regularizers.

Raises:

ValueError – If required experiment configuration is missing or an unsupported retention/regularization option is provided.

run_genome(id_genome, env, filename=None)

Replay one genome in an environment and optionally save a GIF.

Parameters:

• id_genome – Genome id in the current NEAT population.

• env – Environment instance used for the replay.

• filename – Optional GIF suffix written under the result folder.

Returns:

Tuple (total_reward, info) for the replayed episode.

Raises:

ValueError – If the environment or NEAT config is missing.

acds.evolutionary.run module

acds.evolutionary.run.main(name, steps, generations, population_size, n_agents, n_blocks, n_envs, eval_retention, regularization, lambd, config_path, moredrifts, retention_n_prev, reg_n_prevs, seed, workers)

Run a lifelong swarm-foraging NEAT experiment from CLI parameters.

Parameters:

• name – Experiment name used in output paths.

• steps – Maximum number of simulation steps per episode.

• generations – Number of NEAT generations per season.

• population_size – NEAT population size.

• n_agents – Number of swarm agents.

• n_blocks – Number of colored blocks in the arena.

• n_envs – Number of evaluation environments per genome.

• eval_retention – Optional retention-evaluation strategies.

• regularization – Optional regularization strategy after drifts.

• lambd – Regularization coefficient.

• config_path – Path to the NEAT configuration file.

• moredrifts – If True, run four seasonal tasks instead of three.

• retention_n_prev – Number of previous tasks used for retention.

• reg_n_prevs – Number of previous models used for regularization.

• seed – Random seed.

• workers – Number of evaluation workers.

acds.evolutionary.utils module

acds.evolutionary.utils.create_gif(images, gif_path, duration=0.1, loop=0)

Save a list of PIL images as an animated GIF.

Parameters:

• images – Ordered image frames. If empty, no file is written.

• gif_path – Output GIF path.

• duration – Frame duration passed to PIL.

• loop – Loop count passed to PIL, where 0 means infinite.

acds.evolutionary.utils.draw_net(config, genome, view=False, filename=None, node_names=None, show_disabled=True, prune_unused=False, node_colors=None, fmt='svg')

Draw a NEAT genome graph with Graphviz.

Parameters:

• config – NEAT configuration containing input and output keys.

• genome – Genome to visualize.

• view – If True, ask Graphviz to open the rendered file.

• filename – Output filename prefix passed to Graphviz.

• node_names – Optional mapping from node ids to labels.

• show_disabled – If True, draw disabled connections as dotted edges.

• prune_unused – If True, prune nodes that do not affect outputs.

• node_colors – Optional mapping from node ids to fill colors.

• fmt – Graphviz output format.

Returns:

Graphviz Digraph object.

acds.evolutionary.utils.eaEvoStick(population, toolbox, ngen, stats=None, halloffame=None, verbose=True)

Run an elitist mutation-only evolutionary loop.

Parameters:

• population – Initial DEAP population.

• toolbox – DEAP toolbox with selection, clone, mutate, and evaluate operators.

• ngen – Number of generations.

• stats – Optional DEAP statistics collector.

• halloffame – Optional hall-of-fame object updated each generation.

• verbose – If True, print logbook rows.

Returns:

Tuple (population, logbook) after evolution.

acds.evolutionary.utils.eaSimpleWithElitism(population, toolbox, cxpb, mutpb, ngen, stats=None, halloffame=None, verbose=True)

Run a DEAP simple evolutionary loop with hall-of-fame elitism.

Hall-of-fame individuals are injected directly into the next generation and are not modified by crossover or mutation.

Parameters:

• population – Initial DEAP population.

• toolbox – DEAP toolbox with evaluate, select, mate, and mutate operators.

• cxpb – Crossover probability.

• mutpb – Mutation probability.

• ngen – Number of generations.

• stats – Optional DEAP statistics collector.

• halloffame – Required DEAP hall-of-fame object.

• verbose – If True, print logbook rows.

Returns:

Tuple (population, logbook) after evolution.

Raises:

ValueError – If halloffame is missing.

acds.evolutionary.utils.inverse_sigmoid(y)

Compute the logit transform.

Parameters:

y – Value or array in (0, 1).

Returns:

log(y / (1 - y)).

acds.evolutionary.utils.load_experiment_json(path)

Load a saved experiment metadata JSON file.

Parameters:

path – Result directory containing experiment.json.

Returns:

Parsed JSON object.

acds.evolutionary.utils.load_logbook_json(path)

Load a saved evolutionary logbook JSON file.

Parameters:

path – Result directory containing logbook.json.

Returns:

Parsed JSON object.

acds.evolutionary.utils.neat_sigmoid(x)

NEAT-compatible sigmoid activation.

Parameters:

x – Input scalar or array.

Returns:

Logistic activation with NEAT’s 4.9 slope.

acds.evolutionary.utils.plot_evolution(bests, avgs=None, medians=None, stds=None, completion_fitness=None, filename=None)

Plot evolutionary fitness statistics over generations.

Parameters:

• bests – Best fitness values per generation.

• avgs – Optional average fitness values.

• medians – Optional median fitness values.

• stds – Optional standard deviations for averages.

• completion_fitness – Optional horizontal completion threshold.

• filename – If provided, save the figure instead of displaying it.

acds.evolutionary.utils.print_kinematic_matrix()

Print the inverse omniwheel kinematic matrix used by the simulator.

acds.evolutionary.utils.selElitistAndTournament(individuals, k, frac_elitist=0.1, tournsize=3)

Select a mix of elite and tournament-chosen individuals.

Parameters:

• individuals – Candidate individuals.

• k – Target number of selected individuals.

• frac_elitist – Fraction selected with selBest.

• tournsize – Tournament size for the remaining selections.

Returns:

Selected individuals.

acds.evolutionary.utils.visual_grid_to_image(visual_grid, blocks_info=None)

Convert the text-grid renderer output into a PIL image.

Parameters:

• visual_grid – Two-dimensional grid containing . cells, agent ids, or ANSI-colored block symbols.

• blocks_info – Optional (correct, wrong) retrieve counts.

Returns:

Rendered RGB image.

Module contents

Evolutionary swarm-foraging environments and NEAT experiment helpers.