Simulators Package

The Simulators package provides the core simulation engines that coordinate all components of a multi-agent simulation. Simulators manage the integration of populations, environments, interactions, controllers, and data logging to create complete simulation systems.

swarmsim.Simulators

This module provides simulation engines for orchestrating multi-agent system simulations.

The Simulators module contains the core simulation engines that coordinate all aspects of multi-agent simulations, from basic research simulations to specialized reinforcement learning environments. These simulators manage the execution flow, component integration, and timing control for complex multi-agent systems.

Module Contents

  • Simulator : Main simulation engine for research and analysis applications

  • GymSimulator : OpenAI Gym-compatible simulator for reinforcement learning

Key Features

Simulation Orchestration:

  • Component coordination (populations, environment, interactions, controllers)

  • Execution flow management with proper sequencing

  • Progress tracking and early termination handling

  • Real-time visualization and data logging integration

Performance Optimization:

  • Efficient timestep management and loop optimization

  • Configurable sampling rates for different components

  • Memory-efficient state management

  • Parallel interaction computation support

Flexibility and Extensibility:

  • Modular architecture supporting custom components

  • Configuration-driven simulation parameters

  • Support for multiple simulation paradigms

  • Integration with visualization and analysis tools

Examples

Basic simulation setup:

from swarmsim.Simulators import Simulator
from swarmsim.Populations import BrownianMotion
from swarmsim.Environments import EmptyEnvironment
from swarmsim.Integrators import EulerMaruyama

# Create simulation components
population = BrownianMotion(config_path="config.yaml")
environment = EmptyEnvironment(config_path="config.yaml")
integrator = EulerMaruyama(config_path="config.yaml")

# Create and run simulation
simulator = Simulator(
    config_path="config.yaml",
    populations=[population],
    environment=environment,
    integrator=integrator
)
simulator.simulate()

Reinforcement learning setup:

from swarmsim.Simulators import GymSimulator
import numpy as np

# Create RL-compatible simulator
gym_sim = GymSimulator(
    populations=[sheep, herders],
    interactions=[repulsion, attraction],
    environment=shepherding_env,
    integrator=integrator,
    logger=logger,
    renderer=renderer,
    config_path="rl_config.yaml"
)

# RL training loop
for episode in range(num_episodes):
    gym_sim.reset()
    for step in range(max_steps):
        action = agent.get_action(observation)
        gym_sim.step(action)
        gym_sim.render()

Configuration

Simulator configuration via YAML:

simulator:
    T: 100.0          # Total simulation time
    dt: 0.01          # Timestep (inherited from integrator)
    progress_bar: true # Show progress during simulation

Notes

  • All simulators coordinate multiple simulation components in proper sequence

  • Timestep management ensures numerical stability and accuracy

  • Component sampling rates can be configured independently

  • Early termination is supported through logger done flags

  • Memory management prevents accumulation of interaction forces between timesteps

Package Overview

Simulators in SwarmSim provide:

  • Component Coordination: Orchestrate interactions between all simulation elements

  • Time Management: Handle simulation timing, stepping, and synchronization

  • Integration Support: Work with various numerical integrators and time schemes

  • Performance Monitoring: Track simulation performance and resource usage

  • Flexible Architecture: Support different simulation paradigms and use cases

The package includes specialized simulators for different applications, from basic research simulations to reinforcement learning environments.

Core Modules

Base Simulator

The foundational simulator class that provides core simulation functionality.

class swarmsim.Simulators.base_simulator.Simulator(config_path, populations, environment, integrator, interactions=None, controllers=None, logger=None, renderer=None)[source]

Bases: object

Main simulation engine that orchestrates multi-agent system simulations.

The Simulator class coordinates all components of a multi-agent system including populations, environment, interactions, controllers, integrators, loggers, and renderers. It manages the simulation loop and ensures proper execution order of all simulation steps.

Parameters:

  • config_path (str) – Path to the YAML configuration file containing simulation parameters.

  • populations (list of Population) – List of agent populations to simulate.

  • environment (Environment) – The environment in which agents operate.

  • integrator (Integrator) – Numerical integration scheme for updating agent states.

  • interactions (list of Interaction, optional) – List of interaction models between agents. Default is None.

  • controllers (list of Controller, optional) – List of controllers that influence agent behavior. Default is None.

  • logger (Logger, optional) – Logger instance for recording simulation data. Default is None.

  • renderer (Renderer, optional) – Renderer instance for visualization. Default is None.

Variables:

  • dt (float) – Simulation timestep, inherited from the integrator.

  • T (float) – Total simulation time duration.

  • populations (list of Population) – List of agent populations in the simulation.

  • environment (Environment) – The simulation environment.

  • interactions (list of Interaction or None) – List of interaction models.

  • controllers (list of Controller or None) – List of control strategies.

  • logger (Logger or None) – Data logger instance.

  • renderer (Renderer or None) – Visualization renderer.

  • integrator (Integrator) – Numerical integration scheme.

Config Requirements:

  • The YAML configuration file must contain the following parameters under the simulator section

  • T (float, optional) – Total simulation time. Default is 10.0.

  • dt (float, optional) – Simulation timestep. Default is 0.01.

Notes

The simulation loop executes the following steps in order:

  1. Logging: Record current simulation state

  2. Rendering: Visualize current state (if renderer is provided)

  3. Control: Computes control actions (if controllers are provided)

  4. Interactions: Computes inter-agent forces (if interactions are provided)

  5. Integration: Update agent states using numerical integration

  6. Reset Forces: Clear interaction forces for next timestep

  7. Environment Update: Update environment state

Examples

Basic simulation setup:

from swarmsim import BrownianMotion, Simulator
from swarmsim.Environments import EmptyEnvironment
from swarmsim.Integrators import EulerMaruyama

# Create components
population = BrownianMotion('config.yaml')
environment = EmptyEnvironment('config.yaml')
integrator = EulerMaruyama('config.yaml')

# Create and run simulator
simulator = Simulator(
    config_path='config.yaml',
    populations=[population],
    environment=environment,
    integrator=integrator
)
simulator.simulate()

Example YAML configuration:

simulator:
    T: 50.0  # Run simulation for 50 time units
__init__(config_path, populations, environment, integrator, interactions=None, controllers=None, logger=None, renderer=None)[source]

Initialize the Simulator with all required and optional components.

Parameters:

  • config_path (str) – Path to the YAML configuration file containing simulation parameters.

  • populations (list of Population) – List of agent populations to include in the simulation.

  • environment (Environment) – The environment where agents operate.

  • integrator (Integrator) – Numerical integration scheme for state evolution.

  • interactions (list of Interaction, optional) – Inter-agent interaction models. Default is None.

  • controllers (list of Controller, optional) – Control strategies for influencing agent behavior. Default is None.

  • logger (Logger, optional) – Data recording component. Default is None.

  • renderer (Renderer, optional) – Visualization component. Default is None.

Raises:

FileNotFoundError – If the configuration file cannot be found.

simulate()[source]

Execute the main simulation loop.

This method runs the complete simulation from t=0 to t=T, coordinating all simulation components in the proper sequence. It includes progress tracking and handles early termination if requested by the logger.

The simulation loop performs the following steps at each timestep:

  1. Data Logging: Record current simulation state and check for termination

  2. Visualization: Render current state if renderer is available

  3. Control Actions: Apply control inputs from all controllers

  4. Agent Interactions: Compute forces between agents

  5. State Integration: Update agent positions using the integrator

  6. Force Reset: Clear interaction forces for the next timestep

  7. Environment Update: Update environmental conditions

Notes

  • Progress is displayed using a progress bar

  • Controllers operate at their specified sampling rates

  • Interaction forces are reset at each timestep

  • Early termination is possible if the logger returns a done flag

  • All populations are reset to initial conditions before simulation starts

Raises:

RuntimeError – If any component fails during simulation execution.

Key Features:

  • Component Integration: Seamlessly coordinate populations, environments, and interactions

  • Flexible Stepping: Support both fixed and adaptive time stepping

  • State Management: Maintain complete simulation state and history

  • Event Handling: Process simulation events and state changes

  • Extensible Design: Easy to extend for specialized simulation needs

Core Capabilities:

simulator = BaseSimulator(
    populations=[population1, population2],
    environment=environment,
    interactions=[interaction1, interaction2],
    integrator=integrator,
    dt=0.01
)

# Basic simulation loop
for step in range(1000):
    simulator.step()

Gym Simulator

Specialized simulator implementing OpenAI Gym interface for reinforcement learning applications.

class swarmsim.Simulators.gym_simulator.GymSimulator(populations, interactions, environment, integrator, logger, renderer, render_mode=None, config_path=None)[source]

Bases: Simulator

OpenAI Gym-compatible simulator for reinforcement learning applications.

This simulator extends the base Simulator class to provide a Gym-style interface suitable for reinforcement learning algorithms. It implements the standard reset(), step(), render(), and close() methods expected by RL frameworks while maintaining full compatibility with the swarmsim ecosystem.

The GymSimulator is specifically designed for scenarios where one population (typically herders or controllers) receives actions from an RL agent, while other populations follow their programmed dynamics. This makes it ideal for training agents in multi-agent environments like shepherding, swarm control, or cooperative robotics.

Key Features

RL Compatibility:

  • Standard Gym interface (reset, step, render, close)

  • Configurable render modes including “rgb_array” for headless training

  • Episode-based simulation management

  • Action space integration with swarmsim populations

Multi-Agent Integration:

  • Seamless integration with existing swarmsim components

  • Support for mixed controlled/autonomous populations

  • Interaction computation between all agent types

  • Environment state management across episodes

Training Optimization:

  • Efficient episode reset without full reinitialization

  • Configurable rendering for training vs evaluation

  • Memory management for long training sessions

  • Component state preservation between episodes

param populations:

List of agent populations, where populations[1] is typically controlled by RL actions.

type populations:

list of Population

param interactions:

Inter-agent interaction models applied during simulation.

type interactions:

list of Interaction

param environment:

The environment instance containing spatial and physical constraints.

type environment:

Environment

param integrator:

Numerical integration scheme for updating agent states.

type integrator:

Integrator

param logger:

Data recording component for tracking training metrics.

type logger:

Logger

param renderer:

Visualization component with configurable render modes.

type renderer:

Renderer

param render_mode:

Rendering mode: “human” for display, “rgb_array” for numpy arrays. Default is None.

type render_mode:

str, optional

param config_path:

Path to YAML configuration file with simulation parameters.

type config_path:

str, optional

ivar render_mode:

Current rendering mode configuration.

vartype render_mode:

str or None

reset()[source]

Reset all simulation components to initial states for new episode.

step(action)[source]

Execute one simulation timestep with the provided action.

render()[source]

Render current simulation state according to render_mode.

close()[source]

Clean up simulation resources and close rendering.

Examples

Basic RL setup for shepherding:

from swarmsim.Simulators import GymSimulator
from swarmsim.Populations import BrownianMotion, SimpleIntegrators
from swarmsim.Environments import ShepherdingEnvironment

# Create populations (sheep and herders)
sheep = BrownianMotion(config_path="sheep_config.yaml")
herders = SimpleIntegrators(config_path="herder_config.yaml")

# Create RL-compatible simulator
gym_sim = GymSimulator(
    populations=[sheep, herders],  # herders[1] will receive RL actions
    interactions=[repulsion, attraction],
    environment=shepherding_env,
    integrator=integrator,
    logger=logger,
    renderer=renderer,
    render_mode="rgb_array"  # For headless training
)

# RL training loop
for episode in range(1000):
    gym_sim.reset()
    done = False
    while not done:
        action = rl_agent.get_action()  # Shape: (n_herders, action_dim)
        gym_sim.step(action)
        frame = gym_sim.render()  # Returns numpy array
        done = gym_sim.logger.check_termination()

Integration with popular RL libraries:

import gym
from stable_baselines3 import PPO

# Wrap GymSimulator in Gym environment
class SwarmEnv(gym.Env):
    def __init__(self):
        self.simulator = GymSimulator(...)
        self.action_space = gym.spaces.Box(...)
        self.observation_space = gym.spaces.Box(...)

    def reset(self):
        self.simulator.reset()
        return self._get_observation()

    def step(self, action):
        self.simulator.step(action)
        obs = self._get_observation()
        reward = self._compute_reward()
        done = self._check_done()
        return obs, reward, done, {}

# Train with stable-baselines3
env = SwarmEnv()
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=100000)

Notes

  • The controlled population is assumed to be populations[1] by convention

  • Actions are directly assigned to the controlled population’s input (u)

  • All populations and interactions are reset between episodes

  • Logger provides episode termination signals through done flags

  • Rendering behavior depends on the render_mode configuration

__init__(populations, interactions, environment, integrator, logger, renderer, render_mode=None, config_path=None)[source]

Initializes the Simulator class with configuration parameters from a YAML file.

Args:

config_path (str): The path to the YAML configuration file.

reset()[source]

Reset all simulation components to initial states for new episode.

This method prepares the simulator for a new episode by resetting all populations, interactions, and logger to their initial configurations. It ensures that each episode starts from a clean, reproducible state.

Reset Operations

  1. Population Reset: All agent populations return to initial positions and states

  2. Interaction Reset: Interaction models clear any accumulated state

  3. Logger Reset: Logging system prepares for new episode data collection

Performance Notes

  • Optimized to avoid full component reinitialization

  • Reuses existing object instances for memory efficiency

  • Faster than creating new simulator instance

Notes

  • Called at the beginning of each RL episode

  • Does not reset renderer or environment (typically persistent)

  • Maintains component configurations while resetting states

step(action)[source]

Execute one simulation timestep with the provided RL action.

This method advances the simulation by one timestep, applying the provided action to the controlled population and updating all system components according to the standard simulation pipeline.

Parameters:

  • action (np.ndarray) – Control action for the controlled population. Shape should match the controlled population’s input dimension: (n_agents, input_dim).

  • Pipeline (Simulation)

  • -------------------

  • Application (1. Action)

  • Computation (2. Interaction)

  • Integration (3. State)

  • Reset (4. Force)

  • Update (5. Environment)

  • Space (Action)

  • ------------

  • application (The action space depends on the controlled population and)

  • Control (- Acceleration)

  • Control

Notes

  • Assumes populations[1] is the controlled population by convention

  • Action dimensions must match controlled population’s input_dim

  • Forces are automatically reset after each timestep

  • Environment state can change dynamically during simulation

render()[source]

Render the current simulation state according to configured render mode.

This method provides flexible rendering output depending on the render_mode setting, supporting both human visualization and programmatic access to rendered frames for analysis or recording.

Returns:

  • np.ndarray or None –

    • If render_mode == “rgb_array”: Returns numpy array of shape (height, width, 3)

    • Otherwise: Returns None, displays visualization

  • Render Modes

  • ————

  • **”rgb_array” Mode**

  • - Returns rendered frame as numpy array

  • - Suitable for headless training and automated analysis

  • - Efficient for batch processing and video generation

  • - Compatible with gym.wrappers.RecordVideo

  • **Other Mode**

  • - Displays visualization in real-time window

  • - Interactive visualization with user controls

  • - Suitable for debugging and demonstration

  • - May block execution depending on renderer implementation

Notes

  • Render mode can be changed dynamically during simulation

  • Frame dimensions depend on renderer configuration

  • Some renderers may not support all render modes

  • Rendering quality vs performance trade-offs are renderer-dependent

close()[source]

Key Features:

  • OpenAI Gym Interface: Standard RL environment interface (step, reset, render)

  • Action/Observation Spaces: Configurable action and observation spaces

  • Reward Functions: Flexible reward function definition

  • Episode Management: Handle episode termination and reset conditions

  • Multi-Agent Support: Extensions for multi-agent reinforcement learning

RL Integration:

gym_sim = GymSimulator(
    populations=[agents],
    environment=env,
    action_space=action_space,
    observation_space=obs_space,
    reward_function=reward_fn
)

# Standard RL training loop
obs = gym_sim.reset()
for step in range(episode_length):
    action = agent.act(obs)
    obs, reward, done, info = gym_sim.step(action)
    if done:
        break

Usage Examples

Basic Simulation Setup

from swarmsim.Simulators import BaseSimulator
from swarmsim.Populations import BrownianMotion
from swarmsim.Environments import EmptyEnvironment
from swarmsim.Interactions import LennardJones
from swarmsim.Integrators import EulerMaruyama

# Create simulation components
population = BrownianMotion(n=100, x_dim=2)
environment = EmptyEnvironment(boundary_size=[20, 20])
interaction = LennardJones(epsilon=1.0, sigma=1.0)
integrator = EulerMaruyama(dt=0.01)

# Create and configure simulator
simulator = BaseSimulator(
    populations=[population],
    environment=environment,
    interactions=[interaction],
    integrator=integrator,
    dt=0.01
)

# Run simulation
for step in range(1000):
    simulator.step()

    # Access simulation state
    positions = simulator.get_positions()
    velocities = simulator.get_velocities()

Multi-Population Simulation

from swarmsim.Simulators import BaseSimulator
from swarmsim.Populations import BrownianMotion, SimpleIntegrators
from swarmsim.Interactions import PowerLawRepulsion

# Create multiple populations
prey = BrownianMotion(n=200, x_dim=2, species_id=0)
predators = SimpleIntegrators(n=10, x_dim=2, species_id=1)

# Species-specific interactions
prey_interaction = PowerLawRepulsion(
    species_pairs=[(0, 0)],  # Prey-prey repulsion
    strength=0.5,
    power=2
)

predator_interaction = PowerLawRepulsion(
    species_pairs=[(1, 0)],  # Predator-prey attraction
    strength=2.0,
    power=1
)

# Multi-species simulation
simulator = BaseSimulator(
    populations=[prey, predators],
    environment=environment,
    interactions=[prey_interaction, predator_interaction]
)

Controlled Simulation

from swarmsim.Simulators import BaseSimulator
from swarmsim.Controllers import ShepherdingController
from swarmsim.Loggers import Logger

# Setup with controller and logging
simulator = BaseSimulator(
    populations=[sheep_pop, shepherd_pop],
    environment=environment,
    controllers=[shepherding_controller],
    loggers=[data_logger],
    dt=0.02
)

# Simulation with automatic logging
simulator.run(
    total_steps=2000,
    log_interval=10,
    render_interval=50
)

# Access logged data
logged_data = simulator.get_log_data()

Reinforcement Learning Environment

from swarmsim.Simulators import GymSimulator
from swarmsim.Populations import DoubleIntegrators
from swarmsim.Environments import ShepherdingEnvironment
import gymnasium as gym
from gymnasium import spaces
import numpy as np

# Define action and observation spaces
n_agents = 5
action_space = spaces.Box(
    low=-1.0, high=1.0,
    shape=(n_agents, 2),
    dtype=np.float32
)

observation_space = spaces.Box(
    low=-np.inf, high=np.inf,
    shape=(n_agents, 4),  # x, y, vx, vy per agent
    dtype=np.float32
)

def reward_function(state, action, next_state):
    # Custom reward based on formation maintenance
    positions = next_state[:, :2]
    center = np.mean(positions, axis=0)
    distances = np.linalg.norm(positions - center, axis=1)
    formation_reward = -np.std(distances)  # Reward tight formation
    return formation_reward

# Create RL environment
gym_simulator = GymSimulator(
    populations=[DoubleIntegrators(n=n_agents, x_dim=2)],
    environment=ShepherdingEnvironment(),
    action_space=action_space,
    observation_space=observation_space,
    reward_function=reward_function,
    max_episode_steps=1000
)

# Use with RL algorithms
obs = gym_simulator.reset()
for step in range(1000):
    action = policy.predict(obs)  # Your RL policy
    obs, reward, done, info = gym_simulator.step(action)
    if done:
        obs = gym_simulator.reset()

Performance Optimization

Simulators are optimized for various performance scenarios:

  • Large Populations: Efficient algorithms that scale well with agent count

  • Long Simulations: Memory management for extended simulation runs

  • Real-time Applications: Low-latency stepping for interactive use