Tutorial

Modelica Buildings Library

and
Best Practices for Modeling of Thermofluid Flow Systems

Michael Wetter
Simulation Research Group

March 23, 2020

1
 Overview
of
Modelica Buildings Library

2
Primary use of Buildings library

Main applications
• Model repository for building and district energy simulation, see https://lbl-srg.github.io/
soep/
• Development of 5th generation district heating and cooling
• Controls design and performance evaluation.
• Repository of control sequences in the Control Description Language, https://obc.lbl.gov/.
• Model-based design process.
• Development and testing of FDD algorithms.

License
• All development is open-source under BSD.

3
 Model repository: Modelica Buildings Library.
Open-source repository of 1000+ models and functions.
Air-based HVAC Hydronic heating Chiller plants Embedded Python Room air flow

Natural ventilation, Room heat transfer, Solar collectors FLEXLAB Electrical systems
multizone air exchange, incl. window (TARCOG)
contaminant transport

Current developments
District heating Control design & deployment, Make it the core of the Spawn of EnergyPlus.
and cooling systems including ASHRAE G36

Use for real-time building control (OpenBuildingControl)

Emulators for testing and comparison of advanced building

control sequences, including MPC (BOPTEST)

Co-develop with IBPSA Modelica library, including district

heating and cooling systems
simulationresearch.lbl.gov/modelica
4
Michael Wetter, Wangda Zuo, Thierry S. Nouidui and Xiufeng Pang. Modelica Buildings library. Journal of Building Performance Simulation, 7(4):253-270, 2014.
 where f : R ⇥ R ! R is a twice continuously differentiable function
that is bounded on compact sets. We constructed the function p : R ⇥
R ! R in such a way that it satisfies

Separation between library developer, component developer

p(d, x )
p(d, d)
=
= 1/d,
p(d, x ), (4a)
(4b)

and end user p0 (d, d)

0
p (d, 0)
00
=
6= 0,
1/d2 ,

3
(4c)
(4d)
p (d, d) = 2/d , (4e)
1 d/x
where p0 (·, ·) and p00 (·, ·) denote the first and second order par- d p(d, x )
tial derivatives with respect to the second argument. The condition

d f(d, x )
p0 (d, 0) 6= 0 has been selected to avoid that the first derivative van- 0
ishes at the origin, because a Newton solver that solves p(d, x ) = 0
for x may compute the sequence xn+1 = xn p(d, xn )/p0 (d, xn ).
1
The function that we selected and that satisfies (4) is d/x

x 2 3 3 1 1 0 1
p(d, x ) , +x 3 x x + 7 x5 . (5) x/d
d2 d d5 d

Figure 1 shows the graph of this function. The term x/d2 is used to Figure 1: Plot of d f(d, x ).
ensure that the first derivative is non-zero around a neighborhood of
x = 0, and therefore by the Implicit Function Theorem, there exists
in a neighborhood of the origin an inverse function p 1 (d, ·) that is
differentiable.41 41
Polak, E. (1997). Optimization, Algo-
Note that in (2), for ṁ(t) 2 ( ṁd , ṁd ) \ {0}, energy is not con- rithms and Consistent Approximations,
Volume 124 of Applied Mathematical
served. Therefore, ṁd should be chosen small. However, ṁd should Sciences. Springer Verlag
not be too small compared to the design mass flow rate, as this will
cause f(ṁd , ṁ) to be large in magnitude near ṁ ⇡ ±ṁd , which may
lead to problems for numerical solvers. The default setting in the
Buildings library is ṁd = 10 7 ṁ0 , where ṁ0 is the design mass flow
rate. At this low mass flow rate, the impact on the energy consump-
tion is negligible.
To assist component model developers in the regularization of
these functions, the package Buildings.Utilities.Math provides
differentiable approximating functions for many formulations.42 42
Note that Modelica simulation en-
vironments can in general properly
handle non-differentiabilities. How-
ever, a numerically sound treatment
requires an event iteration that is com-
putationally costly. When formulating
equations for physical phenomena, we
therefore replaced non-differentiable
equations with approximations that are
continuously differentiable.

Legend:
Library developer
Component developer
5
End user
Main modeling assumptions

Media Can track moisture (X) and contaminants (C).

HVAC equipment Most equipment based on performance curve, or based on

nominal conditions and similarity laws.
Refrigerant is not modeled.
Most equipment optional steady-state or 1st order transient.

Flow resistances Based on m_flow_nominal and dp_nominal plus similarity law.

Optional flag to linearize or to set dp=0.

Room model Any number of constructions are possible.

Layer-by-layer window model (similar to Window 6).
Optional flag to linearize radiation and/or convection.

Electrical systems DC.

AC 1-phase and 3-phase (dq, dq0).
Quasi-stationary or dynamic phase angle (but not frequency).

6
Documentation and distribution

Documentation
• General user guide (getting started, best practice,
developer instructions, ...).
• 18 user guides for individual packages.
• 2 tutorials with step-by-step instructions.
• All models contain “info” section.
• Small test models for all classes,
large test cases for “smoke tests,”
and various validation cases.

Distribution
• Main site
http://simulationresearch.lbl.gov/modelica
• Development site with version control, wiki and issue tracker:
https://github.com/lbl-srg/modelica-buildings

7
Best practice and modeling
hints

8
Building large system models

How do you build and debug a large system model?

1. Split the model into smaller models.

2. Test the smaller models for well known conditions.

3. Add smaller models to unit tests.

For example, see Chiller Plant

Each small models contains a simple unit test.

9
Use small unit tests, as in

Chiller plant
base classes

Pumps

10
Propagate common parameters
Don't assign values to the same parameters:
Pump pum(m_flow_nominal=0.1) "Pump";
TemperatureSensor sen(m_flow_nominal=0.1) "Sensor";

Instead, propagate parameters and assign the value once:

Modelica.SIunits.MassFlowRate m_flow_nominal = 0.1

"Nominal mass flow rate";
Pump pum(final m_flow_nominal=m_flow_nominal) "Pump";
TemperatureSensor sen(final m_flow_nominal=m_flow_nominal) "Sensor";

Assignments can include computations, such as

Modelica.SIunits.HeatFlowRate QHea_nominal = 3000

"Nominal heating power";
Modelica.SIunits.TemperatureDifference dT = 10
"Nominal temperature difference";
Modelica.SIunits.MassFlowRate m_flow_nominal = QHea_nominal/dT/4200
"Nominal mass flow rate";
...
11
Always define the media at the top-level
Top-level system-model
replaceable package Medium = Buildings.Media.Air
"Medium model";

Propagate medium to instance of model

TemperatureSensor sen(
redeclare final package Medium = Medium,
final m_flow_nominal=m_flow_nominal) "Sensor";

Note: For arrays of parameters, use the each keyword, as in

TemperatureSensor sen[2](
each final m_flow_nominal=m_flow_nominal)
"Sensor";

12
All system models must have a reference pressure

Underdetermined model as no pressure state is assigned

Well defined model, but additional state for pressure as

reservoir p/p0=V0/p

Most efficient model as reservoir p is constant

13
Modeling of fluid junctions

In the model on the right, mixing

takes place in the fluid port B
because the boiler, port A and
port C all connect to port B.

14
Avoid oscillations of sensor signal

Correct use because

dT |ṁ|
⌧ = (✓ T)
dt ṁ0

Incorrect, as sensor output oscillates if

mass flow rate changes sign.
This happens for example if the mass
flow rate is near zero and approximated
by a solver.

See also User Guide.

15
Avoid events

This triggers events:

h = if port_a.m_flow > 0
then inStream(port_a.h_outflow) else port_a.h_outflow;

Avoid events using regularization:

h = Modelica.Fluid.Utilities.regStep(
x = port_a.m_flow,
y1 = inStream(port_a.h_outflow),
y2 = port_a.h_outflow,
x_small = m_flow_nominal*1E-4);

See also User Guide.

16
Beware of oscillating control

If the control input oscillates around

zero, then this model stalls

What happens if this model is model Test

simulated with an adaptive time Real x(start=0.1);
step? equation
der(x) = if x > 0 then -1 else 1;
end Test;

17
Setting of nominal values is important for scaling of residuals

If pressure is around 1E5 Pa, set p(nominal=1E5).

Nominal values are used to scale residuals, such as in Dymola’s dsmodel.c:

{ /* Non-linear system of equations to solve. */

...
const char*const varnames_[]={"floMac1.VMachine_flow",
"floMac2.VMachine_flow"};
const double nominal_[]={0.001, 0.001};
...

Modelica simulation tools typically control the local integration error as

ϵ ≤ trel |xi| + tabs

where the absolute tolerance is scaled with the nominal value as

tabs = trel |xnomi|.

18
Exercise: Modeling of a simple thermofluid flow system

How do you implement a source and boundary condition with a tank in between to create the
model below:

19
Exercise: Modeling of a simple thermofluid flow system

1. Make instances using models from Buildings.Fluid.Sources and

Buildings.Fluid.MixingVolumes.

2. Assign the parameters.

3. Check and simulate the model.

20
Further resources

Tutorials
• Buildings.Examples.Tutorial

User guides
• User guides for specific packages of models.
• User guide with general information.

21
Developer Guide

22
Overview

Main topics

• Coding style and conventions

• Requirements

• Organization of the library

• Adding a new model

• Adding regression tests

Further literature

• User Guide -> Development

• Style guide

23
Coding style and conventions

Based on Modelica Standard Library.

Most variables are 3 letter camel case to avoid too long names, for example,
TOut, QHea, yDamMax, …

Code duplication avoided where practical.

Additional information at
https://github.com/lbl-srg/modelica-buildings/wiki/Style-Guide and
http://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_UsersGuide.html

24
Requirements

Physical requirements

Mathematical requirements

25
Organization of individual packages

Tutorial
UsersGuide

Any other classes (models,

Packages are typically structured as shown on functions etc.)
the right.
Data
To add a new class, look first at Interfaces Types
Examples
and BaseClasses. Validation
Benchmarks
You probably will never implement a component Experimental
without extending a base class, such as from Interfaces
Buildings.Fluid.Interfaces BaseClasses
Internal
Obsolete

26
Implementing new thermofluid flow devices
Buildings.Fluid.Interface provides base classes.

Buildings.Fluid.Interface.UsersGuide describes these classes.

Alternatively, simple models such as the models below may be used as a

starting point for implementing new models for thermofluid flow devices:

Buildings.Fluid.HeatExchangers.HeaterCooler_u
For a device that adds heat to a fluid stream.

Buildings.Fluid.MassExchangers.Humidifier_u
For a device that adds humidity to a fluid stream.

Buildings.Fluid.Chillers.Carnot
For a device that exchanges heat between two fluid streams.

Buildings.Fluid.MassExchangers.ConstantEffectiveness
For a device that exchanges heat and humidity between two fluid streams.

27
Adding a heat exchanger

See HeaterCooler_u

within Buildings.Fluid.HeatExchangers;

model HeaterCooler_u "Heater or cooler with prescribed heat flow rate"

extends Buildings.Fluid.Interfaces.TwoPortHeatMassExchanger(
redeclare final Buildings.Fluid.MixingVolumes.MixingVolume vol(
prescribedHeatFlowRate=true));

parameter Modelica.SIunits.HeatFlowRate Q_flow_nominal

"Heat flow rate at u=1, positive for heating”;

Modelica.Blocks.Interfaces.RealInput u "Control input";

Modelica.Blocks.Interfaces.RealOutput Q_flow(unit="W")
"Heat added to the fluid”;

protected
Buildings.HeatTransfer.Sources.PrescribedHeatFlow preHea
"Prescribed heat flow";
Modelica.Blocks.Math.Gain gai(k=Q_flow_nominal) "Gain";

equation
connect(u, gai.u); ... // other connect statements
annotation (...); // documentation
end HeaterCooler_u; 28
Add examples and validations to unit testing framework

1. Add validation and stress tests for different model

configurations.

2. Validate results and add main outputs to plot script.

These variables become part of the regression tests.

3. Run
modelica-buildings/bin/
runUnitTests.py

4. Update Buildings/package.mo release notes.

5. Issue pull request on https://github.com/lbl-srg/

modelica-buildings.

See Unit Test documentation.

29
?

30