How to Load an Environment

Install the latest CityLearn version from PyPi with the :code:pip command:

!pip install CityLearn

Load an Environment Using Named Dataset

CityLearn provides some data files that are contained in named datasets including those that have been used in The CityLearn Challenge. These datasets names can be used in place of schema filepaths or dict objects to initialize an environment. To get the dataset names run:

from citylearn.data import DataSet

dataset_names = DataSet.get_names()
print(dataset_names)

['baeda_3dem', 'citylearn_challenge_2020_climate_zone_1', 'citylearn_challenge_2020_climate_zone_2', 'citylearn_challenge_2020_climate_zone_3', 'citylearn_challenge_2020_climate_zone_4', 'citylearn_challenge_2021', 'citylearn_challenge_2022_phase_1', 'citylearn_challenge_2022_phase_2', 'citylearn_challenge_2022_phase_3', 'citylearn_challenge_2022_phase_all']

Initialize the environment using any of the valid names:

from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv('citylearn_challenge_2020_climate_zone_1')

The dataset can also be download to a path of choice for inspection. The following code copies a dataset to the current directory:

from citylearn.data import DataSet

DataSet.copy('citylearn_challenge_2020_climate_zone_1')

Load an Environment Using Schema Filepath

The Schema filepath can be use to initialize an environment:

from citylearn.citylearn import CityLearnEnv

schema_filepath = 'citylearn_challenge_2020_climate_zone_1/schema.json'
env = CityLearnEnv(schema_filepath)

This approach is best if using a custom Dataset.

Load an Environment Using Schema Dictionary Object

Alternatively, the schema can be supplied as a dict object. This approach can be used to edit the schema parameter values before constructing the environment. With this approach, the root_directory key-value must be explicitly set: See example below:

from citylearn.citylearn import CityLearnEnv
from citylearn.utilities import read_json

schema_filepath = 'citylearn_challenge_2020_climate_zone_1/schema.json'
schema = read_json(schema_filepath)
schema['root_directory'] = 'citylearn_challenge_2020_climate_zone_1'
env = CityLearnEnv(schema)

Some schema parameters can also be overriden by parsing them directly to the citylearn.citylearn.CityLearnEnv constructor:

from citylearn.citylearn import CityLearnEnv
from citylearn.utilities import read_json

schema_filepath = 'citylearn_challenge_2020_climate_zone_1/schema.json'
schema = read_json(schema_filepath)
env = CityLearnEnv(
    schema,
    root_directory='citylearn_challenge_2020_climate_zone_1',
    central_agent=True,
    simulation_start_time_step=10
)