CLI
The CityLearn installation comes with a CLI for running simulations. The CLI makes use of citylearn.citylearn.simulate.Simulator
and is useful for use cases where multiple environment-agent setups that have been defined in schemas need to be submitted as 1 job for parallel running e.g. in an HPC.
The CLI documentation is returned by executing the following in a Shell Terminal of Powershell:
[1]:
%%sh
python -m citylearn -h
usage: citylearn [-h] [--version] {simulate} ...
An open source OpenAI Gym environment for the implementation of Multi-Agent
Reinforcement Learning (RL) for building energy coordination and demand
response in cities.
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
subcommands:
{simulate}
Running a Simulation using the CLI
The simulate
command is used to run simulations and it has one positional argument, schema
that is a named dataset or path to a schema. Other arguments are optional and have default values. The completed simulation is saved to a pickled citylearn.simulator.Simulator
object in a file that is specified by the optional argument -f
. The -k
argument is a flag to indicate that a list of environment states at the end of each episode be saved as well. The -l
argument is an
integer that specifies the logging level. The output log includes action and reward values at each time step.
[2]:
%%sh
python -m citylearn simulate -h
usage: citylearn simulate [-h] [-f FILEPATH] [-k] [-l LOGGING_LEVEL] schema
Run simulation.
positional arguments:
schema CityLearn dataset name or schema path.
optional arguments:
-h, --help show this help message and exit
-f FILEPATH, --filepath FILEPATH
Filepath to write simulation pickle object to upon
completion. (default: citylearn_simulator.pkl)
-k, --keep_env_history
Indicator to store environment state at the end of
each episode. (default: False)
-l LOGGING_LEVEL, --logging_level LOGGING_LEVEL
Logging level where increasing the level silences
lower level information. (default: 50)
The example below runs a simulation using the citylearn_challenge_2022_phase_1
dataset at a logging level of 100 and is set to store the environment history.
[3]:
%%sh
python -m citylearn simulate citylearn_challenge_2022_phase_1 -k -l 100
Reading a saved Simulator
After a CLI simulation completes, the pickled citylearn.simulator.Simulator
object can be read into memory and its env
property can be utilized as would the env
from a simulation that was run in a python script:
[4]:
from citylearn.simulator import get_simulator
simulator = get_simulator('citylearn_simulator.pkl')
for n, nd in simulator.env.evaluate().groupby('name'):
nd = nd.pivot(index='name', columns='cost_function', values='value').round(3)
print(n, ':', nd.to_dict('records'))
Building_1 : [{'carbon_emissions': 1.134, 'electricity_consumption': 1.184, 'pricing': 1.043, 'zero_net_energy': 1.118}]
Building_2 : [{'carbon_emissions': 1.158, 'electricity_consumption': 1.215, 'pricing': 1.063, 'zero_net_energy': 1.101}]
Building_3 : [{'carbon_emissions': 1.272, 'electricity_consumption': 1.346, 'pricing': 1.145, 'zero_net_energy': 1.294}]
Building_4 : [{'carbon_emissions': 1.181, 'electricity_consumption': 1.237, 'pricing': 1.097, 'zero_net_energy': 1.085}]
Building_5 : [{'carbon_emissions': 1.186, 'electricity_consumption': 1.262, 'pricing': 1.075, 'zero_net_energy': 1.145}]
District : [{'1 - load_factor': 0.987, 'average_daily_peak': 1.15, 'carbon_emissions': 1.186, 'electricity_consumption': 1.249, 'peak_demand': 1.052, 'pricing': 1.085, 'ramping': 1.162, 'zero_net_energy': 1.148}]