Buildings.ThermalZones.EnergyPlus.BaseClasses

Package with base classes for Buildings.ThermalZones.EnergyPlus

Information

This package contains base classes that are used to construct the models in Buildings.ThermalZones.EnergyPlus.

Extends from Modelica.Icons.BasesPackage (Icon for packages containing base classes).

Package Content

Name Description
Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject PartialEnergyPlusObject Partial definitions of an EnergyPlus object
Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject SpawnExternalObject Class used to couple the FMU to interact with a thermal zone
Buildings.ThermalZones.EnergyPlus.BaseClasses.ThermalZoneAdapter ThermalZoneAdapter Block that interacts with this EnergyPlus zone
Buildings.ThermalZones.EnergyPlus.BaseClasses.exchange exchange Exchange the values with the EnergyPlus thermal zone
Buildings.ThermalZones.EnergyPlus.BaseClasses.getParameters getParameters Get parameters for an EnergyPlus object
Buildings.ThermalZones.EnergyPlus.BaseClasses.getUnitAsString getUnitAsString Return the unit enumeration as a string
Buildings.ThermalZones.EnergyPlus.BaseClasses.initialize initialize Initialization for an EnergyPlus thermal zone
Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize Synchronize Package with classes to synchronize Spawn objects
buildingsLibraryRoot=Modelica.Utilities.Strings.substring(string=legalFileLocation, startIndex=1, endIndex=Modelica.Utilities.Strings.length(legalFileLocation) - 11) Root directory of the Buildings library (used to find the spawn executable)
legalFileLocation=Modelica.Utilities.Files.fullPathName(Modelica.Utilities.Files.loadResource("modelica://Buildings/legal.html")) Location of legal.html file (used to find the spawn executable)
Buildings.ThermalZones.EnergyPlus.BaseClasses.Validation Validation Collection of validation models

Types and constants

  constant String buildingsLibraryRoot=
    Modelica.Utilities.Strings.substring(
      string=legalFileLocation,
      startIndex=1,
      endIndex=Modelica.Utilities.Strings.length(legalFileLocation)-11)
    "Root directory of the Buildings library (used to find the spawn executable)";
  constant String legalFileLocation = Modelica.Utilities.Files.fullPathName(Modelica.Utilities.Files.loadResource("modelica://Buildings/legal.html"))
    "Location of legal.html file (used to find the spawn executable)";

Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject Buildings.ThermalZones.EnergyPlus.BaseClasses.PartialEnergyPlusObject

Partial definitions of an EnergyPlus object

Information

Partial model for an EnergyPlus object.

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

Modelica definition

partial block PartialEnergyPlusObject "Partial definitions of an EnergyPlus object" extends Modelica.Blocks.Icons.Block; outer Buildings.ThermalZones.EnergyPlus.Building building "Building-level declarations"; protected constant String modelicaNameBuilding=building.modelicaNameBuilding "Name of the building to which this output variable belongs to"; constant String modelicaInstanceName=getInstanceName() "Name of this instance"; final parameter String idfName=building.idfName "Name of the IDF file that contains this zone"; final parameter String weaName=building.weaName "Name of the EnergyPlus weather file (but with mos extension)"; final parameter Real relativeSurfaceTolerance=building.relativeSurfaceTolerance "Relative tolerance of surface temperature calculations"; final parameter Boolean usePrecompiledFMU=building.usePrecompiledFMU "Set to true to use pre-compiled FMU with name specified by fmuName"; final parameter String fmuName=building.fmuName "Specify if a pre-compiled FMU should be used instead of EnergyPlus (mainly for development)"; final parameter Buildings.ThermalZones.EnergyPlus.Types.LogLevels logLevel=building.logLevel "LogLevels of EnergyPlus output"; parameter Modelica.SIunits.Time startTime( fixed=false) "Simulation start time"; function round input Real u; input Real accuracy; output Real y; algorithm y := if (u > 0) then floor( u/accuracy+0.5)*accuracy else ceil( u/accuracy-0.5)*accuracy; end round; initial equation startTime=time; end PartialEnergyPlusObject;

Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject

Class used to couple the FMU to interact with a thermal zone

Information

Class derived from ExternalObject having two local external function definition, named destructor and constructor respectively.

These functions create and release an external object that allows the storage of the data structure needed to communicate with the EnergyPlus FMU.

Extends from ExternalObject.

Modelica definition

class SpawnExternalObject "Class used to couple the FMU to interact with a thermal zone" extends ExternalObject; function constructor "Construct to connect to a thermal zone in EnergyPlus" extends Modelica.Icons.Function; input Integer objectType "Type of the object (1: ThermalZone, 2: Schedule, 3: Actuator, 4: Surface)"; input Modelica.SIunits.Time startTime "Start time of the simulation"; input String modelicaNameBuilding "Name of this Modelica building instance that connects to this thermal zone"; input String modelicaInstanceName "Name of the Modelica instance of this object"; input String idfName "Name of the IDF"; input String weaName "Name of the weather file"; input Real relativeSurfaceTolerance "Relative tolerance of surface temperature calculations"; input String epName "Name of the object in EnergyPlus"; input Boolean usePrecompiledFMU "Set to true to use precompiled FMU with name specified by input fmuName"; input String fmuName "Specify if a pre-compiled FMU should be used instead of EnergyPlus (mainly for development)"; input String buildingsLibraryRoot "Root directory of the Buildings library (used to find the spawn executable)"; input Buildings.ThermalZones.EnergyPlus.Types.LogLevels logLevel "LogLevels of EnergyPlus output"; input Boolean printUnit "Set to true to print units for OutputVariable object. Must be false for all other objects"; input String jsonName "Name of the object in the json configuration file"; input String jsonKeysValues "Keys and values string to be written to the json configuration file"; input String parOutNames[nParOut] "Names of parameter in modelDescription.xml file"; input String parOutUnits[nParOut] "Modelica units of the parameters"; input Integer nParOut "Number of parameters"; input String inpNames[nInp] "Names of inputs in modelDescription.xml file"; input String inpUnits[nInp] "Modelica units of the inputs"; input Integer nInp "Size of inpNames"; input String outNames[nOut] "Names of outputs in modelDescription.xml file"; input String outUnits[nOut] "Modelica units of the outputs"; input Integer nOut "Size of outNames"; input Integer derivatives_structure[nDer,2] "List of derivatives (1-based index, [i,j] means dy_i/du_j"; input Integer nDer "Size of derivatives"; input Real derivatives_delta[nDer] "Increments for derivative calculation"; output SpawnExternalObject adapter; external "C" adapter=ModelicaSpawnAllocate( objectType, startTime, modelicaNameBuilding, modelicaInstanceName, idfName, weaName, relativeSurfaceTolerance, epName, usePrecompiledFMU, fmuName, buildingsLibraryRoot, logLevel, printUnit, jsonName, jsonKeysValues, parOutNames, nParOut, parOutUnits, nParOut, inpNames, nInp, inpUnits, nInp, outNames, nOut, outUnits, nOut, derivatives_structure, 2, nDer, derivatives_delta, nDer); end constructor; function destructor "Release storage" extends Modelica.Icons.Function; input SpawnExternalObject adapter; external "C" ModelicaSpawnFree(adapter); end destructor; end SpawnExternalObject;

Buildings.ThermalZones.EnergyPlus.BaseClasses.ThermalZoneAdapter Buildings.ThermalZones.EnergyPlus.BaseClasses.ThermalZoneAdapter

Block that interacts with this EnergyPlus zone

Buildings.ThermalZones.EnergyPlus.BaseClasses.ThermalZoneAdapter

Information

Block that exchanges data between Modelica and EnergyPlus. This block is calling the C functions to initialize EnergyPlus, exchange data with EnergyPlus, and free the memory, through the destructor of its class adapter, of EnergyPlus.

Extends from Modelica.Blocks.Icons.Block (Basic graphical layout of input/output block), Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer (Block that synchronizes an object).

Parameters

TypeNameDefaultDescription
StringmodelicaNameBuilding Name of the building to which this thermal zone belongs to
StringidfName Name of the IDF file that contains this zone
StringweaName Name of the Energyplus weather file
RealrelativeSurfaceTolerance Relative tolerance of surface temperature calculations
StringzoneName Name of the thermal zone as specified in the EnergyPlus input
IntegernFluPor Number of fluid ports (Set to 2 for one inlet and one outlet)
Debug
BooleanusePrecompiledFMUfalseSet to true to use pre-compiled FMU with name specified by fmuName
StringfmuName""Specify if a pre-compiled FMU should be used instead of EnergyPlus (mainly for development)
LogLevelslogLevelBuildings.ThermalZones.Energ...LogLevels of EnergyPlus output

Connectors

TypeNameDescription
input RealInputTZone air temperature [K]
input RealInputX_wZone air mass fraction in kg/kg total air [kg/kg]
input RealInputm_flow[nFluPor]Mass flow rate [kg/s]
input RealInputTInlet[nFluPor]Air inlet temperatures [K]
input RealInputQGaiRad_flowRadiative heat gain [W]
output RealOutputTRadRadiative temperature [K]
output RealOutputQCon_flowConvective sensible heat to be added to zone air [W]
output RealOutputQLat_flowLatent heat to be added to zone air [W]
output RealOutputQPeo_flowTotal heat gain from people, to be used for optional computation of CO2 released [W]

Modelica definition

model ThermalZoneAdapter "Block that interacts with this EnergyPlus zone" extends Modelica.Blocks.Icons.Block; extends Buildings.ThermalZones.EnergyPlus.BaseClasses.Synchronize.ObjectSynchronizer; constant String modelicaNameBuilding "Name of the building to which this thermal zone belongs to"; constant String modelicaInstanceName=getInstanceName() "Name of this instance"; parameter String idfName "Name of the IDF file that contains this zone"; parameter String weaName "Name of the Energyplus weather file"; parameter Real relativeSurfaceTolerance "Relative tolerance of surface temperature calculations"; parameter String zoneName "Name of the thermal zone as specified in the EnergyPlus input"; parameter Boolean usePrecompiledFMU=false "Set to true to use pre-compiled FMU with name specified by fmuName"; parameter String fmuName="" "Specify if a pre-compiled FMU should be used instead of EnergyPlus (mainly for development)"; parameter Buildings.ThermalZones.EnergyPlus.Types.LogLevels logLevel=Buildings.ThermalZones.EnergyPlus.Types.LogLevels.Warning "LogLevels of EnergyPlus output"; parameter Integer nFluPor "Number of fluid ports (Set to 2 for one inlet and one outlet)"; final parameter Modelica.SIunits.Area AFlo( fixed=false) "Floor area"; final parameter Modelica.SIunits.Volume V( fixed=false) "Zone volume"; final parameter Real mSenFac( fixed=false) "Factor for scaling the sensible thermal mass of the zone air volume"; Modelica.Blocks.Interfaces.RealInput T( final unit="K", displayUnit="degC") "Zone air temperature"; Modelica.Blocks.Interfaces.RealInput X_w( final unit="kg/kg") "Zone air mass fraction in kg/kg total air"; Modelica.Blocks.Interfaces.RealInput m_flow[nFluPor]( each final unit="kg/s") "Mass flow rate"; Modelica.Blocks.Interfaces.RealInput TInlet[nFluPor]( each final unit="K", each displayUnit="degC") "Air inlet temperatures"; Modelica.Blocks.Interfaces.RealInput QGaiRad_flow( final unit="W") "Radiative heat gain"; Modelica.Blocks.Interfaces.RealOutput TRad( final unit="K", displayUnit="degC") "Radiative temperature"; Modelica.Blocks.Interfaces.RealOutput QCon_flow( final unit="W") "Convective sensible heat to be added to zone air"; Modelica.Blocks.Interfaces.RealOutput QLat_flow( final unit="W") "Latent heat to be added to zone air"; Modelica.Blocks.Interfaces.RealOutput QPeo_flow( final unit="W") "Total heat gain from people, to be used for optional computation of CO2 released"; protected constant Integer nParOut=3 "Number of parameter values retrieved from EnergyPlus"; constant Integer nInp=5 "Number of inputs"; constant Integer nOut=4 "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"; parameter Modelica.SIunits.MassFlowRate m_flow_small( fixed=false) "Small mass flow rate used to avoid TAveInlet = 0"; Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject adapter=Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject( objectType=1, startTime=startTime, modelicaNameBuilding=modelicaNameBuilding, modelicaInstanceName=modelicaInstanceName, idfName=idfName, weaName=weaName, relativeSurfaceTolerance=relativeSurfaceTolerance, epName=zoneName, usePrecompiledFMU=usePrecompiledFMU, fmuName=fmuName, buildingsLibraryRoot=Buildings.ThermalZones.EnergyPlus.BaseClasses.buildingsLibraryRoot, logLevel=logLevel, printUnit=false, jsonName="zones", jsonKeysValues=" \"name\": \""+zoneName+"\"", parOutNames={"AFlo","V","mSenFac"}, parOutUnits={"m2","m3","1"}, nParOut=nParOut, inpNames={"T","X","mInlets_flow","TAveInlet","QGaiRad_flow"}, inpUnits={"K","1","kg/s","K","W"}, nInp=nInp, outNames={"TRad","QConSen_flow","QLat_flow","QPeo_flow"}, outUnits={"K","W","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={{2,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 ////////// parameter Modelica.SIunits.Time startTime( fixed=false) "Simulation start time"; Real yEP[nY] "Output of exchange function"; Modelica.SIunits.Time tNext( start=startTime, fixed=true) "Next sampling time"; //Modelica.SIunits.Time tNextEP(start=startTime-1, fixed=true) "Next sampling time requested from EnergyPlus"; // constant Real dT_dtMax(unit="K/s") = 0.000001 "Bound on temperature derivative to reduce or increase time step"; // Modelica.SIunits.Time dtMax(displayUnit="min", start=600, fixed=true) "Maximum time step before next sampling"; discrete Modelica.SIunits.Time tLast( fixed=true, start=startTime) "Last time of data exchange"; discrete Modelica.SIunits.Time dtLast "Time step since the last synchronization"; discrete Modelica.SIunits.MassFlowRate mInlet_flow "Time averaged inlet mass flow rate"; discrete Modelica.SIunits.Temperature TAveInlet "Time averaged inlet temperature"; discrete Modelica.SIunits.Temperature TRooLast "Room air temperature at last sampling"; // discrete Real dQCon_flow_dT( // final unit="W/K") // "Derivative dQCon_flow / dT"; discrete Modelica.SIunits.HeatFlowRate QConLast_flow( fixed=false, start=0) "Convective sensible heat to be added to zone air if T = TRooLast"; function round input Real u; input Real accuracy; output Real y; algorithm y := if (u > 0) then floor( u/accuracy+0.5)*accuracy else ceil( u/accuracy-0.5)*accuracy; end round; initial equation if usePrecompiledFMU then assert( Modelica.Utilities.Strings.length(fmuName) > 1, "If usePrecompiledFMU = true, must set parameter fmuName"); end if; startTime=time; nObj=Buildings.ThermalZones.EnergyPlus.BaseClasses.initialize( adapter=adapter, isSynchronized=building.isSynchronized); {AFlo,V,mSenFac}=Buildings.ThermalZones.EnergyPlus.BaseClasses.getParameters( adapter=adapter, nParOut=nParOut, isSynchronized=nObj); TAveInlet=293.15; m_flow_small=V*3*1.2/3600*1E-10; assert( AFlo > 0, "Floor area must not be zero."); assert( V > 0, "Volume must not be zero."); assert( mSenFac > 0.9999, "mSenFac must be bigger or equal than one."); equation if usePrecompiledFMU then // For JModelica, this must be in the equation section rather than the initial equation section assert( Modelica.Utilities.Strings.length(fmuName) > 1, "If usePrecompiledFMU = true, must set parameter fmuName"); end if; when {initial(),time >= pre(tNext)} then // Initialization of output variables. TRooLast=T; dtLast=time-pre(tLast); mInlet_flow=noEvent( sum( if m_flow[i] > 0 then m_flow[i] else 0 for i in 1:nFluPor)); TAveInlet=noEvent( (sum( if m_flow[i] > 0 then TInlet[i]*m_flow[i] else 0 for i in 1:nFluPor)+m_flow_small*pre(TAveInlet))/(mInlet_flow+m_flow_small)); // Below, the term X_w/(1.-X_w) is for conversion from kg/kg_total_air (Modelica) to kg/kg_dry_air (EnergyPlus) yEP=Buildings.ThermalZones.EnergyPlus.BaseClasses.exchange( adapter=adapter, initialCall=false, nY=nY, u={T,X_w/(1.-X_w),mInlet_flow,TAveInlet,QGaiRad_flow,round(time,1E-3)}, dummy=AFlo); TRad=yEP[1]; QConLast_flow=yEP[2]; QLat_flow=yEP[3]; QPeo_flow=yEP[4]; //dQCon_flow_dT=yEP[5]; //tNext=yEP[6]; tNext=yEP[5]; tLast=time; end when; //QCon_flow=QConLast_flow+(T-TRooLast)*dQCon_flow_dT; QCon_flow=QConLast_flow; synBui.synchronize.done=nObj; end ThermalZoneAdapter;

Buildings.ThermalZones.EnergyPlus.BaseClasses.exchange Buildings.ThermalZones.EnergyPlus.BaseClasses.exchange

Exchange the values with the EnergyPlus thermal zone

Information

External function that exchanges data with EnergyPlus.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

TypeNameDefaultDescription
SpawnExternalObjectadapter External object
BooleaninitialCall Set to true if initial() is true, false otherwise
IntegernY Size of output y
Realu[:] Input values. First all inputs, then the current model time
Realdummy Dummy value (used to force Modelica tools to call initialize())

Outputs

TypeNameDescription
Realy[nY]Output values. First all outputs, then all derivatives, then next event time

Modelica definition

function exchange "Exchange the values with the EnergyPlus thermal zone" extends Modelica.Icons.Function; input Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject adapter "External object"; input Boolean initialCall "Set to true if initial() is true, false otherwise"; input Integer nY "Size of output y"; input Real u[:] "Input values. First all inputs, then the current model time"; input Real dummy "Dummy value (used to force Modelica tools to call initialize())"; output Real y[nY] "Output values. First all outputs, then all derivatives, then next event time"; external "C" ModelicaSpawnExchange( adapter,initialCall,u,dummy,y); end exchange;

Buildings.ThermalZones.EnergyPlus.BaseClasses.getParameters Buildings.ThermalZones.EnergyPlus.BaseClasses.getParameters

Get parameters for an EnergyPlus object

Information

External function that obtains parameters from the EnergyPlus FMU and returns them to Modelica.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

TypeNameDefaultDescription
SpawnExternalObjectadapter External object
IntegernParOut Number of elements in parOut
RealisSynchronized Set to variable that is used to synchronize the objects

Outputs

TypeNameDescription
RealparOut[nParOut]Parameter values returned from EnergyPlus

Modelica definition

function getParameters "Get parameters for an EnergyPlus object" extends Modelica.Icons.Function; input Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject adapter "External object"; input Integer nParOut "Number of elements in parOut"; input Real isSynchronized "Set to variable that is used to synchronize the objects"; output Real parOut[nParOut] "Parameter values returned from EnergyPlus"; external "C" ModelicaSpawnGetParameters( adapter,isSynchronized,parOut); end getParameters;

Buildings.ThermalZones.EnergyPlus.BaseClasses.getUnitAsString Buildings.ThermalZones.EnergyPlus.BaseClasses.getUnitAsString

Return the unit enumeration as a string

Information

Function that returns the string representation of a unit enumeration from Buildings.ThermalZones.EnergyPlus.Types.Units.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

TypeNameDefaultDescription
Unitsunit Unit as enumeration value

Outputs

TypeNameDescription
StringunitAsStringString representation of the unit

Modelica definition

function getUnitAsString "Return the unit enumeration as a string" extends Modelica.Icons.Function; input Buildings.ThermalZones.EnergyPlus.Types.Units unit "Unit as enumeration value"; output String unitAsString "String representation of the unit"; algorithm unitAsString := if unit == Types.Units.Normalized then "1" elseif unit == Types.Units.AngleRad then "rad" elseif unit == Types.Units.AngleDeg then "deg" elseif unit == Types.Units.Energy then "J" elseif unit == Types.Units.Illuminance then "lm/m2" elseif unit == Types.Units.HumidityAbsolute then "kg/kg" elseif unit == Types.Units.HumidityRelative then "1" elseif unit == Types.Units.LuminousFlux then "cd.sr" elseif unit == Types.Units.MassFlowRate then "kg/s" elseif unit == Types.Units.Power then "W" elseif unit == Types.Units.Pressure then "Pa" elseif unit == Types.Units.Status then "1" elseif unit == Types.Units.Temperature then "K" elseif unit == Types.Units.Time then "s" elseif unit == Types.Units.VolumeFlowRate then "m3/s" else "error"; end getUnitAsString;

Buildings.ThermalZones.EnergyPlus.BaseClasses.initialize Buildings.ThermalZones.EnergyPlus.BaseClasses.initialize

Initialization for an EnergyPlus thermal zone

Information

External function that generates the EnergyPlus FMU.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

TypeNameDefaultDescription
SpawnExternalObjectadapter External object
RealisSynchronized Set to variable that is used to synchronize the objects

Outputs

TypeNameDescription
IntegernObjReturns 1 from C, used to force synchronization

Modelica definition

function initialize "Initialization for an EnergyPlus thermal zone" extends Modelica.Icons.Function; input Buildings.ThermalZones.EnergyPlus.BaseClasses.SpawnExternalObject adapter "External object"; input Real isSynchronized "Set to variable that is used to synchronize the objects"; output Integer nObj "Returns 1 from C, used to force synchronization"; external "C" ModelicaSpawnInitialize( adapter,isSynchronized,nObj); end initialize;