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

Represents a simulation environment with a specified address, database connection, CSV export path, log level, and optional distributed role settings.

If a database URI is provided, the World instance attempts to establish a database connection. It initializes key attributes for market operators, markets, unit operators, bidding strategies, and clearing mechanisms. Additionally, it checks for learning strategy availability and sets up an event loop.

addr

The address of the world, represented as a tuple (host, port) or a string.

Type:

tuple[str, int] | str, optional

distributed_role

Defines the world’s role in distributed execution: - True: Acts as a manager world that schedules events. - False: Acts as a client world receiving schedules from a manager. - None (default): Runs independently without subprocesses.

Type:

bool, optional

export_csv_path

Path for exporting CSV data.

Type:

str, optional

log_level

The logging level for the world instance.

Type:

str, optional

db_uri

The processed database URI.

Type:

sqlalchemy.engine.URL, optional

db

The database connection engine.

Type:

sqlalchemy.engine.base.Engine, optional

container

The container for the world instance.

Type:

mango.Container, optional

loop

The event loop for asynchronous operations.

Type:

asyncio.AbstractEventLoop, optional

clock

External clock instance.

Type:

ExternalClock, optional

start

Start datetime for the simulation.

Type:

datetime.datetime, optional

end

End datetime for the simulation.

Type:

datetime.datetime, optional

market_operators

Market operators in the world instance.

Type:

dict[str, mango.RoleAgent], optional

markets

Market configurations.

Type:

dict[str, MarketConfig], optional

unit_operators

Unit operators.

Type:

dict[str, UnitsOperator], optional

unit_types

Available unit types.

Type:

dict[str, BaseUnit], optional

dst_components

Demand-side technologies.

Type:

dict[str, DemandSideTechnology], optional

bidding_strategies

Bidding strategies for the world instance. - If “pp_learning” is unavailable, learning strategies may be missing due to missing dependencies (e.g., torch).

Type:

dict[str, type[BaseStrategy]], optional

clearing_mechanisms

Market clearing mechanisms.

Type:

dict[str, MarketRole], optional

additional_kpis

Additional performance indicators.

Type:

dict[str, OutputDef], optional

scenario_data

Dictionary for scenario-specific data.

Type:

dict, optional

addresses

Addresses for the world instance.

Type:

list[str], optional

output_agent_addr

Address of the output agent.

Type:

tuple[str, str], optional

bidding_params

Parameters for bidding.

Type:

dict, optional

index

The index for simulation tracking.

Type:

pandas.Series, optional

learning_config

Configuration for learning-based components.

Type:

LearningConfig, optional

learning_mode

Whether learning mode is enabled.

Type:

bool, optional

evaluation_mode

Whether evaluation mode is enabled.

Type:

bool, optional

forecaster

The forecaster used for custom unit types.

Type:

Forecaster, optional

Parameters:

• addr (tuple[str, int] | str, optional) – The world’s address as a (host, port) tuple or a string. Defaults to “world”.

• database_uri (str, optional) – Database URI for establishing a connection. Defaults to “” (no database).

• export_csv_path (str, optional) – Path for exporting CSV data. Defaults to “”.

• log_level (str, optional) – Logging level. Defaults to “INFO”.

• distributed_role (bool, optional) – Defines the world’s role in distributed execution. Defaults to None.

add_learning_strategies_to_learning_role()

Add bidding strategies to the learning role for the specified unit.

Parameters:

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

• bidding_strategies (dict[str, BaseStrategy]) – The bidding strategies for the unit.

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_rl_unit_operator(id: str = 'Operator-RL') → None

Add a RL 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.

The RL unit operator differs from the standard unit operator in that it is used to handle learning units. It has additional functions such as writing to the learning role and scheduling recurrent tasks for writing to the learning role. It also writes learning outputs to the output role.

Parameters:

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

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

Add a unit 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_operator(id: str) → 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])

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: Forecaster) → BaseUnit

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: int = 24, bidding_params: dict = {}, learning_config: LearningConfig = {}, episode: int = 1, eval_episode: int = 1, forecaster: Forecaster | None = None, manager_address=None, **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.

• index (pandas.Series) – The index for the simulation.

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

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

• learning_config (LearningConfig, optional) – Configuration for the learning process. Defaults to an empty configuration.

• forecaster (Forecaster, optional) – The forecaster used for custom unit types. Defaults to None.

• 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.