How to Load an Environment

Install CityLearn in the notebook environment:

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

Initialize the environment using any of the valid names:

from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv('citylearn_challenge_2020_climate_zone_1')
env.close()

The following code copies the cached dataset into a working folder for inspection and editing:

from pathlib import Path
from shutil import copytree
from citylearn.data import DataSet

cached_schema = Path(DataSet().get_dataset('citylearn_challenge_2020_climate_zone_1'))
dataset_directory = Path('citylearn_dataset').resolve()
copytree(cached_schema.parent, dataset_directory, dirs_exist_ok=True)
schema_filepath = str(dataset_directory / 'schema.json')
print('Schema filepath:', schema_filepath)

Load an Environment Using Schema Filepath

The Schema filepath can be used to initialize an environment:

from citylearn.citylearn import CityLearnEnv

schema_filepath = str(Path('citylearn_dataset/schema.json').resolve())
env = CityLearnEnv(schema_filepath)
env.close()

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 FileHandler

schema_filepath = str(Path('citylearn_dataset/schema.json').resolve())
schema = FileHandler.read_json(schema_filepath)
schema['root_directory'] = str(Path(schema_filepath).parent)
env = CityLearnEnv(schema)
env.close()

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

from citylearn.citylearn import CityLearnEnv
from citylearn.utilities import FileHandler

schema_filepath = str(Path('citylearn_dataset/schema.json').resolve())
schema = FileHandler.read_json(schema_filepath)
env = CityLearnEnv(
    schema,
    root_directory=str(Path(schema_filepath).parent),
    central_agent=True,
    simulation_start_time_step=10
)
env.close()