Numerical Integrators

The integrators package provides sophisticated numerical integration schemes for stochastic differential equations (SDEs) that govern agent dynamics in multi-agent systems. These integrators handle the temporal evolution of agent states, incorporating both deterministic drift and stochastic diffusion components.

Overview

SwarmSim’s integration framework implements state-of-the-art numerical methods for solving SDEs of the form:

\[d\mathbf{X}_t = \mathbf{f}(\mathbf{X}_t, t) dt + \mathbf{g}(\mathbf{X}_t, t) d\mathbf{W}_t\]

where \(\mathbf{X}_t\) represents the agent state vector, \(\mathbf{f}\) is the drift term capturing deterministic dynamics, \(\mathbf{g}\) is the diffusion term modeling stochastic fluctuations, and \(d\mathbf{W}_t\) is a Wiener process increment.

Key Features

  • High-Order Integration: Support for multiple integration schemes with varying accuracy and stability

  • Stochastic Support: Native handling of noise processes and random fluctuations

  • Adaptive Stepping: Configurable time stepping with stability considerations

  • Multi-Agent Scalability: Efficient vectorized operations for large population sizes

  • Modular Design: Extensible architecture for custom integration methods

Module Reference

Integrators Module

This module provides numerical integration schemes for evolving agent dynamics in multi-agent simulations. Integrators handle both deterministic and stochastic differential equations, enabling realistic agent motion with noise and uncertainty.

Available Integrators

Integrator

Abstract base class defining the interface for all numerical integration methods.

EulerMaruyama

Stochastic integrator for SDEs using the Euler-Maruyama scheme. Suitable for populations with both drift and diffusion components (e.g., Brownian motion).

Key Features

  • Stochastic Integration: Support for stochastic differential equations (SDEs)

  • Modular Design: Easy to implement custom integration schemes

  • Population Support: Handles multiple populations with different dynamics

  • Configurable Timestep: Adjustable integration timestep for accuracy vs. speed

Mathematical Background

The integrators solve equations of the form:

dx = f(x, t) dt + g(x, t) dW

where: - f(x, t) is the drift term (deterministic component) - g(x, t) is the diffusion term (stochastic component) - dW is a Wiener process (Brownian motion)

Examples

Basic integrator usage:

from swarmsim.Integrators import EulerMaruyama
from swarmsim.Populations import BrownianMotion

# Create integrator
integrator = EulerMaruyama('config.yaml')

# Create population
population = BrownianMotion('config.yaml')
population.reset()

# Perform integration step
integrator.step([population])

Configuration Example

integrator:
    dt: 0.01  # Small timestep for accuracy

For stochastic systems, smaller timesteps generally improve accuracy but increase computational cost.

Base Integrator Interface

The foundation for all numerical integration schemes, providing the abstract interface and common functionality.

class swarmsim.Integrators.base_integrator.Integrator(config_path)[source]

Bases: ABC

Abstract base class for numerical integration schemes in stochastic multi-agent systems.

This class provides the interface for implementing various numerical integration methods for stochastic differential equations (SDEs) that govern agent dynamics. It handles the temporal evolution of agent states based on drift and diffusion components.

Parameters:

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

Variables:

dt (float) – The timestep value for numerical integration.

Config Requirements:

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

  • dt (float, optional) – The timestep value for numerical integration. Default is 0.01.

Notes

  • Subclasses must implement the abstract method step() to define the integration scheme.

  • Common integration schemes include Euler-Maruyama for SDEs.

  • The timestep should be chosen carefully to ensure numerical stability and accuracy.

Raises:

  • FileNotFoundError – If the configuration file is not found.

  • KeyError – If required integration parameters are missing in the configuration file.

Examples

Example YAML configuration:

integrator:
    dt: 0.05

This sets the integration timestep to 0.05 time units.

For stochastic systems, smaller timesteps generally improve accuracy but increase computational cost. The choice depends on the specific dynamics and required precision.

__init__(config_path)[source]

Initialize the Integrator with configuration parameters.

Parameters:

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

Raises:

FileNotFoundError – If the configuration file cannot be found.

abstractmethod step(populations)[source]

Perform a single numerical integration step.

This abstract method must be implemented by subclasses to define the specific numerical integration scheme. It advances the state of all agent populations by one timestep according to their dynamics.

Parameters:

populations (list of Population) – List of Population objects whose states will be updated by the integration step. Each population provides drift and diffusion terms through their respective methods.

Notes

The implementation should:

  • Call get_drift() and get_diffusion() methods for each population

  • Apply the numerical integration scheme (e.g., Euler-Maruyama, Runge-Kutta)

  • Update the state x attribute of each population

  • Handle stochastic terms appropriately for SDE integration

  • Respect any state or input limits defined in the populations

Raises:

NotImplementedError – If called from the base class without being implemented in a subclass.

Euler-Maruyama Integrator

The most commonly used stochastic integrator, implementing the Euler-Maruyama scheme for SDEs.

class swarmsim.Integrators.euler_maruyama.EulerMaruyamaIntegrator(config_path)[source]

Bases: Integrator

Euler-Maruyama numerical integrator for stochastic differential equations.

This integrator implements the Euler-Maruyama scheme for solving stochastic differential equations (SDEs) governing multi-agent dynamics. It handles both scalar and matrix-valued diffusion terms, making it suitable for complex stochastic systems with correlated noise.

The integration scheme follows:

\[x_{n+1} = x_n + f(x_n, t_n) \Delta t + g(x_n, t_n) \sqrt{\Delta t} \, \xi_n\]

where: - \(x_n\) is the state at time step n - \(f(x_n, t_n)\) is the drift term (deterministic dynamics) - \(g(x_n, t_n)\) is the diffusion term (noise amplitude) - \(\xi_n\) is standard Gaussian white noise - \(\Delta t\) is the integration timestep

Parameters:

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

Variables:

dt (float) – Integration timestep, inherited from the Integrator base class.

Config Requirements:

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

  • dt (float, optional) – Integration timestep for the Euler-Maruyama scheme. Default is 0.01. Smaller timesteps improve accuracy but increase computational cost.

Notes

Diffusion Term Handling:

The integrator automatically detects the dimensionality of the diffusion term:

  • Scalar/Vector Diffusion (shape (N, d)): Element-wise multiplication with noise

  • Matrix Diffusion (shape (N, d, d)): Matrix-vector multiplication for correlated noise

State Constraints:

Agent states are automatically clipped to respect population limits after each integration step.

Numerical Stability:

For strong convergence, the timestep should satisfy stability conditions specific to the drift and diffusion terms. Generally, smaller timesteps are required for systems with large diffusion coefficients.

Raises:

  • FileNotFoundError – If the configuration file is not found.

  • KeyError – If required integration parameters are missing in the configuration file.

  • AttributeError – If population objects lack required methods or attributes.

Examples

Configuration Example:

integrator:
    dt: 0.01  # Small timestep for good accuracy

This will set dt = 0.05 as the timestep value for numerical integration.

__init__(config_path)[source]

Initializes the Euler-Maruyama Integrator with configuration parameters from a YAML file.

Parameters:

config_path (str) – Path to the YAML configuration file.

step(populations)[source]

Perform a single Euler-Maruyama integration step for all populations.

This method updates the state of each population by applying the Euler-Maruyama scheme with automatic handling of scalar and matrix diffusion terms. The state update follows the discrete SDE formula with proper noise scaling.

Parameters:

populations (list of Population) –

List of population objects to integrate. Each population must provide:

  • x (np.ndarray): Current state array of shape (N, d)

  • get_drift() method: Returns drift term of shape (N, d)

  • get_diffusion() method: Returns diffusion term of shape (N, d) or (N, d, d)

  • lim_i (np.ndarray): Lower state bounds for clipping

  • lim_s (np.ndarray): Upper state bounds for clipping

Notes

Integration Algorithm:

For each population, the state update is:

  1. Drift Computation: Get deterministic dynamics \(f(x,t)\)

  2. Diffusion Computation: Get noise amplitude \(g(x,t)\)

  3. Noise Generation: Sample \(\xi \sim \mathcal{N}(0,I)\)

  4. State Update: Apply Euler-Maruyama formula

  5. Constraint Enforcement: Clip states to population limits

Diffusion Term Handling:

  • Vector Diffusion (shape (N, d)): noise_term = diffusion * noise

  • Matrix Diffusion (shape (N, d, d)): noise_term = diffusion @ noise

State Constraints:

After integration, all agent states are clipped to respect the population’s spatial or behavioral limits defined by lim_i and lim_s.

Raises:

  • AttributeError – If any population object lacks required methods (get_drift, get_diffusion) or attributes (x, lim_i, lim_s).

  • ValueError – If diffusion term shape is incompatible with noise or state dimensions.

Troubleshooting

Common Integration Issues

Numerical Instability

  • Reduce time step size

  • Verify boundary conditions

See Also