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_dataset_names()
print(dataset_names)

INFO:root:The dataset names DNE in cache. Will download from intelligent-environments-lab/CityLearn GitHub repository and write to /Users/kingsleyenweye/Library/Caches/citylearn/v2.2.0/dataset_names.json. Next time DataSet.get_dataset_names is called, it will read from cache unless DataSet.clear_cache is run first.

['baeda_3dem', 'ca_alameda_county_neighborhood', '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', 'citylearn_challenge_2022_phase_all_plus_evs', 'citylearn_challenge_2023_phase_1', 'citylearn_challenge_2023_phase_2_local_evaluation', 'citylearn_challenge_2023_phase_2_online_evaluation_1', 'citylearn_challenge_2023_phase_2_online_evaluation_2', 'citylearn_challenge_2023_phase_2_online_evaluation_3', 'citylearn_challenge_2023_phase_3_1', 'citylearn_challenge_2023_phase_3_2', 'citylearn_challenge_2023_phase_3_3', 'quebec_neighborhood_with_demand_response_set_points', 'quebec_neighborhood_without_demand_response_set_points', 'tx_travis_county_neighborhood', 'vt_chittenden_county_neighborhood']

Initialize the environment using any of the valid names:

from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv('citylearn_challenge_2020_climate_zone_1')

Couldn't import dot_parser, loading of dot files will not be possible.

INFO:root:The citylearn_challenge_2020_climate_zone_1 dataset DNE in cache. Will download from intelligent-environments-lab/CityLearn GitHub repository and write to /Users/kingsleyenweye/Library/Caches/citylearn/v2.2.0/datasets. Next time DataSet.get_dataset('citylearn_challenge_2020_climate_zone_1') is called, it will read from cache unless DataSet.clear_cache is run first.
INFO:root:The PV sizing data DNE in cache. Will download from intelligent-environments-lab/CityLearn GitHub repository and write to /Users/kingsleyenweye/Library/Caches/citylearn/v2.2.0/misc. Next time DataSet.get_pv_sizing_data is called, it will read from cache unless DataSet.clear_cache is run first.
INFO:root:The battery sizing data DNE in cache. Will download from intelligent-environments-lab/CityLearn GitHub repository and write to /Users/kingsleyenweye/Library/Caches/citylearn/v2.2.0/misc. Next time DataSet.get_battery_sizing_data is called, it will read from cache unless DataSet.clear_cache is run first.

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

schema_filepath = DataSet().get_dataset('citylearn_challenge_2020_climate_zone_1', directory='citylearn_dataset')
print('Schema filepath:', schema_filepath)

Schema filepath: citylearn_dataset/citylearn_challenge_2020_climate_zone_1/schema.json

Load an Environment Using Schema Filepath

The Schema filepath can be use to initialize an environment:

from citylearn.citylearn import CityLearnEnv

schema_filepath = 'citylearn_dataset/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_dataset/citylearn_challenge_2020_climate_zone_1/schema.json'
schema = read_json(schema_filepath)
schema['root_directory'] = 'citylearn_dataset/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_dataset/citylearn_challenge_2020_climate_zone_1/schema.json'
schema = read_json(schema_filepath)
env = CityLearnEnv(
    schema,
    root_directory='citylearn_dataset/citylearn_challenge_2020_climate_zone_1',
    central_agent=True,
    simulation_start_time_step=10
)