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

World instance with the provided address, database URI, export CSV path, log level, and distributed role settings.

If a database URI is provided, it establishes a database connection. Additionally, it sets up various dictionaries and attributes for market operators, markets, unit operators, unit types, bidding strategies, and clearing mechanisms. If available, it imports learning strategies and handles any potential import errors. Finally, it sets up the event loop for asynchronous operations.

logger

The logger for the world instance.

Type:

logging.Logger

addr

The address of the world, represented as a tuple of string and int or a string.

Type:

Union[tuple[str, int], str]

container

The container for the world instance.

Type:

mango.Container, optional

distributed_role

A boolean indicating whether distributed roles are enabled.

Type:

bool, optional

export_csv_path

The path for exporting CSV data.

Type:

str

db

The database connection.

Type:

sqlalchemy.engine.base.Engine, optional

market_operators

The market operators for the world instance.

Type:

dict[str, mango.RoleAgent]

markets

The markets for the world instance.

Type:

dict[str, MarketConfig]

unit_operators

The unit operators for the world instance.

Type:

dict[str, UnitsOperator]

unit_types

The unit types for the world instance.

Type:

dict[str, BaseUnit]

bidding_strategies

The bidding strategies for the world instance.

Type:

dict[str, type[BaseStrategy]]

clearing_mechanisms

The clearing mechanisms for the world instance.

Type:

dict[str, MarketRole]

addresses

The addresses for the world instance.

Type:

list[str]

loop

The event loop for the world instance.

Type:

asyncio.AbstractEventLoop

clock

The external clock for the world instance.

Type:

ExternalClock

start

The start datetime for the simulation.

Type:

datetime.datetime

end

The end datetime for the simulation.

Type:

datetime.datetime

learning_config

The configuration for the learning process.

Type:

LearningConfig

evaluation_mode

A boolean indicating whether the evaluation mode is enabled.

Type:

bool

forecaster

The forecaster used for custom unit types.

Type:

Forecaster, optional

learning_mode

A boolean indicating whether the learning mode is enabled.

Type:

bool

output_agent_addr

The address of the output agent.

Type:

tuple[str, str]

bidding_params

Parameters for bidding.

Type:

dict

index

The index for the simulation.

Type:

pandas.Series

Parameters:

• addr – The address of the world, represented as a tuple of string and int or a string.

• database_uri – The URI for the database connection.

• export_csv_path – The path for exporting CSV data.

• log_level – The logging level for the world instance.

• distributed_role – A boolean indicating whether distributed roles are enabled.

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: 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. If in learning mode, additional context parameters related to learning and output agents are set for the unit operator’s role context.

Parameters:

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

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

Asynchronously adds a unit to the simulation, checking if the unit operator exists, verifying the unit type, and ensuring that the unit operator does not already have a unit with the same id. It then creates bidding strategies for the unit and adds the unit within the associated unit operator.

Parameters:

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

• unit_type (str) – The type of unit to be added.

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

• unit_params (dict) – Parameters for configuring the unit.

• forecaster (Forecaster) – The forecaster used by the 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.

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.

async setup(start: datetime, end: datetime, simulation_id: str, index: Series, save_frequency_hours: int = 24, bidding_params: dict = {}, learning_config: LearningConfig = {}, 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

async setup_learning() → 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.

async setup_output_agent(simulation_id: str, save_frequency_hours: 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:

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

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