Buildings.ThermalZones.EnergyPlus.UsersGuide

EnergyPlus package user's guide

Information

Spawn logo

This user guide describes how to use the EnergyPlus building envelope model and exchange data during simulation between Modelica and EnergyPlus. This allows to simulate HVAC and control systems in Modelica, coupled to the EnergyPlus envelope model. The implementation is such that the joint simulation between Modelica and EnergyPlus is automatically setup, without the user having to configure a co-simulation setup. During the simulation, different data can be exchanged between Modelica and EnergyPlus.

Spawn coupling

The figure above shows an overview of the exchanged coupling variables. The coupling variables can connect Modelica thermal zone model with EnergyPlus envelope model, or Modelica heat transfer models to EnergyPlus surfaces, for example to model a radiant floor. They also allow reading the value of EnergyPlus output variables for use in Modelica-implemented controllers, and writing to EnergyPlus schedules and EnergyPlus Energy Management System actuators. This can be used, for instance, to send supervisory control signals to EnergyPlus, such as for active facade control, or to control lights and equipment schedules that contribute to heat gains in the room and its surfaces.

Currently Windows 64 bit and Linux 64 bit are supported.

References

Michael Wetter, Kyle Benne, Antoine Gautier, Thierry S. Nouidui, Agnes Ramle, Amir Roth, Hubertus Tummescheit, Stuart Mentzer and Christian Winther.
Lifting the Garage Door on Spawn, an Open-Source BEM-Controls Engine.
Proc. of Building Performance Modeling Conference and SimBuild, p. 518--525, Chicago, IL, USA, September 2020.

Extends from Modelica.Icons.Information (Icon for general information packages).

Package Content

Name	Description
GettingStarted	Getting started
Conventions	Conventions
UnitConversion	Unit Conversion
EnergyPlusWarmUp	EnergyPlus warm-up
KnownIssues	Known issues
NotesForDymola	Notes for Dymola

Buildings.ThermalZones.EnergyPlus.UsersGuide.GettingStarted

Getting started

Information

How to instantiate models for one or several buildings

To instantiate one or several building models, proceed as follows:

Create an instance of Buildings.ThermalZones.EnergyPlus.Building to specify the building model. This instance is automatically named building and this name must not be changed.
In the instance building, specify building-level parameters such as the EnergyPlus input file name and weather file name.
For the weather file, both .mos and .epw files must be provided in the same directory. The files must have the same name, except for the different extension. The .epw file will be used by the EnergyPlus envelope model, and the .mos file will be used by the Modelica model, and must be specified by the parameter weaName in the instance building.

The following coupling objects can then be integrated in the model that contains the instance building, or in any model instantiated by that model.

To connect Modelica zone models with the equivalent EnergyPlus zone envelopes, instantiate any number of Buildings.ThermalZones.EnergyPlus.ThermalZone models and parameterize them with the name of the thermal zones as they are entered in the EnergyPlus input data file. Each model should also be assigned the medium of heat transfer (typically air), as is done for any other fluid flow component.
To write to EnergyPlus actuators or schedules during the simulation, instantiate any number of Buildings.ThermalZones.EnergyPlus.Actuator or Buildings.ThermalZones.EnergyPlus.Schedule models.
To retrieve the current values of output variables from EnergyPlus, instantiate any number of Buildings.ThermalZones.EnergyPlus.OutputVariable models.
To model an opaque construction such as a radiant slab in Modelica and interface it to EnergyPlus, instantiate any number of Buildings.ThermalZones.EnergyPlus.OpaqueConstruction models.
To set individual surface temperatures in EnergyPlus and retrieve their room-side heat gains, instantiate any number of Buildings.ThermalZones.EnergyPlus.ZoneSurface models.

If you have more than one building, you can repeat the above steps for each building and combine these building models in a top-level model. See for example Buildings.ThermalZones.EnergyPlus.Validation.MultipleBuildings.ThreeZonesTwoBuildings for how to combine two buildings in one Modelica model.

For details of how to configure these models, see the information section of these models, and look at the example models below.

Example models

To get started, we recommend to look at the simple examples in Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse which illustrate the use of all these objects based on a single family house. Also, read the information section of the models you plan to use in Buildings.ThermalZones.EnergyPlus.

We suggest looking at the examples in the following order which starts with the simplest example and moves to more comprehensive ones.

Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.Unconditioned is modeling one zone, the living room, in Modelica as an unconditioned zone with a fixed amount of outside air infiltration.
Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.AirHeating adds an air-based heating system that recirculates air to track a heating setpoint temperature.
Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.EquipmentSchedule shows how to set the equipment schedule in Modelica and override the schedule in EnergyPlus. It also uses the unconditioned thermal zone to keep it simple.
Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.LightsControl is showing how to set the value of an EMS Actuator, here the one that sets internal gains caused by the lights which are controlled by Modelica based on time of day and sun position. The model also shows how to read an EnergyPlus output variable, here for the lighting electricity consumption.
Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.ShadeControl reads from EnergyPlus the incident solar radiation, retrieves from the thermal zone its temperature, and based on these values, actuates the window shading control using an EMS actuator.
Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingWithGroundHeatTransfer illustrates how to couple a radiant slab for heating in a configuration in which the bottom of the slab is connected to a ground heat transfer model in Modelica.
Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingCooling is similar to the previous model, but it adds a radiant slab for cooling which interfaces two surfaces in EnergyPlus: The floor that connects the slab to the zone above, and the ceiling that connects the slab to the zone below.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica definition

class GettingStarted "Getting started" extends Modelica.Icons.Information; end GettingStarted;

Buildings.ThermalZones.EnergyPlus.UsersGuide.Conventions

Conventions

Information

Conventions

The following conventions are made:

If a zone is in the idf file but not modeled in Modelica, then
- EnergyPlus will simulate the zone as free floating, and
- EnergyPlus will simulate the outside air infiltration if specified in the idf file.
This allows unconditioned zones such as a basement or an attic to simulate in EnergyPlus without having to use an instance of Buildings.ThermalZones.EnergyPlus.ThermalZone.
If a zone is in the idf file and modeled in Modelica using Buildings.ThermalZones.EnergyPlus.ThermalZone, then EnergyPlus will remove all infiltration objects for this zone. This is done because Modelica computes the mass balance of the zone air, and infiltration depends on the static pressure of the HVAC system. Pressure-driven infiltration can be modeled using Buildings.Airflow.Multizone, or a fixed infiltration rate can be imposed as is shown in Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.AirHeating.
All EnergyPlus HVAC objects that are present in the idf file are removed when coupled to Spawn.
Output variables and EMS actuators need not be present in the idf file.
For the EnergyPlus envelope, either the CTF transfer function or the finite difference method can be used.
The coupling time step is determined by EnergyPlus based on the zone time step, as declared in the idf file.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica definition

class Conventions "Conventions" extends Modelica.Icons.Information; end Conventions;

Buildings.ThermalZones.EnergyPlus.UsersGuide.UnitConversion

Unit Conversion

Information

Unit conversion

Units between Modelica and EnergyPlus are automatically converted, if they are specified. The conversion is according to the table at Buildings.ThermalZones.EnergyPlus.Types.Units.

To see what units are used, set printUnits=true (the default) in the instance Buildings.ThermalZones.EnergyPlus.Building. This will cause the used units to be reported in the Modelica log file.

The thermal zone model automatically converts the units.

To do unit conversion for values sent by Buildings.ThermalZones.EnergyPlus.Actuator and by Buildings.ThermalZones.EnergyPlus.Schedule, set the parameter unit to the unit of the variable obtained at the input connector u. The value will then be converted before it is sent to EnergyPlus. The units that are used in the input u of this block are reported to the Modelica log file.

To do unit conversion for values read by Buildings.ThermalZones.EnergyPlus.OutputVariable, Modelica will use the units reported by EnergyPlus. The units that are used in the output y of this block are reported to the Modelica log file.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica definition

class UnitConversion "Unit Conversion" extends Modelica.Icons.Information; end UnitConversion;

Buildings.ThermalZones.EnergyPlus.UsersGuide.EnergyPlusWarmUp

EnergyPlus warm-up

Information

EnergyPlus warm-up

In Spawn there can be both connected and unconnected zones defined in the EnergyPlus input file. Connected zones have a corresponding zone model Buildings.ThermalZones.EnergyPlus.ThermalZone in Modelica that communicates with the EnergyPlus zone heat balance model. Unconnected zones are thermal zones which are defined entirely within the EnergyPlus input file, and for these zones the conventional EnergyPlus algorithms are used to simulate the zone conditions, including the air temperature and humidity, which are free floating. In contrast, for connected zones, Modelica models the temperature and humidity. During the initialization of a new simulation it is necessary to compute initial values for the zone air conditions as well as the conditions of any thermal mass, such as for walls, floors and ceilings. Conventionally, EnergyPlus handles this requirement using a warmup period, and in Spawn the traditional EnergyPlus warmup algorithm is employed to initialize unconnected zones. The EnergyPlus warmup algorithm is described in the EnergyPlus Engineering Reference, and summarized in the following steps.

Zone and wall surface temperatures are initialized to 23°C.
Zone humidity ratios are initialized to the outdoor conditions.
During warmup, the outdoor conditions are determined by the EnergyPlus weather file.
The first day of the simulation is repeated until warmup convergence, which occurs when the minimum and maximum air temperatures during the warmup day remain nearly the same between two successive iterations.

Spawn initializes unconnected zones using the warmup algorithm that was just described. However, connected zones are treated differently than in a conventional EnergyPlus simulation because initial zone air properties are specified in the Modelica zone model. During Spawn warmup, the following steps occur:

All wall surface temperatures are initialized to 23°C just as they are in a conventional EnergyPlus warmup period. However, as in EnergyPlus, during the warmup iterations, the exterior walls will be subject to the ambient conditions defined by the weather file. Therefore, exterior surface temperatures will not remain fixed at their 23°C initial condition during the warmup process. Similarly, room-facing wall surfaces will be exposed to the zone temperature, and therefore approach a quasi-steady state at the conclusion of warmup.
The air temperatures of unconnected zones are initialized to 23°C.
The humidity ratios of unconnected zones are initialized to the outdoor conditions.
The air temperatures and humidity ratios of connected zones are initialized to the initial values defined in Modelica, and held fixed during the warmup period.
During warmup, the outdoor conditions are determined by the EnergyPlus weather file in the same way as a conventional EnergyPlus simulation.
The first day of the simulation is repeated until the minimum and maximum air temperatures during the warmup day remain nearly the same between two successive iterations.

The Spawn warmup procedure is still invoked even if there are no unconnected zones defined in the model. However, in this case the warmup convergence criteria will be met after only two iterations of the warmup day because all zone temperature and humidity values are fixed to the initial values defined in Modelica. It is possible for startup transients to still exist after Spawn warmup due thermal mass in the wall materials not being fully exposed to the surface boundary conditions defined by the outdoor environment and the initial zone air conditions. A future enhancement may define a new warmup convergence criteria that takes into account the internal wall temperatures.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica definition

class EnergyPlusWarmUp "EnergyPlus warm-up" extends Modelica.Icons.Information; end EnergyPlusWarmUp;

Buildings.ThermalZones.EnergyPlus.UsersGuide.KnownIssues

Known issues

Information

Known issues

EnergyPlus warnings

EnergyPlus may issue a warning such as

Calculated Relative Humidity out of range (PsyRhFnTdbWPb)

Such warnings can be ignored. The humidity balance of EnergyPlus is not used because Modelica computes the humidity balance.
This will be addressed through issue 2220.

Signals to time schedules and actuators

If Modelica overrides a time schedule or an actuator at a time instant that does not coincide with an EnergyPlus time step, the change in value may be ignored for the heat balance of the current EnergyPlus time step.
This will be addressed through issue 2000.

Simulation must not start at a negative time

If a simulation starts at a time smaller than 0, then an error will be issued and the simulation won't start.
This will be addressed through issue 1938.

FMUs generated with a Spawn model may still require a Buildings library installation

If an FMU is generated that contains a Spawn model and then simulated on another computer, the simulation may fail to start because of depedencies to the Buildings library and the Spawn binaries. .
This will be addressed through issue 2054.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica definition

class KnownIssues "Known issues" extends Modelica.Icons.Information; end KnownIssues;

Buildings.ThermalZones.EnergyPlus.UsersGuide.NotesForDymola

Notes for Dymola

Information

Notes for Dymola

64 bit configuration

Make sure Dymola compiles in 64 bit, which can be done by setting the flag

Advanced.CompileWith64 = 2

Otherwise, you may get an error such as

/usr/bin/ld: cannot find -lfmilib_shared
collect2: error: ld returned 1 exit status

Models with multiple thermal zones

For Dymola 2019FD01 and Dymola 2020, only one thermal zone can be in EnergyPlus. For Dymola 2020x, this limitation is removed if the flag

Hidden.AvoidDoubleComputation=true

is set in the Dymola command line window. For Dymola 2021, this flag will be set to true by default.

This limitation only affects Dymola. OPTIMICA and JModelica can simulate Modelica models for which the EnergyPlus model has multiple thermal zones, or for which multiple buildings are simulated in EnergyPlus.

Extends from Modelica.Icons.Information (Icon for general information packages).

Modelica definition

class NotesForDymola "Notes for Dymola" extends Modelica.Icons.Information; end NotesForDymola;