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 YAML 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 YAML 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 sinergym/data/buildings/.
weather_specification	No	Set of weather files used to generate different environments. Located in sinergym/data/weather/.
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	time_variables list definition.
variables	No	variables dict definition.
meters	No	meters dict definition.
actuators	No	actuators dict definition.
context	No	context dict definition.
initial_context	Yes	Initial values for specified context dict. If not specified, it is initialized with the default values provided by the building’s definition.
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 YAML example of how to use them:

# Documentation: https://ugr-sail.github.io/sinergym/compilation/main/pages/environments_registration.html
# ---------------------------------------------------------------------------- #
#                        ID BASE FROM ENVIRONMNET NAMES                        #
# ---------------------------------------------------------------------------- #
id_base: 5zone

# ---------------------------------------------------------------------------- #
#                         BUILDING AND WEATHER SETTINGS                        #
# ---------------------------------------------------------------------------- #
building_file: 5ZoneAutoDXVAV.epJSON

# A environment alternative for each weather key
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

# ---------------------------------------------------------------------------- #
#                         BUILDING EXTRA CONFIGURATION                         #
# ---------------------------------------------------------------------------- #
config_params: null


# ---------------------------------------------------------------------------- #
#                        WEATHER VARIABILITY (OPTIONAL)                        #
# ---------------------------------------------------------------------------- #
# Alternative stochastic environments if it is defined
weather_variability:
  Dry Bulb Temperature:
    - 1.0 # sigma
    - 0.0 # mu
    - 24.0 # tau

# ---------------------------------------------------------------------------- #
#                          EPISODES FOLDER GENERATION                          #
# ---------------------------------------------------------------------------- #
max_ep_data_store_num: 3

# ---------------------------------------------------------------------------- #
#                             OBSERVATION VARIABLES                            #
# ---------------------------------------------------------------------------- #

# --------------- TIME VARIABLES (same name as EnergyPlus API) --------------- #
time_variables:
  - month
  - day_of_month
  - hour
# More variables in Data Transfer API: https://energyplus.readthedocs.io/en/latest/datatransfer.html

# ----------------------------- OUTPUT:VARIABLES ----------------------------- #
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

# ------------------------------- OUTPUT:METERS ------------------------------ #
meters:
  Electricity:HVAC: total_electricity_HVAC

# ---------------------------------------------------------------------------- #
#                               ACTION VARIABLES                               #
# ---------------------------------------------------------------------------- #

# --------------------------- ACTUATORS TO CONTROL --------------------------- #
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

# ---------------------------------------------------------------------------- #
#                   DYNAMIC CONTEXT CONFIGURABLE IN REAL-TIME                  #
# ---------------------------------------------------------------------------- #
context: {}

# ---------------------------------------------------------------------------- #
#                                 ACTIONS SPACE                                #
# ---------------------------------------------------------------------------- #
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 FUNCTION                               #
# ---------------------------------------------------------------------------- #
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: 1.0e-4
  lambda_temperature: 1.0

Based on this YAML 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, actuators and context fields.