Command Line Interface

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.

usage: citylearn [-h] [--version]
                 {run_work_order,list_datasets,list_default_time_series_variables,simulate}
                 ...

Named Arguments

--version: show program’s version number and exit

subcommands

subcommands: Possible choices: run_work_order, list_datasets, list_default_time_series_variables, simulate

Sub-commands

run_work_order

Run commands in parallel. Useful for running many citylearn simulate commands in parallel.

citylearn run_work_order [-h] [-w MAX_WORKERS] [-is START_INDEX]
                         [-ie END_INDEX]
                         work_order_filepath

Positional Arguments

work_order_filepath: Filepath to script containing list of commands to be run in parallel with each command defined on a new line.

Named Arguments

-w, --max_workers

Maximum number of commands to run at a time. Default is the number of CPUs.

-is, --start_index

Line index of first command to execute. Commands above this index are not executed. The default is to execute from the first line.

Default: 0

-ie, --end_index

Line index of last command to execute. Commands below this index are not exectued. The default is to execute till the last line.

list_datasets

Lists available dataset names that can be parsed as schema in citylearn simulate schema.

citylearn list_datasets [-h]

list_default_time_series_variables

Lists the default time series variables that will be reported and saved in a JSON file post-evaluation.

citylearn list_default_time_series_variables [-h]

simulate

Train or evaluate a trained agent against an environment.

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.

Named Arguments

-a, --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

Initialization parameters for`citylearn.citylearn.CityLearnEnv`.

-ka, --agent_kwargs

Initialization parameters for agent class.

-w, --wrappers

Name path to environment wrappers e.g., ‘citylearn.wrappers.ClippedObservationWrapper’.

-tv, --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.

-sid, --simulation_id

SImulation reference ID used in directory and file names.

-fa, --agent_filepath

Filepath to previously saved agent to use for training or evaluation.

-d, --output_directory

Directory to save all simulation output to.

-te, --evaluation_episode_time_steps

Start and end time steps in data set to evaluate on otherwise, the agent is evaluated on entire dataset.

-p, --append

Add to output for existing simulation with simulation_id i.e. do not overwrite.

Default: True

-rs, --random_seed

Random seed used during environment and agent initialization.

simulate subcommands

subcommands: Possible choices: train, evaluate

Sub-commands

train

Train an agent.

citylearn simulate train [-h] [-e EPISODES] [--save_agent] [--evaluate]

Named Arguments

-e, --episodes

Number of training episodes/epochs.

--save_agent

Whether to save agent to disk at the end of training.

Default: False

--evaluate

Whether to run deterministic evaluation for one episode at the end of training.

Default: False

evaluate

Deterministically evaluate an agent.

citylearn simulate evaluate [-h]