babylon.engine.simdb

Simulation database module (ephemeral per-run state).

The simulation database stores ephemeral state during simulation runs: - Agent state snapshots per tick - Production events (c/v/s tensor) - Network graph edges - Territorial control and heat dynamics - Aggregate metrics per tick

This database is separate from the reference database (immutable federal statistical data) and is created fresh for each simulation run.

Implements ADR030 (Unified SQLite Runtime Architecture) - uses SQLite instead of the previous DuckDB implementation.

Usage:

from babylon.engine.simdb import SimulationDB

# In-memory for testing with SimulationDB(in_memory=True) as sim:

sim.record_tick_summary(tick=0, total_c=100, total_v=50, …)

# File-based for production (persists to data/runs/) with SimulationDB(run_id=”experiment_001”) as sim:

# Record simulation state sim.con.execute(“INSERT INTO agent_state VALUES (…)”)

Architecture:

Reference DB (SQLite) ── Immutable federal data (3NF)

(census, QCEW, geography)

Simulation DB (SQLite) ── Ephemeral per-run state

Created fresh, discarded after analysis

class babylon.engine.simdb.SimulationDB(run_id=None, in_memory=False, attach_reference=True)

Bases: object

Ephemeral SQLite database for simulation state.

Each simulation run creates a fresh database (or uses in-memory). Implements ADR030 (Unified SQLite Runtime) and ADR031 (Tick-Keyed Temporal Tables).

Parameters:

• run_id (str | None)

• in_memory (bool)

• attach_reference (bool)

run_id

Unique identifier for this simulation run.

db_path

Path to the SQLite file (None for in-memory).

con

sqlite3 connection handle.

__enter__()

Context manager entry.

Return type:

SimulationDB

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

Return type:

None

Parameters:

• exc_type (type[BaseException] | None)

• exc_val (BaseException | None)

• exc_tb (object)

__init__(run_id=None, in_memory=False, attach_reference=True)

Initialize simulation database.

Parameters:

• run_id (str | None) – Unique run identifier. Defaults to timestamp-based ID.

• in_memory (bool) – If True, use :memory: database (no persistence).

• attach_reference (bool) – Deprecated. Previously used for DuckDB ATTACH. Now a no-op - reference data should be queried separately.

Return type:

None

__repr__()

String representation.

Return type:

str

close()

Close the database connection.

Return type:

None

get_metadata(key)

Retrieve simulation metadata.

Parameters:

key (str) – Metadata key.

Return type:

str | None

Returns:

Metadata value or None if not found.

record_tick_summary(tick, total_c, total_v, total_s, avg_consciousness, uprising_count)

Record aggregate metrics for a simulation tick.

Parameters:

• tick (int) – Simulation tick number.

• total_c (float) – Total constant capital (c).

• total_v (float) – Total variable capital/wages (v).

• total_s (float) – Total surplus value (s).

• avg_consciousness (float) – Average class consciousness [0,1].

• uprising_count (int) – Number of uprising events this tick.

Return type:

None

set_metadata(key, value)

Store simulation metadata.

Parameters:

• key (str) – Metadata key (e.g., ‘scenario_name’, ‘config_hash’).

• value (str) – Metadata value.

Return type:

None

transaction()

Context manager for explicit transactions.

Return type:

Iterator[Connection]

Usage:

with sim.transaction() as con:

con.execute(“INSERT INTO …”) con.execute(“UPDATE …”)

Yields:

sqlite3 connection within an active transaction.

Return type:

Iterator[Connection]

Modules

database	Simulation database (ephemeral SQLite per-run).
schema	Simulation database schema (ephemeral per-run state).