6. Environments Configuration and Registration
When defining a new environment, we can use the Sinergym environment constructor and fill the parameters that we explained in section Available Parameters.
Many environments can be made based on the same building, depending on its configurations. Therefore, this can be tedious to create (or register Gymnasium ID’s) of all of them.
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.
The structure of these JSON configuration definitions will be explained in this section. Additionally, this structure facilitates
the definition of observation variables (time_variables, variables and meters) and action variables (actuators).
Instead of defining in EnergyPlus Python API format like environment constructor, Sinergym will read this simpler structure and parse
to 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. |
variation |
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
As you can see, the continuous action space is mandatory, while the discrete one is not. This is because Sinergym starts from continuous environments and then discretizes them through a wrapper. For more information see DiscretizeEnv.
These are the keys of the JSON, an example could be more intuitive:
{
"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,
"variation" : [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([15.0, 22.5], dtype=np.float32), high=np.array([23.0, 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]
}
}
With this JSON configuration for the building 5ZoneAutoDXVAV.epJSON, we will have the next environment 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 variation, the discrete and stochastic versions will not appear in the list.
Warning
For Discrete environments, it must be defined an action mapping in constants.py with the name DEFAULT_<id_base in upper case>_DISCRETE_FUNCTION to register correctly.
6.1. Weather Specification field
Weather specification is configured to generate several environments depending on the weathers defined. Weather files must be in the correct folder and the keys are used in order to define the final name in environment’s ID’s.
6.2. Variables field
variables field have a specific format in order to define all the variables observed in the environment faster. The variable names and keys
can be an individual str or a list of str. The next graph explain how its functionality is:
Sinergym will parse this information to variables parameter to env constructor (same that EnergyPlus Python API) in the registration.
The same is done with meters and actuators fields, but they are simpler.