Buildings.ThermalZones.EnergyPlus

Package with models to connect to the EnergyPlus SOEP thermal zone model

Information

Package for Spawn of EnergyPlus that couples Modelica directly to the EnergyPlus envelope model.
The models in this package allow simulating the envelope heat transfer of one or several buildings in EnergyPlus, and simulating HVAC and controls in Modelica. EnergyPlus objects are represented graphically as any other Modelica models, and the coupling and co-simulation is done automatically based on these models.

Models are provided to connect to EnergyPlus thermal zones, actuators, output variables and schedules.

See Buildings.ThermalZones.EnergyPlus.UsersGuide for more information.

Extends from Modelica.Icons.Package (Icon for standard packages).

Package Content

Name	Description
UsersGuide	EnergyPlus package user's guide
Actuator	Block to write to an EnergyPlus actuator
Building	Model that declares a building to which EnergyPlus objects belong to
OpaqueConstruction	Model to exchange heat of an opaque construction with EnergyPlus
OutputVariable	Block to read an EnergyPlus output variable
Schedule	Block to write to an EnergyPlus schedule
ThermalZone	Model to connect to an EnergyPlus thermal zone
ZoneSurface	Model to exchange heat with a inside-facing surface of a thermal zone
Types	Package with type definitions
Examples	Collection of models that illustrate model use and test models
Validation	Collection of validation models
BaseClasses	Package with base classes for Buildings.ThermalZones.EnergyPlus

Buildings.ThermalZones.EnergyPlus.Actuator

Block to write to an EnergyPlus actuator

Information

Block that writes to an EMS actuator object in EnergyPlus.

This model writes at every EnergyPlus zone time step the value of the input u to an EnergyPlus EMS actuator with name variableName. For example, if EnergyPlus has 6 time steps per hour, as specified in the idf-file with the entry Timestep,6; and the input u to this block is

then EnergyPlus will receive the inputs

The parameter unit specifies the unit of the signal u. This unit is then converted internally to the units required by EnergyPlus before the value is sent to EnergyPlus. See Buildings.ThermalZones.EnergyPlus.Types.Units for the supported units. If the value of the parameter unit is left at its default value of Buildings.ThermalZones.EnergyPlus.Types.Units.unspecified, then the simulation will stop with an error.

Usage

This section explain how to use actuators for different EnergyPlus objects. For other actuators, please see the EnergyPlus EMS Application Guide.

Configuring an actuator for lights

Consider the example Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.LightsControl. In this example, Modelica overwrites the EnergyPlus Lights object. The idf-file has the following entry:

  Lights,
    LIVING ZONE Lights,      !- Name
    LIVING ZONE,             !- Zone or ZoneList Name
    HOUSE LIGHTING,          !- Schedule Name
    LightingLevel,           !- Design Level Calculation Method
    1000,                    !- Lighting Level {W}
    ,                        !- Watts per Zone Floor Area {W/m2}
    ,                        !- Watts per Person {W/person}
    0,                       !- Return Air Fraction
    0.2000000,               !- Fraction Radiant
    0.2000000,               !- Fraction Visible
    0,                       !- Fraction Replaceable
    GeneralLights;           !- End-Use Subcategory

and the EnergyPlus EMS Application Guide specifies An actuator called "Lights" is available with a control type called "Electric Power Level" (in W). This allows you to set the lighting power associated with each Lights input object. The unique identifier is the name of the Lights input object.

Therefore, the Lights object can be overwritten by specifying the Modelica instance

  Buildings.ThermalZones.EnergyPlus.Actuator actLig(
    variableName="LIVING ZONE Lights",
    componentType="Lights",
    controlType="Electric Power Level",
    unit=Buildings.ThermalZones.EnergyPlus.Types.Units.Power)
      "Actuator for lights";

and setting its input to the required power in Watts.

Configuring an actuator for a shade

Consider the example Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.ShadeControl. In this example, the idf-file has the following entry:

  EnergyManagementSystem:Actuator,
    Zn001_Wall001_Win001_Shading_Deploy_Status,  !- Name
    Zn001:Wall001:Win001,    !- Actuated Component Unique Name
    Window Shading Control,  !- Actuated Component Type
    Control Status;          !- Actuated Component Control Type

This causes EnergyPlus to overwrite the shade of the FenestrationSurface:Detailed with name Zn001:Wall001:Win001. According to the EnergyPlus EMS Application Guide, the EnergyPlus Control Status can be set to 0 to remove the shade, or to 6 to activate the interior blind.

Therefore, in Modelica, the instantiation

  Buildings.ThermalZones.EnergyPlus.Actuator actSha(
    variableName="Zn001:Wall001:Win001",
    componentType="Window Shading Control",
    controlType="Control Status",
    unit=Buildings.ThermalZones.EnergyPlus.Types.Units.Normalized)
      "Actuator for window shade"

will write to the Window Shading Control of the EnergyPlus object FenestrationSurface:Detailed with name Zn001:Wall001:Win001. The entry units=Buildings.ThermalZones.EnergyPlus.Types.Units.Normalized will cause the input value of the Modelica instance actSha to be sent to EnergyPlus without any unit conversion. Hence, in the example, the input actSha.u is set to 0 or 6.

Note that the entry EnergyManagementSystem:Actuator in the idf-file is optional. If specified, it will be ignored and the Modelica object be used instead.

Supported Actuators

The table below shows all EMS actuator objects supported by Spawn. Which of these are available for a particular model depends on the EnergyPlus idf-file. To list the EMS actuator objects that are available in your model, add the line

Output:EnergyManagementSystem,
  Verbose,                 !- Actuator Availability Dictionary Reporting
  Verbose,                 !- Internal Variable Availability Dictionary Reporting
  Verbose;                 !- EMS Runtime Language Debug Output Level

to the EnergyPlus idf-file. This will produce an EnergyPlus EMS data dictionary (*.edd) file that lists the actuators for this model. Those that are listed in the *.edd file and in the table below are supported.

In the table below, the name in the first column must be used as the value for the parameter componentType and the name of the second column must be used as the value for the parameter controlType.

Extends from Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject (Partial definitions of an EnergyPlus object), Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer (Block that synchronizes an object).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.Building

Model that declares a building to which EnergyPlus objects belong to

Information

Model that declares building-level specifications for Spawn of EnergyPlus.

This model is used to configure EnergyPlus. Each EnergyPlus idf file must have one instance of this model, and the instance name must be building. The instance must be placed in the model hierarchy at the same or at a higher level than the EnergyPlus objects that are related to the EnergyPlus idf file specified in this model through the parameter idfName.

For the parameter weaName, the name of the Modelica weather file must be provided. This is the file that can be read, for example, with Buildings.BoundaryConditions.WeatherData.ReaderTMY3. However, both weather files .mos and .epw must be provided in the same directory. When starting the simulation, EnergyPlus will be run with the weather file whose name is identical to weaName, but with the extension .mos replaced with .epw.

Extends from Modelica.Blocks.Icons.Block (Basic graphical layout of input/output block).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.OpaqueConstruction

Model to exchange heat of an opaque construction with EnergyPlus

Information

Model that interfaces with the EnergyPlus object BuildingSurface:Detailed. It sets in EnergyPlus the temperature of the front and back surface to the values obtained from Modelica through the heat ports of this model, and imposes the heat flow rate obtained from EnergyPlus at the heat ports of this model.

For the front surface, this heat flow rate consists of

• convective heat flow rate,
• absorbed solar radiation,
• absorbed infrared radiation minus emitted infrared radiation.

For the back-side surface, the above quanties, but now for the back-side of the construction, are also returned if the back-side faces another thermal zone or the outside. If the back-side surface is above ground, then the heat flow rate from the ground is returned.

Usage

This model allows for example coupling of a radiant slab that is modeled in Modelica to the EnergyPlus thermal zone model. Examples of such radiant systems include a floor slab with embedded pipes and a radiant cooling panel that is suspended from a ceiling. The model Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingCooling illustrates the use of this model for a floor and ceiling slab.

Note that if the ground heat transfer of the floor slab is modeled in Modelica, then the model Buildings.ThermalZones.EnergyPlus.ZoneSurface can be used, as shown for the floor slab in Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingWithGroundHeatTransfer.

By convention, if a surface cools the thermal zone, then heaPorFro.Q_flow < 0 for a front surface and heaPorBac.Q_flow < 0 for a back surface.

The variable qFro_flow is equal to qFro_flow = heaPorFor.Q_flow/A, where A is the area of the heat transfer surface as obtained from EnergyPlus. Similarly, use qBac_flow to check the back side heat flux.

Configuration for EnergyPlus

Consider an EnergyPlus input data file that has the following entry for the surface of an attic above a living room:

  BuildingSurface:Detailed,
    Attic:LivingFloor,       !- Name
    FLOOR,                   !- Surface Type
    reverseCEILING:LIVING,   !- Construction Name
    ATTIC ZONE,              !- Zone Name
    Surface,                 !- Outside Boundary Condition
    Living:Ceiling,          !- Outside Boundary Condition Object
    NoSun,                   !- Sun Exposure
    NoWind,                  !- Wind Exposure
    0.5000000,               !- View Factor to Ground
    4,                       !- Number of Vertices
    0,0,2.4384,  !- X,Y,Z ==> Vertex 1 {m}
    0,10.778,2.4384,  !- X,Y,Z ==> Vertex 2 {m}
    17.242,10.778,2.4384,  !- X,Y,Z ==> Vertex 3 {m}
    17.242,0,2.4384;  !- X,Y,Z ==> Vertex 4 {m}

If this construction is modeled with a radiant slab, that may have pipes embedded near the ceiling to cool the living room, then this model can be used as

Buildings.ThermalZones.EnergyPlus.OpaqueConstruction attFlo(surfaceName="Attic:LivingFloor")
    "Floor of the attic above the living room";

The heat port attFlo.heaPorFor can then be connected to the heat port of the upward facing surface of a radiant slab, and the heat port attFlo.heaPorBac can be connected to the downward facing surface of the radiant slab that cool the living room via the surface Living:Ceiling. This configuration is illustrated in the example Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingCooling.

Extends from Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject (Partial definitions of an EnergyPlus object), Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer (Block that synchronizes an object).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.OutputVariable

Block to read an EnergyPlus output variable

Information

Block that retrieves an output variable from EnergyPlus.

This model reads at every EnergyPlus zone time step the output variable specified by the parameters componentKey and variableName. These parameters are the values for the EnergyPlus variable key and name, which can be found in the EnergyPlus result dictionary file (.rdd file) or the EnergyPlus meter dictionary file (.mdd file).

The variable of the output y has Modelica SI units, as declared in Modelica.SIunits. For example, temperatures will be in Kelvin, and mass flow rates will be in kg/s.

The output signal y gets updated at each EnergyPlus time step.

Usage

To use an output variable, it is best to add in the EnergyPlus idf file the entry

Output:VariableDictionary, Regular;

and then simulate the model. This will create the file eplusout.rdd that contains all output variables. The file has lines such as

Zone,Average,Zone Electric Equipment Electricity Rate [W]
Zone,Average,Site Outdoor Air Drybulb Temperature [C]

Next, instantiate the output variable in Modelica. To obtain the value of Zone,Average,Zone Electric Equipment Electricity Rate [W] for the zone LIVING ZONE, the Modelica instantiation would be

Buildings.ThermalZones.EnergyPlus.OutputVariable equEle(
  name="Zone Electric Equipment Electricity Rate",
  key="LIVING ZONE")
  "Block that reads output from EnergyPlus";

To obtain the value of Site Outdoor Air Drybulb Temperature [C] from EnergyPlus, the Modelica instantiation would be

Buildings.ThermalZones.EnergyPlus.OutputVariable TOut(
  name="Site Outdoor Air Drybulb Temperature",
  key="Environment")
  "Block that reads output from EnergyPlus";

(Note that this variable could be read directly from the Modelica weather data bus, which can be accessed from Buildings.ThermalZones.EnergyPlus.Building.)

By default, the Modelica log file will display the unit in the form

Output OneZoneOneOutputVariable.equEle.y has in Modelica the unit W.

For this diagnostic message, Modelica knows that the unit is Watts because EnergyPlus wrote the unit for this output when it instantiated the model. (The output signal y of this block will not have a unit attribute set because it is not possible to automatically set the unit attribute of the output y based on the information that EnergyPlus provides.)

Direct dependency of output

Some output variables directly depend on input variables, i.e., if an input variable changes, the output changes immediately. Examples are the illuminance in a room that changes instantaneously when the window blind is changed, or the output variable Zone Electric Equipment Electricity Rate which changes instantaneously when a schedule value switches it on (see Buildings.ThermalZones.EnergyPlus.Validation.Schedule.EquipmentScheduleOutputVariable). For such variables, users should set isDirectDependent=true. Output variables that do not depend directly on an input variable include continuous time states such as the inside temperature of a wall and variables that only depend on time such as weather data. For these variables, users should leave isDirectDependent=false.

If a user sets isDirectDependent=true, then the model enables the input connector directDependency. Users then need to connect this input to the output(s) of these instance of Buildings.ThermalZones.EnergyPlus.Actuator or Buildings.ThermalZones.EnergyPlus.Schedule on which this output directly depends on. See for example Buildings.ThermalZones.EnergyPlus.Validation.Schedule.EquipmentScheduleOutputVariable. If the output depends on multiple inputs, just multiply these inputs and connect their product to the connector directDependency. What the value is is irrelevant, but a Modelica code generator will then understand that first the input needs to be sent to EnergyPlus before the output is requested.

Supported output variables

The table below shows all output variables supported by Spawn. Which of these are available for a particular model depends on the EnergyPlus idf-file. To list the output variables that are available in your model, add the line

Output:VariableDictionary, IDF;

to the EnergyPlus idf-file. This will produce an EnergyPlus result data dictionary (rdd) file.

In the table below, the name in the first column must be used as the value for the parameter name in instances of Buildings.ThermalZones.EnergyPlus.OutputVariable.

Extends from Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject (Partial definitions of an EnergyPlus object), Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer (Block that synchronizes an object).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.Schedule

Block to write to an EnergyPlus schedule

Information

Block that writes to a schedule object in EnergyPlus.

This model writes at every EnergyPlus zone time step the value of the input u to an EnergyPlus schedule with name name. For example, if EnergyPlus has 6 time steps per hour, as specified in the idf-file with the entry Timestep,6; and the input u to this block is

then EnergyPlus will receive the inputs

The parameter unit specifies the unit of the signal u. This unit is then converted internally to the units required by EnergyPlus before the value is sent to EnergyPlus. See Buildings.ThermalZones.EnergyPlus.Types.Units for the supported units. If the value of the parameter unit is left at its default value of Buildings.ThermalZones.EnergyPlus.Types.Units.unspecified, then the simulation will stop with an error.

Usage

To use an schedule, set up the schedule in the EnergyPlus idf file. For example, an entry may be

Schedule:Compact,
  INTERMITTENT,            !- Name
  Fraction,                !- Schedule Type Limits Name
  Through: 12/31,          !- Field 1
  For: WeekDays,           !- Field 2
  Until: 8:00,0.0,         !- Field 3
  Until: 18:00,1.00,       !- Field 5
  Until: 24:00,0.0,        !- Field 7
  For: AllOtherDays,       !- Field 9
  Until: 24:00,0.0;        !- Field 10

Next, instantiate the actuator in Modelica. For the above Schedule:Compact, the Modelica instantiation would be

  Buildings.ThermalZones.EnergyPlus.Schedule schInt(
    name = "INTERMITTENT",
    unit = Buildings.ThermalZones.EnergyPlus.Types.Units.Normalized)
    "Block that writes to the EnergyPlus schedule INTERMITTENT";

The entry units=Buildings.ThermalZones.EnergyPlus.Types.Units.Normalized will cause the value to be sent to EnergyPlus without any unit conversion.

Extends from Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject (Partial definitions of an EnergyPlus object), Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer (Block that synchronizes an object).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.ThermalZone

Model to connect to an EnergyPlus thermal zone

Information

Model for a thermal zone that is implemented in EnergyPlus.

This model instantiates the FMU with the name idfName and connects to the thermal zone with name zoneName. The idfName needs to be specified in an instance of Buildings.ThermalZones.EnergyPlus.Building that is named building, and that is placed at this or at a higher hierarchy-level of the model. If the FMU is already instantiated by another instance of this model, it will use the already instantiated FMU. Hence, for each thermal zone in an EnergyPlus FMU, one instance of this model needs to be used. See Buildings.ThermalZones.EnergyPlus.UsersGuide for how zones are simulated that are declared in the EnergyPlus input data file but not in Modelica.

If there are two instances that declare the same zoneName and have in the model hierarchy the same instance of Buildings.ThermalZones.EnergyPlus.Building, then the simulation will stop with an error.

Main Equations

This model computes in Modelica the air energy, mass and species balance. Outside air infiltration needs to be modeled in Modelica, because any infiltration that the EnergyPlus model may specify is ignored. The convective heat transfer with the building fabric, the long-wave and the short-wave radiation are computed by EnergyPlus.

Heat and mass balance

The zone uses a volume of air that is fully mixed. The size of this volume, and its floor area, which is used to scale the heat gains q_flow, are obtained from the EnergyPlus model.

Contaminant balance

The model has a parameter use_C_flow. If set to true, then an input connector C_flow is enabled, which allows adding trace substances to the room air. Note that this requires a medium model that has trace substances enabled.

Heat gains and CO2 added by people

If the EnergyPlus model computes internal heat gains such as from people or equipment, then their sensible convective and latent heat gains are automatically added to this room model, and the radiant fraction is added to the EnergyPlus envelope and thus treated correctly. In addition, if desired, radiant, convective and latent heat gains in units of W/m² can be added using the input connector qGai_flow.

Similarly, if people are modeled in EnergyPlus (using the EnergyPlus People object), and if the Modelica Medium contains CO2 (e.g., if Medium.nC > 0 and there is a Medium.substanceName = "CO2"), then the CO2 emitted by the people is automatically added to this volume. However, the "Generic Contaminant" modeled in EnergyPlus is not added to the air volume. (Because EnergyPlus does not declare the name of the species or its molar mass and hence it cannot be matched to species in Modelica or converted to emitted mass flow rate.)

Also, note that while CO2 emitted from people simulated in EnergyPlus is added automatically to the air balance of this model, there is no CO2 added automatically for the heat gain specified through the input connector qGai_flow. Hence, if qGai_flow accounts for people and CO2 should be modelled, then the CO2 emitted by the people specified in qGai_flow needs to be added manually to the input connector C_flow. (This manual addition is needed because qGai_flow can also contain heat gains not caused by people.)

Extends from Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject (Partial definitions of an EnergyPlus object).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.ZoneSurface

Model to exchange heat with a inside-facing surface of a thermal zone

Information

Block that sends for a room-side facing surface its temperature to EnergyPlus and receives the room-side heat flow rate from EnergyPlus.

This model writes at every EnergyPlus zone time step the value of the input T to an EnergyPlus surface object with name surfaceName, and produces at the output Q_flow the net heat flow rate added to the surface from the air-side. This heat flow rate consists of

• convective heat flow rate,
• absorbed solar radiation,
• absorbed infrared radiation minus emitted infrared radiation.

By convention, Q_flow > 0 if there is net heat flow rate from the thermal zone to the surface, e.g., if the surface cools the thermal zone. The output q_flow is equal to q_flow = Q_flow/A, where A is the area of the heat transfer surface as obtained from EnergyPlus.

Note that for most applications that require interfacing the front-facing and back-side facing surface with the building model, the model Buildings.ThermalZones.EnergyPlus.OpaqueConstruction is easier to use.

Usage

This model is typically used for a radiant slab above soil if the ground heat transfer is also modeled in Modelica. Consider an EnergyPlus input data file that has the following entry:

  BuildingSurface:Detailed,
    Living:Floor,            !- Name
    FLOOR,                   !- Surface Type
    FLOOR:LIVING,            !- Construction Name
    LIVING ZONE,             !- Zone Name
    Surface,                 !- Outside Boundary Condition
    Living:Floor,            !- Outside Boundary Condition Object
    NoSun,                   !- Sun Exposure
    NoWind,                  !- Wind Exposure
    0,                       !- View Factor to Ground
    4,                       !- Number of Vertices
    0,       0,     0,       !- X,Y,Z ==> Vertex 1 {m}
    0,      10.778, 0,       !- X,Y,Z ==> Vertex 2 {m}
    17.242, 10.778, 0,       !- X,Y,Z ==> Vertex 3 {m}
    17.242,  0,     0;       !- X,Y,Z ==> Vertex 4 {m}

To set the temperature of this surface, this model can be used as

Buildings.ThermalZones.EnergyPlus.ZoneSurface flo(surfaceName="Living:Floor");

The temperature of this surface will then be set to the value received at the connector T, and the net heat flow rate received from the thermal zone is produced at the output Q_flow. The output q_flow = Q_flow / A is the heat flux per unit area of the surface.

The model Buildings.ThermalZones.EnergyPlus.Examples.SingleFamilyHouse.RadiantHeatingWithGroundHeatTransfer illustrates this use. Note that if the ground heat transfer were modeled in EnergyPlus, then Buildings.ThermalZones.EnergyPlus.OpaqueConstruction should have been used, which is simpler to setup.

Extends from Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject (Partial definitions of an EnergyPlus object), Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer (Block that synchronizes an object).

Parameters

Connectors

Modelica definition

Buildings.ThermalZones.EnergyPlus.Building.Linux64Binaries

Modelica definition