7. Environments Configuration and Registration
When defining a new environment, we can use the Sinergym environment constructor and fill the parameters explained in section Available Parameters.
Many environments can be created based on the same building, depending on its configurations. Therefore, creating (or registering Gymnasium IDs) for all of them can be tedious.
Sinergym has a system that automates this process. From a JSON file hosted in sinergym/data/default_configuration, a set of parameters for each of the possible configurations will be built, along with an associated ID, and will be registered in Gymnasium automatically.
This section will explain the structure of these JSON configuration definitions. Additionally, this structure
facilitates the definition of observation variables (time_variables, variables and meters) and
action variables (actuators). Instead of defining in the EnergyPlus Python API format like the environment
constructor, Sinergym will read this simpler structure and parse it to the EnergyPlus Python API format
automatically.
Key |
Optional |
Description |
|---|---|---|
id_base |
No |
Base name to refer to the ID’s with this building model. |
building_file |
No |
Building model file allocated in |
weather_specification |
No |
Set of weather to generate an environment with each one, allocated in |
config_params |
Yes |
Extra parameters for the environments; it is optional. |
weather_variability |
Yes |
Create additionally a version of all environments with stochasticity in weather. |
max_ep_data_store_num |
Yes |
Max storage in Sinergym episodes, by default 10. |
time_variables |
No |
|
variables |
No |
|
meters |
No |
|
actuators |
No |
|
action_space |
No |
Gymnasium action space definition. |
action_space_discrete |
Yes |
If you want that Sinergym auto-generate a discrete version of environments, you should write this space too. |
only_discrete |
Yes |
If you have specified action_space and a discrete_space based on action_space (required, see DiscretizeEnv), you can only register discrete version with this flag |
reward |
No |
Reward class name to use. |
reward_kwargs |
No |
Reward kwargs for Reward class constructor in dict format. |
Important
Sinergym requires a continuous action space, but not a discrete one. It begins with continuous environments and discretizes them using a wrapper. For more details, refer to DiscretizeEnv.
These are the keys of the JSON. An example might make it clearer:
{
"id_base" : "5zone",
"building_file" : "5ZoneAutoDXVAV.epJSON",
"weather_specification" : {
"weather_files" : ["USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw",
"USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw",
"USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw"
],
"keys" : ["hot", "mixed", "cool"]
},
"config_params" : null,
"weather_variability":{
"Dry Bulb Temperature": [1.0, 0.0, 0.001]
},
"max_ep_data_store_num" : 10,
"time_variables" : ["month", "day_of_month", "hour"],
"variables" : {
"Site Outdoor Air DryBulb Temperature" : {
"variable_names" : "outdoor_temperature",
"keys" : "Environment"
},
"Site Outdoor Air Relative Humidity" : {
"variable_names" : "outdoor_humidity",
"keys" : "Environment"
},
"Site Wind Speed" : {
"variable_names" : "wind_speed",
"keys" : "Environment"
},
"Site Wind Direction" : {
"variable_names" : "wind_direction",
"keys" : "Environment"
},
"Site Diffuse Solar Radiation Rate per Area" : {
"variable_names" : "diffuse_solar_radiation",
"keys" : "Environment"
},
"Site Direct Solar Radiation Rate per Area" : {
"variable_names" : "direct_solar_radiation",
"keys" : "Environment"
},
"Zone Thermostat Heating Setpoint Temperature" : {
"variable_names" : "htg_setpoint",
"keys" : "SPACE5-1"
},
"Zone Thermostat Cooling Setpoint Temperature" : {
"variable_names" : "clg_setpoint",
"keys" : "SPACE5-1"
},
"Zone Air Temperature" : {
"variable_names" : "air_temperature",
"keys" : "SPACE5-1"
},
"Zone Air Relative Humidity" : {
"variable_names" : "air_humidity",
"keys" : "SPACE5-1"
},
"Zone People Occupant Count" : {
"variable_names" : "people_occupant",
"keys" : "SPACE5-1"
},
"Environmental Impact Total CO2 Emissions Carbon Equivalent Mass" : {
"variable_names" : "co2_emission",
"keys" : "site"
},
"Facility Total HVAC Electricity Demand Rate" : {
"variable_names" : "HVAC_electricity_demand_rate",
"keys" : "Whole Building"
}
},
"meters" : {
"Electricity:HVAC" : "total_electricity_HVAC"
},
"actuators" : {
"HTG-SETP-SCH" : {
"variable_name" : "Heating_Setpoint_RL",
"element_type" : "Schedule:Compact",
"value_type" : "Schedule Value"
},
"CLG-SETP-SCH" : {
"variable_name" : "Cooling_Setpoint_RL",
"element_type" : "Schedule:Compact",
"value_type" : "Schedule Value"
}
},
"action_space" : "gym.spaces.Box(low=np.array([12.0, 23.25], dtype=np.float32), high=np.array([23.25, 30.0], dtype=np.float32), shape=(2,), dtype=np.float32)",
"action_space_discrete" : "gym.spaces.Discrete(10)",
"reward" : "LinearReward",
"reward_kwargs" : {
"temperature_variables" : ["air_temperature"],
"energy_variables" : ["HVAC_electricity_demand_rate"],
"range_comfort_winter" : [20.0, 23.5],
"range_comfort_summer" : [23.0, 26.0],
"summer_start" : [6, 1],
"summer_final" : [9, 30],
"energy_weight" : 0.5,
"lambda_energy" : 1e-4,
"lambda_temperature" : 1.0
}
}
With this JSON configuration for the building 5ZoneAutoDXVAV.epJSON, the following
environments will be automatically configured
['Eplus-5zone-hot-continuous-v1',
'Eplus-5zone-hot-discrete-v1',
'Eplus-5zone-hot-continuous-stochastic-v1',
'Eplus-5zone-hot-discrete-stochastic-v1',
'Eplus-5zone-mixed-continuous-v1',
'Eplus-5zone-mixed-discrete-v1',
'Eplus-5zone-mixed-continuous-stochastic-v1',
'Eplus-5zone-mixed-discrete-stochastic-v1',
'Eplus-5zone-cool-continuous-v1',
'Eplus-5zone-cool-discrete-v1',
'Eplus-5zone-cool-continuous-stochastic-v1',
'Eplus-5zone-cool-discrete-stochastic-v1'
]
For example, if you don’t define discrete space or weather variability, the discrete and stochastic versions will not appear in the list.
Warning
For discrete environments, an action mapping must be defined in constants.py named as DEFAULT_<id_base in upper case>_DISCRETE_FUNCTION for correct registration.
7.1. Weather Specification field
The weather specification is set up to generate multiple environments based on the defined weathers. Weather files must be in the correct folder, and the keys are used to define the final name in the environment’s IDs.
7.2. Variables field
The variables field uses a specific format to quickly define all the observed variables
in the environment. The variable names and keys can be either an individual string or a list of
strings. The following graph explains its functionality:
Sinergym will parse this information into the variables parameter for the environment constructor
(similar to the EnergyPlus Python API) during registration. The same process is applied to the
meters and actuators fields, although they are simpler.