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.
- addr#
The address of the world, represented as a tuple of string and int or a string.
- container#
The container for the world instance.
- Type:
mango.Container, optional
- db#
The database connection.
- Type:
sqlalchemy.engine.base.Engine, optional
- market_operators#
The market operators for the world instance.
- Type:
- markets#
The markets for the world instance.
- Type:
- unit_operators#
The unit operators for the world instance.
- Type:
- bidding_strategies#
The bidding strategies for the world instance.
- Type:
dict[str, type[BaseStrategy]]
- clearing_mechanisms#
The clearing mechanisms for the world instance.
- Type:
- loop#
The event loop for the world instance.
- clock#
The external clock for the world instance.
- Type:
ExternalClock
- start#
The start datetime for the simulation.
- Type:
- end#
The end datetime for the simulation.
- Type:
- learning_config#
The configuration for the learning process.
- Type:
- forecaster#
The forecaster used for custom unit types.
- Type:
Forecaster, optional
- index#
The index for the simulation.
- Type:
- 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. If True - this world is a manager world which schedules events itself. If False - this world is a client world which receives schedules from a manager through the DistributedClock mechanism. If None (default) - this world is not distributed and does not use subprocesses
- 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
- 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 = {}, 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() 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(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.