Environments configuration and registration
New Sinergym environments can be created using the constructor of the EplusEnv class and the parameters listed in section Available parameters.
Since multiple environments can be generated from the same building, Sinergym provides an automated way for creating and registering them. Using a JSON file located in sinergym/data/default_configuration, a predefined set of parameters for each possible configuration will be applied to generate the environments. Each environment will be assigned a unique ID and automatically registered in Gymnasium.
This section outlines the structure of these JSON configuration files. Moreover, this structure allows for the definition of observation variables (time_variables, variables and meters) and action variables (actuators). Instead of manually specifying these in the EnergyPlus Python API format as part of the environment constructor, Sinergym will read this simplified structure and automatically convert it into the appropriate EnergyPlus Python API format.
Key |
Optional |
Description |
|---|---|---|
id_base |
No |
Building base name / ID model. |
building_file |
No |
Building model file located in |
weather_specification |
No |
Set of weather files used to generate different environments. Located in |
config_params |
Yes |
Extra environments parameters (optional). |
weather_variability |
Yes |
Indicates if additional versions of all environments adding episodic weather noise will be created. |
max_ep_data_store_num |
Yes |
Maximum number of episodes for which data will be stored. Default: 10. |
time_variables |
No |
|
variables |
No |
|
meters |
No |
|
actuators |
No |
|
action_space |
No |
Gymnasium action space definition. |
action_space_discrete |
Yes |
Allows the creation of discrete action-space versions of the environments. |
only_discrete |
Yes |
Used in composite action space problems where continuous values must be discretized. If an action space and a discrete space based on it have been defined (required; see DiscretizeEnv), you can only register the discrete version using this flag. |
reward |
No |
Reward class name. |
reward_kwargs |
No |
Reward kwargs for the Reward class constructor. |
Important
Sinergym uses continuous action spaces by default, rather than discrete ones. If needed, environments are discretized afterwards using a wrapper. For additional details, refer to DiscretizeEnv.
Having presented the available parameters, the following is a JSON example of how to use them:
{
"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
}
}
Based on this JSON configuration for the building 5ZoneAutoDXVAV.epJSON, the following
environments will be automatically created:
[
'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'
]
Note how the weather specification enables the creation of multiple environments based on different weather files. These files must be located in the appropriate folder, and their keys are used to construct the environment IDs.
For example, if the discrete space or weather variability are not defined, the discrete and stochastic versions of the environment will not be created.
Warning
For discrete environments, an action mapping must be defined in
constants.py
named as DEFAULT_<upper case id_base>_DISCRETE_FUNCTION.
Variables specification
The variables field follows a specific format to efficiently define all observed variables in the environment. Variable names and keys can be provided as either individual strings or lists of strings. The functionality is illustrated in the following graph:
During registration, Sinergym parses the information introduced in the variables parameter to the environment constructor, previously adapting it to the format used by the EnergyPlus Python API. A similar process is followed with the meters and actuators fields.