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:

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

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

%%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:

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}]