Schema
A schema is the JSON configuration used to construct
citylearn.citylearn.CityLearnEnv. It selects members, data files,
equipment, observations, actions, reward and optional services.
Start from a public dataset’s schema, then change the sections required for your experiment. File paths are resolved against the dataset root. The Schema Reference gives the supported fields and defaults; Dataset Reference describes the referenced data.
Load a schema by dataset name, local path or a Python dictionary as shown in How to Load an Environment. Configuration is part of the simulator’s Python/JSON workflow. CityLearn UI is for exploring exported results.
Example structure
schema.json
├── simulation window and timestep
├── observations and actions
├── reward_function
├── buildings: data files, devices and electrical_service
├── electric_vehicles_def
└── optional community_market, demand_response, topology and robustness
A complete existing schema is provided 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"
]
}
}
}
}
}