Buildings.ThermalZones.Detailed.UsersGuide

User's Guide

Information

The package Buildings.ThermalZones.Detailed contains models for heat transfer through the building envelope. Multiple instances of these models can be connected to create a multi-zone building model. To compute the air exchange between rooms and between a room and the exterior, the room models can be connected to multi-zone air exchange models from the package Buildings.Airflow. The room models can also be linked to models of HVAC systems that are composed of the components in the package Buildings.Fluid.

There are two different room models, one assumes the room air to be completely mixed, and the other implements a computuational fluid dynamic model to compute air flow, temperature and species distribution inside the room. These models are further described in their respective user's guide, Buildings.ThermalZones.Detailed.UsersGuide.MixedAir and Buildings.ThermalZones.Detailed.UsersGuide.CFD.

Modeling of conventional and electrochromic windows

Both models have the option of modeling electrochromic windows. The window properties are specified in a record Buildings.HeatTransfer.Data.GlazingSystems which contains for the glass layer the record Buildings.HeatTransfer.Data.Glasses. If any glass layer has multiple properties, then the glass is assumed to be controllable, and the room model will have an input connector uWin that is used for the control input signal of the glass. This connnector is a vector in which each element is a control signal, with value between 0 and 1, for a particular window. Hence, either all or none of the windows must be electrochromic. (If your room has a mixture of conventional and electrochromic windows, then set all windows to be electrochromic, but simply use a constant control signal for the conventional windows, and set it to the off-state.) If all windows are conventional, then the connector uWin is removed. However, its icon may still be visible as the visual rendering engine may not evaluate the equations that are needed to determine whether there are controllable windows.

The model Buildings.ThermalZones.Detailed.Examples.ElectroChromicWindow shows how to configure electrochromic windows.

Experimental settings

Both models have the option to time sample the heat transfer calculation. Setting the parameter sampleModel samples the radiative heat transfer with a sampling time of 2 minutes. This can give shorter simulation time if there is already a time sampling in the system model. This option is experimental and may be changed or removed in future versions.

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

Package Content

Name Description
Buildings.ThermalZones.Detailed.UsersGuide.MixedAir MixedAir Room model with instantaneously mixed air
Buildings.ThermalZones.Detailed.UsersGuide.CFD CFD Room model with air heat and mass balance computed using Computational Fluid Dynamics

Buildings.ThermalZones.Detailed.UsersGuide.MixedAir Buildings.ThermalZones.Detailed.UsersGuide.MixedAir

Room model with instantaneously mixed air

Information

The model Buildings.ThermalZones.Detailed.MixedAir is a model of a room with completely mixed air. The room can have any number of constructions and surfaces that participate in the heat exchange through convection, conduction, infrared radiation and solar radiation.

Physical description

A description of the model assumptions and the implemention and validation of this room model can be found in Wetter et al. (2011). Note that this paper describes a previous version of the room model. The equations have not changed. However, what is shown in Figure 2 in the paper has in this version of the model been integrated directly into what is shown in Figure 1.

The room models the following physical processes:

  1. Transient or steady-state heat conduction through opaque surfaces, using the model Buildings.HeatTransfer.Conduction.MultiLayer
  2. Heat transfer through glazing system, taking into account solar radiation, infrared radiation, heat conduction and heat convection. The solar radiation is modeled using Buildings.HeatTransfer.Windows.BaseClasses.WindowRadiation. The overall heat transfer is modeled using the model Buildings.HeatTransfer.Windows.Window for the glass assembly, and the models Buildings.HeatTransfer.Windows.ExteriorHeatTransfer, Buildings.HeatTransfer.Windows.InteriorHeatTransferConvective and Buildings.HeatTransfer.Windows.BaseClasses.ShadeRadiation for the exterior and interior heat transfer. A window can have both, an overhang and a side fin. Overhangs and side fins are modeled using Buildings.HeatTransfer.Windows.Overhang and Buildings.HeatTransfer.Windows.SideFins, respectively. These models compute the reduction in direct solar irradiation due to the external shading device.
  3. Convective heat transfer between the outside air and outside-facing surfaces using either a wind-speed, wind-direction and temperature-dependent heat transfer coefficient, or using a constant heat transfer coefficient, as described in Buildings.HeatTransfer.Convection.Exterior.
  4. Solar and infrared heat transfer between the room enclosing surfaces, convective heat transfer between the room enclosing surfaces and the room air, and temperature, pressure and species balance inside the room volume. These effects are modeled as follows:
    1. The model Buildings.ThermalZones.Detailed.BaseClasses.MixedAirHeatMassBalance is used to compute heat convection between the room air and the surface of opaque constructions. It is also used to compute the heat and mass balance of the room air. This model is a composite model that contains Buildings.HeatTransfer.Windows.InteriorHeatTransferConvective to compute the convective heat balance of the window and a shade, if present. The convective heat transfer coefficient can be selected to be either temperature-dependent or constant. The convective heat transfer is computed using Buildings.HeatTransfer.Convection.Interior. The heat and mass balance of the room air is computed using Buildings.Fluid.MixingVolumes.MixingVolume, which assumes the room air to be completely mixed. Depending on the medium model, moisture and species concentrations, such as CO2, can be modeled transiently.
    2. The latent heat gain of the room, which is a user-input, is converted to a moisture source using the model Buildings.ThermalZones.Detailed.BaseClasses.HeatGain.
    3. The radiant heat gains in the infrared spectrum are also a user input. They are distributed to the room enclosing surfaces using the model Buildings.ThermalZones.Detailed.BaseClasses.InfraredRadiationGainDistribution.
    4. The infrared radiative heat exchange between the room enclosing surfaces is modeled in Buildings.ThermalZones.Detailed.BaseClasses.InfraredRadiationExchange. This model takes into account the absorptivity of the surfaces and the surface area. However, the view factors are assumed to be proportional to the area of the receiving surface, without taking into account the location of the surfaces.
    5. The solar radiation exchange is modeled in Buildings.ThermalZones.Detailed.BaseClasses.SolarRadiationExchange. The assumptions in this model is that all solar radiation first hits the floor, and is then partially absorbed and partially reflected by the floor. The reflectance are diffuse, and the reflected radiation is distributed in proportion to the product of the receiving areas times their solar absorptivity.

Model instantiation

The next paragraphs describe how to instantiate a room model. To instantiate a room model,

  1. make an instance of the room model in your model,
  2. make instances of constructions from the package Buildings.HeatTransfer.Data.OpaqueConstructions to model opaque constructions such as walls, floors, ceilings and roofs,
  3. make an instance of constructions from the package Buildings.HeatTransfer.Data.GlazingSystems to model glazing systems, and
  4. enter the parameters of the room.

Entering parameters may be easiest in a textual editor.

In the here presented example, we assume we made several instances of data records for the construction material by dragging them from the package Buildings.HeatTransfer.Data to create the following list of declarations:

  Buildings.HeatTransfer.Data.OpaqueConstructions.Insulation100Concrete200
    matLayExt "Construction material for exterior walls"
    annotation (Placement(transformation(extent={{-60,140},{-40,160}})));
  Buildings.HeatTransfer.Data.OpaqueConstructions.Brick120 matLayPar 
    "Construction material for partition walls"
    annotation (Placement(transformation(extent={{-20,140},{0,160}})));
  Buildings.HeatTransfer.Data.OpaqueConstructions.Generic matLayRoo(
        material={
          HeatTransfer.Data.Solids.InsulationBoard(x=0.2),
          HeatTransfer.Data.Solids.Concrete(x=0.2)},
        final nLay=2) "Construction material for roof"
    annotation (Placement(transformation(extent={{20,140},{40,160}})));
  Buildings.HeatTransfer.Data.OpaqueConstructions.Generic matLayFlo(
        material={
          HeatTransfer.Data.Solids.Concrete(x=0.2),
          HeatTransfer.Data.Solids.InsulationBoard(x=0.1),
          HeatTransfer.Data.Solids.Concrete(x=0.05)},
        final nLay=3) "Construction material for floor"
    annotation (Placement(transformation(extent={{60,140},{80,160}})));
  Buildings.HeatTransfer.Data.GlazingSystems.DoubleClearAir13Clear glaSys(
    UFra=2,
    shade=Buildings.HeatTransfer.Data.Shades.Gray(),
    haveExteriorShade=false,
    haveInteriorShade=true) "Data record for the glazing system"
annotation (Placement(transformation(extent={{100,140},{120,160}})));

Note that construction layers are assembled from the outside to the room-side. Thus, the construction matLayRoo has an exterior insulation. This constructions can then be used in the room model.

Before we explain how to declare and parametrize a room model, we explain the different models that can be used to compute heat transfer through the room enclosing surfaces and constructions. The room model Buildings.ThermalZones.Detailed.MixedAir contains the constructions shown in the table below. The first row of the table lists the name of the data record that is used by the user to assign the model parameters. The second row lists the name of the instance of the model that simulates the equations. The third column provides a reference to the class definition that implements the equations. The forth column describes the main applicability of the model.

Record name Model instance name Class name Description of the model
datConExt modConExt Buildings.ThermalZones.Detailed.Constructions.Construction Exterior constructions that have no window.
datConExtWin modConExtWin Buildings.ThermalZones.Detailed.Constructions.ConstructionWithWindow Exterior constructions that have a window. Each construction of this type must have one window.
Within the same room, all windows can either have an interior shade, an exterior shade or no shade. Each window has its own control signal for the shade. This signal is exposed by the port uSha, which has the same dimension as the number of windows. The values for uSha must be between 0 and 1. Set uSha=0 to open the shade, and uSha=1 to close the shade.
Windows can also have an overhang, side fins, both (overhang and sidefins) or no external shading device.
datConPar modConPar Buildings.ThermalZones.Detailed.Constructions.Construction Interior constructions such as partitions within a room. Both surfaces of this construction are inside the room model and participate in the infrared and solar radiation balance. Since the view factor between these surfaces is zero, there is no infrared radiation from one surface to the other of the same construction.
datConBou modConBou Buildings.ThermalZones.Detailed.Constructions.Construction Constructions that expose the other boundary conditions of the other surface to the outside of this room model. The heat conduction through these constructions is modeled in this room model. The surface at the port opa_b is connected to the models for convection, infrared and solar radiation exchange with this room model and with the other surfaces of this room model. The surface at the port opa_a is connected to the port surf_conBou of this room model. This could be used, for example, to model a floor inside this room and connect to other side of this floor model to a model that computes heat transfer in the soil.
surBou N/A Buildings.HeatTransfer.Data.OpaqueSurfaces.Generic Opaque surfaces of this room model whose heat transfer through the construction is modeled outside of this room model. This object is modeled using a data record that contains the area, solar and infrared emissivities and surface tilt. The surface then participates in the convection and radiation heat balance of the room model. The heat flow rate and temperature of this surface are exposed at the heat port surf_surBou. An application of this object may be to connect the port surf_surBou of this room model with the port surf_conBou of another room model in order to couple two room models. Another application would be to model a radiant ceiling outside of this room model, and connect its surface to the port surf_conBou in order for the radiant ceiling model to participate in the heat balance of this room.

With these constructions, we may define a room as follows:

  Buildings.ThermalZones.Detailed.MixedAir roo(
    redeclare package Medium = MediumA,
    AFlo=6*4,
    hRoo=2.7,
    nConExt=2,
    datConExt(layers={matLayRoo, matLayExt},
           A={6*4, 6*3},
           til={Buildings.Types.Tilt.Ceiling, Buildings.Types.Tilt.Wall},
           azi={Buildings.Types.Azimuth.S, Buildings.Types.Azimuth.W}),
    nConExtWin=nConExtWin,
    datConExtWin(layers={matLayExt}, A={4*3},
              glaSys={glaSys},
              hWin={2},
              wWin={2},
              fFra={0.1},
              til={Buildings.Types.Tilt.Wall},
              azi={Buildings.Types.Azimuth.S}),
    nConPar=1,
    datConPar(layers={matLayPar}, each A=10,
           each til=Buildings.Types.Tilt.Wall),
    nConBou=1,
    datConBou(layers={matLayFlo}, each A=6*4,
           each til=Buildings.Types.Tilt.Floor),
    nSurBou=1,
    surBou(each A=6*3, each absIR=0.9, each absSol=0.9, each til=Buildings.Types.Tilt.Wall),
    linearizeRadiation = true ,
    energyDynamics=Modelica.Fluid.Types.Dynamics.FixedInitial,
    lat=0.73268921998722) "Room model"
    annotation (Placement(transformation(extent={{46,20},{86,60}})));

The following paragraphs explain the different declarations.

The statement

    redeclare package Medium = MediumA,
    AFlo=20,
    V=20*2.5,

declares that the medium of the room air is set to MediumA, that the floor area is 20 m2 and that the room air volume is 20*2.5 m3. The floor area is used to scale the internal heat gains, which are declared with units of W/m2 using the input signal qGai_flow.

The next entries specify constructions and surfaces that participate in the heat exchange.

The entry

    nConExt=2,

declares that there are two exterior constructions.

The lines

    datConExt(layers={matLayRoo, matLayExt},
           A={6*4, 6*3},
           til={Buildings.Types.Tilt.Ceiling, Buildings.Types.Tilt.Wall},
           azi={Buildings.Types.Azimuth.S, Buildings.Types.Azimuth.W}),

declare that the material layers in these constructions are set the records matLayRoo and matLayExt. What follows are the declarations for the surface area, the tilt of the surface and the azimuth of the surfaces. Thus, the surface with construction matLayExt is 6*3 m2 large and it is a west-facing wall.

Next, the declaration

    nConExtWin=nConExtWin,
    datConExtWin(layers={matLayExt}, A={4*3},
              glaSys={glaSys},
              hWin={2},
              wWin={2},
              fFra={0.1},
              til={Buildings.Types.Tilt.Wall},
              azi={Buildings.Types.Azimuth.S}),

declares the construction that contains a window. This construction is built using the materials defined in the record matLayExt. Its total area, including the window, is 4*3 m2. The glazing system is built using the construction defined in the record glaSys. The window area is hwin=2 m high and wwin=2 m wide. The ratio of frame to total glazing system area is 10%.

Optionally, each window can have an overhang, side fins or both. If the above window were to have an overhang of 2.5 m width that is centered above the window, and hence extends each side of the window by 0.25 m, and has a depth of 1 m and a gap between window and overhang of 0.1 m, then its declaration would be

              ove(wL={0.25}, wR={0.25}, gap={0.1}, dep={1}),

This line can be placed below the declaration of wWin. This would instanciate the model Buildings.HeatTransfer.Windows.Overhang to model the overhang. See this class for a picture of the above dimensions.

If the window were to have side fins that are 2.5 m high, measured from the bottom of the windows, and hence extends 0.5 m above the window, are 1 m depth and are placed 0.1 m to the left and right of the window, then its declaration would be

              sidFin(h={0.5}, gap={0.1}, dep={1}),

This would instanciate the model Buildings.HeatTransfer.Windows.SideFins to model the side fins. See this class for a picture of the above dimensions.

The lines

              til={Buildings.Types.Tilt.Wall},
              azi={Buildings.Types.Azimuth.S}),

declare that the construction is a wall that is south exposed.

Note that if the room were to have two windows, and one window has side fins and the other window has an overhang, the following declaration could be used, which sets the value of dep to 0 for the non-present side fins or overhang, respectively:

              sidFin(h  = {0.5, 0}, gap = {0.1, 0.0}, dep = {1, 0}),
              ove(wL = {0.0, 0.25}, wR = {0.0, 0.25}, gap = {0.0, 0.1}, dep = {0, 1}),

What follows is the declaration of the partition constructions, as declared by

    nConPar=1,
    datConPar(layers={matLayPar}, each A=10,
           each til=Buildings.Types.Tilt.Wall),

Thus, there is one partition construction. Its area is 10 m2 for each surface, to form a total surface area inside this thermal zone of 20 m2.

Next, the declaration

    nConBou=1,
    datConBou(layers={matLayFlo}, each A=6*4,
           each til=Buildings.Types.Tilt.Floor),

declares one construction whose other surface boundary condition is exposed by this room model (through the heat port surf_conBou).

Note that by default, there is a temperature state at the surface of this wall. Therefore, connecting to the heat port surf_conBou a prescribed temperature boundary condition such as Modelica.Thermal.HeatTransfer.Sources.PrescribedTemperature would lead to an error and the model won't translate. The reason is that both, the state defines the temperature at the surface, and Modelica.Thermal.HeatTransfer.Sources.PrescribedTemperature prescribes the value of this temperature, leading to an overspecification. To avoid this, add between surf_conBou and the prescribed boundary condition a thermal conductance such as Modelica.Thermal.HeatTransfer.Components.ThermalConductor or a thermal convection model such as Buildings.HeatTransfer.Convection.Exterior. Alternatively, you could remove the state from the surface by declaring

    nConBou=1,
    datConBou(layers={matLayFlo}, each A=6*4,
           each til=Buildings.Types.Tilt.Floor,
           each stateAtSurface_a = false),

The declaration

    nSurBou=1,
    surBou(each A=6*3, each absIR=0.9, each absSol=0.9, each til=Buildings.Types.Tilt.Wall),

is used to instantiate a model for a surface that is in this room. The surface has an area of 6*3 m2, absorptivity in the infrared and the solar spectrum of 0.9 and it is a wall. The room model will compute infrared radiative heat exchange, solar radiative heat gains and infrared radiative heat gains of this surface. The surface temperature and heat flow rate are exposed by this room model at the heat port surf_surBou. A model builder may use this construct to couple this room model to another room model that may model the construction.

The declaration

    linearizeRadiation = true,

causes the equations for radiative heat transfer to be linearized. This can reduce computing time at the expense of accuracy.

The declaration

    energyDynamics=Modelica.Fluid.Types.Dynamics.FixedInitial,

is used to initialize the air volume inside the thermal zone.

Finally, the declaration

    lat=0.73268921998722) "Room model"

sets the latitude of the building which needs to correspond with the latitude of the weather data file.

Modeling of contaminants

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. See the example Buildings.ThermalZones.Detailed.Examples.MixedAirCO2.

Notes

To connect two rooms, the model Buildings.HeatTransfer.Conduction.MultiLayer can be connected to the ports surf_surBou of the two rooms. However, make sure to set stateAtSurface_a = true and stateAtSurface_b = true in the instance of the heat conduction model, as this allows to avoid a nonlinear system of equation to compute the radiative heat transfer, thereby leading to faster simulation. See Buildings.ThermalZones.Detailed.Validation.BESTEST.Cases9xx.Case960 for an example.

By setting linearizeRadiation = false, nonlinear equations will be used to compute the infrared radiation exchange among surfaces. This can lead to slower computation.

References

Michael Wetter, Wangda Zuo and Thierry Stephane Nouidui.
Modeling of Heat Transfer in Rooms in the Modelica "Buildings" Library.
Proc. of the 12th IBPSA Conference, p. 1096-1103. Sydney, Australia, November 2011.

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

Modelica definition

class MixedAir "Room model with instantaneously mixed air" extends Modelica.Icons.Information; end MixedAir;

Buildings.ThermalZones.Detailed.UsersGuide.CFD Buildings.ThermalZones.Detailed.UsersGuide.CFD

Room model with air heat and mass balance computed using Computational Fluid Dynamics

Information

The model Buildings.ThermalZones.Detailed.CFD is a room model in which the room air heat and mass balance is computed using the Computational Fluid Dynamics (CFD).

The model is identical with Buildings.ThermalZones.Detailed.MixedAir, except for the following points:

A description of the model assumptions and the implemention and validation of this room model can be found in Zuo et al. (2016) and in Zuo et al. (2014).

Conventions

The following conventions are made:

The quantities that are exchanged between the programs are defined as follows:

Implementation

This section explains how the data exchange between Modelica and CFD is implemented. The section is only of interest to developers. Users may skip this section.

Interface to Modelica models

Interfacing CFD with the Modelica room air heat and mass balance is done in the model Buildings.ThermalZones.Detailed.BaseClasses.CFDAirHeatMassBalance. To interface variables from Modelica and CFD, the following classes and conventions are used in this model.

Data exchange with CFD

The data exchange with the CFD interface is done through the instance cfd, and implemented in Buildings.ThermalZones.Detailed.BaseClasses.CFDExchange. This block exchanges the following data with the CFD simulation:

During the initialzation, the following data are sent from Modelica to CFD:

During the time integration, and array u is sent from Modelica to CFD, and Modelica receives an array y from CFD. The elements of the array u are as follows:

  1. Either temperature or heat flow rate boundary conditions, in the same order as the array name. The units are [K] or [W]. The array bouCon that is sent during the initialization declares the type of boundary condition. There are nSur elements for surfaces.
  2. If at least one window in the room has a shade, then the next nConExtWin elements are the shading control signals. u=0 means that the shade is not deployed, and u=1 means that the shade is completely deployed (blocking solar radiation). If there is no window in the room, then these elements are not present.
  3. If at least one window in the room has a shade, then the next nConExtWin elements are the radiations in [W] that are absorbed by the respective shades. If there is no window in the room, then these elements are not present.
  4. The convective sensible heat input into the room in [W], which is a scalar. A positive value means that heat is added to the room.
  5. The latent heat input into the room in [W], which is a scalar. A positive value means that moisture is added to the room.
  6. The next element is the room average static pressure in [Pa].
  7. The next nPorts elements are the mass flow rates into the room in [kg/s]. A positive value is used if the air flows into the room, otherwise the value is negative. The first element is connected to ports[1], the second to ports[2] etc.
  8. The next nPorts elements are the air temperatures that the medium has if it were flowing into the room, e.g., the "inflowing medium" computed based on inStream(h_outflow).
  9. The next nPorts*Medium.nXi elements are the species concentration of the inflowing medium. The first Medium.nXi elements are for port 1, then for port 2 etc. The units are in [kg/kg] total mass, and not in [kg/kg] dry air.
  10. The next nPorts*Medium.nC elements are the trace substances of the inflowing medium. The first Medium.nC elements are for port 1, then for port 2 etc.
The elements of the array y that is sent from CFD to Modelica are as follows:
  1. Either temperature or heat flow rate at the surfaces, in the same order as the array name. The array bouCon that is sent during the initialization declares the type of boundary condition. If bouCon[i] = 1, then heat flow rate in [W] is sent from CFD to Modelica. If bouCon[i] = 2, then temperature in [K] is sent from CFD to Modelica. There are nSur elements for surfaces.
  2. The average room air temperature in [K].
  3. If the room has at least one window with a shade, then the next nConExtWin elements are the temperature of the shade in [K].
  4. The next nPorts elements are the air temperatures in [K] of the cells that are connected to the inlet or outlet diffusor of ports[1], ports[2], etc..
  5. The next nPorts*Medium.nXi elements are the species concentration of the cells to which the ports are connected. The first Medium.nXi elements are for port 1, then for port 2 etc. The units are in [kg/kg] total mass, and not in [kg/kg] dry air.
  6. The next nPorts*Medium.nC elements are the trace substances of the cells to which the ports are connected to. The first Medium.nC elements are for port 1, then for port 2 etc.

References

Wangda Zuo, Michael Wetter, Wei Tian, Dan Li, Mingang Jin, Qingyan Chen.
Coupling Indoor Airflow, HVAC, Control and Building Envelope Heat Transfer in the Modelica Buildings Library.
Journal of Building Performance Simulation, 9(4), pp. 366-381, 2016.
http://dx.doi.org/10.1080/19401493.2015.1062557.

Wangda Zuo, Michael Wetter, Dan Li, Mingang Jin, Wei Tian, Qingyan Chen.
Coupled Simulation of Indoor Environment, HVAC and Control System by Using Fast Fluid Dynamics and the Modelica Buildings Library.
Proc. of the 2014 ASHRAE/IBPSA-USA Building Simulation Conference, Atlanta, GA, September 10-12, 2014.

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

Modelica definition

class CFD "Room model with air heat and mass balance computed using Computational Fluid Dynamics" extends Modelica.Icons.Information; end CFD;