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 |
---|---|
|
Absolute path to directory that contains the data files including the schema. Can be |
|
Set to |
|
Time step in the data files to start the simulation from. |
|
Time step in the data files to end the simulation at. |
|
Either the number of time steps in an episode or list of episode start and end time steps between |
|
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 |
|
True if episode splits are to be selected at random during training otherwise, False to select sequentially. |
|
Used to define the time resolution of the data files. |
|
Used to define the observation space. |
|
Set to |
|
Set to |
|
Used to define the action space. |
|
Set to |
|
Used tp define control algorithm to use in simulation. |
|
Control algorithm class in |
|
Used to define attributes/hyperparameters that are used to construct control algorithm class specified in |
|
Value to set named |
|
Used to define reward function to use in simulation. |
|
Reward function class in |
|
Used to define attributes/hyperparameters that are used to construct reward function class specified in |
|
Value to set named |
|
Used tp define buildings to use in simulation. |
|
Used to define the attributes of a building uniquely named |
|
Set to |
|
Filename of building data file for |
|
Filename of weather data file for |
|
Filename of carbon intensity data file for |
|
Filename of electricity pricing data file for |
|
|
|
List of building-specific inactive observations that overrides |
|
List of building-specific inactive actions that overrides |
|
Used to define a <device> for |
|
|
|
Set to |
|
Used to define attributes that are used to autosize |
|
Value to set named |
|
Used to define attributes that are used to construct |
|
Value to set named |
|
Used to define building temperature dynamics LSTM models. |
|
Used to define building temperature dynamics LSTM model for specific HVAC mode where |
|
temperature dynamics class in |
|
Used to define attributes that are used to construct |
|
Used to define power outage preferences and stochastic model. |
|
Whether to allow time steps when the grid is unavailable and loads must be met using only the building’s flexible resources. |
|
Whether to use a stochastic function to determine outage time steps otherwise, |
|
Used to define stochastic power outage model. |
|
Stochastic power outage model in |
|
Used to define attributes/hyperparameters that are used to construct stochastic power outage model class in |
An Example Schema
An example schema is shown below:
{
"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_6h": {
"active": true,
"shared_in_central_agent": true
},
"outdoor_dry_bulb_temperature_predicted_12h": {
"active": true,
"shared_in_central_agent": true
},
"outdoor_dry_bulb_temperature_predicted_24h": {
"active": true,
"shared_in_central_agent": true
},
"outdoor_relative_humidity": {
"active": false,
"shared_in_central_agent": true
},
"outdoor_relative_humidity_predicted_6h": {
"active": false,
"shared_in_central_agent": true
},
"outdoor_relative_humidity_predicted_12h": {
"active": false,
"shared_in_central_agent": true
},
"outdoor_relative_humidity_predicted_24h": {
"active": false,
"shared_in_central_agent": true
},
"diffuse_solar_irradiance": {
"active": true,
"shared_in_central_agent": true
},
"diffuse_solar_irradiance_predicted_6h": {
"active": false,
"shared_in_central_agent": true
},
"diffuse_solar_irradiance_predicted_12h": {
"active": false,
"shared_in_central_agent": true
},
"diffuse_solar_irradiance_predicted_24h": {
"active": false,
"shared_in_central_agent": true
},
"direct_solar_irradiance": {
"active": true,
"shared_in_central_agent": true
},
"direct_solar_irradiance_predicted_6h": {
"active": true,
"shared_in_central_agent": true
},
"direct_solar_irradiance_predicted_12h": {
"active": true,
"shared_in_central_agent": true
},
"direct_solar_irradiance_predicted_24h": {
"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_6h": {
"active": true,
"shared_in_central_agent": true
},
"electricity_pricing_predicted_12h": {
"active": true,
"shared_in_central_agent": true
},
"electricity_pricing_predicted_24h": {
"active": true,
"shared_in_central_agent": true
},
"cooling_device_cop": {
"active": true,
"shared_in_central_agent": false
},
"heating_device_cop": {
"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
},
"indoor_dry_bulb_temperature_set_point": {
"active": true,
"shared_in_central_agent": false
},
"indoor_dry_bulb_temperature_delta": {
"active": true,
"shared_in_central_agent": false
},
"power_outage": {
"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
}
},
"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_6h",
"diffuse_solar_irradiance_predicted_12h",
"diffuse_solar_irradiance_predicted_24h",
"direct_solar_irradiance_predicted_6h",
"direct_solar_irradiance_predicted_12h",
"direct_solar_irradiance_predicted_24h",
"heating_storage_soc",
"electrical_storage_soc",
"carbon_intensity"
],
"inactive_actions": [
"dhw_storage",
"heating_storage",
"electrical_storage"
],
"dynamics": {
"cooling": {
"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"
]
}
},
"heating": {
"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",
"heating_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_6h",
"diffuse_solar_irradiance_predicted_12h",
"diffuse_solar_irradiance_predicted_24h",
"direct_solar_irradiance_predicted_6h",
"direct_solar_irradiance_predicted_12h",
"direct_solar_irradiance_predicted_24h",
"heating_storage_soc",
"electrical_storage_soc",
"carbon_intensity"
],
"inactive_actions": [
"heating_storage",
"electrical_storage"
],
"dynamics": {
"cooling": {
"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"
]
}
},
"heating": {
"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",
"heating_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_6h",
"diffuse_solar_irradiance_predicted_12h",
"diffuse_solar_irradiance_predicted_24h",
"direct_solar_irradiance_predicted_6h",
"direct_solar_irradiance_predicted_12h",
"direct_solar_irradiance_predicted_24h",
"heating_storage_soc",
"electrical_storage_soc",
"carbon_intensity"
],
"inactive_actions": [
"heating_storage",
"electrical_storage"
],
"dynamics": {
"cooling": {
"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"
]
}
},
"heating": {
"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",
"heating_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": {
"cooling": {
"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"
]
}
},
"heating": {
"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",
"heating_demand",
"hour_sin",
"hour_cos",
"day_type_sin",
"day_type_cos",
"month_sin",
"month_cos",
"indoor_dry_bulb_temperature"
]
}
}
}
}
}
}