CLI

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

!pip install CityLearn

The CityLearn installation comes with a CLI for running simulations. The CLI 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:

!python -m citylearn -h

Couldn't import dot_parser, loading of dot files will not be possible.
usage: citylearn [-h] [--version]
                 {run_work_order,list_datasets,list_default_time_series_variables,simulate}
                 ...

An open source Farama Foundation Gymnasium environment for benchmarking
distributed energy resource control algorithms to provide energy flexibility
in a district of buildings. Compatible with training and evaluating internally
defined CityLearn agents in `citylearn.agents`, user-defined agents that
inherit from `citylearn.agents.base.Agent` and use the same interface as it,
and agents provided by stable-baselines3.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

subcommands:
  {run_work_order,list_datasets,list_default_time_series_variables,simulate}
    run_work_order      Run commands in parallel. Useful for running many
                        `citylearn simulate` commands in parallel.
    list_datasets       Lists available dataset names that can be parsed as
                        `schema` in `citylearn simulate schema`.
    list_default_time_series_variables
                        Lists the default time series variables that will be
                        reported and saved in a `JSON` file post-evaluation.
    simulate            Train or evaluate a trained agent against an
                        environment.

Running a Simulation using the CLI

The simulate command is used to train or evaluate a trained agent:

!python -m citylearn simulate -h

Couldn't import dot_parser, loading of dot files will not be possible.
usage: citylearn simulate [-h] [-a AGENT_NAME] [-ke ENV_KWARGS]
                          [-ka AGENT_KWARGS] [-w WRAPPERS [WRAPPERS ...]]
                          [-tv TIME_SERIES_VARIABLES [TIME_SERIES_VARIABLES ...]]
                          [-sid SIMULATION_ID] [-fa AGENT_FILEPATH]
                          [-d OUTPUT_DIRECTORY]
                          [-te EVALUATION_EPISODE_TIME_STEPS EVALUATION_EPISODE_TIME_STEPS]
                          [-p] [-rs RANDOM_SEED]
                          schema {train,evaluate} ...

positional arguments:
  schema                Name of CityLearn dataset or filepath to a schema.
                        Call `citylearn list_datasets` to get list of valid
                        dataset names.

options:
  -h, --help            show this help message and exit
  -a AGENT_NAME, --agent_name AGENT_NAME
                        Name path to agent. Currently only compatible with
                        internally defined CityLearn agents in
                        `citylearn.agents`, user-defined agents that inherit
                        from `citylearn.agents.base.Agent` and use the same
                        interface as it, and agents provided by stable-
                        baselines3. To use stable-baselines3 agents, make sure
                        to run `pip install stable-baselines3` before using
                        the `simulate command.` (default:
                        citylearn.agents.base.BaselineAgent)
  -ke ENV_KWARGS, --env_kwargs ENV_KWARGS
                        Initialization parameters
                        for`citylearn.citylearn.CityLearnEnv`. (default: None)
  -ka AGENT_KWARGS, --agent_kwargs AGENT_KWARGS
                        Initialization parameters for agent class. (default:
                        None)
  -w WRAPPERS [WRAPPERS ...], --wrappers WRAPPERS [WRAPPERS ...]
                        Name path to environment wrappers e.g.,
                        'citylearn.wrappers.ClippedObservationWrapper'.
                        (default: None)
  -tv TIME_SERIES_VARIABLES [TIME_SERIES_VARIABLES ...], --time_series_variables TIME_SERIES_VARIABLES [TIME_SERIES_VARIABLES ...]
                        Names of building-level time series properties to be
                        stored in the evaluation `JSON` post-evaluation. Call
                        `citylearn list_default_time_series_variables` to see
                        the default variable in use. (default: None)
  -sid SIMULATION_ID, --simulation_id SIMULATION_ID
                        SImulation reference ID used in directory and file
                        names. (default: None)
  -fa AGENT_FILEPATH, --agent_filepath AGENT_FILEPATH
                        Filepath to previously saved agent to use for training
                        or evaluation. (default: None)
  -d OUTPUT_DIRECTORY, --output_directory OUTPUT_DIRECTORY
                        Directory to save all simulation output to. (default:
                        None)
  -te EVALUATION_EPISODE_TIME_STEPS EVALUATION_EPISODE_TIME_STEPS, --evaluation_episode_time_steps EVALUATION_EPISODE_TIME_STEPS EVALUATION_EPISODE_TIME_STEPS
                        Start and end time steps in data set to evaluate on
                        otherwise, the agent is evaluated on entire dataset.
                        (default: None)
  -p, --append          Add to output for existing simulation with
                        `simulation_id` i.e. do not overwrite. (default: True)
  -rs RANDOM_SEED, --random_seed RANDOM_SEED
                        Random seed used during environment and agent
                        initialization. (default: None)

simulate subcommands:
  {train,evaluate}
    train               Train an agent.
    evaluate            Deterministically evaluate an agent.