5. Environments

As mentioned in introduction, Sinergym follows the next structure:

Sinergym is composed of three main components: agent, communication interface and simulation. The agent sends actions and receives observations from the environment through the Gymnasium interface. At the same time, the gym interface communicates with the simulator engine via EnergyPlus Python API, which provide the functionality to manage handlers such as actuators, meters and variables, so their current values have a direct influence on the course of the simulation.

The next image shows this process more detailed:

The Modeling module works at the same level as the API and allows to adapt the building models before the start of each episode. This allows that the API can work correctly with the user’s definitions in the environment.

This scheme is very abstract, since these components do some additional tasks such as handling the folder structure of the output, preparing the handlers before using them, initiating callbacks for data collection during simulation, and much more.

5.1. Additional observation information

In addition to the observations returned in the step and reset methods as you can see in the images above, both return a Python dictionary with additional information:

• Reset info: This dictionary has the next keys:

info = {
          'time_elapsed(hours)': # <Simulation time elapsed in hours>,
          'month': # <Month in which the episode starts.>,
          'day': # <Day in which the episode starts.>,
          'hour': # <Hour in which the episode starts.>,
          'is_raining': # <True if it is raining in the simulation.>,
          'timestep': # <Timesteps count.>,
      }

• step info: This dictionary has the same keys than reset info, but it is added the action sent (action sent to the simulation, not the action sent to the environment), the reward and reward terms. The reward terms depend on the reward function used.

5.2. Environments List

The list of available environments is the following:

Env. name	epJSON file	EPW file	Weather variability	Action space	Simulation period
Eplus-demo-v1	5ZoneAutoDXVAV.epJSON	USA_PA_Pittsburgh-Allegheny.County.AP.725205_TMY3.epw	No	Discrete(10)	01/01 - 31/03
Eplus-5zone-hot-discrete-v1	5ZoneAutoDXVAV.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-5zone-mixed-discrete-v1	5ZoneAutoDXVAV.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-5zone-cool-discrete-v1	5ZoneAutoDXVAV.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-5zone-hot-continuous-v1	5ZoneAutoDXVAV.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-5zone-mixed-continuous-v1	5ZoneAutoDXVAV.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-5zone-cool-continuous-v1	5ZoneAutoDXVAV.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-5zone-hot-discrete-stochastic-v1	5ZoneAutoDXVAV.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-5zone-mixed-discrete-stochastic-v1	5ZoneAutoDXVAV.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-5zone-cool-discrete-stochastic-v1	5ZoneAutoDXVAV.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-5zone-hot-continuous-stochastic-v1	5ZoneAutoDXVAV.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-5zone-mixed-continuous-stochastic-v1	5ZoneAutoDXVAV.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-5zone-cool-continuous-stochastic-v1	5ZoneAutoDXVAV.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-datacenter-hot-discrete-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-datacenter-hot-continuous-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Box(4)	01/01 - 31/12
Eplus-datacenter-hot-discrete-stochastic-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-datacenter-hot-continuous-stochastic-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Box(4)	01/01 - 31/12
Eplus-datacenter-mixed-discrete-stochastic-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-datacenter-mixed-continuous-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Box(4)	01/01 - 31/12
Eplus-datacenter-mixed-discrete-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-datacenter-mixed-continuous-stochastic-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Box(4)	01/01 - 31/12
Eplus-datacenter-cool-discrete-stochastic-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-datacenter-cool-continuous-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Box(4)	01/01 - 31/12
Eplus-datacenter-cool-discrete-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-datacenter-cool-continuous-stochastic-v1	2ZoneDataCenterHVAC_wEconomizer.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Box(4)	01/01 - 31/12
Eplus-warehouse-hot-discrete-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-warehouse-hot-continuous-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Box(5)	01/01 - 31/12
Eplus-warehouse-hot-discrete-stochastic-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-warehouse-hot-continuous-stochastic-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Box(5)	01/01 - 31/12
Eplus-warehouse-mixed-discrete-stochastic-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-warehouse-mixed-continuous-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Box(5)	01/01 - 31/12
Eplus-warehouse-mixed-discrete-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-warehouse-mixed-continuous-stochastic-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Box(5)	01/01 - 31/12
Eplus-warehouse-cool-discrete-stochastic-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-warehouse-cool-continuous-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Box(5)	01/01 - 31/12
Eplus-warehouse-cool-discrete-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-warehouse-cool-continuous-stochastic-v1	ASHRAE9012016_Warehouse_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Box(5)	01/01 - 31/12
Eplus-office-hot-discrete-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-office-hot-continuous-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-office-hot-discrete-stochastic-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-office-hot-continuous-stochastic-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-office-mixed-discrete-stochastic-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-office-mixed-continuous-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-office-mixed-discrete-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-office-mixed-continuous-stochastic-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-office-cool-discrete-stochastic-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-office-cool-continuous-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-office-cool-discrete-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-office-cool-continuous-stochastic-v1	ASHRAE9012016_OfficeMedium_Denver.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-officegrid-cool-continuous-v1	OfficeGridStorageSmoothing.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Box(4)	01/01 - 31/12
Eplus-officegrid-mixed-continuous-v1	OfficeGridStorageSmoothing.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Box(4)	01/01 - 31/12
Eplus-officegrid-hot-continuous-v1	OfficeGridStorageSmoothing.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Box(4)	01/01 - 31/12
Eplus-officegrid-cool-continuous-stochastic-v1	OfficeGridStorageSmoothing.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Box(4)	01/01 - 31/12
Eplus-officegrid-mixed-continuous-stochastic-v1	OfficeGridStorageSmoothing.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Box(4)	01/01 - 31/12
Eplus-officegrid-hot-continuous-stochastic-v1	OfficeGridStorageSmoothing.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Box(4)	01/01 - 31/12
Eplus-officegrid-cool-discrete-v1	OfficeGridStorageSmoothing.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-officegrid-mixed-discrete-v1	OfficeGridStorageSmoothing.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-officegrid-hot-discrete-v1	OfficeGridStorageSmoothing.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-officegrid-cool-discrete-stochastic-v1	OfficeGridStorageSmoothing.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-officegrid-mixed-discrete-stochastic-v1	OfficeGridStorageSmoothing.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-officegrid-hot-discrete-stochastic-v1	OfficeGridStorageSmoothing.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-shop-cool-continuous-v1	ShopWithVandBattery.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-shop-mixed-continuous-v1	ShopWithVandBattery.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-shop-hot-continuous-v1	ShopWithVandBattery.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Box(2)	01/01 - 31/12
Eplus-shop-cool-continuous-stochastic-v1	ShopWithVandBattery.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-shop-mixed-continuous-stochastic-v1	ShopWithVandBattery.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-shop-hot-continuous-stochastic-v1	ShopWithVandBattery.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Box(2)	01/01 - 31/12
Eplus-shop-cool-discrete-v1	ShopWithVandBattery.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-shop-mixed-discrete-v1	ShopWithVandBattery.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-shop-hot-discrete-v1	ShopWithVandBattery.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	Discrete(10)	01/01 - 31/12
Eplus-shop-cool-discrete-stochastic-v1	ShopWithVandBattery.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-shop-mixed-discrete-stochastic-v1	ShopWithVandBattery.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-shop-hot-discrete-stochastic-v1	ShopWithVandBattery.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	Discrete(10)	01/01 - 31/12
Eplus-autobalance-cool-discrete-v1	autobalanceStorageSmoothing.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	No	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-mixed-discrete-v1	autobalanceStorageSmoothing.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	No	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-hot-discrete-v1	autobalanceStorageSmoothing.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	No	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-stockholm-discrete-v1	autobalanceStorageSmoothing.epJSON	SWE_Stockholm.Arlanda.024600_IWEC.epw	No	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-cool-discrete-stochastic-v1	autobalanceStorageSmoothing.epJSON	USA_WA_Port.Angeles-William.R.Fairchild.Intl.AP.727885_TMY3.epw	Yes	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-mixed-discrete-stochastic-v1	autobalanceStorageSmoothing.epJSON	USA_NY_New.York-J.F.Kennedy.Intl.AP.744860_TMY3.epw	Yes	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-hot-discrete-stochastic-v1	autobalanceStorageSmoothing.epJSON	USA_AZ_Davis-Monthan.AFB.722745_TMY3.epw	Yes	MultiDiscrete(5)	01/10 - 30/04 (next year)
Eplus-autobalance-stockholm-discrete-stochastic-v1	autobalanceStorageSmoothing.epJSON	SWE_Stockholm.Arlanda.024600_IWEC.epw	Yes	MultiDiscrete(5)	01/10 - 30/04 (next year)

Important

Since Sinergym v3.0.9, these environments are generated automatically using JSON configuration files for each building instead of register manually each environment id with parameters directly set in environment constructor. See Environments Configuration and Registration.

Warning

Discrete environments can be customized. In fact, the default control of discrete environments is very simple. You can use a continuous environment and custom discretization using our dedicated wrapper directly, for more information see DiscretizeEnv.

Note

For more information about buildings (epJSON column) and weathers (EPW column), please, visit sections Buildings and Weathers respectively.

5.3. Available Parameters

With the environment constructor we can configure the complete context of our environment for experimentation, either starting from one predefined by Sinergym shown in the table above or creating a new one.

Sinergym initially provides non-configured buildings and weathers. Depending of these argument values, these files are updated in order to adapt it to this new features, this will be made by Sinergym automatically. For example, using another weather file requires building location and design days update, using new observation variables requires to update the Output:Variable and Output:Meter fields, the same occurs with extra configuration context concerned with simulation directly, if weather variability is set, then a weather with noise will be used. These new building and weather file versions, is saved in the Sinergym output folder, leaving the original intact.

The next subsections will show which parameters are available and what their function are:

5.3.1. building file

The parameter building_file is the epJSON file, a new adaptation of IDF (Intermediate Data Format) where EnergyPlus building model is defined. These files are not configured for a particular environment as we have mentioned. Sinergym does a previous building model preparation to the simulation, see the Modeling element in Sinergym backend diagram.

5.3.2. Weather files

The parameter weather_file is the EPW (EnergyPlus Weather) file name where climate conditions during a year is defined.

This parameter can be either a weather file name (str) as mentioned, or a list of different weather files (List[str]). When a list of several files is defined, Sinergym will select an EPW file in each episode and re-adapt building model randomly. This is done in order to increase the complexity in the environment whether is desired.

The weather file used in each episode is stored in Sinergym episode output folder, if variability (section Weather Variability is defined), the EPW stored will have that noise included.

5.3.3. Weather Variability

Weather variability can be integrated into an environment using weather_variability parameter.

It implements the Ornstein-Uhlenbeck process in order to introduce noise to the weather data episode to episode. Then, parameter established is a Python tuple of three variables (sigma, mu and tau) whose values define the nature of that noise.

5.3.4. Reward

The parameter called reward is used to define the reward class (see section Rewards) that the environment is going to use to calculate and return reward values each timestep.

5.3.5. Reward Kwargs

Depending on the reward class that is specified to the environment, it may have different arguments depending on its type. In addition, if a user creates a new custom reward, it can have new parameters as well.

Moreover, depending on the building being used for the environment, the values of these reward parameters may need to be different, such as the comfort range or the energy and temperature variables of the simulation that will be used to calculate the reward.

Then, the parameter called reward_kwargs is a Python dictionary where we can specify all reward class arguments that they are needed. For more information about rewards, visit section Rewards.

5.3.6. Maximum Episode Data Stored in Sinergym Output

Sinergym stores all the output of an experiment in a folder organized in sub-folders for each episode (see section Output format for more information). Depending on the value of the parameter max_ep_data_store_num, the experiment will store the output data of the last n episodes set, where n is the value of the parameter.

In any case, if Sinergym Logger (See Logger section) is activate, progress.csv will be present with the summary data of each episode.

5.3.7. Time variables

EnergyPlus Python API has several methods in order to extract information about simulation time in progress. The argument time_variables is a list in which we can specify the name of the API methods whose values we want to include in our observation.

By default, Sinergym environments will have the time variables month, day_of_month and hour.

5.3.8. Variables

The argument called variables is a dictionary in which it is specified the Output:Variable’s we want to include in the environment observation. The format of each element, in order to Sinergym can process it, is the next:

variables = {
  # <custom_variable_name> : (<"Output:Variable" original name>,<variable_key>),
  # ...
}

Note

For more information about the available variables in an environment, execute a default simulation with EnergyPlus engine and see RDD file generated in the output.

5.3.9. Meters

In a similar way, the argument meters is a dictionary in which we can specify the Output:Meter’s we want to include in the environment observation. The format of each element must be the next:

meters = {
  # <custom_meter_name> : <"Output:Meter" original name>,
  # ...
}

Note

For more information about the available meters in an environment, execute a default simulation with EnergyPlus engine and see MDD and MTD files generated in the output.

5.3.10. Actuators

The argument called actuators is a dictionary in which we specify the actuators we want to control with gymnasium interface, the format must be the next:

actuators = {
  # <custom_actuator_name> : (<actuator_type>,<actuator_value>,<actuator_original_name>),
  # ...
}

Important

Actuators that have not been specified will be controlled by the building’s default schedulers.

Note

For more information about the available actuators in an environment, execute a default control with Sinergym directly (empty action space) and see data_available.txt generated.

5.3.11. Action space

As you have been able to observe, by defining the previous arguments, a definition of the observation and action space of the environment is being made. time_variables, variables and meters make up our environment observation, while the actuators alone make up the environment action:

This allows us to do a dynamic definition of spaces, Sinergym will adapt the building model. Observation space is created automatically, but action space must be defined in order to set up the range values supported by the Gymnasium interface in the actuators, or the number of discrete values if it is a discrete environment (using the wrapper for discretization).

Then, the argument called action_space defines this action space following the gymnasium standard. EnergyPlus simulator works only with continuous values, so Sinergym action space defined must be continuous too (gym.spaces.Box). This definition must be consistent with the previously defined actuators (Sinergym will show possible inconsistencies).

Note

If you want to adapt a environment to a gym Discrete, MultiDiscrete or MultiBinary spaces, like our predefined discrete environments, see section DiscretizeEnv and an example in Environment Discretization Wrapper

Important

Sinergym’s listed environments have a default observation and action variables defined, all information is available in default_configuration. However, the users can experiment with this spaces, see Changing observation and action spaces.

Sinergym offers the possibility to create empty action interfaces too, so that you can take advantage of all its benefits instead of using the EnergyPlus simulator directly, meanwhile the control is managed by default building model schedulers as mentioned. For more information, see the example of use Default building control setting up an empty action interface.

5.3.12. Environment name

The parameter env_name is used to define the name of working directory generation. It is very useful to difference several experiments in the same environment, for example.

5.3.13. Extra configuration

Some parameters directly associated with the building model and simulator can be set as extra configuration as well, such as people occupant, timesteps per simulation hour, runperiod, etc.

Like this extra configuration context can grow up in the future, this is specified in config_params argument. It is a Python Dictionary where this values are specified. For more information about extra configuration available for Sinergym visit section Extra Configuration in Sinergym simulations.

5.4. Adding new weathers for environments

Sinergym includes several weathers covering different types of climate in different areas of the world. The aim is to provide the greatest possible diversity for the experiments taking into account certain characteristics.

However, you may need or want to include a new weather for an experiment. Therefore, this section is dedicated to give an explanation of how to do it:

1. Download EPW file and DDY file in EnergyPlus page. DDY file contains information about the location and different design days available for that weather.

2. Both files (EPW and DDY) must have exactly the same name, being the extension the only difference. They should be placed in the weathers folder.

That is all! Sinergym should be able to adapt SizingPeriod:DesignDays and Site:Location fields in building model file using DDY automatically for that weather.

5.5. Adding new buildings for environments

As we have already mentioned, a user can change the already available environments or even create new environment definitions including new climates, action and observation spaces, etc. However, perhaps you want to use a new building model (epJSON file) than the ones we support.

This section is intended to provide information if someone decides to add new buildings for use with Sinergym. The main steps you have to follow are the next:

1. Add your building file (epJSON) to buildings. EnergyPlus pretends to work with JSON format instead of IDF format in their building definitions and simulations. Then, Sinergym pretends to work with this format from v2.4.0 or higher directly. You can download a IDF file and convert to epJSON using their ConvertInputFormat tool from EnergyPlus. Be sure that new epJSON model version is compatible with EnergyPlus version.

2. Add your own EPW file for weather conditions (section Adding new weathers for environments) or use ours in environment constructor.

3. Sinergym will check that observation and action variables specified in environments constructor are available in the simulation before starting. You need to ensure that the variables definition are correct.

4. Use the environment constructor or register your own environment ID here following the same structure than the demo environment. You will have to specify environment components. We have examples about how to get environment information in Getting information about Sinergym environments.

5. Now, you can use your own environment ID with gym.make() like our documentation examples.

Once the first step has been performed, it is also possible to register a set of environments automatically in Sinergym by writing its corresponding configuration file in sinergym/data/default_configuration/<configuration_JSON_file>. For more information on this, see Environments Configuration and Registration.

Important

In order to know the available variables, meters, actuators, etc. You can try to do an empty control in the building and look for files such as RDD, MDD, MTD or data_available.txt file generated with EnergyPlus API in the output folder by Sinergym.