Introduction to Modelica Modeling for

Building Systems

A Tutorial Developed for MIT Class 4.421:

Space-Conditioning Systems for Low-
Carbon Buildings

3/29/2021

By David Blum
I. Requirements
1. Dassault Systemes Dymola (v2020), License, and C Compiler

a. For notes about choosing and setting up the C Compiler, see:

https://www.3ds.com/products-services/catia/products/dymola/c-
compiler/

2. Modelica Buildings Library (v7.0.0)

a. For download, see:

https://simulationresearch.lbl.gov/modelica/download.html

b. For notes about setting up the library, see:

https://simulationresearch.lbl.gov/modelica/installLibrary.html

II. Additional Resources

This is going to be a brief introduction. There is much more to learn about how to
use Modelica and Dymola. I recommend the following resources:

1. Dymola Users Guide

2. Modelica by Example
(https://mbe.modelica.university/)

3. Buildings Library Users Guide

(https://simulationresearch.lbl.gov/modelica/userGuide/index.html)

4. Buildings Library Tutorials

(https://simulationresearch.lbl.gov/modelica/training.html)
Part 1: Modelica Syntax and Dymola Development Environment
Modelica is a language, like C++ or Python. Therefore, you need to learn its
syntax and how it can be used to represent models. Dymola is the development
environment that will help us do that, in addition to helping us organize, compile,
and simulate our models, as well as explore the results of those simulations.

Therefore, in this part, you will:

1. Write a simple heat transfer model in Modelica

2. Check that the model is valid
3. Simulate the model
4. Explore the results

First, let’s define the physical phenomenon we will model. Consider a heat
transfer problem where a small rock is being cooled by an air stream, as shown in
the diagram. We are interested in simulating the temperature of the rock over time.
This can be described by the differential equation and initial condition below:

"! ℎ

&, (, ), *
"($)

𝑑𝑇
𝜌𝑉𝑐! = ℎ𝐴(𝑇" − 𝑇)
𝑑𝑡
𝑇(𝑡 = 0) = 𝑇#

Where:

𝑇 is the rock temperature [K]

𝑇# is the initial rock temperature [K]

𝑇" is the air temperature [K]

𝜌 is the rock density [kg/m3]

𝑉 is the rock volume [m3]

𝑐! is the rock specific heat capacity [J/kg-K]

ℎ is the rock-air heat transfer coefficient [W/m2-K]

𝐴 is the rock surface area [m2]

1. Open Dymola. Go to File > Save > SaveAs and save the model file as shown in
the Figure below (it will be saved as Rock.mo). Then, switch to the “Modelica
Text” view by clicking on the icon indicated in the top Figure on the next page.
Your screen should look like the bottom Figure on the next page.

By default, Dymola will open to the “Diagram View.” This view is used to
configure models using graphical blocks that can be pieced together. We will
explore this later in the tutorial. For now, we are concentrating on the underlying
text-based implementation of models.
Modelica Text View
Diagram View
2. Declare all of the variables in the model as shown in the Figure below.

The syntax of defining a basic model is split into two main sections, one that is
used to declare all of the variables in the model and one that is used to define the
equations of the model. The declaration section is above the word “equation” and
the equations section is below the word “equation.”

The declaration section is used to give variables names and various

characteristics. Here, parameter means the variable is given a value that does
not change over time. Real means that the value of the variable is a real number,
as opposed to an Integer or Boolean (True/False). Other attributes can be
assigned, such as the unit and start value. Finally, “descriptions” of the
variables can be given, which are used later to help us document the model.

Notice that all of our variables are given, except the temperature of the rock. This
is our only variable that will change with time and needs to be calculated using an
equation (this is also called a “state” variable). Notice also that the volume and
area parameters are defined as a function of the radius parameter, assuming that
our rock is a sphere.
3. Write the equations of the model as shown in the Figure below.

Here, we only have one equation. It is an ordinary differential equation (ODE).

Modelica syntax naturally accepts the specification of variable derivatives with
respect to time using the der() syntax.

Notice we can also write equations in an “acausal” manner. That is, it does not
matter which variables appear on each side of the equation. In addition, it does
not matter the order in which we specify equations, if we had more than one. All of
this makes it easier for us to define systems of differential and algebraic equations
(DAEs) without having to first solve them analytically and determine the proper
order of assigning values to variables. Instead, we define them in Modelica, and
let the tool (in this case Dymola) solve them for us.
4. Check that the model is valid by using the “Check” command, indicated by a
green check mark at the top middle of the screen. You should see messages at the
bottom of your screen as shown in the Figure.

Notice that Dymola has identified that there is 1 unknown variable in our model
(T), and that there is 1 equation in the model (our ODE). Since we have the same
number of equations and unknowns, we can solve the problem. Dymola also runs
a number of other checks on the model which are not explicitly listed here.
However, if there were problems with the syntax or problems with how the model
is implemented, Dymola would try to detect and report them here, as either
Warnings or Errors. Models with Warnings can still be simulated, while models
with Errors will not simulate.

Check Model
5. Go to the Simulation view by clicking on the “Simulation” tab at the top of the
screen. Then, setup the simulation of the model using the “Setup” command at the
top middle of the screen. Configure as shown in the Figure. Finally, simulate the
model using the “Simulate” command at the top of the screen.

In the simulation setup, we are configuring the simulation to run for one hour of
simulation time, have an output interval of one second, and utilize the Dassl solver
with a tolerance of 1e-6. Note that the output interval of one second does NOT
define our integration timestep. The Dassl solver is a variable time-step solver,
meaning the actual integration timestep will be whatever is needed to successfully
solve the equations through time, and will vary depending on how quickly the
variables are changing.

Clicking the “Simulate” command actually invokes Dymola to perform multiple

processes. First, it processes the equations into a format in which the variables
can be sequentially solved. It also determines which groups of equations may need
to be solved iteratively, called algebraic loops (we do not have that problem in this
simple example). Then, it writes the equations into C code and compiles it.
Finally, it executes the compiled code, using the specified solver to solve (or
“integrate”) the model through time.

Simulation Setup
Simulate
6. Explore the results by selecting variables to plot in the Variable Browser to the
left of the screen. You can create new plot windows and plot diagrams by using
the commands at the top of the screen in the Plot Options tab, which appears when
you select a plot window. Plot the rock temperature and air temperature over time.
How long does it take for the rock to cool down?

Change the values of the parameters for air temperature and initial rock
temperature in the Variable Browser within the Value boxes and simulate again.
Does the cool-down time change? Now change the values of the parameters for
heat transfer coefficient or the radius of the rock. Does the cool-down time
change?

New Diagram

New Plot Window

Part 2: Connectors, Components, and Graphic Syntax
One of the strengths of Modelica is that it is object-oriented. This helps us be able
to build up libraries of component models which can be pieced together to form
larger, custom system models. There are two additional aspects that help us
achieve this capability. The first is the definition of connectors and the second is
graphical annotation.

Therefore, in this part, you will:

1. Learn the basic concept of connectors

2. Use the graphical syntax to connect component models into a larger system

First, let’s again give ourselves an example problem. Consider heat flow through a
multilayer wall, as shown in the diagram below, and a corresponding resistor-
capacitor network model (resistor-capacitor modeling in heat transfer is an
analogue to electrical circuit modeling). We are interested in simulating the
temperature of the inside air over time given a time-varying outside air
temperature.

ℎ%& ℎ"#$
!! !(
"%& ""#$
#, %, * %&

#, %, &, ' ' #, %, &, ' (

1 $' $& 1
ℎ!" % )' % )& % ℎ#$% %
!' !&
!!" !#$%

"#* !" "#$% ' "#$% &

In this problem, we could write down the governing system of equations and
implement the model in Modelica as we did in Part 1. However, this would be
time-consuming. Instead, let’s utilize the connector, component modeling, and
graphic syntax capabilities of Modelica to not only solve this problem, but give us
the ability to easily solve other, similar, problems.

Before doing this, we need to explore the nature of the resistance-capacitor model
a bit. To make things easier, we can simplify the model variables by giving the
resistors a resistance, R, and the capacitors a capacitance, C, which can each be
calculated from the more specific variables described before.

#!" #' #& ##$%

!' !&
!!" !#$%
"!" "' "&

For a resistor, a constitutive equation relates the heat flow through it to the
resistance and temperature different across it:

"
!! !"

𝑇$ − 𝑇%
𝑞=
𝑅

For a capacitor, a state equation relates the heat flow into the capacitor to the
capacitance and time-rate-of-change of the temperature:

"!

#
!!

𝑑𝑇$
𝐶$ =𝑞
𝑑𝑡
For any node where two or more components (a resistor or capacitor) connect,
Kirchoff Current and Voltage Laws (also conservation of energy) say that the net
heat flow at the node is zero and the temperature of all components at the node is
equal. That is, energy that leaves one component must flow into its neighbors and
at the point it connects to its neighbors the temperature must be the same:

!!

"! "#

""

𝑞$ + 𝑞% − 𝑞& = 0

Thinking back to our original problem, we have 19 unknown variables (4 R’s, 3

C’s, 5 node temperatures, and 7 component heat flows). We can assign all of the
R’s and C’s based on material properties. Furthermore, we can assume the outside
air temperature is just an input that we define. Therefore, we have 11 remaining
unknown variables; 4 remaining node temperatures and 7 component heat flows.
If we build a generic resistor model using the constitutive equation and instantiate
4 of them, that gives us 4 more equations. Similarly, if we build a generic
capacitor model using the state equation and instantiate 3 of them, that gives us
another 3 equations. Finally, if we could “connect” these components together as
shown in the diagram, we could gain 1 more equation per node which says that the
sum of heat flows is zero at the node. Then, we would have 4+3+4=11 equations,
which will allow us to solve for all 11 unknown variables!

Why did we go through all of this? What it tells us is we can individually build
generic component models that just define the relationship between the heat flow
through the component and the temperature(s) at the interface(s). Then, we can
connect these component models together in virtually any configuration and have
enough equations to solve for the whole system!

Now, let’s call the heat flow the “flow” variable and the temperature the
“potential” variable for a particular component (you can think of heat flowing
through the component while the temperature drives the potential for heat flow).
Then, we could say more generally that at a connection node: “flow” variables sum
to zero and “potential” variables are equal. As it turns out, this pairing of “flow”
and “potential” variables is analogous in other domains than just heat transfer. In
particular, electrical circuits, fluid flow, translational kinematics, and rotational
kinematics! This is one of the most powerful concepts that Modelica takes
advantage of in order to be able to facilitate the simulation of new systems. If
you’re interested in learning more about this concept of modeling that generalizes
across physical domains, it is often referred to as Linear Graph Modeling, and a
good discussion is presented from the MIT Mechanical Engineering Department:
• Part 1: http://web.mit.edu/2.14/www/Handouts/OnePorts.pdf
• Part 2: http://web.mit.edu/2.14/www/Handouts/TwoPorts.pdf

Physical Domain Potential (Across) Flow (Through)

Heat Transfer Temperature (!) Heat Flow (")
Fluid Flow Pressure (#) Mass Flow ($)
Electrical Voltage (%) Current (&)
Translational Displacement (') Force (()
Rotational Angle ()) Torque (*)

Having gone through all of this, let’s build our wall model.
1. Open Dymola. Go to File > Save > SaveAs and save the model file as shown in
the Figure below (it will be saved as Wall.mo).
2. Explore the Modelica Standard Library using the Package Browser on the left
side of the screen. In particular, navigate to the Thermal Resistor component
model at Modelica.Thermal.HeatTransfer.Components.ThermalResistor.
Then, click and drag it onto the modeling canvas. Then, double-click on the model
to configure it with the name “R1” and parameter R=0.05 K/W.

Double-click on the Thermal Resistor model in the Package Browser to open it.
Switch to the Modelica Text view (as we used in Part 1) and notice that the
graphical component has a corresponding text implementation. In fact, notice that
the parameter R is defined just as we did in our analytical model in Part 1, and
that Dymola used that information to populate the configuration we just used to
assign a value of 0.05 in a graphical context. Try also switching to the
“Documentation” view to read any information the model developer may have
given about the model, such as modeling approach, major assumptions, and
typical usage. Finally, switch to the “Icon” view to see how the graphic content is
constructed.

After you’ve finished exploring, switch back to the “Diagram” view of our Wall
model to continue building.
 Modelica Text View
Documentation View
Diagram View

Icon View
3. Add a second resistor to the Wall model by clicking and dragging a second
instance of Modelica.Thermal.HeatTransfer.Components.ThermalResistor
to the right of R1. Then, configure it to have the name “R2” and parameter R=0.1
K/W. Then, click the right heat port of R1 and hold while dragging your mouse to
the left heat port of R2. Then, let go. This “connects” the two components
together at that heat port. Continue this process of dragging, dropping,
configuring, and connecting components until all resistors and capacitors are added
according to the specifications in the table below. For capacitors, use
Modelica.Thermal.HeatTransfer.Components.HeatCapacitor.

Component Name Parameter Value

R1 R=0.05 K/W
R2 R=0.1 K/W
ROut R=0.01 K/W
RIn R=0.02 K/W
C1 C=1e4 J/K
C2 C=1e5 J/K
CIn C=1e3 J/K

Once the component models are implemented, switch to the Modelica Text view
and explore the corresponding text syntax of the wall model. Notice the
declaration of component models, instead of individual variables, and the uses of
the “connect” statements in the equation section.
4. Specify the outside air temperature by using Modelica.Blocks.Sources.Sine
and Modelica.Thermal.HeatTransfer.Sources.PrescribedTemperature.
For the sine block, use the parameterization shown on the next page. Flip the
direction of the blocks by selecting on them and using Arrange > Flip Horizontal at
the top of the screen (a keyboard shortcut is to press the letter “h” while selected).

Note that the sine block has an interface made of an “output” instead of a “heat port” as the
heat transfer models do. This block outputs a Real signal. In Modelica, we can incorporate the
generation, mathematical manipulation, and usage of Real signals in our system models. The
connection of signals from an output of one component to the input of another is done similarly
to connecting the heat ports from before. Here, the prescribed temperature component model
uses a Real signal as an input to specify the value of the temperature at its heat port, which
allows us to define the outside temperature node for ROut. In this case, according to a
sinusoidal signal defined by the sine block. Explore some of the other types of Real signal
generation blocks, as well as Boolean signals and available logic blocks. Note that signals are
only for the passage of numeric or Boolean values from one component to another and do not
represent anything physical like heat ports.

Arrange
5. Simulate the model for 1 day (86400 seconds) and an output interval of 60
seconds with the Dassl solver and tolerance of 1e-6. Plot the outside temperature
and the inside temperature as shown in the Figure below.

Change the x-axis to hours by right-clicking on the word “Time” > Time Unit > h.
Change the y-axis to °C by clicking Setup… > Display Unit > degC. Export the
results in the plot to a .csv file by right-clicking the word “Wall” in the Variable
Browser > Export Result > Only Plot Window. Then, for “Files of type” select
“Comma Separated Values”, give the file a name, and save it. Try opening it in
excel or using it in a Python script for post-processing.

Try changing the values of the R and C parameters and explore how it changes the
indoor air temperature. Plot the temperatures of C1 and C2 to understand how the
temperature is changing through the wall over time. Add more layers to the wall,
or try adding more sources of heat to the outside, like the sun, or inside, like lights!
For this, you will find the model
Modelica.Thermal.HeatTransfer.Sources.PrescribedHeatFlow helpful.

Setup
Part III: System Modeling
Now that you’ve learned the basics of Modelica syntax, the Dymola environment,
and connecting component models to form larger models, let’s build and analyze a
simple system model that contains a room and HVAC system for cooling. In doing
so, we can explore the performance of a number of design and control scenarios.

Therefore, in this part, you will:

1. Implement a system model that includes a room, fan, and weather data.
2. Explore the impact of increased thermal mass on the inside air temperature
with and without fan operation.
3. Add a simple vapor-compression cooling coil with thermostat control to
maintain the room air temperature according to a setpoint.
4. Adjust the room air temperature setpoint to simulate a demand-response
event and compare the cooling power profile to the case without the
demand-response event.
1. Open Dymola. Load the Modelica Buildings Library by File > Open > Load and
browsing to the “package.mo” file within the Buildings Library. Once loaded, you
should see Buildings available in your Package Browser. Then, go to File > Save
> SaveAs and save the model file as “System.mo.”
2. Use the following component models to build the system as shown in the
diagram below. Screenshots are shown for how to parameterize the models. Note
that the parameter values to edit are displayed in black text. Those in grey text are
defaults that are already configured and should be left as they are.

Model Path Description/Usage

Buildings.BoundaryConditions.WeatherData.ReaderTMY3 Loads weather data from a weather file
based on EPW.
Buildings.BoundaryConditions.WeatherData.Bus Allows for the use of weather data
throughout the model.
Buildings.Air.Systems.SingleZone.VAV.Examples.BaseClasses.Room Single zone room model with 4 exterior
walls, a roof, and a floor. The south
wall has a large window. The model
implements a detailed heat balance to
calculate the inside air temperature,
including conduction through exterior
walls/roof/floor from the outside (using
a 1-D finite difference approximation),
solar radiation on exterior surfaces and
windows, interior radiation exchange,
surface convection based on
temperature difference and surface
orientation, internal gains and
schedules, and infiltration.
Buildings.Fluid.Movers.FlowControlled_m_flow Fan model with mass flowrate as
control input signal.
Buildings.Fluid.Sensors.TemperatureTwoPort Temperature sensor for supply air.
Buildings.Fluid.Sources.Outside Ideal boundary from where air can flow
into the fan and out of the room.
Weather data can be used to specify the
conditions of the boundary air through
time.
Modelica.Blocks.Sources.Constants Generates a constant signal as output.
Used here as a control signal for the
fan.
For the “filNam” parameter, specify the full path to the weather file within the
quotations. There are example weather files within the Buildings library. Here is
an example on my system of how the parameter should look:

Notice that the weather file is a .mos file and not a .epw file. This is because the
data format needs to be in a “Modelica table” format to be read into the model.
The Buildings library provides a program to convert .epw files into .mos files. The
program is located at Buildings/Resources/bin/ConvertWeatherData.jar and
instructions can be found in the Documentation section “Adding new weather
data” of the model Buildings.BoundaryConditions.WeatherData.ReaderTMY3.
3. Simulate the model from day 120 to 125 with a 60 second output interval using
the Dassl solver with a tolerance of 1e-6. Plot the outside air temperature and
inside air temperature as shown in the plot below.
4. Increase the thermal mass in the room by increasing the concrete floor slab
thickness from 1” to 6”. Do this by opening the “room” configuration (double-
click on the room model). Then, click on the grey box to the right of the parameter
called “matFlo”, which sets the material layers for the floor construction. Then,
click on the small black arrow next to the “material” parameter and choose Edit
Text. Then, change the line that reads “x=0.025” to “x=0.025*6”. This is the
concrete slab floor thickness in meters. Click OK on all of the open windows.
Now, simulate the model again. The results in the plot will update. Compare with
the previous simulation by expanding the previous result in the Variable Browser
and plotting the room air temperature variable.

What do you notice about the air temperature with higher thermal mass compared
to the temperature with lower thermal mass?
5. Turn on the fan by changing the changing the “k” parameter of the model “con”
to 0.5. This will specify that the fan constantly blows 0.5 kg/s of air into the room.
Since it looks like our outside air temperature is always less than our inside air
temperature, this will help us cool down the room. Simulate the model and look at
the updated results.
6. The peak inside air temperature still reaches over 305 K, which is about 32 C
and 89 F! Add a simple vapor-compression cooling model and controls by adding
the following component models as shown in the diagram and screenshots below.

Model Path Description/Usage

Buildings.Fluid.HeatExchangers.HeaterCooler_u An ideal heater or cooler with a control input signal
that specifies the fraction of maximum heating or
cooling power to apply to the passing fluid.
Buildings.Controls.Continuous.LimPID A PID feedback controller that is used to control the
cooling power based on room air temperature setpoint
and room air temperature measurement.
Modelica.Blocks.Sources.CombiTimeTable The output signal is specified using a table of values
that can be defined at particular simulation times. We
will use this to specify the room air temperature
setpoint. When connecting to the component
“conCoo”, use index [1] in the resulting prompt.
Modelica.Blocks.Math.Gain Multiplies the input signal by a constant value and
outputs the result. We will use this to convert the
thermal power calculated by the cooler model to
electrical power by a constant assumed COP.
Modelica.Blocks.Interfaces.RealOutput Allows the input signal to serve as an output for the
whole model. This makes it easier to view results, and
also allows the model to be connected to other models.
Click on the grey box to the right of the parameter “table” to edit the table. We
will just define the output value (22 C) at simulation time 0, and let it be constant
for the entire simulation.
Two additional parameters will specify the output to be constant segments between
time intervals (instead of interpolating), and to hold the last value specified for the
rest of the simulation time (instead of another extrapolation scheme).
7. Simulate the model and plot the room air temperature, outside air temperature,
and cooling power. Use the “New Diagram” command icon to split the plot
window between temperature and power measurements. Then, open the “Setup”
window, and set the display unit to deg C.
8. Let’s implement a demand-response event on the 4th day between 1pm and 4pm.
To respond, we want to increase the zone temperature setpoint by 3 C. Edit the
setpoint table to achieve this. Then, simulate the model again. Compare the power
consumption profile to that without the demand response event. What do you
notice?
Zoom in on the demand response day by using plot Setup and modifying the
horizontal range. You must do this for both subplots. You can also modify the
vertical range for the temperature plot, compare the demand response room air
temperature measurement to the previous, and further edit the plot properties as
you wish.