Simulator

class econsimulacra.simulator.Simulator(config, env_class, logger=None, summarizer_class=None)

Bases: Generic[ObsT]

Simulator class.

The Simulator class is responsible for running the simulation. Basic usage:

>>> config_path = pathlib.Path("path/to/config.json")
>>> logger = DictLogger()
>>> simulator = Simulator(
>>>     config=config_path,
>>>     env_class=Environment,
>>>     logger=logger,
>>>     summarizer_class=SimulationSummarizer,
>>> )
>>> asyncio.run(simulator.simulate(seed=42))

Parameters:

• config (dict[str, Any] | Path)

• env_class (Type[Environment])

• logger (Optional[Logger])

• summarizer_class (Optional[Type[SimulationSummarizer]])

async simulate(seed=None)

Execute the full simulation loop asynchronously.

Parameters:

seed (-) – Random seed.

Return type:

None

Note

This method is the main entry point for running a simulation episode. It resets the environment, iteratively collects actions from all agents, applies the joint action to the environment at each step, and finalizes optional logging and summarization at the end of the run.

The simulation proceeds as follows:

1. The environment is reset with the given random seed.

2. If a summarizer is configured, the simulation start is recorded.

3. For each simulation step: observations are generated for all agents; each agent asynchronously computes its action via act(); agents are evaluated in chunks determined by parallel_batch_size so that multiple agents can act concurrently without launching all coroutines at once; list-valued actions are recursively converted into tuples for downstream consistency and hashability; the resulting joint action dictionary is passed to env.step().

4. After all steps are completed, the logger is saved if present.

5. If a summarizer is configured, the simulation end is recorded.

This method is intentionally asynchronous because agent decision-making may involve I/O-bound or high-latency components such as LLM inference, API calls, or remote services. By using asyncio.gather(), the simulator can evaluate multiple agents concurrently within each batch, improving throughput while still preserving step-level synchronization: all actions for a step are collected before the environment advances.

Concurrency model: agent actions are computed concurrently within each batch, but the environment transition itself is performed once per step after all actions have been collected. Therefore, this method implements synchronous environment stepping with asynchronous per-agent action generation.

register_classes(class_list)

Parameters:

class_list (list[Type])

Return type:

None

class econsimulacra.simulator.SimulationSummarizer(env)

Bases: object

Parameters:

env (Environment)

summarize_start()

Return type:

None

summarize_end()

Return type:

None