World module

class assume.world.World(addr: tuple[str, int] | str = 'world', database_uri: str = '', export_csv_path: str = '', log_level: str = 'INFO', distributed_role: bool | None = None)

Bases: object

Orchestrates ASSUME simulation setup, execution, and output handling.

World is the central runtime container for markets, operators, units, and simulation clocks. It coordinates the end-to-end lifecycle: initialize runtime infrastructure in setup(), register market and unit entities, initialize forecasts, and execute the simulation loop via run().

The class supports standalone execution (default) and distributed execution (manager/worker roles). Output can be persisted to a SQL database and/or CSV exports through an output agent; learning/evaluation roles are configured in setup() via learning_dict.

market_operators

Registered market operator mango agents in the current world.

Type:

dict[str, RoleAgent]

markets

Configurations of registered markets available to bidding for UnitOperators.

Type:

dict[str, MarketConfig]

unit_operators

Registered unit operator mango agents, responsible for formulating bids, based on the needs of their associated units.

Type:

dict[str, UnitsOperator]

units

All registered unit instances by id.

Type:

dict[str, BaseUnit]

bidding_strategies

Strategy registry used when creating unit and portfolio strategies.

Type:

dict[str, type]

clearing_mechanisms

Market mechanism mechanism registry used by add_market().

Type:

dict[str, type[MarketRole]]

Parameters:

• addr (tuple[str, int] | str, optional) – Address used when creating the Mango container. Use "world" for local event-container execution, a (host, port) tuple for TCP-based execution, or a string client id for MQTT-based execution. Defaults to "world".

• database_uri (str, optional) – SQLAlchemy database URI used by output and learning components. If empty, no database backend is created. Defaults to "".

• export_csv_path (str, optional) – Directory path for CSV output exports. If empty, CSV export is disabled. Defaults to "".

• log_level (str, optional) – Logging level applied to the assume logger. Defaults to "INFO".

• distributed_role (bool | None, optional) – Distributed execution role: True for manager (time distribution), False for worker (receives distributed clock), None for standalone execution. Defaults to None.

add_market(market_operator_id: str, market_config: MarketConfig) → None

Add a market to the simulation by creating a market role based on the specified market mechanism in the market configuration. Then, add this role to the specified market operator and append the market configuration to the list of markets within the market operator. Additionally, store the market configuration in the simulation’s markets dictionary.

Parameters:

• market_operator_id (str) – The identifier of the market operator to which the market will be added.

• market_config (MarketConfig) – The configuration for the market to be added.

Returns:

None

add_market_operator(id: str) → None

Add a market operator to the simulation by creating a new role agent for the market operator and setting additional context parameters. If not in learning mode and not in evaluation mode, it includes the output agent address and ID in the role context data dictionary.

Parameters:

id (str) – The identifier for the market operator.

add_unit(id: str, unit_type: str, unit_operator_id: str, unit_params: dict, forecaster: UnitForecaster) → None

Creates a unit and adds it to the World instance.

This method checks if the unit operator exists, verifies the unit type, and ensures that the unit operator does not already have a unit with the same id. It then creates bidding strategies for the unit and creates the unit within the associated unit operator.

Parameters:

• id (str) – The identifier for the unit.

• unit_type (str) – The type of the unit.

• unit_operator_id (str) – The identifier of the unit operator.

• unit_params (dict) – Parameters specific to the unit.

• forecaster (Forecaster) – The forecaster associated with the unit.

add_unit_instance(operator_id: str, unit: BaseUnit)

Add an existing unit to the World instance.

This method checks if the unit operator exists and then assigns the provided unit instance to it.

Parameters:

• operator_id (str) – The identifier of the unit operator.

• unit (BaseUnit) – The unit instance to be added.

add_unit_operator(id: str, strategies: dict[str, UnitOperatorStrategy] = {}) → None

Add a unit operator to the simulation, creating a new role agent and applying the role of a unit operator to it. The unit operator is then added to the list of existing operators. Unit operator receives the output agent address if not in learning mode.

Parameters:

id (str) – The identifier for the unit operator.

add_units_with_operator_subprocess(id: str, units: list[dict], strategies: dict[str, UnitOperatorStrategy])

Adds a units operator with given ID in a separate process and creates and adds the given list of unit dictionaries to it through a creator function

Parameters:

• id (str) – the id of the units operator

• units (list[dict]) – list of unit dictionaries forwarded to create_unit

async async_run(start_ts: datetime, end_ts: datetime)

Run the simulation asynchronously, progressing the simulation time from the start timestamp to the end timestamp, allowing registration before the first opening. If distributed roles are enabled, broadcast the simulation time. Iterate through the simulation time, updating the progress bar and the simulation description. Once the simulation time reaches the end timestamp, close the progress bar and shut down the simulation container.

Parameters:

• start_ts (datetime.datetime) – The start timestamp for the simulation run.

• end_ts (datetime.datetime) – The end timestamp for the simulation run.

create_unit(id: str, unit_type: str, unit_operator_id: str, unit_params: dict, forecaster: UnitForecaster) → BaseUnit

init_forecasts(forecast_df: DataFrame = None)

reset()

Reset the market operators, markets, unit operators, and forecast providers to empty dictionaries.

Returns:

None

run()

Run the simulation.

This method converts the start and end timestamps to UTC time and then runs the asynchronous simulation using the async_run method. It progresses the simulation time from the start timestamp to the end timestamp, allowing registration before the first opening. If distributed roles are enabled, it broadcasts the simulation time. The method then iterates through the simulation time, updating the progress bar and the simulation description. Once the simulation time reaches the end timestamp, the method closes the progress bar and shuts down the simulation container.

setup(start: datetime, end: datetime, simulation_id: str, save_frequency_hours, bidding_params: dict = {}, learning_dict: dict = {}, episode: int = 1, eval_episode: int = 1, manager_address=None, real_time=False, **kwargs: dict) → None

Set up the environment for the simulation, initializing various parameters and components required for the simulation run.

Parameters:

• start (datetime.datetime) – The start datetime for the simulation.

• end (datetime.datetime) – The end datetime for the simulation.

• simulation_id (str) – The unique identifier for the simulation.

• save_frequency_hours (int) – The frequency (in hours) at which to save simulation data.

• bidding_params (dict, optional) – Parameters for bidding. Defaults to an empty dictionary.

• learning_dict (dict, optional) – Configuration for the learning process. Defaults to an empty dictionary.

• episode (int, optional) – The episode number for learning. Defaults to 1.

• eval_episode (int, optional) – The episode number for evaluation. Defaults to 1.

• manager_address – The address of the manager.

• **kwargs – Additional keyword arguments.

Returns:

None

setup_learning(episode: int, eval_episode: int) → None

Set up the learning process for the simulation, updating bidding parameters with the learning configuration and initializing the reinforcement learning (RL) learning role with the specified parameters. It also sets up the RL agent and adds the learning role to it for further processing.

setup_output_agent(save_frequency_hours: int, episode: int, eval_episode: int) → None

Set up the output agent for the simulation, creating an output role responsible for writing simulation output, including data storage and export settings. Depending on the platform (currently supported only on Linux), it adds the output agent to the container’s processes, or directly adds the output role to the output agent.

Parameters:

save_frequency_hours (int) – The frequency (in hours) at which to save simulation data.