Skip to content

API_SPECIFICATION.md

Latest commit

 

History

History
127 lines (92 loc) · 4.17 KB

API_SPECIFICATION.md

File metadata and controls

127 lines (92 loc) · 4.17 KB

Simulation - API Specification

Version: v1.2.3 | Status: Alpha | Last Updated: March 2026

Overview

The Simulation module provides a step-based simulation engine. It exposes two primary constructs: the SimulationConfig dataclass for configuration and the Simulator class for execution.

Core API

Configuration

from codomyrmex.simulation import SimulationConfig

config = SimulationConfig(
    name="my_simulation",
    max_steps=500,
    seed=42,
    params={"learning_rate": 0.01, "population": 100}
)

Simulation Execution

from codomyrmex.simulation import Simulator, SimulationConfig

# Full run
config = SimulationConfig(name="experiment_1", max_steps=1000, seed=42)
sim = Simulator(config)
results = sim.run()

# Step-by-step
sim = Simulator()
for _ in range(10):
    sim.step()
results = sim.get_results()

Endpoints / Functions / Interfaces

Class: SimulationConfig

  • Description: Dataclass that holds all configuration parameters for a simulation run.
  • Method: N/A (Python dataclass)
  • Fields:
    • name (str): Human-readable simulation name. Default: "default_simulation".
    • max_steps (int): Maximum number of steps before the simulation terminates. Default: 1000.
    • seed (int | None): Random seed for reproducibility. Default: None.
    • params (dict[str, Any]): Arbitrary key-value parameters for model-specific configuration. Default: {}.

Class: Simulator

  • Description: Core simulation engine that manages lifecycle, step execution, and result collection.
  • Method: N/A (Python class)
  • Parameters/Arguments (constructor):
    • config (SimulationConfig | None): Configuration for the simulation. If None, uses default SimulationConfig().

Function: Simulator.run()

  • Description: Executes the simulation loop, calling step() repeatedly until max_steps is reached or the simulation is stopped. Returns the final results.
  • Method: N/A (Instance method)
  • Parameters/Arguments: None
  • Returns/Response:
    • dict[str, Any]: Result dictionary with the following structure: 
      {
  "steps_completed": 1000,
  "config": "my_simulation",
  "status": "completed"
}
  • Error Handling: Exceptions raised during step() are logged with step context and re-raised. The _running state is always reset via finally.

Function: Simulator.step()

  • Description: Executes a single simulation step. Override this method in subclasses to implement custom simulation logic.
  • Method: N/A (Instance method)
  • Parameters/Arguments: None
  • Returns/Response: None

Function: Simulator.get_results()

  • Description: Returns the current simulation results as a structured dictionary.
  • Method: N/A (Instance method)
  • Parameters/Arguments: None
  • Returns/Response:
    • dict[str, Any]: Result dictionary containing:
      • steps_completed (int): Number of steps executed so far.
      • config (str): Name of the simulation configuration.
      • status (str): "completed" if the simulation has finished, "running" if still active.

Data Models

Model: SimulationConfig

  • name (str): Simulation name identifier.
  • max_steps (int): Upper bound on simulation steps.
  • seed (int | None): Optional random seed.
  • params (dict[str, Any]): Arbitrary model parameters.

Model: Result Dictionary

  • steps_completed (int): Total steps executed.
  • config (str): Configuration name.
  • status (str): One of "completed" or "running".

Authentication & Authorization

Not applicable for this internal simulation module.

Rate Limiting

Not applicable for this internal simulation module.

Versioning

This module follows the general versioning strategy of the Codomyrmex project. API stability is aimed for, with changes documented in future CHANGELOG entries.

Navigation