Buildings.DHC.Loads.BaseClasses

Package with base classes

Information

This package contains base classes that are used to construct the classes in Buildings.DHC.Loads.

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

Package Content

Name	Description
BuildingRCZ1Valve	One-zone RC building model with distribution pumps and mixing valves
BuildingRCZ6	Six-zone RC building model based on URBANopt GeoJSON export, with distribution pumps
BuildingSpawnZ1	One-zone EnergyPlus building model
BuildingSpawnZ6	Six-zone EnergyPlus building model based on URBANopt GeoJSON export, with distribution pumps
BuildingTimeSeries	Building model with heating and/or cooling loads provided as time series
ConstraintViolation	Block that outputs the fraction of time when a constraint is violated
FanCoil4Pipe	Model of a sensible only four-pipe fan coil unit computing a required water mass flow rate
FanCoil4PipeHeatPorts	Model of a sensible only four-pipe fan coil unit computing a required water mass flow rate
FlowDistribution	Model of a building hydraulic distribution system
PartialBuilding	Partial class for building model
PartialBuildingWithPartialETS	Partial model of a building with an energy transfer station
PartialFanCoil4Pipe	Partial model of a sensible only four-pipe fan coil unit computing a required water mass flow rate
PartialTerminalUnit	Partial model for HVAC terminal unit
SimpleRoomODE	Simplified model for assessing room air temperature variations around a set point
getPeakLoad	Function that reads the peak load from the load profile
Controls	Package of control sequences for DHC systems
Types	Package with type definitions
Examples	Example models integrating multiple components
Validation	Collection of validation models

Buildings.DHC.Loads.BaseClasses.BuildingRCZ1Valve

One-zone RC building model with distribution pumps and mixing valves

Information

This is a simplified one-zone building model based on a one-element reduced order room model. The corresponding heating and cooling loads are computed with a four-pipe fan coil unit model derived from Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit and connected to the room model by means of fluid ports.

The heating and chilled water distribution to the terminal units is modeled with an instance of Buildings.DHC.Loads.BaseClasses.FlowDistribution including a mixing valve to control the supply temperature.

Extends from Buildings.DHC.Loads.BaseClasses.PartialBuilding (Partial class for building model).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.BuildingRCZ6

Six-zone RC building model based on URBANopt GeoJSON export, with distribution pumps

Information

This is a simplified six-zone building model based on two-element reduced order model. It was generated from translating a GeoJSON model specified within the URBANopt UI. The heating and cooling loads are computed with a four-pipe fan coil unit model derived from Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit and connected to the room model by means of heat ports.

Extends from Buildings.DHC.Loads.BaseClasses.PartialBuilding (Partial class for building model).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.BuildingSpawnZ1

One-zone EnergyPlus building model

Information

This is a simplified one-zone building model based on EnergyPlus building envelope model. The heating and cooling loads are computed with a four-pipe fan coil unit model derived from Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit and connected to the room model by means of fluid ports.

Extends from Buildings.DHC.Loads.BaseClasses.PartialBuilding (Partial class for building model).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.BuildingSpawnZ6

Six-zone EnergyPlus building model based on URBANopt GeoJSON export, with distribution pumps

Information

This is a simplified six-zone building model based on an EnergyPlus building envelope model. It was generated from translating a GeoJSON model specified within the URBANopt UI. The heating and cooling loads are computed with a four-pipe fan coil unit model derived from Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit and connected to the room model by means of fluid ports. The Attic zone is unconditionned, with a free floating temperature.

Extends from Buildings.DHC.Loads.BaseClasses.PartialBuilding (Partial class for building model).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.BuildingTimeSeries

Building model with heating and/or cooling loads provided as time series

Information

This is a simplified building model where the space heating and cooling loads are provided as time series. In order to approximate the emission characteristic of the building HVAC system, this model uses idealized fan coil models that are parameterized with the peak load, determined from the provided time series, and design values of the hot water and chilled water supply and return temperatures.

The time series that provide the loads are read from the file filNam. This file must have columns as shown in this example:

#1
#Heating, cooling and domestic hot water loads
#
#First column: Seconds in the year (loads are hourly)
#Second column: cooling loads in Watts (as negative numbers).
#Third column: space heating loads in Watts
#Fourth column: domestic hot water loads in Watts
#
#Peak space cooling load = -146960 Watts
#Peak space heating load = 167690 Watts
#Peak water heating load = 9390 Watts
double tab1(8760,4)
0;0;18230;0
3600;0;17520;0
7200;0;20170;0
10800;0;22450;0
[further rows omitted]

• The first column must be the time of the year in seconds.
• If have_chiWat = true, then the next column must be the space cooling load in Watts. Note that cooling is a negative number.
  If have_chiWat = false, this column must be present but it will be ignored, and hence it can be set to any number such as 0.
• If have_heaWat = true, the next column must be the space heating load in Watts.
  If have_heaWat = false, this column must be present but it will be ignored, and hence it can be set to any number such as 0.
• If have_hotWat = true, the next column must be the domestic hot water load in Watts.
  If have_hotWat = false, this column must be present but it will be ignored, and hence it can be set to any number such as 0.

The entry double tab1(8760,4) shows how many columns and rows are present.

The header also needs to contain the lines that start with #Peak as shown in the example above.

Implementation details

The total space heating (resp. cooling) load is split between facMulHea (resp. facMulCoo) identical terminal units with heat transfer performance approximated based on design specifications of a reference terminal unit. It is not expected that the user modifies the default values that are proposed for facMulHea and facMulCoo unless detailed design data are available for the building HVAC system. In that latter case, the following set of parameters should be modified consistently to match the design data.

• Hot water (resp. chilled water) supply and return temperature T_aHeaWat_nominal and T_bHeaWat_nominal (resp. T_aChiWat_nominal and T_bChiWat_nominal)
• Terminal unit entering air temperature T_aLoaHea_nominal (resp. T_aLoaCoo_nominal) and humidity ratio w_aLoaCoo_nominal
• Terminal unit air mass flow rate mLoaHea_flow_nominal (resp. mLoaCoo_flow_nominal)
• Terminal unit scaling factor facMulHea (resp. facMulCoo)

For reference, the default reference terminal unit performance is based on manufacturer data (Carrier fan coil model 42NL/NH) at selection conditions as specified in the "Advanced" tab.

Extends from Buildings.DHC.Loads.BaseClasses.PartialBuilding (Partial class for building model).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.ConstraintViolation

Block that outputs the fraction of time when a constraint is violated

Information

Block that outputs the running fractional time during which any element u_i of the input signal is not within u_min ≤ u_i ≤ u_max.

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.FanCoil4Pipe

Model of a sensible only four-pipe fan coil unit computing a required water mass flow rate

Information

This is a simplified model of a sensible only four-pipe fan coil unit for heating and cooling. It is intended to be coupled to a room model by means of fluid ports. See Buildings.DHC.Loads.BaseClasses.PartialFanCoil4Pipe for a description of the modeling principles.

Extends from PartialFanCoil4Pipe (Partial model of a sensible only four-pipe fan coil unit computing a required water mass flow rate).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.FanCoil4PipeHeatPorts

Model of a sensible only four-pipe fan coil unit computing a required water mass flow rate

Information

This is a simplified model of a sensible only four-pipe fan coil unit for heating and cooling. It is intended to be coupled to a room model by means of heat ports. See Buildings.DHC.Loads.BaseClasses.PartialFanCoil4Pipe for a description of the modeling principles.

Extends from PartialFanCoil4Pipe (Partial model of a sensible only four-pipe fan coil unit computing a required water mass flow rate).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.FlowDistribution

Model of a building hydraulic distribution system

Information

This model represents a two-pipe hydraulic distribution system serving multiple terminal units. It is primarily intended to be used in conjunction with models that extend Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit. The typical model structure for a whole building connected to an energy transfer station (or a dedicated plant) is illustrated in the schematics in the info section of Buildings.DHC.Loads.BaseClasses.PartialBuilding.

The pipe network modeling is decoupled between a main distribution loop and several terminal branch circuits:

• The mass flow rate in each branch circuit is equal to the mass flow rate demand yielded by the terminal unit model, constrained by the condition that the sum of all demands is lower or equal to the flow rate in the main loop. Additionally if the total flow rate demand exceeds the nominal mass flow rate the model generates an error.
• The inlet temperature in each branch circuit is equal to the supply temperature in the main loop. The outlet temperature in the main loop results from transferring the enthalpy flow rate of each individual fluid stream to the main fluid stream.
• The pressure drop in the main distribution loop corresponds to the pressure drop over the whole distribution system (the pump head). It is governed by an equation representing the control logic of the distribution pump.

Optionally:

• A distribution pump can be modeled with a prescribed flow rate corresponding to the total flow rate demand.
• A mixing valve can be modeled (together with a distribution pump) with a control loop tracking the supply temperature. Note that the nominal pressure drop of the valve is not an exposed parameter: it is set by default to 10% of the nominal total pressure drop.

Implementation

The modeling approach aims to minimize the number of algebraic equations by avoiding an explicit modeling of the terminal actuators and the whole flow network. In addition, the assumption allowFlowReversal=false is used systematically together with boundary conditions which actually ensure that no reverse flow conditions are encountered in simulation. This allows directly accessing the inlet enthalpy value of a component from the fluid port port_a with the built-in function inStream. This approach is preferred to the use of two-port sensors which introduce a state to ensure a smooth transition at flow reversal. All connected components must meet the same requirements. The impact on the computational performance is illustrated below.

Pump head computation

The pump head is computed as follows (see also Buildings.DHC.Loads.BaseClasses.Validation.FlowDistributionPumpControl for a comparison with an explicit modeling of the piping network).

• In case of a constant pump head,

  dpPum = dp_nominal.

• In case of a constant flow rate (three-way valves) the network flow characteristics is considered independent from the actuator positions. Hence,

  dpPum = dp_nominal.

• In case of a linear head,

  dpPum = dpMin + (dp_nominal - dpMin) * m_flow / m_flow_nominal.

• In case of a constant speed, the pump head is computed based on the pump pressure curve and the total required mass flow rate.
• In case of a constant pressure difference at a given location, the pump head is computed according to the schematics hereunder, under the assumption of a two-pipe distribution system,

  dpPum = dpMin + dpVal + 2 * Σ_i dpDis[i],

  where

  • dpMin is the differential pressure set point.
  • dpVal is the pressure drop across the optional mixing valve. It is considered independent from the valve position, i.e., dpVal = dpVal_nominal,
  • dpDis[i] is the pressure drop in the supply pipe segment directly upstream the i^th connection,

    dpDis[i] = 1 / K[i]² * mDis_flow[i] ²,

    where mDis_flow[i] = Σ_{i to nUni} mReq_flow[i] is the mass flow rate in the same pipe segment, and K[i] = (Σ_{i to nUni} mUni_flow_nominal[i]) / dpDis_nominal[i]^0.5 is the corresponding flow coefficient (constant).

• The pressure drop in the corresponding pipe segment of the return line is considered equal, hence the factor of 2 in the above equation.

  The default value for dpDis_nominal corresponds to a configuration where the differential pressure sensor is located before the most remote connected unit, 20% of the nominal pressure drop in the distribution network occurs between the pump and the first connected unit (supply and return), the remaining pressure drop is evenly distributed over each pipe segment between the other connected units. The user can override these default values with the requirement that the nominal pressure drop of each pipe segment downstream of the differential pressure sensor must be set to zero.

Energy and mass dynamics

The energy dynamics and the time constant used in the ideal heater and cooler model are exposed as advanced parameters. They are used to represent the typical dynamics over the whole piping network, from supply to return. The mass dynamics are by default identical to the energy dynamics.

Simplifying assumptions are used otherwise, namely

• the pump is modeled in steady-state, and
• the valve and the flow splitter are modeled with fixed initial conditions. This is because the temperature of the fluid leaving the valve is used as a control input signal. If a steady-state model is used, that temperature is computed by assuming ideal mixing at the inner fluid ports of the valve. In case of zero flow rate, the temperature value results from regularizing the corresponding equation that is not well defined in that domain. That triggers non-physical temperature variations which themselves lead to control transients when the flow rate gets reestablished. Those effects turn out to be detrimental to computational performance.

Computational performance

The figure below compares the computational performance of this model (labelled simple, see model Buildings.DHC.Loads.BaseClasses.Validation.BenchmarkFlowDistribution1) with an explicit modeling of the distribution network and the terminal unit actuators (labelled detailed, see model Buildings.DHC.Loads.BaseClasses.Validation.BenchmarkFlowDistribution2). The models are simulated with the solver CVODE from Sundials. The impact of a varying number of connected loads, nLoa, is assessed on

1. the total time for all model evaluations,
2. the total time spent between model evaluations, and
3. the number of continuous state variables.

A linear, resp. quadratic, regression line and the corresponding confidence interval are also plotted for the model labelled simple, resp. detailed.

Extends from Buildings.Fluid.Interfaces.PartialTwoPortInterface (Partial model with two ports and declaration of quantities that are used by many models).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.PartialBuilding

Partial class for building model

Information

Partial model to be used for modeling the thermal loads on an energy transfer station or a dedicated plant. Models extending this class are typically used in conjunction with Buildings.DHC.Loads.BaseClasses.FlowDistribution and models extending Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit as described in the schematics here under. The fluid ports represent the connection between the production system and the building distribution system.

Scaling

Scaling is implemented by means of a multiplier factor facMul. Each extensive quantity (mass and heat flow rate, electric power) flowing out through fluid ports, or connected to an output connector is multiplied by facMul. Each extensive quantity (mass and heat flow rate, electric power) flowing in through fluid ports, or connected to an input connector is multiplied by 1/facMul. This allows modeling, with a single instance, multiple identical buildings served by the same energy transfer station.

Examples

See various use cases in Buildings.DHC.Loads.BaseClasses.Examples.

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.PartialBuildingWithPartialETS

Partial model of a building with an energy transfer station

Information

Partial model to be used for modeling

• an energy transfer station and the optional in-building primary systems, based on a model extending Buildings.DHC.ETS.BaseClasses.PartialETS, and
• the served building, based on a model extending Buildings.DHC.Loads.BaseClasses.PartialBuilding.

See the schematics below for a description of the physical boundaries of the composing systems.

The parameters defining the set of outside connectors of this class are propagated up from the ETS and building components. The connect clauses between the ETS and the building connectors are automatically generated based on the previous parameters and the additional parameters nPorts_heaWat and nPorts_chiWat that need to be specified. In case of a heating service line, the model allows for using two different media at the inlet port_aSerHea and at the oulet port_bSerHea to represent a steam supply and condensate return.

Scaling

Scaling is implemented by means of a multiplier factor facMul. Each extensive quantity (mass and heat flow rate, electric power) flowing out through fluid ports, or connected to an output connector is multiplied by facMul. Each extensive quantity (mass and heat flow rate, electric power) flowing in through fluid ports, or connected to an input connector is multiplied by 1/facMul. This allows modeling, with a single instance, multiple identical buildings with identical energy transfer stations, served by the same service line.

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.PartialFanCoil4Pipe

Partial model of a sensible only four-pipe fan coil unit computing a required water mass flow rate

Information

This is a simplified partial model of a sensible only four-pipe fan coil unit for heating and cooling. It is intended to be used in conjunction with Buildings.DHC.Loads.BaseClasses.FlowDistribution, and hence it computes the water mass flow rate required to meet the temperature set point.

For the sake of simplicity, a sensible only heat exchanger model is considered.

For the sake of computational performance, a PI controller is used instead of an inverse model of the heat exchanger to assess the required water mass flow rate. Each controller output signal is mapped linearly to the water mass flow rate, from zero to its nominal value. The maximum of the two output signals is mapped linearly to the air mass flow rate, from zero to its nominal value.

The model takes the measured room air temperature as an input (as opposed to the fan inlet temperature) to maintain a valid control loop output in case of zero air flow rate.

The model is partial to allow various connectivity options on the load side: either with fluid ports or with heat ports.

Extends from Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit (Partial model for HVAC terminal unit).

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.PartialTerminalUnit

Partial model for HVAC terminal unit

Information

Partial model to be used for modeling an HVAC terminal unit.

The models inheriting from this class are typically used in conjunction with Buildings.DHC.Loads.BaseClasses.FlowDistribution. They must compute a so-called required mass flow rate defined as the heating or chilled water mass flow rate needed to meet the load. It can be approximated using a control loop to avoid inverting a heat exchanger model as illustrated in Buildings.DHC.Loads.BaseClasses.Examples.

The model connectivity can be modified to address various use cases:

• On the source side (typically connected to Buildings.DHC.Loads.BaseClasses.FlowDistribution):
  • Fluid ports for chilled water and heating water can be conditionally instantiated by respectively setting have_chiWat and have_heaWat to true.
• On the load side (typically connected to a room model):
  • Fluid ports can be conditionally instantiated by setting have_fluPor to true.
  • Alternatively heat ports (for convective and radiative heat transfer) can be conditionally instantiated by setting have_heaPor to true.
  • Real input connectors can be conditionally instantiated by setting have_QReq_flow to true. Those connectors can be used to provide heating and cooling loads as time series, see Buildings.DHC.Loads.BaseClasses.Examples.CouplingTimeSeries for an illustration of that use case. The impact on the room air temperature of an unmet load can be assessed with Buildings.DHC.Loads.BaseClasses.SimpleRoomODE.

The heating or cooling nominal capacity is provided for the water based heat exchangers only. Electric heating or cooling systems are supposed to have an infinite capacity.

Connection with the flow distribution model

When connecting the model to Buildings.DHC.Loads.BaseClasses.FlowDistribution:

• The nominal pressure drop on the source side (heating or chilled water) is irrelevant as the computation of the pump head relies on a specific algorithm described in Buildings.DHC.Loads.BaseClasses.FlowDistribution.
• The parameter allowFlowReversal must be set to false (default) in consistency with Buildings.DHC.Loads.BaseClasses.FlowDistribution. This requirement only applies to the source side. On the load side one is free to use whatever option suitable for the modeling needs. Note that typically for an air flow network connected to the outdoor air (either at the room level for modeling infiltration or at the system level for the fresh air source), the unidirectional air flow condition cannot be guaranteed. The reason is the varying pressure of the outdoor air that can lead to a negative pressure difference at the terminal unit boundaries when the fan is off.

Scaling

Scaling is implemented by means of two multiplier factors.

• The parameter facMul serves as a terminal unit multiplier. Each extensive quantity (mass and heat flow rate, electric power) flowing out through fluid or heat ports, or connected to an output connector is multiplied by facMul. Each extensive quantity (mass and heat flow rate, electric power) flowing in through fluid or heat ports, or connected to an input connector is multiplied by 1/facMul. This parameter allows modeling, with a single instance, multiple identical units served by the same distribution system, and serving an aggregated load (e.g., a thermal zone representing several rooms).
• The parameter facMulZon serves as a thermal zone multiplier. Except for the variables connected to the load side, which are not affected by facMulZon, the logic is otherwise identical to the one described for facMul. This parameter allows modeling, with a single instance (of both the terminal unit model and the load model), multiple identical units served by the same distribution system, and serving multiple identical loads (e.g., a thermal zone representing a single room).

Note that the two multiplier factors serve different modeling purposes. As such they typically should not be used simultaneously. Both multiplier factors are of type real (as opposed to integer) to allow for instance modeling a set of terminal units based on manufacturer data, while still being able to size the full set based on a peak load. See Buildings.DHC.Loads.BaseClasses.Validation.TerminalUnitScaling for an illustration of the use case when heating and cooling loads are provided as time series.

Change-over mode

When modeling a change-over system:

• The parameters have_chiWat and have_chaOve must both be set to true and have_heaWat must be set to false.
• The heat exchanger is sized by providing the nominal parameters for the cooling configuration (suffix ChiWat). The nominal mass flow rate on the source and the load side must also be provided for the heating configuration (suffix HeaWat) as it can differ from the cooling configuration.
• The computed heat flow rate must be split into its positive part that gets connected to QActHea_flow and its negative part that gets connected to QActCoo_flow.
• The computed required mass flow rate must be connected to mReqChiWat_flow.

Base class parameters

All the parameters of this base class that pertain to the nominal conditions shall not be exposed in the derived class, as this would lead to an overdetermined model. For instance, the nominal mass flow rate may not be exposed but rather computed from the nominal heat flow rate, entering and leaving fluid temperature. However, those parameters are included in the base class because other components are likely to reference them. For instance the distribution system model may use the nominal mass flow rate of each terminal unit to compute the nominal mass flow rate of the circulation pump.

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.SimpleRoomODE

Simplified model for assessing room air temperature variations around a set point

Information

This is a first order ODE model assessing the indoor air temperature variations around a set point, based on the difference between the required and actual heating or cooling heat flow rate and a minimum set of parameters at nominal conditions.

The lumped thermal conductance G representing all heat transfer mechanisms that depend on the temperature difference with the outside (transmission, infiltration and ventilation) is assessed from the steady-state energy balance at heating nominal conditions as

0 = Q̇_{heating, nom} + G (T_{out, heating, nom} - T_{ind, heating, nom}).

Note that for model representativeness, it is important for Q̇_{heating, nom} to be evaluated in close to steady-state conditions with no internal heat gains and no solar heat gains.

The lumped thermal conductance G is then considered constant for all operating conditions.

The required heating or cooling heat flow rate (i.e. the space load) Q̇_{heat_cool, req} corresponds to a steady-state control error equal to zero,

0 = Q̇_{heat_cool, req} + G (T_out - T_{ind, set}) + Q̇_various,

where Q̇_various represents the miscellaneous heat gains. The indoor temperature variation rate due to an unmet load is given by

C ∂T_ind / ∂t = Q̇_{heat_cool, act} + G (T_out - T_ind) + Q̇_various,

where Q̇_{heat_cool, act} is the actual heating or cooling heat flow rate and C is the thermal capacitance of the indoor volume. The two previous equations yield

τ ∂T_ind / ∂t = (Q̇_{heat_cool, act} - Q̇_{heat_cool, req}) / G - T_ind + T_{ind, set},

where τ = C / G is the time constant of the indoor temperature.

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

Parameters

Connectors

Modelica definition

Buildings.DHC.Loads.BaseClasses.getPeakLoad

Function that reads the peak load from the load profile

Information

Function that reads a double value from a text file.

This function scans a file that has a format such as

#1
#Some other text
#Peak space cooling load = -383165.6989 Watts
#Peak space heating load = 893931.4335 Watts
double tab1(8760,4)
0,0,5972.314925,16
3600,0,4925.839944,1750.915684
...

The parameter string is a string that the function searches for, starting at the first line. If it finds the string, it expects an equality sign, and returns the double value after this equality sign. If the function encounters the end of the file, it terminates the simulation with an assertion.

See Buildings.DHC.Loads.BaseClasses.Validation.GetPeakLoad for how to invoke this function.

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

Inputs

Outputs

Modelica definition