Schema

The schema is a .json file containing key-value pairs that define the parameters to use in constructing a citylearn.citylearn.CityLearnEnv object (environment). The aim of the schema is to provide an interface that is analogous to the .idf used to define an EnergyPlus model.

Schema Definition

The key-value pairs in the schema are summarized in the table:

Key	Definition
root_directory	Absolute path to directory that contains the data files including the schema. Can be null if schema is supplied to citylearn.citylearn.CityLearnEnv constructor as a filepath.
central_agent	Set to true for centralized control architecture else false.
simulation_start_time_step	Time step in the data files to start the simulation from.
simulation_end_time_step	Time step in the data files to end the simulation at.
episode_time_steps	Either the number of time steps in an episode or list of episode start and end time steps between simulation_start_time_step and simulation_end_time_step
rolling_episode_split	True if episode sequences are split such that each time step is a candidate for episode_start_time_step otherwise, False to split episodes in steps of episode_time_steps
random_episode_split	True if episode splits are to be selected at random during training otherwise, False to select sequentially.
seconds_per_time_step	Used to define the time resolution of the data files.
observations	Used to define the observation space.
observations:<observation>:active	Set to true if named <observation> should be added to the observation space and provided to the agent else false.
observations:<observation>:shared_in_central_agent	Set to true if if named <observation> values will be common in all buildings.
actions	Used to define the action space.
actions:<action>:active	Set to true if agent will provide named <action> to environment.
agent	Used to define control algorithm to use in simulation.
agent:type	Control algorithm class in citylearn.agents or user-defined algorithm class path.
agent:attributes	Used to define attributes/hyperparameters that are used to construct control algorithm class specified in agent:type.
agent:attributes:<attribute>	Value to set named <attribute> to in control algorithm.
reward_function	Used to define reward function to use in simulation.
reward_function:type	Reward function class in citylearn.reward_function or user-defined reward function class path.
reward_function:attributes	Used to define attributes/hyperparameters that are used to construct reward function class specified in reward_function:type.
reward_function:attributes:<attribute>	Value to set named <attribute> to in reward function.
buildings	Used to define buildings to use in simulation.
buildings:<building_name>	Used to define the attributes of a building uniquely named <building_name>.
buildings:<building_name>:include	Set to true if <building_name> should be included in simulation.
buildings:<building_name>:energy_simulation	Filename of building data file for <building_name>. This file must be located in root_directory.
buildings:<building_name>:weather	Filename of weather data file for <building_name>. This file must be located in root_directory.
buildings:<building_name>:carbon_intensity	Filename of carbon intensity data file for <building_name>. This file must be located in root_directory.
buildings:<building_name>:pricing	Filename of electricity pricing data file for <building_name>. This file must be located in root_directory.
buildings:<building_name>:type	<building_name> class in citylearn.building or user-defined building class path.
buildings:<building_name>:inactive_observations	List of building-specific inactive observations that overrides observations:<observation>:active.
buildings:<building_name>:inactive_actions	List of building-specific inactive actions that overrides actions:<action>:active.
buildings:<building_name>:<device>	Used to define a <device> for <building_name>. <device> can be cooling_device, heating_device, dhw_device, cooling_storage, heating_storage, dhw_storage, electrical_storage or pv.
buildings:<building_name>:<device>:type	<device> class in citylearn.energy_model or user-defined device class path.
buildings:<building_name>:<device>:autosize	Set to true if the <device> should be autosized for <building_name> else false.
buildings:<building_name>:<device>:autosize_attributes	Used to define attributes that are used to autosize <device> class specified in buildings:<building_name>:<device>:type.
buildings:<building_name>:<device>:autosize_attributes:<attribute>	Value to set named <attribute> to autosize <device> class specified in buildings:<building_name>:<device>:type.
buildings:<building_name>:<device>:attributes	Used to define attributes that are used to construct <device> class specified in buildings:<building_name>:<device>:type.
buildings:<building_name>:<device>:attributes:<attribute>	Value to set named <attribute> of <device> class specified in buildings:<building_name>:<device>:type.
buildings:<building_name>:dynamics	Used to define building temperature dynamics LSTM models.
buildings:<building_name>:dynamics:<mode>	Used to define building temperature dynamics LSTM model for specific HVAC mode where <mode> may be cooling or heating.
buildings:<building_name>:dynamics:<mode>:type	Temperature dynamics class in citylearn.dynamics or user-defined dynamics class path.
buildings:<building_name>:dynamics:<mode>:attributes	Used to define attributes that are used to construct buildings:<building_name>:dynamics:<mode>:type.
buildings:<building_name>:power_outage	Used to define power outage preferences and stochastic model.
buildings:<building_name>:power_outage:simulate_power_outage	Whether to allow time steps when the grid is unavailable and loads must be met using only the building’s flexible resources.
buildings:<building_name>:power_outage:stochastic_power_outage	Whether to use a stochastic function to determine outage time steps otherwise, citylearn.building.Building.energy_simulation.power_outage time series is used.
buildings:<building_name>:power_outage:stochastic_power_outage_model	Used to define stochastic power outage model.
buildings:<building_name>:power_outage:stochastic_power_outage_model:type	Stochastic power outage model in citylearn.power_outage or user-defined model class path.
buildings:<building_name>:power_outage:stochastic_power_outage_model:attributes	Used to define attributes/hyperparameters that are used to construct stochastic power outage model class in buildings:<building_name>:power_outage:stochastic_power_outage_model:type.

An Example Schema

An example schema is shown below:

{
  "random_seed": 0,
  "root_directory": null,
  "central_agent": false,
  "simulation_start_time_step": 0,
  "simulation_end_time_step": 2927,
  "episode_time_steps": null,
  "rolling_episode_split": false,
  "random_episode_split": false,
  "seconds_per_time_step": 3600.0,
  "observations": {
    "month": {
      "active": true,
      "shared_in_central_agent": true
    },
    "day_type": {
      "active": true,
      "shared_in_central_agent": true
    },
    "hour": {
      "active": true,
      "shared_in_central_agent": true
    },
    "daylight_savings_status": {
      "active": false,
      "shared_in_central_agent": true
    },
    "outdoor_dry_bulb_temperature": {
      "active": true,
      "shared_in_central_agent": true
    },
    "outdoor_dry_bulb_temperature_predicted_1": {
      "active": true,
      "shared_in_central_agent": true
    },
    "outdoor_dry_bulb_temperature_predicted_2": {
      "active": true,
      "shared_in_central_agent": true
    },
    "outdoor_dry_bulb_temperature_predicted_3": {
      "active": true,
      "shared_in_central_agent": true
    },
    "outdoor_relative_humidity": {
      "active": false,
      "shared_in_central_agent": true
    },
    "outdoor_relative_humidity_predicted_1": {
      "active": false,
      "shared_in_central_agent": true
    },
    "outdoor_relative_humidity_predicted_2": {
      "active": false,
      "shared_in_central_agent": true
    },
    "outdoor_relative_humidity_predicted_3": {
      "active": false,
      "shared_in_central_agent": true
    },
    "diffuse_solar_irradiance": {
      "active": true,
      "shared_in_central_agent": true
    },
    "diffuse_solar_irradiance_predicted_1": {
      "active": false,
      "shared_in_central_agent": true
    },
    "diffuse_solar_irradiance_predicted_2": {
      "active": false,
      "shared_in_central_agent": true
    },
    "diffuse_solar_irradiance_predicted_3": {
      "active": false,
      "shared_in_central_agent": true
    },
    "direct_solar_irradiance": {
      "active": true,
      "shared_in_central_agent": true
    },
    "direct_solar_irradiance_predicted_1": {
      "active": true,
      "shared_in_central_agent": true
    },
    "direct_solar_irradiance_predicted_2": {
      "active": true,
      "shared_in_central_agent": true
    },
    "direct_solar_irradiance_predicted_3": {
      "active": true,
      "shared_in_central_agent": true
    },
    "carbon_intensity": {
      "active": true,
      "shared_in_central_agent": true
    },
    "indoor_dry_bulb_temperature": {
      "active": true,
      "shared_in_central_agent": false
    },
    "average_unmet_cooling_setpoint_difference": {
      "active": false,
      "shared_in_central_agent": false
    },
    "indoor_relative_humidity": {
      "active": false,
      "shared_in_central_agent": false
    },
    "non_shiftable_load": {
      "active": true,
      "shared_in_central_agent": false
    },
    "solar_generation": {
      "active": true,
      "shared_in_central_agent": false
    },
    "cooling_storage_soc": {
      "active": true,
      "shared_in_central_agent": false
    },
    "heating_storage_soc": {
      "active": false,
      "shared_in_central_agent": false
    },
    "dhw_storage_soc": {
      "active": true,
      "shared_in_central_agent": false
    },
    "electrical_storage_soc": {
      "active": true,
      "shared_in_central_agent": false
    },
    "net_electricity_consumption": {
      "active": false,
      "shared_in_central_agent": false
    },
    "electricity_pricing": {
      "active": true,
      "shared_in_central_agent": true
    },
    "electricity_pricing_predicted_1": {
      "active": true,
      "shared_in_central_agent": true
    },
    "electricity_pricing_predicted_2": {
      "active": true,
      "shared_in_central_agent": true
    },
    "electricity_pricing_predicted_3": {
      "active": true,
      "shared_in_central_agent": true
    },
    "cooling_device_efficiency": {
      "active": true,
      "shared_in_central_agent": false
    },
    "heating_device_efficiency": {
      "active": false,
      "shared_in_central_agent": false
    },
    "cooling_demand": {
      "active": false,
      "shared_in_central_agent": false
    },
    "heating_demand": {
      "active": false,
      "shared_in_central_agent": false
    },
    "occupant_count": {
      "active": true,
      "shared_in_central_agent": false
    },
    "power_outage": {
      "active": false,
      "shared_in_central_agent": false
    },
    "hvac_mode": {
      "active": false,
      "shared_in_central_agent": false
    },
    "comfort_band": {
      "active": false,
      "shared_in_central_agent": false
    },
    "indoor_dry_bulb_temperature_cooling_set_point": {
      "active": true,
      "shared_in_central_agent": false
    },
    "indoor_dry_bulb_temperature_heating_set_point": {
      "active": false,
      "shared_in_central_agent": false
    },
    "indoor_dry_bulb_temperature_cooling_delta": {
      "active": true,
      "shared_in_central_agent": false
    },
    "indoor_dry_bulb_temperature_heating_delta": {
      "active": false,
      "shared_in_central_agent": false
    }
  },
  "actions": {
    "cooling_storage": {
      "active": true
    },
    "heating_storage": {
      "active": false
    },
    "dhw_storage": {
      "active": true
    },
    "electrical_storage": {
      "active": false
    },
    "cooling_device": {
      "active": true
    },
    "heating_device": {
      "active": false
    },
    "cooling_or_heating_device": {
      "active": false
    }
  },
  "agent": {
    "type": "citylearn.agents.sac.SAC",
    "attributes": {
      "hidden_dimension": [
        256,
        256
      ],
      "discount": 0.9,
      "tau": 0.005,
      "lr": 0.001,
      "batch_size": 512,
      "replay_buffer_capacity": 100000.0,
      "standardize_start_time_step": 2928,
      "end_exploration_time_step": 2929,
      "action_scaling_coef": 0.5,
      "reward_scaling": 5.0,
      "update_per_time_step": 2,
      "alpha": 1.0
    }
  },
  "reward_function": {
    "type": "citylearn.reward_function.ComfortReward",
    "attributes": null
  },
  "buildings": {
    "Building_1": {
      "include": true,
      "energy_simulation": "Building_1.csv",
      "weather": "weather.csv",
      "carbon_intensity": null,
      "pricing": "pricing.csv",
      "type": "citylearn.building.LSTMDynamicsBuilding",
      "cooling_device": {
        "type": "citylearn.energy_model.HeatPump",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 1.0
        },
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.2,
          "target_cooling_temperature": 8,
          "target_heating_temperature": 45
        }
      },
      "dhw_device": {
        "type": "citylearn.energy_model.ElectricHeater",
        "autosize": true,
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.9
        }
      },
      "cooling_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.006
        }
      },
      "inactive_observations": [
        "dhw_storage_soc",
        "solar_generation",
        "diffuse_solar_irradiance",
        "diffuse_solar_irradiance_predicted_1",
        "diffuse_solar_irradiance_predicted_2",
        "diffuse_solar_irradiance_predicted_3",
        "direct_solar_irradiance_predicted_1",
        "direct_solar_irradiance_predicted_2",
        "direct_solar_irradiance_predicted_3",
        "heating_storage_soc",
        "electrical_storage_soc",
        "carbon_intensity"
      ],
      "inactive_actions": [
        "dhw_storage",
        "heating_storage",
        "electrical_storage"
      ],
      "dynamics": {
        "type": "citylearn.dynamics.LSTMDynamics",
        "attributes": {
          "input_size": 11,
          "hidden_size": 8,
          "num_layers": 2,
          "lookback": 12,
          "filename": "Building_1.pth",
          "input_normalization_minimum": [
            0.0,
            10.80833,
            0.0,
            0.0,
            -1.0,
            -1.0,
            -0.97493,
            -0.90097,
            -1.0,
            -1.0,
            18.12067
          ],
          "input_normalization_maximum": [
            1037.6663,
            36.90833,
            30.81475,
            24.73536719,
            1.0,
            1.0,
            0.97493,
            1.0,
            0.0,
            0.0,
            29.89854
          ],
          "input_observation_names": [
            "direct_solar_irradiance",
            "outdoor_dry_bulb_temperature",
            "occupant_count",
            "cooling_demand",
            "hour_sin",
            "hour_cos",
            "day_type_sin",
            "day_type_cos",
            "month_sin",
            "month_cos",
            "indoor_dry_bulb_temperature"
          ]
        }
      }
    },
    "Building_2": {
      "include": true,
      "energy_simulation": "Building_2.csv",
      "weather": "weather.csv",
      "carbon_intensity": null,
      "pricing": "pricing.csv",
      "type": "citylearn.building.LSTMDynamicsBuilding",
      "cooling_device": {
        "type": "citylearn.energy_model.HeatPump",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 1.0
        },
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.21,
          "target_cooling_temperature": 9,
          "target_heating_temperature": 45
        }
      },
      "dhw_device": {
        "type": "citylearn.energy_model.ElectricHeater",
        "autosize": true,
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.92
        }
      },
      "cooling_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.006
        }
      },
      "dhw_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.008
        }
      },
      "inactive_observations": [
        "solar_generation",
        "diffuse_solar_irradiance",
        "diffuse_solar_irradiance_predicted_1",
        "diffuse_solar_irradiance_predicted_2",
        "diffuse_solar_irradiance_predicted_3",
        "direct_solar_irradiance_predicted_1",
        "direct_solar_irradiance_predicted_2",
        "direct_solar_irradiance_predicted_3",
        "heating_storage_soc",
        "electrical_storage_soc",
        "carbon_intensity"
      ],
      "inactive_actions": [
        "heating_storage",
        "electrical_storage"
      ],
      "dynamics": {
        "type": "citylearn.dynamics.LSTMDynamics",
        "attributes": {
          "input_size": 11,
          "hidden_size": 8,
          "num_layers": 2,
          "lookback": 12,
          "filename": "Building_2.pth",
          "input_normalization_minimum": [
            0.0,
            10.80833,
            0.0,
            0.0,
            -1.0,
            -1.0,
            -0.97493,
            -0.90097,
            -1.0,
            -1.0,
            22.63211
          ],
          "input_normalization_maximum": [
            1037.6663,
            36.90833,
            296.33365,
            109.74094531,
            1.0,
            1.0,
            0.97493,
            1.0,
            0.0,
            0.0,
            27.65767
          ],
          "input_observation_names": [
            "direct_solar_irradiance",
            "outdoor_dry_bulb_temperature",
            "occupant_count",
            "cooling_demand",
            "hour_sin",
            "hour_cos",
            "day_type_sin",
            "day_type_cos",
            "month_sin",
            "month_cos",
            "indoor_dry_bulb_temperature"
          ]
        }
      }
    },
    "Building_3": {
      "include": true,
      "energy_simulation": "Building_3.csv",
      "weather": "weather.csv",
      "carbon_intensity": null,
      "pricing": "pricing.csv",
      "type": "citylearn.building.LSTMDynamicsBuilding",
      "cooling_device": {
        "type": "citylearn.energy_model.HeatPump",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 1.0
        },
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.23,
          "target_cooling_temperature": 8,
          "target_heating_temperature": 45
        }
      },
      "dhw_device": {
        "type": "citylearn.energy_model.ElectricHeater",
        "autosize": true,
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.87
        }
      },
      "cooling_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.006
        }
      },
      "dhw_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.008
        }
      },
      "inactive_observations": [
        "solar_generation",
        "diffuse_solar_irradiance",
        "diffuse_solar_irradiance_predicted_1",
        "diffuse_solar_irradiance_predicted_2",
        "diffuse_solar_irradiance_predicted_3",
        "direct_solar_irradiance_predicted_1",
        "direct_solar_irradiance_predicted_2",
        "direct_solar_irradiance_predicted_3",
        "heating_storage_soc",
        "electrical_storage_soc",
        "carbon_intensity"
      ],
      "inactive_actions": [
        "heating_storage",
        "electrical_storage"
      ],
      "dynamics": {
        "type": "citylearn.dynamics.LSTMDynamics",
        "attributes": {
          "input_size": 11,
          "hidden_size": 8,
          "num_layers": 2,
          "lookback": 12,
          "filename": "Building_3.pth",
          "input_normalization_minimum": [
            0.0,
            10.80833,
            0.0,
            0.0,
            -1.0,
            -1.0,
            -0.97493,
            -0.90097,
            -1.0,
            -1.0,
            18.22155
          ],
          "input_normalization_maximum": [
            1037.6663,
            36.90833,
            258.90265,
            72.14350781,
            1.0,
            1.0,
            0.97493,
            1.0,
            0.0,
            0.0,
            30.50947
          ],
          "input_observation_names": [
            "direct_solar_irradiance",
            "outdoor_dry_bulb_temperature",
            "occupant_count",
            "cooling_demand",
            "hour_sin",
            "hour_cos",
            "day_type_sin",
            "day_type_cos",
            "month_sin",
            "month_cos",
            "indoor_dry_bulb_temperature"
          ]
        }
      }
    },
    "Building_4": {
      "include": true,
      "energy_simulation": "Building_4.csv",
      "weather": "weather.csv",
      "carbon_intensity": null,
      "pricing": "pricing.csv",
      "type": "citylearn.building.LSTMDynamicsBuilding",
      "cooling_device": {
        "type": "citylearn.energy_model.HeatPump",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 1.0
        },
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.22,
          "target_cooling_temperature": 9,
          "target_heating_temperature": 45
        }
      },
      "dhw_device": {
        "type": "citylearn.energy_model.ElectricHeater",
        "autosize": true,
        "attributes": {
          "nominal_power": null,
          "efficiency": 0.9
        }
      },
      "cooling_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.006
        }
      },
      "dhw_storage": {
        "type": "citylearn.energy_model.StorageTank",
        "autosize": true,
        "autosize_attributes": {
          "safety_factor": 3.0
        },
        "attributes": {
          "capacity": null,
          "loss_coefficient": 0.008
        }
      },
      "pv": {
        "type": "citylearn.energy_model.PV",
        "autosize": false,
        "attributes": {
          "nominal_power": 120
        }
      },
      "inactive_observations": [
        "heating_storage_soc",
        "electrical_storage_soc",
        "carbon_intensity"
      ],
      "inactive_actions": [
        "heating_storage",
        "electrical_storage"
      ],
      "dynamics": {
        "type": "citylearn.dynamics.LSTMDynamics",
        "attributes": {
          "input_size": 11,
          "hidden_size": 50,
          "num_layers": 1,
          "lookback": 12,
          "filename": "Building_4.pth",
          "input_normalization_minimum": [
            0.0,
            10.80833,
            0.0,
            0.0,
            -1.0,
            -1.0,
            -0.97493,
            -0.90097,
            -1.0,
            -1.0,
            23.36176
          ],
          "input_normalization_maximum": [
            1037.6663,
            36.90833,
            254.76593,
            245.52803125,
            1.0,
            1.0,
            0.97493,
            1.0,
            0.0,
            0.0,
            30.95352
          ],
          "input_observation_names": [
            "direct_solar_irradiance",
            "outdoor_dry_bulb_temperature",
            "occupant_count",
            "cooling_demand",
            "hour_sin",
            "hour_cos",
            "day_type_sin",
            "day_type_cos",
            "month_sin",
            "month_cos",
            "indoor_dry_bulb_temperature"
          ]
        }
      }
    }
  }
}