Appendix C: API Quick Reference
All public classes and functions grouped by category. Module paths use the simudyne.engine package prefix.
Core Primitives (simudyne.engine.sdk)
| Class | Description |
|---|---|
ABMModel | Abstract base class for all agent-based models. Lifecycle: init -> setup -> step -> done. |
Agent | Base class for rule-based agents. Typed state via __state_schema__, deterministic PRNG via self.rng. |
Message | Base message class for inter-agent communication. Subclass for custom payloads. |
EmptyMessage | Signal-only message with no payload. |
DoubleMessage | Message carrying a single float. Methods: get_body(), set_body(). |
IntegerMessage | Message carrying a single integer. Methods: get_body(), set_body(). |
Link | Typed, weighted, directed edge between two agents. |
Action | Binds an agent type to a callable. Factory: Action.create(type, fn, name). |
Sequence | Ordered chain of actions with message delivery between each. |
Split | Simultaneous execution of multiple actions. |
GlobalState | Model-level configuration state, read-only proxy to agents. |
Accumulator | Thread-safe aggregation primitive. Methods: add(), get(), reset(), set(). |
BehaviorType | Enum: RULE_BASED, LLM_BASED, HYBRID. |
Agent Types
| Class | Module | Description |
|---|---|---|
LLMAgent | simudyne.engine.genai | LLM-powered agent with mandatory rule_decide() fallback. |
HybridAgent | simudyne.engine.genai | Probabilistic LLM/rule routing via llm_probability. |
RLAgent | simudyne.engine.rl | Reinforcement learning agent. Abstract: observe(), compute_reward(), apply_action(). |
ExternalAgentProxy | simudyne.engine.external_agent | Cross-process agent via HTTP/MCP with fallback support. |
LLM Infrastructure (simudyne.engine.genai)
| Class / Function | Description |
|---|---|
LLMConfig | Dataclass: model, max_tokens, temperature, cache, cost budgets. |
MockLLMBackend | Deterministic backend for testing (no API calls). |
DebugLLMBackend | Real API calls with logging for development. |
LLMBackendPool | Load-balanced multi-endpoint pool with round-robin strategy. |
LLMEndpoint | Single LLM API endpoint with provider, model, and API key. |
ResponseCache | Content-addressed prompt cache (memory or SQLite backend). |
retry_llm_call | Decorator: retry with exponential backoff and jitter. |
estimate_cost | Estimate USD cost from token counts and model name. |
RL Infrastructure (simudyne.engine.rl)
| Class | Description |
|---|---|
RandomPolicy | Uniform random actions for baselines. |
TabularQPolicy | Q-learning with epsilon-greedy exploration. |
Execution Backends
| Class | Module | Description |
|---|---|---|
ExecutionBackend | simudyne.engine.backend | Abstract base with execute_action(), deliver_messages(). |
LocalBackend | simudyne.engine.backend | Sequential single-threaded execution. |
ThreadPoolBackend | simudyne.engine.backend | Thread pool with configurable max_workers. |
ProcessPoolBackend | simudyne.engine.backend | Process pool for GIL bypass. |
MCPBackend | simudyne.engine.backend | Distributed execution via MCP HTTP servers. |
AsyncBackend | simudyne.engine.backend_async | asyncio with configurable semaphore_limit. |
PregelBackend | simudyne.engine.pregel | BSP graph-parallel with vote-to-halt convergence. |
DaskBackend | simudyne.engine.backend_dask | Distributed cluster execution via Dask. |
Spaces & Topology
| Class / Function | Module | Description |
|---|---|---|
GridSpace | simudyne.engine.space | 2D grid with Von Neumann or Moore neighbourhoods, optional wrap. |
NetworkSpace | simudyne.engine.space | Arbitrary graph with BFS neighbourhood queries. |
Space2D | simudyne.engine.space2d | Continuous 2D space with spatial hash grid. |
Space2DEnvironment | simudyne.engine.space2d | Environment with push-based observations and field layers. |
FieldLayer | simudyne.engine.space2d | NumPy scalar field with deposit, sample, gradient, evaporate, diffuse. |
Neighborhood | simudyne.engine.space | Enum: VON_NEUMANN, MOORE. |
fully_connected | simudyne.engine.topology | Complete graph: every agent linked to every other. |
ring | simudyne.engine.topology | Ring lattice: each agent linked to two neighbours. |
small_world | simudyne.engine.topology | Watts-Strogatz: k nearest with rewiring probability p. |
scale_free | simudyne.engine.topology | Barabasi-Albert: preferential attachment with m edges per node. |
grid | simudyne.engine.topology | 2D grid lattice with optional wrap. |
from_data | simudyne.engine.topology | User-provided edge list for empirical networks. |
Parameters (simudyne.engine.params)
| Class / Function | Description |
|---|---|
Input | User-configurable parameter with min/max, units, group, differentiable flag. |
Variable | Observable model state with description and units. |
Constant | Immutable parameter (set once, raises on reassignment). |
get_inputs() | Introspect all Input descriptors on a class. |
get_params() | Introspect all descriptors (Input + Variable + Constant). |
Seeding & Determinism
| Class / Function | Module | Description |
|---|---|---|
SeedManager | simudyne.engine.seeds | SHA-256 hierarchical seeding. Methods: mc_seeds(), agent_rng(), environment_rng(). |
DeterminismChecker | simudyne.engine.determinism | Multi-pair determinism verification with tolerance. |
cross_process_check | simudyne.engine.determinism | Cross-process determinism verification. |
Partitioning (simudyne.engine.partition)
| Class | Description |
|---|---|
TypeBasedPartition | Partition agents by type. O(N). |
TopologyAwarePartition | Greedy BFS minimising cross-partition edges. O(N+E). |
ManualPartition | User-specified agent-to-partition mapping. |
PartitionMetrics | Static methods: compute_cut_ratio(), compute_balance(), report(). |
Output & Recording
| Class / Function | Module | Description |
|---|---|---|
OutputRecorder | simudyne.engine.output | Low-level time series recorder with multi-format export. |
TimeConfig | simudyne.engine.output | Timestamp mapping (start, step_duration, timezone). |
OutputFormat | simudyne.engine.output | Enum: CSV, CSV_GZ, PARQUET, DATABASE, S3. |
SimulationRecorder | simudyne.engine.recorder | Multi-level hook-based recorder (model/agent_group/agent/env). |
RecorderConfig | simudyne.engine.recorder | Configuration: levels, format, plots, sample rate. |
RecordLevel | simudyne.engine.recorder | Enum: MODEL, AGENT_GROUP, AGENT, ENVIRONMENT. |
auto_record | simudyne.engine.recorder | Convenience: create + attach recorder in one call. |
Evaluation
| Class / Function | Module | Description |
|---|---|---|
MCRunner | simudyne.engine.mc_runner | Monte Carlo runner with parallel seed execution. |
ProcessPoolMCRunner | simudyne.engine.mc_runner | Production MC runner with configurable workers and batching. |
MCResult | simudyne.engine.mc_runner | Aggregate MC result with per-seed traces and metrics. |
ExperimentRunner | simudyne.engine.experiment | Parameter sweep runner (grid, LHS, Sobol). |
ParameterRange | simudyne.engine.experiment | Parameter sweep specification (values or min/max/steps). |
GridSweep | simudyne.engine.experiment | Exhaustive Cartesian product sweep. |
LatinHypercubeSweep | simudyne.engine.experiment | Space-filling Latin Hypercube Sampling. |
SobolSweep | simudyne.engine.experiment | Quasi-random Sobol sequence for sensitivity analysis. |
Features & Validation (simudyne.engine.features)
| Class / Constant | Module | Description |
|---|---|---|
Feature | simudyne.engine.features | Named quantitative signal extractor with target range. |
FeatureSet | simudyne.engine.features | Collection with compute, validate, compare, distance. |
ValidationReport | simudyne.engine.features | Validation result with score, grade, per-feature results. |
FINANCIAL_FEATURES | simudyne.engine.features.contrib.financial | 8 financial stylized facts. |
SUPPLY_CHAIN_FEATURES | simudyne.engine.features.contrib.supply_chain | 4 supply chain features. |
EPIDEMIOLOGY_FEATURES | simudyne.engine.features.contrib.epidemiology | 4 epidemiology features. |
Statistics (simudyne.engine.statistics)
| Function | Description |
|---|---|
ks_two_sample | Kolmogorov-Smirnov two-sample test. |
anderson_darling_two_sample | Anderson-Darling two-sample test (tail-sensitive). |
permutation_test | Exact p-value via resampling. |
mann_whitney_u | Rank-based location test. |
bootstrap_ci | BCa bootstrap confidence interval. |
wasserstein_distance | Earth mover's distance (L1 optimal transport). |
energy_distance | Energy distance (Szekely & Rizzo). |
mmd_distance | Maximum Mean Discrepancy with RBF kernel. |
jsd_distance | Jensen-Shannon divergence. |
bonferroni_correction | Conservative family-wise error control. |
holm_correction | Step-down Holm-Bonferroni. |
benjamini_hochberg_fdr | False discovery rate control. |
benjamini_yekutieli_fdr | FDR control for dependent tests. |
Calibration & Ablation
| Class / Function | Module | Description |
|---|---|---|
ABCSMCCalibrator | simudyne.engine.calibration | ABC-SMC Bayesian calibration with adaptive epsilon. |
Prior | simudyne.engine.calibration | Prior distribution (5 types: uniform, log_uniform, truncated_normal, beta, scipy). |
ABCSMCResult | simudyne.engine.calibration | Posterior: MAP, mean, std, CI, samples, predictive. |
compare_models | simudyne.engine.calibration | Complexity-penalised multi-model comparison. |
MechanismDeclaration | simudyne.engine.ablation | Mechanism metadata with hypothesis and predicted effect. |
AblationRunner | simudyne.engine.ablation | Single + pairwise mechanism ablation. |
NestedMCRunner | simudyne.engine.variance_decomposition | Nested ANOVA for LLM-ABM variance decomposition. |
NestedANOVAResult | simudyne.engine.variance_decomposition | ICC, F-statistic, diagnosis. |
Observability & Safety
| Class | Module | Description |
|---|---|---|
HookEvent | simudyne.engine.hooks | 11 lifecycle events (BEFORE/AFTER_SETUP, BEFORE/AFTER_STEP, etc.). |
HookRegistry | simudyne.engine.hooks | Register/fire hook callbacks. |
GuardrailRegistry | simudyne.engine.guardrails | Runtime safety check management. |
MaxAgentsGuardrail | simudyne.engine.guardrails | Agent population limit. |
BudgetGuardrail | simudyne.engine.guardrails | LLM cost budget cap. |
DeterminismGuardrail | simudyne.engine.guardrails | Seed and random module checks. |
StateInvariantGuardrail | simudyne.engine.guardrails | Custom predicate invariant. |
OTelInstrumentation | simudyne.engine.otel | OpenTelemetry span and metric instrumentation. |
AgentMemory | simudyne.engine.memory | Per-agent persistent key-value memory. |
AuditTrail | simudyne.engine.audit | Decision and event audit logging. |
CheckpointManager | simudyne.engine.checkpoint | State save/restore with SHA-256 integrity. |
Deployment
| Class / Function | Module | Description |
|---|---|---|
ABMSettings | simudyne.engine.settings | Top-level settings container from settings.json. |
ABMRuntime | simudyne.engine.runtime | Orchestrates settings + config + model execution. |
Dashboard | simudyne.engine.dashboard | Web dashboard for monitoring. |
SimulationStreamer | simudyne.engine.streaming | WebSocket server for live step data. |
ModelVisualizer | simudyne.engine.viz | Factory: from_recorder(), from_mc_result(), from_model(). |
GraphBuilder | simudyne.engine.graph_builder | Declarative model topology construction. |
RunStore | simudyne.engine.run_store | Persistent run metadata storage. |
Scenario | simudyne.engine.scenario | Named parameter presets for reproducible experiment configurations. |
Chat | simudyne.engine.chat | Conversational model interaction interface. |