Buildings.ThermalZones.EnergyPlus_9_6_0

Package with models to connect to EnergyPlus

Information

Spawn logo

Package for Spawn of EnergyPlus that couples Modelica directly to EnergyPlus.

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_9_6_0.UsersGuide for more information.

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

Package Content

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

Buildings.ThermalZones.EnergyPlus_9_6_0.Actuator Buildings.ThermalZones.EnergyPlus_9_6_0.Actuator

Block to write to an EnergyPlus actuator

Buildings.ThermalZones.EnergyPlus_9_6_0.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

Model time (min) Input u
0...5 0
5...15 1
15...20 2
20 3

then EnergyPlus will receive the inputs

Model time (min) Input u
0 0
10 1
20 3

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_9_6_0.Types.Units for the supported units. If the value of the parameter unit is left at its default value of Buildings.ThermalZones.EnergyPlus_9_6_0.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_9_6_0.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_9_6_0.Actuator actLig(
    variableName="LIVING ZONE Lights",
    componentType="Lights",
    controlType="Electric Power Level",
    unit=Buildings.ThermalZones.EnergyPlus_9_6_0.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_9_6_0.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_9_6_0.Actuator actSha(
    variableName="Zn001:Wall001:Win001",
    componentType="Window Shading Control",
    controlType="Control Status",
    unit=Buildings.ThermalZones.EnergyPlus_9_6_0.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_9_6_0.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.

componentType controlType Unit as received in Modelica Unit used by EnergyPlus
ElectricEquipment Electricity Rate W W
ExteriorLights Electricity Rate W W
Lights Electricity Rate W W
Material Surface Property Solar Absorptance 1 1
Material Surface Property Thermal Absorptance 1 1
Material Surface Property Visible Absorptance 1 1
People Number of People 1 1
Schedule:Compact Schedule Value 1 1
Schedule:Constant Schedule Value 1 1
Surface Construction State 1 1
Surface Exterior Surface Convection Heat Transfer Coefficient W/m2.K W/m2.K
Surface Interior Surface Convection Heat Transfer Coefficient W/m2.K W/m2.K
Surface Outdoor Air Wind Direction rad deg
Surface Outdoor Air Wind Speed m/s m/s
Surface Surface Inside Temperature K degC
Surface Surface Outside Temperature K degC
Surface View Factor To Ground 1 1
Weather Data Diffuse Solar W/m2 W/m2
Weather Data Direct Solar W/m2 W/m2
Weather Data Outdoor Dew Point K degC
Weather Data Outdoor Dry Bulb K degC
Weather Data Outdoor Relative Humidity 1 %
Weather Data Wind Direction rad deg
Weather Data Wind Speed m/s m/s
Zone Outdoor Air Drybulb Temperature K degC
Zone Outdoor Air Wetbulb Temperature K degC
Zone Infiltration Air Exchange Flow Rate m3/s m3/s

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

Parameters

TypeNameDefaultDescription
StringvariableName Actuated component unique name in the EnergyPlus idf file
StringcomponentType Actuated component type
StringcontrolType Actuated component control type
Unitsunit Unit of variable as used in Modelica

Connectors

TypeNameDescription
input RealInputuContinuous input signal to be written to EnergyPlus
output RealOutputyValue written to EnergyPlus (use for direct dependency of Actuators and Schedules)

Modelica definition

block Actuator "Block to write to an EnergyPlus actuator" extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.PartialEnergyPlusObject; extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.Synchronize.ObjectSynchronizer; parameter String variableName "Actuated component unique name in the EnergyPlus idf file"; parameter String componentType "Actuated component type"; parameter String controlType "Actuated component control type"; parameter Buildings.ThermalZones.EnergyPlus_9_6_0.Types.Units unit "Unit of variable as used in Modelica"; Modelica.Blocks.Interfaces.RealInput u "Continuous input signal to be written to EnergyPlus"; Modelica.Blocks.Interfaces.RealOutput y "Value written to EnergyPlus (use for direct dependency of Actuators and Schedules)"; protected constant Integer nParOut=0 "Number of parameter values retrieved from EnergyPlus"; constant Integer nInp=1 "Number of inputs"; constant Integer nOut=0 "Number of outputs"; constant Integer nDer=0 "Number of derivatives"; constant Integer nY=nOut+nDer+1 "Size of output vector of exchange function"; parameter Integer nObj( fixed=false, start=0) "Total number of Spawn objects in building"; final parameter String unitString=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.getUnitAsString(unit) "Unit as a string"; Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject adapter=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject( objectType=3, startTime=startTime, modelicaNameBuilding=modelicaNameBuilding, modelicaInstanceName=modelicaInstanceName, spawnExe=spawnExe, idfVersion=idfVersion, idfName=idfName, epwName=epwName, relativeSurfaceTolerance=relativeSurfaceTolerance, epName=variableName, usePrecompiledFMU=usePrecompiledFMU, fmuName=fmuName, buildingsRootFileLocation=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.buildingsRootFileLocation, logLevel=logLevel, printUnit=false, jsonName="emsActuators", jsonKeysValues=" \"variableName\": \""+variableName+"\", \"componentType\": \""+componentType+"\", \"controlType\": \""+controlType+"\", \"unit\": \""+unitString+"\", \"fmiName\": \""+variableName+"_"+componentType+"\"", parOutNames=fill("",nParOut), parOutUnits=fill("",nParOut), nParOut=nParOut, inpNames={componentType}, inpUnits={unitString}, nInp=nInp, outNames=fill("",nOut), outUnits=fill("",nOut), nOut=nOut, derivatives_structure=fill(fill(nDer,2),nDer), nDer=nDer, derivatives_delta=fill(0,nDer)) "Class to communicate with EnergyPlus"; Real yEP[nY] "Output of exchange function"; initial equation assert( not usePrecompiledFMU, "Use of pre-compiled FMU is not supported for block Actuator."); nObj=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.initialize( adapter=adapter, isSynchronized=building.isSynchronized); equation yEP=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.exchange( adapter=adapter, nY=nY, u={u,round(time,1E-3)}, dummy=nObj); y=yEP[1]; nObj=synBui.synchronize.done; end Actuator;

Buildings.ThermalZones.EnergyPlus_9_6_0.Building Buildings.ThermalZones.EnergyPlus_9_6_0.Building

Model that declares a building to which EnergyPlus objects belong to

Buildings.ThermalZones.EnergyPlus_9_6_0.Building

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. When starting the simulation, EnergyPlus will be run with the weather file whose name is identical to epwName, while Modelica will use the file specified by weaName.

Note regarding setInitialRadiativeHeatGainToZero and relativeSurfaceTolerance

To configure models that connect components for radiative heat exchange to the thermal zone model, it is recommended to leave the parameter setInitialRadiativeHeatGainToZero at its default value true. This sets the radiative heat flow rate sent from Modelica to EnergyPlus to zero during the initialization of the model, thereby avoiding a potential nonlinear system of equations that may give convergence problems. This only affects the initialization of the model but not the time integration, hence the error should be small for typical models.

If you decide to set setInitialRadiativeHeatGainToZero = false, you need to be aware of the following: If setInitialRadiativeHeatGainToZero = false, then the radiative heat gain from the model input is being used. If this radiative heat gain depends on the radiative temperature that is an output of the EnergyPlus model, a nonlinear equation is formed. Because in EnergyPlus, computing the radiative temperature involves an iterative solution, this can cause convergence problems due to having two nested solvers, the outer being the Modelica solver that solves for the radiative heat flow rate QGaiRad_flow, and the innner being the EnergyPlus solver that solves for the radiative temperature TRad. Hence, we recommend to leave setInitialRadiativeHeatGainToZero = true.

If you decide to set setInitialRadiativeHeatGainToZero = false, you may need to also tighten the tolerance of the EnergyPlus solver by tightening relativeSurfaceTolerance, but one cannot assure that the nested nonlinear equations converge.

Because a Modelica model does not have knowledge of the solver tolerance, automatically tightening relativeSurfaceTolerance as a function of the Modelica solver tolerance is not possible.

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

Parameters

TypeNameDefaultDescription
StringidfName Name of the IDF file
StringepwName Name of the EPW file
StringweaName Name of the weather file, in .mos format and with .mos extension
Diagnostics
BooleanprintUnitstrueSet to true to print units of OutputVariable instances to log file
Debug
LogLevelslogLevelBuildings.ThermalZones.Energ...Log level of EnergyPlus output
Advanced
BooleancomputeWetBulbTemperaturetrueIf true, then this model computes the wet bulb temperature
BooleansetInitialRadiativeHeatGainToZerotrueIf true, then the radiative heat gain sent from Modelica to EnergyPlus is zero during the model initialization
RealrelativeSurfaceTolerance1E-6Relative tolerance of surface temperature calculations

Connectors

TypeNameDescription
BusweaBusWeather data bus
SynchronizeConnectorsynchronizeConnector that synchronizes all Spawn objects of this buildings

Modelica definition

model Building "Model that declares a building to which EnergyPlus objects belong to" extends Modelica.Blocks.Icons.Block; constant String spawnExe="spawn-0.4.3-7048a72798" "Name of the spawn executable, without extension, such as spawn-0.4.3-7048a72798aaa"; constant String idfVersion = "9_6_0" "IDF version with underscore, used for error report"; final constant String modelicaNameBuilding=getInstanceName() "Name of this instance"; constant Boolean usePrecompiledFMU=false "Set to true to use pre-compiled FMU with name specified by fmuName"; constant String fmuName="" "Specify if a pre-compiled FMU should be used instead of EnergyPlus (for development)"; parameter String idfName "Name of the IDF file"; parameter String epwName "Name of the EPW file"; parameter String weaName "Name of the weather file, in .mos format and with .mos extension"; parameter Buildings.ThermalZones.EnergyPlus_9_6_0.Types.LogLevels logLevel=Buildings.ThermalZones.EnergyPlus_9_6_0.Types.LogLevels.Warning "Log level of EnergyPlus output"; parameter Boolean computeWetBulbTemperature=true "If true, then this model computes the wet bulb temperature"; parameter Boolean setInitialRadiativeHeatGainToZero = true "If true, then the radiative heat gain sent from Modelica to EnergyPlus is zero during the model initialization"; parameter Real relativeSurfaceTolerance(min=1E-12) = 1E-6 "Relative tolerance of surface temperature calculations"; parameter Boolean printUnits=true "Set to true to print units of OutputVariable instances to log file"; BoundaryConditions.WeatherData.Bus weaBus "Weather data bus"; BaseClasses.Synchronize.SynchronizeConnector synchronize "Connector that synchronizes all Spawn objects of this buildings"; Real isSynchronized "Flag used to synchronize Spawn objects"; protected Real synchronization_done=synchronize.done "Intermediate variable as acausal connectors cannot be used in the algorithm section"; /* final parameter String idf=Modelica.Utilities.Files.loadResource(idfName) "idf file to be loaded into the FMU"; final parameter String epw=Modelica.Utilities.Files.loadResource(epwName) "idf file to be loaded into the FMU"; */ BoundaryConditions.WeatherData.ReaderTMY3 weaDat( final filNam=weaName, final computeWetBulbTemperature=computeWetBulbTemperature) "Weather data reader"; equation synchronize.do=0; connect(weaDat.weaBus,weaBus); algorithm isSynchronized := synchronization_done; end Building;

Buildings.ThermalZones.EnergyPlus_9_6_0.OpaqueConstruction Buildings.ThermalZones.EnergyPlus_9_6_0.OpaqueConstruction

Model to exchange heat of an opaque construction with EnergyPlus

Buildings.ThermalZones.EnergyPlus_9_6_0.OpaqueConstruction

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

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_9_6_0.Examples.SingleFamilyHouse.RadiantHeatingCooling_TRoom 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_9_6_0.ZoneSurface can be used, as shown for the floor slab in Buildings.ThermalZones.EnergyPlus_9_6_0.Examples.SingleFamilyHouse.HeatPumpRadiantHeatingGroundHeatTransfer.

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_9_6_0.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_9_6_0.Examples.SingleFamilyHouse.RadiantHeatingCooling_TRoom.

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

Parameters

TypeNameDefaultDescription
StringsurfaceName Surface unique name in the EnergyPlus idf file

Connectors

TypeNameDescription
HeatPort_aheaPorFroHeat port for front surface
HeatPort_bheaPorBacHeat port for back surface

Modelica definition

model OpaqueConstruction "Model to exchange heat of an opaque construction with EnergyPlus" extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.PartialEnergyPlusObject; extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.Synchronize.ObjectSynchronizer; parameter String surfaceName "Surface unique name in the EnergyPlus idf file"; final parameter Modelica.Units.SI.Area A(final fixed=false, min=1E-10) "Surface area"; Modelica.Thermal.HeatTransfer.Interfaces.HeatPort_a heaPorFro "Heat port for front surface"; Modelica.Thermal.HeatTransfer.Interfaces.HeatPort_b heaPorBac "Heat port for back surface"; Modelica.Units.SI.HeatFlux qFro_flow "Heat flow rate at front surface per unit area"; Modelica.Units.SI.HeatFlux qBac_flow "Heat flow rate at front surface per unit area"; protected constant Integer nParOut=1 "Number of parameter values retrieved from EnergyPlus"; constant Integer nInp=2 "Number of inputs"; constant Integer nOut=2 "Number of outputs"; constant Integer nDer=0 "Number of derivatives"; constant Integer nY=nOut+nDer+1 "Size of output vector of exchange function"; parameter Integer nObj( fixed=false, start=0) "Total number of Spawn objects in building"; Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject adapter=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject( objectType=6, startTime=startTime, modelicaNameBuilding=modelicaNameBuilding, modelicaInstanceName=modelicaInstanceName, spawnExe=spawnExe, idfVersion=idfVersion, idfName=idfName, epwName=epwName, relativeSurfaceTolerance=relativeSurfaceTolerance, epName=surfaceName, usePrecompiledFMU=usePrecompiledFMU, fmuName=fmuName, buildingsRootFileLocation=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.buildingsRootFileLocation, logLevel=logLevel, printUnit=false, jsonName="buildingSurfaceDetailed", jsonKeysValues=" \"name\": \""+surfaceName+"\"", parOutNames={"A"}, parOutUnits={"m2"}, nParOut=nParOut, inpNames={"TFront","TBack"}, inpUnits={"K","K"}, nInp=nInp, outNames={"QFront_flow","QBack_flow"}, outUnits={"W","W"}, nOut=nOut, derivatives_structure=fill(fill(nDer,2),nDer), nDer=nDer, derivatives_delta=fill(0,nDer)) "Class to communicate with EnergyPlus"; ////////// // The derivative structure was: // derivatives_structure={{1,1},{2,2}}, // nDer=nDer, // derivatives_delta={0.01,0.01} // This has been removed due to numerical noise, // see https://github.com/lbl-srg/modelica-buildings/issues/2358#issuecomment-819578850 ////////// Real yEP[nY] "Output of exchange function"; Modelica.Units.SI.Time tNext(start=startTime, fixed=true) "Next sampling time"; discrete Modelica.Units.SI.Time tLast(fixed=true, start=startTime) "Last time of data exchange"; discrete Modelica.Units.SI.Time dtLast "Time step since the last synchronization"; discrete Modelica.Units.SI.Temperature TFroLast "Front surface temperature at last sampling"; discrete Modelica.Units.SI.Temperature TBacLast "Back surface temperature at last sampling"; discrete Modelica.Units.SI.HeatFlowRate QFroLast_flow(fixed=false, start=0) "Surface heat flow rate at front if T = TLast"; discrete Modelica.Units.SI.HeatFlowRate QBacLast_flow(fixed=false, start=0) "Surface heat flow rate at back if T = TLast"; // discrete Real dQFro_flow_dT( // final unit="W/K") // "Derivative dQFroCon_flow / dT"; // discrete Real dQBac_flow_dT( // final unit="W/K") // "Derivative dQBacCon_flow / dT"; initial equation assert( not usePrecompiledFMU, "Use of pre-compiled FMU is not supported for ZoneSurface."); nObj=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.initialize( adapter=adapter, isSynchronized=building.isSynchronized); {A}=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.getParameters( adapter=adapter, nParOut=nParOut, isSynchronized=nObj); assert( A > 0, "Surface area must not be zero."); equation // Make sure the heat ports are connected. // These statements must be in the equation section. Otherwise, // Dymola 2021 does trigger an error during the symbolic processing // rather than these assertions if the heat port is not connected. assert(cardinality(heaPorFro) > 0, "In " + getInstanceName() +": The heat port heaPorFro must be connected to another heat port."); assert(cardinality(heaPorBac) > 0, "In " + getInstanceName() +": The heat port heaPorBac must be connected to another heat port."); when {initial(),time >= pre(tNext)} then // Initialization of output variables. TFroLast=heaPorFro.T; TBacLast=heaPorBac.T; dtLast=time-pre(tLast); yEP=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.exchange( adapter=adapter, nY=nY, u={heaPorFro.T,heaPorBac.T,round(time,1E-3)}, dummy=A); QFroLast_flow=-yEP[1]; QBacLast_flow=-yEP[2]; //dQFro_flow_dT=-yEP[3]; //dQBac_flow_dT=-yEP[4]; tNext=yEP[3]; tLast=time; end when; heaPorFro.Q_flow=QFroLast_flow; //+(heaPorFro.T-TFroLast)*dQFro_flow_dT; heaPorBac.Q_flow=QBacLast_flow; //+(heaPorBac.T-TBacLast)*dQBac_flow_dT; qFro_flow=heaPorFro.Q_flow/A; qBac_flow=heaPorBac.Q_flow/A; nObj=synBui.synchronize.done; end OpaqueConstruction;

Buildings.ThermalZones.EnergyPlus_9_6_0.OutputVariable Buildings.ThermalZones.EnergyPlus_9_6_0.OutputVariable

Block to read an EnergyPlus output variable

Buildings.ThermalZones.EnergyPlus_9_6_0.OutputVariable

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.Units.SI. 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_9_6_0.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_9_6_0.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_9_6_0.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_9_6_0.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_9_6_0.Actuator or Buildings.ThermalZones.EnergyPlus_9_6_0.Schedule on which this output directly depends on. See for example Buildings.ThermalZones.EnergyPlus_9_6_0.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_9_6_0.OutputVariable.

name Unit as received in Modelica Unit used by EnergyPlus
Debug Surface Solar Shading Model DifShdgRatioHoriz 1 1
Debug Surface Solar Shading Model DifShdgRatioIsoSky 1 1
Debug Surface Solar Shading Model WithShdgIsoSky 1 1
Debug Surface Solar Shading Model WoShdgIsoSky 1 1
Electric Equipment Convective Heating Energy J J
Electric Equipment Convective Heating Rate W W
Electric Equipment Electric Energy J J
Electric Equipment Electric Power W W
Electric Equipment Latent Gain Energy J J
Electric Equipment Latent Gain Rate W W
Electric Equipment Lost Heat Energy J J
Electric Equipment Lost Heat Rate W W
Electric Equipment Radiant Heating Energy J J
Electric Equipment Radiant Heating Rate W W
Electric Equipment Total Heating Energy J J
Electric Equipment Total Heating Rate W W
Environmental Impact Electricity CH4 Emissions Mass kg kg
Environmental Impact Electricity CO Emissions Mass kg kg
Environmental Impact Electricity CO2 Emissions Mass kg kg
Environmental Impact Electricity Hg Emissions Mass kg kg
Environmental Impact Electricity N2O Emissions Mass kg kg
Environmental Impact Electricity NH3 Emissions Mass kg kg
Environmental Impact Electricity NMVOC Emissions Mass kg kg
Environmental Impact Electricity NOx Emissions Mass kg kg
Environmental Impact Electricity Nuclear High Level Waste Mass kg kg
Environmental Impact Electricity Nuclear Low Level Waste Volume m3 m3
Environmental Impact Electricity PM Emissions Mass kg kg
Environmental Impact Electricity PM10 Emissions Mass kg kg
Environmental Impact Electricity PM2.5 Emissions Mass kg kg
Environmental Impact Electricity Pb Emissions Mass kg kg
Environmental Impact Electricity SO2 Emissions Mass kg kg
Environmental Impact Electricity Source Energy J J
Environmental Impact Electricity Water Consumption Volume m3 L
Environmental Impact Natural Gas CH4 Emissions Mass kg kg
Environmental Impact Natural Gas CO Emissions Mass kg kg
Environmental Impact Natural Gas CO2 Emissions Mass kg kg
Environmental Impact Natural Gas Hg Emissions Mass kg kg
Environmental Impact Natural Gas N2O Emissions Mass kg kg
Environmental Impact Natural Gas NH3 Emissions Mass kg kg
Environmental Impact Natural Gas NMVOC Emissions Mass kg kg
Environmental Impact Natural Gas NOx Emissions Mass kg kg
Environmental Impact Natural Gas Nuclear High Level Waste Mass kg kg
Environmental Impact Natural Gas Nuclear Low Level Waste Volume m3 m3
Environmental Impact Natural Gas PM Emissions Mass kg kg
Environmental Impact Natural Gas PM10 Emissions Mass kg kg
Environmental Impact Natural Gas PM2.5 Emissions Mass kg kg
Environmental Impact Natural Gas Pb Emissions Mass kg kg
Environmental Impact Natural Gas SO2 Emissions Mass kg kg
Environmental Impact Natural Gas Source Energy J J
Environmental Impact Natural Gas Water Consumption Volume m3 L
Environmental Impact Purchased Electricity Source Energy J J
Environmental Impact Surplus Sold Electricity Source J J
Environmental Impact Total CH4 Emissions Carbon Equivalent Mass kg kg
Environmental Impact Total CO2 Emissions Carbon Equivalent Mass kg kg
Environmental Impact Total N2O Emissions Carbon Equivalent Mass kg kg
Exterior Lights Electric Energy J J
Exterior Lights Electric Power W W
Facility Cooling Setpoint Not Met Time s hr
Facility Cooling Setpoint Not Met While Occupied Time s hr
Facility Heating Setpoint Not Met Time s hr
Facility Heating Setpoint Not Met While Occupied Time s hr
Facility Thermal Comfort ASHRAE 55 Simple Model Summer Clothes Not Comfortable Time s hr
Facility Thermal Comfort ASHRAE 55 Simple Model Summer or Winter Clothes Not Comfortable Time s hr
Facility Thermal Comfort ASHRAE 55 Simple Model Winter Clothes Not Comfortable Time s hr
Lights Convective Heating Energy J J
Lights Convective Heating Rate W W
Lights Electric Energy J J
Lights Electric Power W W
Lights Radiant Heating Energy J J
Lights Radiant Heating Rate W W
Lights Return Air Heating Energy J J
Lights Return Air Heating Rate W W
Lights Total Heating Energy J J
Lights Total Heating Rate W W
Lights Visible Radiation Heating Energy J J
Lights Visible Radiation Heating Rate W W
People Air Relative Humidity 1 %
People Air Temperature K degC
People Convective Heating Energy J J
People Convective Heating Rate W W
People Latent Gain Energy J J
People Latent Gain Rate W W
People Occupant Count 1 1
People Radiant Heating Energy J J
People Radiant Heating Rate W W
People Sensible Heating Energy J J
People Sensible Heating Rate W W
People Total Heating Energy J J
People Total Heating Rate W W
Schedule Value 1 1
Site Beam Solar Radiation Luminous Efficacy lm/W lm/W
Site Day Type Index 1 1
Site Daylight Saving Time Status 1 1
Site Daylighting Model Sky Brightness 1 1
Site Daylighting Model Sky Clearness 1 1
Site Deep Ground Temperature K degC
Site Diffuse Solar Radiation Rate per Area W/m2 W/m2
Site Direct Solar Radiation Rate per Area W/m2 W/m2
Site Exterior Beam Normal Illuminance lm/m2 lux
Site Exterior Horizontal Beam Illuminance lm/m2 lux
Site Exterior Horizontal Sky Illuminance lm/m2 lux
Site Ground Reflected Solar Radiation Rate per Area W/m2 W/m2
Site Ground Temperature K degC
Site Horizontal Infrared Radiation Rate per Area W/m2 W/m2
Site Mains Water Temperature K degC
Site Outdoor Air Barometric Pressure Pa Pa
Site Outdoor Air Density kg/m3 kg/m3
Site Outdoor Air Dewpoint Temperature K degC
Site Outdoor Air Drybulb Temperature K degC
Site Outdoor Air Enthalpy J/kg J/kg
Site Outdoor Air Humidity Ratio 1 kgWater/kgDryAir
Site Outdoor Air Relative Humidity 1 %
Site Outdoor Air Wetbulb Temperature K degC
Site Precipitation Depth m m
Site Rain Status 1 1
Site Simple Factor Model Ground Temperature K degC
Site Sky Diffuse Solar Radiation Luminous Efficacy lm/W lm/W
Site Sky Temperature K degC
Site Snow on Ground Status 1 1
Site Solar Altitude Angle rad deg
Site Solar Azimuth Angle rad deg
Site Solar Hour Angle rad deg
Site Surface Ground Temperature K degC
Site Total Surface Heat Emission to Air J J
Site Total Zone Exfiltration Heat Loss J J
Site Total Zone Exhaust Air Heat Loss J J
Site Wind Direction rad deg
Site Wind Speed m/s m/s
Surface Anisotropic Sky Multiplier 1 1
Surface Average Face Conduction Heat Gain Rate W W
Surface Average Face Conduction Heat Loss Rate W W
Surface Average Face Conduction Heat Transfer Energy J J
Surface Average Face Conduction Heat Transfer Rate W W
Surface Average Face Conduction Heat Transfer Rate per Area W/m2 W/m2
Surface Heat Storage Energy J J
Surface Heat Storage Gain Rate W W
Surface Heat Storage Loss Rate W W
Surface Heat Storage Rate W W
Surface Heat Storage Rate per Area W/m2 W/m2
Surface Inside Face Absorbed Shortwave Radiation Rate W W
Surface Inside Face Adjacent Air Temperature K degC
Surface Inside Face Beam Solar Radiation Heat Gain Rate W W
Surface Inside Face Conduction Heat Gain Rate W W
Surface Inside Face Conduction Heat Loss Rate W W
Surface Inside Face Conduction Heat Transfer Energy J J
Surface Inside Face Conduction Heat Transfer Rate W W
Surface Inside Face Conduction Heat Transfer Rate per Area W/m2 W/m2
Surface Inside Face Convection Classification Index 1 1
Surface Inside Face Convection Heat Gain Energy J J
Surface Inside Face Convection Heat Gain Rate W W
Surface Inside Face Convection Heat Gain Rate per Area W/m2 W/m2
Surface Inside Face Convection Heat Transfer Coefficient W/m2.K W/m2.K
Surface Inside Face Convection Model Equation Index 1 1
Surface Inside Face Convection Reference Air Index 1 1
Surface Inside Face Exterior Windows Incident Beam Solar Radiation Energy J J
Surface Inside Face Exterior Windows Incident Beam Solar Radiation Rate W W
Surface Inside Face Exterior Windows Incident Beam Solar Radiation Rate per Area W/m2 W/m2
Surface Inside Face Heat Source Gain Rate per Area W/m2 W/m2
Surface Inside Face Initial Transmitted Diffuse Absorbed Solar Radiation Rate W W
Surface Inside Face Initial Transmitted Diffuse Transmitted Out Window Solar Radiation Rate W W
Surface Inside Face Interior Movable Insulation Temperature K degC
Surface Inside Face Interior Windows Incident Beam Solar Radiation Energy J J
Surface Inside Face Interior Windows Incident Beam Solar Radiation Rate W W
Surface Inside Face Interior Windows Incident Beam Solar Radiation Rate per Area W/m2 W/m2
Surface Inside Face Internal Gains Radiation Heat Gain Energy J J
Surface Inside Face Internal Gains Radiation Heat Gain Rate W W
Surface Inside Face Internal Gains Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Inside Face Lights Radiation Heat Gain Energy J J
Surface Inside Face Lights Radiation Heat Gain Rate W W
Surface Inside Face Lights Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Inside Face Net Surface Thermal Radiation Heat Gain Energy J J
Surface Inside Face Net Surface Thermal Radiation Heat Gain Rate W W
Surface Inside Face Net Surface Thermal Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Inside Face Solar Radiation Heat Gain Energy J J
Surface Inside Face Solar Radiation Heat Gain Rate W W
Surface Inside Face Solar Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Inside Face System Radiation Heat Gain Energy J J
Surface Inside Face System Radiation Heat Gain Rate W W
Surface Inside Face System Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Inside Face Temperature K degC
Surface Outside Face Beam Solar Incident Angle Cosine Value 1 1
Surface Outside Face Conduction Heat Gain Rate W W
Surface Outside Face Conduction Heat Loss Rate W W
Surface Outside Face Conduction Heat Transfer Energy J J
Surface Outside Face Conduction Heat Transfer Rate W W
Surface Outside Face Conduction Heat Transfer Rate per Area W/m2 W/m2
Surface Outside Face Convection Classification Index 1 1
Surface Outside Face Convection Heat Gain Energy J J
Surface Outside Face Convection Heat Gain Rate W W
Surface Outside Face Convection Heat Gain Rate per Area W/m2 W/m2
Surface Outside Face Convection Heat Transfer Coefficient W/m2.K W/m2.K
Surface Outside Face Forced Convection Model Equation Index 1 1
Surface Outside Face Heat Emission to Air Rate W W
Surface Outside Face Heat Source Gain Rate per Area W/m2 W/m2
Surface Outside Face Incident Beam Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Beam To Beam Surface Reflected Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Beam To Diffuse Ground Reflected Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Beam To Diffuse Surface Reflected Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Ground Diffuse Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Sky Diffuse Ground Reflected Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Sky Diffuse Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Sky Diffuse Surface Reflected Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Incident Solar Radiation Rate per Area W/m2 W/m2
Surface Outside Face Natural Convection Model Equation Index 1 1
Surface Outside Face Net Thermal Radiation Heat Gain Energy J J
Surface Outside Face Net Thermal Radiation Heat Gain Rate W W
Surface Outside Face Net Thermal Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Outside Face Outdoor Air Drybulb Temperature K degC
Surface Outside Face Outdoor Air Wetbulb Temperature K degC
Surface Outside Face Outdoor Air Wind Direction rad deg
Surface Outside Face Outdoor Air Wind Speed m/s m/s
Surface Outside Face Solar Radiation Heat Gain Energy J J
Surface Outside Face Solar Radiation Heat Gain Rate W W
Surface Outside Face Solar Radiation Heat Gain Rate per Area W/m2 W/m2
Surface Outside Face Sunlit Area m2 m2
Surface Outside Face Sunlit Fraction 1 1
Surface Outside Face Temperature K degC
Surface Outside Face Thermal Radiation to Air Heat Transfer Coefficient W/m2.K W/m2.K
Surface Outside Face Thermal Radiation to Air Heat Transfer Rate W W
Surface Outside Face Thermal Radiation to Ground Heat Transfer Coefficient W/m2.K W/m2.K
Surface Outside Face Thermal Radiation to Sky Heat Transfer Coefficient W/m2.K W/m2.K
Surface Outside Normal Azimuth Angle rad deg
Surface Shading Device Is On Time Fraction 1 1
Surface Storm Window On Off Status 1 1
Surface Window BSDF Beam Direction Number 1 1
Surface Window BSDF Beam Phi Angle rad rad
Surface Window BSDF Beam Theta Angle rad rad
Surface Window Back Face Temperature Layer 1 K degC
Surface Window Blind Slat Angle rad deg
Surface Window Front Face Temperature Layer 1 K degC
Surface Window Gap Convective Heat Transfer Energy J J
Surface Window Gap Convective Heat Transfer Rate W W
Surface Window Glazing Beam to Beam Solar Transmittance 1 1
Surface Window Glazing Beam to Diffuse Solar Transmittance 1 1
Surface Window Glazing Diffuse to Diffuse Solar Transmittance 1 1
Surface Window Heat Gain Energy J J
Surface Window Heat Gain Rate W W
Surface Window Heat Loss Energy J J
Surface Window Heat Loss Rate W W
Surface Window Inside Face Divider Condensation Status 1 1
Surface Window Inside Face Frame Condensation Status 1 1
Surface Window Inside Face Glazing Condensation Status 1 1
Surface Window Model Solver Iteration Count 1 1
Surface Window Net Heat Transfer Energy J J
Surface Window Net Heat Transfer Rate W W
Surface Window Outside Reveal Reflected Beam Solar Radiation Energy J J
Surface Window Outside Reveal Reflected Beam Solar Radiation Rate W W
Surface Window Shading Device Absorbed Solar Radiation Energy J J
Surface Window Shading Device Absorbed Solar Radiation Rate W W
Surface Window Solar Horizontal Profile Angle rad deg
Surface Window Solar Vertical Profile Angle rad deg
Surface Window System Solar Absorptance 1 1
Surface Window System Solar Reflectance 1 1
Surface Window System Solar Transmittance 1 1
Surface Window Total Glazing Layers Absorbed Shortwave Radiation Rate W W
Surface Window Total Glazing Layers Absorbed Solar Radiation Energy J J
Surface Window Total Glazing Layers Absorbed Solar Radiation Rate W W
Surface Window Transmitted Beam Solar Radiation Energy J J
Surface Window Transmitted Beam Solar Radiation Rate W W
Surface Window Transmitted Beam To Beam Solar Radiation Energy J J
Surface Window Transmitted Beam To Beam Solar Radiation Rate W W
Surface Window Transmitted Beam To Diffuse Solar Radiation Energy J J
Surface Window Transmitted Beam To Diffuse Solar Radiation Rate W W
Surface Window Transmitted Diffuse Solar Radiation Energy J J
Surface Window Transmitted Diffuse Solar Radiation Rate W W
Surface Window Transmitted Solar Radiation Energy J J
Surface Window Transmitted Solar Radiation Rate W W
Zone Air Heat Balance Air Energy Storage Rate W W
Zone Air Heat Balance Internal Convective Heat Gain Rate W W
Zone Air Heat Balance Interzone Air Transfer Rate W W
Zone Air Heat Balance Outdoor Air Transfer Rate W W
Zone Air Heat Balance Surface Convection Rate W W
Zone Air Heat Balance System Air Transfer Rate W W
Zone Air Heat Balance System Convective Heat Gain Rate W W
Zone Cooling Setpoint Not Met Time s hr
Zone Cooling Setpoint Not Met While Occupied Time s hr
Zone Electric Equipment Convective Heating Energy J J
Zone Electric Equipment Convective Heating Rate W W
Zone Electric Equipment Electric Energy J J
Zone Electric Equipment Electric Power W W
Zone Electric Equipment Latent Gain Energy J J
Zone Electric Equipment Latent Gain Rate W W
Zone Electric Equipment Lost Heat Energy J J
Zone Electric Equipment Lost Heat Rate W W
Zone Electric Equipment Radiant Heating Energy J J
Zone Electric Equipment Radiant Heating Rate W W
Zone Electric Equipment Total Heating Energy J J
Zone Electric Equipment Total Heating Rate W W
Zone Exfiltration Heat Transfer Rate W W
Zone Exfiltration Latent Heat Transfer Rate W W
Zone Exfiltration Sensible Heat Transfer Rate W W
Zone Exhaust Air Heat Transfer Rate W W
Zone Exhaust Air Latent Heat Transfer Rate W W
Zone Exhaust Air Sensible Heat Transfer Rate W W
Zone Exterior Windows Total Transmitted Beam Solar Radiation Energy J J
Zone Exterior Windows Total Transmitted Beam Solar Radiation Rate W W
Zone Exterior Windows Total Transmitted Diffuse Solar Radiation Energy J J
Zone Exterior Windows Total Transmitted Diffuse Solar Radiation Rate W W
Zone Heating Setpoint Not Met Time s hr
Zone Heating Setpoint Not Met While Occupied Time s hr
Zone Interior Windows Total Transmitted Beam Solar Radiation Energy J J
Zone Interior Windows Total Transmitted Beam Solar Radiation Rate W W
Zone Interior Windows Total Transmitted Diffuse Solar Radiation Energy J J
Zone Interior Windows Total Transmitted Diffuse Solar Radiation Rate W W
Zone Lights Convective Heating Energy J J
Zone Lights Convective Heating Rate W W
Zone Lights Electric Energy J J
Zone Lights Electric Power W W
Zone Lights Radiant Heating Energy J J
Zone Lights Radiant Heating Rate W W
Zone Lights Return Air Heating Energy J J
Zone Lights Return Air Heating Rate W W
Zone Lights Total Heating Energy J J
Zone Lights Total Heating Rate W W
Zone Lights Visible Radiation Heating Energy J J
Zone Lights Visible Radiation Heating Rate W W
Zone Mean Air Dewpoint Temperature K degC
Zone Mean Air Humidity Ratio 1 kgWater/kgDryAir
Zone Mean Air Temperature K degC
Zone Mean Radiant Temperature K degC
Zone Operative Temperature K degC
Zone Outdoor Air Drybulb Temperature K degC
Zone Outdoor Air Wetbulb Temperature K degC
Zone Outdoor Air Wind Direction rad deg
Zone Outdoor Air Wind Speed m/s m/s
Zone People Convective Heating Energy J J
Zone People Convective Heating Rate W W
Zone People Latent Gain Energy J J
Zone People Latent Gain Rate W W
Zone People Occupant Count 1 1
Zone People Radiant Heating Energy J J
Zone People Radiant Heating Rate W W
Zone People Sensible Heating Energy J J
Zone People Sensible Heating Rate W W
Zone People Total Heating Energy J J
Zone People Total Heating Rate W W
Zone Thermal Comfort ASHRAE 55 Simple Model Summer Clothes Not Comfortable Time s hr
Zone Thermal Comfort ASHRAE 55 Simple Model Summer or Winter Clothes Not Comfortable Time s hr
Zone Thermal Comfort ASHRAE 55 Simple Model Winter Clothes Not Comfortable Time s hr
Zone Thermal Comfort Clothing Surface Temperature K degC
Zone Thermal Comfort Fanger Model PMV 1 1
Zone Thermal Comfort Fanger Model PPD 1 %
Zone Thermal Comfort Mean Radiant Temperature K degC
Zone Thermal Comfort Operative Temperature K degC
Zone Total Internal Convective Heating Energy J J
Zone Total Internal Convective Heating Rate W W
Zone Total Internal Latent Gain Energy J J
Zone Total Internal Latent Gain Rate W W
Zone Total Internal Radiant Heating Energy J J
Zone Total Internal Radiant Heating Rate W W
Zone Total Internal Total Heating Energy J J
Zone Total Internal Total Heating Rate W W
Zone Total Internal Visible Radiation Heating Energy J J
Zone Total Internal Visible Radiation Heating Rate W W
Zone Windows Total Heat Gain Energy J J
Zone Windows Total Heat Gain Rate W W
Zone Windows Total Heat Loss Energy J J
Zone Windows Total Heat Loss Rate W W
Zone Windows Total Transmitted Solar Radiation Energy J J
Zone Windows Total Transmitted Solar Radiation Rate W W

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

Parameters

TypeNameDefaultDescription
Stringname EnergyPlus name of the output variable as in the EnergyPlus .rdd or .mdd file
Stringkey EnergyPlus key of the output variable
BooleanisDirectDependentfalseSet to false for states or weather variables, or true for algebraic variables with direct dependency on input variables

Connectors

TypeNameDescription
input RealInputdirectDependencySet to algebraic variable on which this output directly depends on
output RealOutputyOutput received from EnergyPlus

Modelica definition

model OutputVariable "Block to read an EnergyPlus output variable" extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.PartialEnergyPlusObject; extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.Synchronize.ObjectSynchronizer; parameter String name "EnergyPlus name of the output variable as in the EnergyPlus .rdd or .mdd file"; parameter String key "EnergyPlus key of the output variable"; parameter Boolean isDirectDependent=false "Set to false for states or weather variables, or true for algebraic variables with direct dependency on input variables"; Modelica.Blocks.Interfaces.RealInput directDependency if isDirectDependent "Set to algebraic variable on which this output directly depends on"; discrete Modelica.Blocks.Interfaces.RealOutput y "Output received from EnergyPlus"; protected final parameter Boolean printUnit=building.printUnits "Set to true to print unit of OutputVariable objects to log file"; Modelica.Blocks.Interfaces.RealInput directDependency_in_internal "Needed to connect to conditional connector"; constant Integer nParOut=0 "Number of parameter values retrieved from EnergyPlus"; constant Integer nInp=0 "Number of inputs"; constant Integer nOut=1 "Number of outputs"; constant Integer nDer=0 "Number of derivatives"; constant Integer nY=nOut+nDer+1 "Size of output vector of exchange function"; parameter Integer nObj( fixed=false, start=0) "Total number of Spawn objects in building"; Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject adapter=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject( objectType=4, startTime=startTime, modelicaNameBuilding=modelicaNameBuilding, modelicaInstanceName=modelicaInstanceName, spawnExe=spawnExe, idfVersion=idfVersion, idfName=idfName, epwName=epwName, relativeSurfaceTolerance=relativeSurfaceTolerance, epName=name, usePrecompiledFMU=usePrecompiledFMU, fmuName=fmuName, buildingsRootFileLocation=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.buildingsRootFileLocation, logLevel=logLevel, printUnit=printUnit, jsonName="outputVariables", jsonKeysValues=" \"name\": \""+name+"\", \"key\": \""+key+"\", \"fmiName\": \""+name+"_"+key+"\"", parOutNames=fill("",nParOut), parOutUnits=fill("",nParOut), nParOut=nParOut, inpNames=fill("",nInp), inpUnits=fill("",nInp), nInp=0, outNames={key}, outUnits=fill("",nOut), nOut=nOut, derivatives_structure=fill(fill(nDer,2),nDer), nDer=nDer, derivatives_delta=fill(0,nDer)) "Class to communicate with EnergyPlus"; Real yEP[nY] "Output of exchange function"; Modelica.Units.SI.Time tNext(start=startTime, fixed=true) "Next sampling time"; initial equation assert( not usePrecompiledFMU, "Use of pre-compiled FMU is not supported for block OutputVariable."); nObj=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.initialize( adapter=adapter, isSynchronized=building.isSynchronized); equation if isDirectDependent then connect(directDependency,directDependency_in_internal); else directDependency_in_internal=0; end if; when {initial(),time >= pre(tNext)} then yEP=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.exchange( adapter=adapter, nY=nY, u={round(time,1E-3),directDependency_in_internal}, dummy=nObj); y=yEP[1]; tNext=yEP[2]; end when; nObj=synBui.synchronize.done; end OutputVariable;

Buildings.ThermalZones.EnergyPlus_9_6_0.Schedule Buildings.ThermalZones.EnergyPlus_9_6_0.Schedule

Block to write to an EnergyPlus schedule

Buildings.ThermalZones.EnergyPlus_9_6_0.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

Model time (min) Input u
0...5 0
5...15 1
15...20 2
20 3

then EnergyPlus will receive the inputs

Model time (min) Input u
0 0
10 1
20 3

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_9_6_0.Types.Units for the supported units. If the value of the parameter unit is left at its default value of Buildings.ThermalZones.EnergyPlus_9_6_0.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_9_6_0.Schedule schInt(
    name = "INTERMITTENT",
    unit = Buildings.ThermalZones.EnergyPlus_9_6_0.Types.Units.Normalized)
    "Block that writes to the EnergyPlus schedule INTERMITTENT";

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

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

Parameters

TypeNameDefaultDescription
Stringname Name of schedule
Unitsunit Unit of variable as used in Modelica

Connectors

TypeNameDescription
input RealInputuContinuous input signal to be written to EnergyPlus
output RealOutputyValue written to EnergyPlus (use for direct dependency of Actuators and Schedules)

Modelica definition

block Schedule "Block to write to an EnergyPlus schedule" extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.PartialEnergyPlusObject; extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.Synchronize.ObjectSynchronizer; parameter String name "Name of schedule"; parameter Buildings.ThermalZones.EnergyPlus_9_6_0.Types.Units unit "Unit of variable as used in Modelica"; Modelica.Blocks.Interfaces.RealInput u "Continuous input signal to be written to EnergyPlus"; Modelica.Blocks.Interfaces.RealOutput y "Value written to EnergyPlus (use for direct dependency of Actuators and Schedules)"; protected constant Integer nParOut=0 "Number of parameter values retrieved from EnergyPlus"; constant Integer nInp=1 "Number of inputs"; constant Integer nOut=0 "Number of outputs"; constant Integer nDer=0 "Number of derivatives"; constant Integer nY=nOut+nDer+1 "Size of output vector of exchange function"; parameter Integer nObj( fixed=false, start=0) "Total number of Spawn objects in building"; final parameter String unitString=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.getUnitAsString(unit) "Unit as a string"; Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject adapter=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject( objectType=2, startTime=startTime, modelicaNameBuilding=modelicaNameBuilding, modelicaInstanceName=modelicaInstanceName, spawnExe=spawnExe, idfVersion=idfVersion, idfName=idfName, epwName=epwName, relativeSurfaceTolerance=relativeSurfaceTolerance, epName=name, usePrecompiledFMU=usePrecompiledFMU, fmuName=fmuName, buildingsRootFileLocation=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.buildingsRootFileLocation, logLevel=logLevel, printUnit=false, jsonName="schedules", jsonKeysValues=" \"name\": \""+name+"\", \"unit\": \""+unitString+"\", \"fmiName\": \""+name+"_"+modelicaInstanceName+"\"", parOutNames=fill("",nParOut), parOutUnits=fill("",nParOut), nParOut=nParOut, inpNames={modelicaInstanceName}, inpUnits={unitString}, nInp=nInp, outNames=fill("",nOut), outUnits=fill("",nOut), nOut=nOut, derivatives_structure=fill(fill(nDer,2),nDer), nDer=nDer, derivatives_delta=fill(0,nDer)) "Class to communicate with EnergyPlus"; Real yEP[nY] "Output of exchange function"; initial equation assert( not usePrecompiledFMU, "Use of pre-compiled FMU is not supported for block Schedule."); nObj=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.initialize( adapter=adapter, isSynchronized=building.isSynchronized); equation yEP=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.exchange( adapter=adapter, nY=nY, u={u,round(time,1E-3)}, dummy=nObj); y=yEP[1]; nObj=synBui.synchronize.done; end Schedule;

Buildings.ThermalZones.EnergyPlus_9_6_0.ThermalZone Buildings.ThermalZones.EnergyPlus_9_6_0.ThermalZone

Model to connect to an EnergyPlus thermal zone

Buildings.ThermalZones.EnergyPlus_9_6_0.ThermalZone

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_9_6_0.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_9_6_0.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_9_6_0.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.

The zone has a fluid port fluPor that can be used to connect one or several HVAC inlets, flow paths for air infiltration and exfiltration, or for interzonal air exchange, using for example models from Buildings.Airflow.Multizone.

The model also has a heat port heaPorAir that connects to the sensible heat balance of the room air, and a heat port heaPorRad that connects to the radiative heat balance of the room inside surfaces. If heat is added to heaPorRad.Q_flow, then this heat is sent to EnergyPlus as if it were a radiant heat gain of the zone. The heat port temperature heaPorRad.T is the radiant temperature of the room. Hence, these two ports heatPorAir and heaPorRad could be used to connect a radiator. Note, however, that such a coupling is an approximation as the surface temperature of the radiator will not be reflected in the radiative temperature of the room. Also, read to section Notes about modeling components that are connected to the radiative heat port below.

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/m2 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.)

Notes about modeling components that are connected to the radiative heat port

Models in which a component is connected to the radiative heat port heaPorRad may cause convergence problems during the initialization of the simulation if that component computes the radiative heat exchange heaPorRad.Q_flow based on the temperature heaPorRad.T, and if the parameter building.setInitialRadiativeHeatGainToZero is changed from its default value true. It is therefore recommended to leave the parameter setInitialRadiativeHeatGainToZero at its default value true. This sets the radiative heat flow rate sent from Modelica to EnergyPlus to zero during the initialization of the model, thereby avoiding a potential nonlinear system of equations that may give convergence problems. This only affects the initialization of the model but not the time integration, hence the error should be small for typical models.

If you decide to set setInitialRadiativeHeatGainToZero = false, you need to be aware of the following: If setInitialRadiativeHeatGainToZero = false, then the radiative heat gain from the model input is being used. If this radiative heat gain depends on the radiative temperature that is an output of the EnergyPlus model, a nonlinear equation is formed. Because in EnergyPlus, computing the radiative temperature involves an iterative solution, this can cause convergence problems due to having two nested solvers, the outer being the Modelica solver that solves for the radiative heat flow rate QGaiRad_flow, and the innner being the EnergyPlus solver that solves for the radiative temperature TRad. Hence, we recommend to leave building.setInitialRadiativeHeatGainToZero = true.

If you decide to set building.setInitialRadiativeHeatGainToZero = false, you may need to also tighten the tolerance of the EnergyPlus solver by tightening building.relativeSurfaceTolerance, but one cannot assure that the nested nonlinear equations converge.

Because a Modelica model does not have knowledge of the solver tolerance, automatically tightening building.relativeSurfaceTolerance as a function of the Modelica solver tolerance is not possible.

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

Parameters

TypeNameDefaultDescription
StringzoneName Name of the thermal zone as specified in the EnergyPlus input
replaceable package MediumModelica.Media.Interfaces.Pa...Medium in the component
Ports
Booleanuse_C_flowfalseSet to true to enable input connector for trace substance that is connected to room air
Initialization
AbsolutePressurep_startMedium.p_defaultStart value of zone air pressure [Pa]
TemperatureT_startMedium.T_defaultStart value of zone air temperature [K]
MassFractionX_start[Medium.nX]Medium.X_defaultStart value of zone air mass fractions m_i/m [kg/kg]
ExtraPropertyC_start[Medium.nC]fill(0, Medium.nC)Start value of zone air trace substances
ExtraPropertyC_nominal[Medium.nC]fill(1E-2, Medium.nC)Nominal value of zone air trace substances. (Set to typical order of magnitude.)

Connectors

TypeNameDescription
replaceable package MediumMedium in the component
input RealInputqGai_flow[3]Radiant, convective sensible and latent heat input into room (positive if heat gain) [W/m2]
input RealInputC_flow[Medium.nC]Trace substance mass flow rate added to the medium
HeatPort_aheaPorAirHeat port to air volume
HeatPort_aheaPorRadHeat port to radiative temperature and radiative energy balance
VesselFluidPorts_bports[nPorts]Fluid inlets and outlets
output RealOutputTAirAir temperature of the zone [K]
output RealOutputTRadRadiative temperature of the zone [K]
output RealOutputphiRelative humidity [1]

Modelica definition

model ThermalZone "Model to connect to an EnergyPlus thermal zone" extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.PartialEnergyPlusObject; parameter String zoneName "Name of the thermal zone as specified in the EnergyPlus input"; parameter Integer nPorts=0 "Number of fluid ports (equals to 2 for one inlet and one outlet)"; //////////////////////////////////////////////////////////////////////////// // Media declaration. This is identical to // Buildings.Fluid.Interfaces.LumpedVolumeDeclarations, except // that the comments have been changed to avoid a confusion about // what energyDynamics refers to. replaceable package Medium=Modelica.Media.Interfaces.PartialMedium "Medium in the component"; // Ports parameter Boolean use_C_flow=false "Set to true to enable input connector for trace substance that is connected to room air"; // Initialization parameter Medium.AbsolutePressure p_start=Medium.p_default "Start value of zone air pressure"; parameter Medium.Temperature T_start=Medium.T_default "Start value of zone air temperature"; parameter Medium.MassFraction X_start[Medium.nX]( quantity=Medium.substanceNames)=Medium.X_default "Start value of zone air mass fractions m_i/m"; parameter Medium.ExtraProperty C_start[Medium.nC]( quantity=Medium.extraPropertiesNames)=fill( 0, Medium.nC) "Start value of zone air trace substances"; parameter Medium.ExtraProperty C_nominal[Medium.nC]( quantity=Medium.extraPropertiesNames)=fill( 1E-2, Medium.nC) "Nominal value of zone air trace substances. (Set to typical order of magnitude.)"; final parameter Modelica.Units.SI.Volume V=fmuZon.V "Zone volume"; final parameter Modelica.Units.SI.Area AFlo=fmuZon.AFlo "Floor area"; final parameter Real mSenFac( min=1)=fmuZon.mSenFac "Factor for scaling the sensible thermal mass of the zone air volume"; Modelica.Blocks.Interfaces.RealInput qGai_flow[3]( each unit="W/m2") "Radiant, convective sensible and latent heat input into room (positive if heat gain)"; Modelica.Blocks.Interfaces.RealInput[Medium.nC] C_flow if use_C_flow "Trace substance mass flow rate added to the medium"; Modelica.Thermal.HeatTransfer.Interfaces.HeatPort_a heaPorAir "Heat port to air volume"; Modelica.Thermal.HeatTransfer.Interfaces.HeatPort_a heaPorRad "Heat port to radiative temperature and radiative energy balance"; Modelica.Fluid.Vessels.BaseClasses.VesselFluidPorts_b ports[nPorts]( redeclare each package Medium=Medium) "Fluid inlets and outlets"; Modelica.Blocks.Interfaces.RealOutput TAir( final unit="K", displayUnit="degC") "Air temperature of the zone"; Modelica.Blocks.Interfaces.RealOutput TRad( final unit="K", displayUnit="degC") "Radiative temperature of the zone"; Modelica.Blocks.Interfaces.RealOutput phi( final unit="1") "Relative humidity"; protected constant Modelica.Units.SI.SpecificEnergy h_fg=Medium.enthalpyOfCondensingGas( 273.15 + 37) "Latent heat of water vapor"; final parameter Modelica.Units.SI.MassFlowRate m_flow_nominal=V*3/3600 "Nominal mass flow rate (used for regularization)"; final parameter Boolean setInitialRadiativeHeatGainToZero = building.setInitialRadiativeHeatGainToZero "If true, then the radiative heat gain sent from Modelica to EnergyPlus is zero during the model initialization"; Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.ThermalZoneAdapter fmuZon( final modelicaNameBuilding=modelicaNameBuilding, final modelicaInstanceName=modelicaInstanceName, final spawnExe=spawnExe, final idfVersion=idfVersion, final idfName=idfName, final epwName=epwName, final relativeSurfaceTolerance=relativeSurfaceTolerance, final setInitialRadiativeHeatGainToZero=setInitialRadiativeHeatGainToZero, final zoneName=zoneName, final nFluPor=nPorts, final usePrecompiledFMU=usePrecompiledFMU, final fmuName=fmuName, final logLevel=logLevel) "FMU zone adapter"; Buildings.Fluid.Interfaces.ConservationEquation vol( redeclare final package Medium=Medium, final energyDynamics=Modelica.Fluid.Types.Dynamics.FixedInitial, final massDynamics=Modelica.Fluid.Types.Dynamics.FixedInitial, final p_start=p_start, final T_start=T_start, final X_start=X_start, final C_start=C_start, final C_nominal=C_nominal, final mSenFac=mSenFac, final use_mWat_flow=Medium.nXi > 0, final use_C_flow=use_C_flow, final fluidVolume=V, final nPorts=nPorts) "Air volume of the thermal zone"; Buildings.ThermalZones.Detailed.BaseClasses.HeatGain heaGai( final AFlo=AFlo) "Model to convert internal heat gains"; Modelica.Blocks.Math.Gain mWat_flow( final k( unit="kg/J")=1/h_fg, u(final unit="W"), y(final unit="kg/s")) "Water flow rate due to latent heat gain"; Modelica.Blocks.Math.Add QLat_flow(final k1=1, final k2=1) "Total latent heat gains of the zone"; Modelica.Blocks.Math.Add QGaiSenLat_flow( final k1=1, final k2=1) "Sensible and latent heat gains of the zone"; Modelica.Blocks.Math.Add QConSen_flow( final k1=1, final k2=1) "Convective sensible heat gains of the zone from EnergyPlus and Modelica input connector qGai_flow"; Buildings.HeatTransfer.Sources.PrescribedHeatFlow conQCon_flow "Converter for convective heat flow rate"; final parameter String substanceName="CO2" "Name of trace substance"; final parameter Modelica.Units.SI.MolarMass MM=Modelica.Media.IdealGases.Common.SingleGasesData.CO2.MM "Molar mass of the trace substance"; Modelica.Blocks.Routing.Replicator QPeaRep( nout=Medium.nC) if use_C_flow "Replicator to convert QPea_flow into a vector"; Modelica.Blocks.Math.Add CTot_flow[Medium.nC]( each final k1=1, final k2={ if (Modelica.Utilities.Strings.isEqual( string1=Medium.extraPropertiesNames[i], string2=substanceName, caseSensitive=false)) then 3.82E-8*Modelica.Media.IdealGases.Common.SingleGasesData.CO2.MM/Modelica.Media.IdealGases.Common.SingleGasesData.Air.MM else 0 for i in 1:Medium.nC}, u1( each final unit="W")) if use_C_flow "Total trace substance flow rate"; Buildings.Fluid.Sensors.MassFlowRate senMasFlo[nPorts]( redeclare each final package Medium=Medium, each final allowFlowReversal=true) "Mass flow rate sensor"; Modelica.Blocks.Sources.RealExpression TAirIn[nPorts]( y=Medium.temperature( state=Medium.setState_phX( p=ports.p, h=inStream(ports.h_outflow), X=inStream(ports.Xi_outflow)))) if nPorts > 0 "Temperature that the air has if it were flowing into the room"; Modelica.Thermal.HeatTransfer.Sensors.HeatFlowSensor heaFloSen "Heat flow sensor"; Buildings.HeatTransfer.Sources.PrescribedTemperature preTem "Port temperature"; Modelica.Blocks.Sources.RealExpression TFlu( y=Medium.temperature_phX( p=vol.medium.p, h=vol.hOut, X=cat(1,vol.XiOut,{1-sum(vol.XiOut)}))) "Air temperature of control volume"; Modelica.Blocks.Sources.RealExpression pFlu( y=vol.medium.p) "Air pressure"; Utilities.Psychrometrics.Phi_pTX relHum "Relative humidity"; Controls.OBC.CDL.Reals.Divide X_w "Water vapor mass fraction per kg total air"; HeatTransfer.Sources.PrescribedTemperature preRadTem "Prescribed radiative temperature"; Modelica.Thermal.HeatTransfer.Sensors.HeatFlowSensor radHeaFloSen "Radiative heat flow sensor"; Modelica.Blocks.Math.Add QRad_flow( final k1=1, final k2=1, u1(final unit="W"), u2(final unit="W"), y(final unit="W")) "Total radiant heat gains of the zone"; initial equation assert( idfName <> "", "Must provide the name of the fmu file."); assert( zoneName <> "", "Must provide the name of the zone."); // assert(nPorts >= 2, "The zone must have at least one air inlet and outlet."); equation connect(heaGai.qGai_flow,qGai_flow); connect(fmuZon.TRad,TRad); connect(QGaiSenLat_flow.u1,QConSen_flow.y); connect(QGaiSenLat_flow.u2, QLat_flow.y); connect(QGaiSenLat_flow.y,conQCon_flow.Q_flow); connect(conQCon_flow.port,heaPorAir); connect(QLat_flow.y, mWat_flow.u); connect(mWat_flow.y,vol.mWat_flow); connect(CTot_flow.y,vol.C_flow); connect(C_flow,CTot_flow.u1); for i in 1:nPorts loop connect(ports[i],senMasFlo[i].port_a); connect(fmuZon.m_flow[i],senMasFlo[i].m_flow); connect(senMasFlo[i].port_b,vol.ports[i]); end for; connect(fmuZon.TInlet,TAirIn.y); connect(TFlu.y,preTem.T); connect(heaFloSen.port_b,preTem.port); connect(heaFloSen.port_a,heaPorAir); connect(TFlu.y,fmuZon.T); connect(TFlu.y,TAir); connect(heaFloSen.Q_flow,vol.Q_flow); connect(vol.XiOut[1],fmuZon.X_w); connect(X_w.y,relHum.X_w); connect(vol.mXiOut[1],X_w.u1); connect(vol.mOut,X_w.u2); connect(TFlu.y,relHum.T); connect(pFlu.y,relHum.p); connect(relHum.phi,phi); connect(QPeaRep.y,CTot_flow.u2); connect(QPeaRep.u,fmuZon.QPeo_flow); connect(QConSen_flow.u2,heaGai.QCon_flow); connect(fmuZon.QCon_flow,QConSen_flow.u1); connect(fmuZon.QLat_flow, QLat_flow.u1); connect(heaGai.QLat_flow, QLat_flow.u2); connect(radHeaFloSen.port_b, preRadTem.port); connect(radHeaFloSen.port_a, heaPorRad); connect(fmuZon.TRad, preRadTem.T); connect(fmuZon.QGaiRad_flow, QRad_flow.y); connect(QRad_flow.u1, heaGai.QRad_flow); connect(QRad_flow.u2, radHeaFloSen.Q_flow); end ThermalZone;

Buildings.ThermalZones.EnergyPlus_9_6_0.ZoneSurface Buildings.ThermalZones.EnergyPlus_9_6_0.ZoneSurface

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

Buildings.ThermalZones.EnergyPlus_9_6_0.ZoneSurface

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

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_9_6_0.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_9_6_0.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_9_6_0.Examples.SingleFamilyHouse.HeatPumpRadiantHeatingGroundHeatTransfer illustrates this use. Note that if the ground heat transfer were modeled in EnergyPlus, then Buildings.ThermalZones.EnergyPlus_9_6_0.OpaqueConstruction should have been used, which is simpler to setup.

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

Parameters

TypeNameDefaultDescription
StringsurfaceName Surface unique name in the EnergyPlus idf file

Connectors

TypeNameDescription
input RealInputTSurface temperature [K]
output RealOutputQ_flowNet heat flow rate from the thermal zone to the surface (positive if surface is cold) [W]
output RealOutputq_flowNet heat flux from the thermal zone to the surface (positive if surface is cold) [W/m2]

Modelica definition

model ZoneSurface "Model to exchange heat with a inside-facing surface of a thermal zone" extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.PartialEnergyPlusObject; extends Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.Synchronize.ObjectSynchronizer; parameter String surfaceName "Surface unique name in the EnergyPlus idf file"; final parameter Modelica.Units.SI.Area A(final fixed=false, min=1E-10) "Surface area"; Modelica.Blocks.Interfaces.RealInput T( final unit="K", displayUnit="degC", final quantity="ThermodynamicTemperature") "Surface temperature"; Modelica.Blocks.Interfaces.RealOutput Q_flow( final unit="W", final quantity="Power") "Net heat flow rate from the thermal zone to the surface (positive if surface is cold)"; Modelica.Blocks.Interfaces.RealOutput q_flow( final unit="W/m2", final quantity="HeatFlux") "Net heat flux from the thermal zone to the surface (positive if surface is cold)"; protected constant Integer nParOut=1 "Number of parameter values retrieved from EnergyPlus"; constant Integer nInp=1 "Number of inputs"; constant Integer nOut=1 "Number of outputs"; constant Integer nDer=0 "Number of derivatives"; constant Integer nY=nOut+nDer+1 "Size of output vector of exchange function"; parameter Integer nObj( fixed=false, start=0) "Total number of Spawn objects in building"; Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject adapter=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.SpawnExternalObject( objectType=5, startTime=startTime, modelicaNameBuilding=modelicaNameBuilding, modelicaInstanceName=modelicaInstanceName, spawnExe=spawnExe, idfVersion=idfVersion, idfName=idfName, epwName=epwName, relativeSurfaceTolerance=relativeSurfaceTolerance, epName=surfaceName, usePrecompiledFMU=usePrecompiledFMU, fmuName=fmuName, buildingsRootFileLocation=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.buildingsRootFileLocation, logLevel=logLevel, printUnit=false, jsonName="zoneSurfaces", jsonKeysValues=" \"name\": \""+surfaceName+"\"", parOutNames={"A"}, parOutUnits={"m2"}, nParOut=nParOut, inpNames={"T"}, inpUnits={"K"}, nInp=nInp, outNames={"Q_flow"}, outUnits={"W"}, nOut=nOut, derivatives_structure=fill(fill(nDer,2),nDer), nDer=nDer, derivatives_delta=fill(0,nDer)) "Class to communicate with EnergyPlus"; ////////// // The derivative structure was: // derivatives_structure={{1,1}}, // nDer=nDer, // derivatives_delta={0.1} // This has been removed due to numerical noise, // see https://github.com/lbl-srg/modelica-buildings/issues/2358#issuecomment-819578850 ////////// Real yEP[nY] "Output of exchange function"; Modelica.Units.SI.Time tNext(start=startTime, fixed=true) "Next sampling time"; discrete Modelica.Units.SI.Time tLast(fixed=true, start=startTime) "Last time of data exchange"; discrete Modelica.Units.SI.Time dtLast "Time step since the last synchronization"; discrete Modelica.Units.SI.Temperature TLast "Surface temperature at last sampling"; discrete Modelica.Units.SI.HeatFlowRate QLast_flow(fixed=false, start=0) "Surface heat flow rate if T = TLast"; // discrete Real dQ_flow_dT( // final unit="W/K") // "Derivative dQCon_flow / dT"; initial equation assert( not usePrecompiledFMU, "Use of pre-compiled FMU is not supported for ZoneSurface."); nObj=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.initialize( adapter=adapter, isSynchronized=building.isSynchronized); {A}=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.getParameters( adapter=adapter, nParOut=nParOut, isSynchronized=nObj); assert( A > 0, "Surface area must not be zero."); equation when {initial(),time >= pre(tNext)} then // Initialization of output variables. TLast=T; dtLast=time-pre(tLast); yEP=Buildings.ThermalZones.EnergyPlus_9_6_0.BaseClasses.exchange( adapter=adapter, nY=nY, u={T,round(time,1E-3)}, dummy=A); QLast_flow=yEP[1]; //dQ_flow_dT=yEP[2]; //tNext=yEP[3]; tNext=yEP[2]; tLast=time; end when; //Q_flow=QLast_flow+(T-TLast)*dQ_flow_dT; Q_flow=QLast_flow; q_flow=Q_flow/A; nObj=synBui.synchronize.done; end ZoneSurface;