lbl-srg/modelica-buildings

Modelica Buildings library

Modelica Buildings library

This is the development site for the Modelica Buildings library and its user guide.

Stable releases including all previous releases are available from the main project site at http://simulationresearch.lbl.gov/modelica.

Instructions for developers are available on the wiki.

Library description

The Modelica Buildings library is a free open-source library with dynamic simulation models for building energy and control systems. The library contains models for

• HVAC systems,
• energy storage,
• controls, including a reference implementation of ASHRAE Standard 231P,
• heat transfer among rooms and the outside, either
  • natively in Modelica with a detailed or a reduced order model, or
  • integrated run-time coupling with EnergyPlus, aka, Spawn of EnergyPlus
• multizone airflow, including natural ventilation and contaminant transport,
• single-zone computational fluid dynamics coupled to heat transfer and HVAC systems,
• data-driven load prediction for demand response applications, and
• electrical DC and AC systems with two- or three-phases that can be balanced and unbalanced.

The main project site is http://simulationresearch.lbl.gov/modelica.

Current release

Download Buildings Library 11.0.0 (2024-04-09)

License

The Modelica Buildings Library is available under a 3-clause BSD-license. See Modelica Buildings Library license.

Python modules are available under a 3-clause BSD-license. See BuildingsPy license.

Development and contribution

You may report any issues with using the Issues button.

Contributions in the form of Pull Requests are always welcome. Prior to issuing a pull request, make sure your code follows the style guide and coding conventions.

Building binaries

The distribution at https://simulationresearch.lbl.gov/modelica/download.html contains all binaries.

Developers may build the binaries as follows.

Spawn of EnergyPlus

The Buildings library already contains the compiled binaries that are needed to link to EnergyPlus.

To rebuild the Spawn of EnergyPlus binaries, CMake is required. The binaries consist of the fmi-library, and a library that connects Modelica to EnergyPlus.

To build the fmi-library, which is only needed if https://github.com/modelon-community/fmi-library is updated, run

cd Buildings/Resources/src/fmi-library
rm -rf build && mkdir build && \
  cd build && cmake .. && cmake --build . && \
  cd .. && rm -rf build

To build the Modelica to EnergyPlus library, run

cd modelica-buildings
rm -rf build && mkdir build && cd build && \
  cmake ../ && cmake --build . --target install && \
  cd .. && rm -rf build

To install the EnergyPlus binaries for the Spawn interface for the current operating system, run

Buildings/Resources/src/ThermalZones/install.py --binaries-for-os-only

To install the binaries for all operating systems, omit the flag --binaries-for-os-only

Citation

To cite the library, use

Michael Wetter, Wangda Zuo, Thierry S. Nouidui and Xiufeng Pang. Modelica Buildings library. Journal of Building Performance Simulation, 7(4):253-270, 2014.

@Article{WetterZuoNouiduiPang2014,
  author  =  {Michael Wetter and Wangda Zuo and Thierry S. Nouidui and Xiufeng Pang},
  title   =  {Modelica {Buildings} library},
  journal =  {Journal of Building Performance Simulation},
  volume  =  {7},
  number  =  {4},
  pages   =  {253--270},
  year    =  {2014},
  doi     =  {10.1080/19401493.2013.765506},
  url     = "https://doi.org/10.1080/19401493.2013.765506"
}

modelica-buildings's Issues

add a block that computes wind pressure

In Buildings.Airflow.Multizone, add a block that computes the pressure on a facade due to wind. This model may also include the term for the static pressure of the outside air (p=rho_g_h) to model air flow due to stack effect and wind pressure.

add default component name to all models and blocks

Add a default component name to all models and blocks.
Revise the file ../../bin/checkRelease.sh to check for missing default component names.

add multiplier for room air heat capacity

Add a parameter that multiplies the heat capacity of the air volume. This will allow approximation of the heat capacity of furniture.

fix typo in function name glassAbsInterirorIrradiationNoShading

The function {{{Buildings.HeatTransfer.Windows.Functions.glassAbsInterirorIrradiationNoShading}}}
should be called
{{{Buildings.HeatTransfer.Windows.Functions.glassAbsInteriorIrradiationNoShading}}}

add model for design day weather data

Add a model that allow computing winter and summer design day weather data. The model should use the same weather bus as the current weather data reader.

This will be needed for LearnGB.

improve dry coil model

In !DryCoilDiscretized, ensure that hA computation is fixed at compile time. This may reduce the nonlinear system of equations.

Test with
{{{
Buildings/Fluid/HeatExchangers/Examples/DryCoilDiscretized.mo
Buildings/Fluid/HeatExchangers/Examples/DryCoilDiscretizedPControl.mo
}}}
Also test with the wet coil implementation.

test-ticket

add ramp model for signals

When switching a component on or off, such as a pump, the solver can have difficulties in finding a solution to nonlinear systems of equations in large fluid flow network. As a work-around, a first order differential equation is often used.

As an alternative approach, a block that limits the rate of change of its output signal should be developed, tested with large system models, and if successful added to the library.

For a step input from a to b, this block should output a ramp that continuously changes the output between a and b.

update release notes with improvements for window model

The improvement to the window model need to be reported in the release notes
{{{
Buildings.UsersGuide.ReleaseNotes.Version_X_Y_buildY
}}}
so that users understand what has been changed from one version to another.

Add wind speed to weather bus and fix variable description

In {{{Buildings.BoundaryConditions.WeatherData.ReadWeatherData}}}, the wind speed is missing. This is required for the convective heat transfer model of the window.

Also, the comment of some variables that are on the weather bus need to be fixed. For example, pAtm should be "Atmospheric pressure" or "Outside pressure", the comment of nTol is wrong and the Outside relative humidity should be dimensionless.

rewrite code for optical model that triggers events

Buildings.HeatTransfer.WindowsBeta.BaseClasses.AbsorbedRadiation and TransmittedRadiation trigger many state events:

The events are caused by the "if" statement and the "integer(x)". This causes about 10 event iterations for each day of simulation, which limits the integration step size (and is expensive).

As a work-around, the "integer(x)" may be avoided if another interpolation is used than the cubicHermite function, or if the whole section between integer(x) and cubicHermite(...)" is put into a function and the smooth annotation is used.

As a test case, enable event logging during simulation and run Buildings.RoomsBeta.Examples.MixedAirFreeResponse

The problematic section is:
{{{
if incAng < 0.5_Modelica.Constants.pi then
x := 2_(NDIR - 1)_abs(incAng)/Modelica.Constants.pi
"x=(index-1)_incAng/(0.5pi), 0<=x<=NDIR";
x := x + 2;
k1 := integer(x) "2<=k<=NDIR+2=HEM+1";
k2 := k1 + 1 "3<=k2<=NDIR+3=HEM+2";

for i in 1:N loop
  // Glass without shading: Add absorbed direct radiation
  y1d := (coeAbsEx[NoShade, i, k1 + 1] - coeAbsEx[NoShade, i, k1 - 1])/2;
  y2d := (coeAbsEx[NoShade, i, k2 + 1] - coeAbsEx[NoShade, i, k2 - 1])/2;
  tmpNoSha := Modelica.Fluid.Utilities.cubicHermite(...

}}}

bug in long-wave radiation exchange

The model RoomsBeta.BaseClasses.InfraredRadiationExchange.mo computes wrong radiative heat exchange. The error seems to be largest if there are surfaces in the room with largely different areas. Energy is conserved by the model, but the distribution of the radiative heat exchange is wrong.

The attached total model illustrates the problem. The model has no windows.
If in the attached total model, the areas are changed from
A = {40, 8, ...
to
A = {24, 24, ...
then the room-facing surface of the first construction (roo.conExt[1].opa.port_b.T) changes its temperature by a significant amount. It appears that a larger surface area leads to a smaller temperature.

Examples.SingleUTubeBoundaryCondition hangs

When running dymola run.mos with Dymola 2012-FD01 on Linux, where run.mos contains the lines
{{{
openModel("package.mo");
Modelica.Utilities.Files.remove("unitTests.log");
RunScript("Resources/Scripts/Dymola/Fluid/HeatExchangers/Boreholes/BaseClasses/Examples/SingleUTubeBoundaryCondition.mos");
// Save log file
savelog("unitTests.log");
Modelica.Utilities.System.exit();
}}}
then Dymola 2012-FD01 does not return. The same behavior has been observed when the example is run from the pull-down menu.

The example works with Dymola 2012 for Linux.

Add switch in weather data reader

Add switch in weather data so that it can read real weather data or user specified input

Move SimTim into Weather Data Reader

Added Simtim into ReadWeatherData.mo and updated 10 examples using it.

Add radiation model for uncoated glass

Add radiation model for uncoated glass. The model will be based on WINDOW4.0 documentation page 26 and 27.

Radiator nominal power may need to be adjusted

In RadiatorEN442_2, due to the discretization, the finite volume model gives a different nominal power compared to the EN calculation.

Check if a correction term can be used to scale Q_flow_nominal so that the nominal power is the same as if computed using EN 442-2.

Unit tests fail Buildings.BoundaryConditions.SolarIrradiation

The following unit tests fail on the trunk
simulateModel("Buildings.BoundaryConditions.SolarIrradiation.BaseClasses.Examples.BrighteningCoeffcient", stopTime=8640000, method="dassl", resultFile="BrighteningCoeffcient");
simulateModel("Buildings.BoundaryConditions.SolarIrradiation.BaseClasses.Examples.RelativeAirMass", stopTime=864000, method="dassl", resultFile="RelativeAirMass");
simulateModel("Buildings.BoundaryConditions.SolarIrradiation.BaseClasses.Examples.SkyBrightness", stopTime=8640000, method="dassl", resultFile="SkyBrightness");
simulateModel("Buildings.BoundaryConditions.SolarIrradiation.Examples.DiffuseSolarIrradiationPerez", stopTime=8640000, method="dassl", resultFile="DiffuseSolarIrradiationPerez");
simulateModel("Buildings.BoundaryConditions.SolarIrradiation.Examples.DirectSolarIrradiationTiltedSurface", stopTime=8640000, method="dassl", resultFile="DirectSolarIrradiationTiltedSurface");

The model RelativeAirMass also fails on Wangda's branch. To reproduce, run
cd Buildings
../../bin/runUnitTest.py
dymola runAll

Bug in WindowRadiation. Shade does not absorb radiaton.

The test model
bie/branches/mwetter/work/bie/modelica/Buildings/HeatTransfer/Windows/BaseClasses/Examples/WindowRadiation.mo, revision 1791
has an interior shade.

When running !WindowRadiation.mos, the solar radiation that is absorbed by the shade is zero. The same is true if the shade is set to an exterior shade. However, the transmitted solar radiation into the room is lower if the shade is deployed.

Running a diff on !RadiationData.mo and !WindowRadiation.mo on the branches mwetter and wzuo does not seem to give any differences in the model other than renaming of variables and parameters. However, in the test model in Wangda's branch, the shade does absorb radiation.

Any idea what can cause this? Please revise on bie/branches/mwetter/work/bie/modelica as there was quite some change in comments and in variable names to be consistent with the other models of the room model.

move Building.Fluid.Utilities to Building.Utilities

The functions in Buildings.Fluid.Utilities belong to the Math package in Buildings.Utilities

add check for uses statement in bin/checkRelease.py

Add a check to bin/checkRelease.py to ensure that only Buildings/package.mo has the annotation uses(...)

Rename the weather data reader

To clarify that the weather data reader is designed for TMY3 data, we will change the name of Reader.mo to ReaderTMY3.mo. We need to change the Reader in all models that use it.

Overshooting in enhanced stratified tank

There are some problems in the implementation of enhanced stratified tank. The current implementation will cause energy unbalance. Although we remedy this by adding a energy correction function, it causes temperature overshoot. A better implementation is needed for solving this problem.

Add comments in Reader for 30 mins shift in radiation data

To explain why we shift the time for 30 mins when we read the radiation data, we will add comments and figure in the Reader.

Wrong units for radiation in epw file

The E+ weather data unit is written as Wh/m2, which is also written in the EnergyPlusWeatherDataExplanation. However, it is wrong. The correct unit should be W/m2. Otherwise, the radiation will be too small (less than 1W/m2 in SF).

Need to

1. Correct the java code
2. Update the units in weather data file
3. Change the input unit for ConvertRadiation.mo

Add additional test cases for medium packages

The medium models compute u and h in the BaseProperties package, using an implementation of
h = u + p*v
There are also modelica functions to compute h and u as a function of the state.

To make sure that the two implementations are consistent, unit tests need to be implemented that trigger an assert if u and h, as computed in the BaseProperties, are different from the values computed by the functions. This implementation should be done for all medium models.

As part of this task, the implementations of other functions, in particular the Gibbs and Helmholtz energy for media other than ideal gases, need also be reviewed.

The reason for this task is that inconsistent implementation of u and h have been shown to lead to wrong initialization of the temperature of mixing volumes, thereby introducing fast temperature changes at the beginning of the simulation.

add port for adding radiant heat gains to Rooms/MixedAir

To connect a radiator to the room model, convective and radiative heat gain needs to be added to the room.

Therefore, the room model needs to have a port ({{{HeatPort}}} or {{{RealInput}}}?) that allows adding radiative heat to the radiation heat distribution model.

If a {{{HeatPort}}} is used, then the implementation needs to make sure that {{{HeatPort.Q_flow}}} is zero if the port is unconnected. Most likely, a {{{RealInput}}} is a better design as it would not be clear whether {{{HeatPort.T}}} is the radiative temperature of the room or of the radiator.

Bug in BlackBody

A model that uses WeatherData.ReaderTMY3 can not be translated when the parameter calTSky is set to Buildings.BoundaryConditions.Types.SkyTemperatureCalculation.HorizontalRadiation.

check fan and pump models for pressure differences that are outside the performance curves

Check what happens to the fan (and pump) model if

• the inlet pressure is higher than the outlet pressure (such as a return fan that is off in a building with net positive pressure).
• the outlet pressure minus the inlet pressure is higher than the fan head at zero flow (e.g., two parallel pumps, where one is on and the other is off).

clean up illegal html code

The library contains illegal HTML code. Most of this will be
corrected by the viewing browser but I thought it's best to point you to
it. We have similar problems in the MSL. Typically are things like
non-opened or non-closed environments (e.g.,

...

). The way I
tested it in the past was to let Dymola generate the documentation and
then look at it with for example http://users.skynet.be/mgueury/mozilla/
The only problem here is that Dymola itself pollutes the HTML code with
illegal statements during the export process. The best would actually be
if you have the means of script extracting the html code from the
Modelica files and then checking with a validator :)

error in weather data reader

The model Buildings.BoundaryConditions.WeatherData.BaseClasses.ConvertTime has been reformulated to avoid use of the integer function inside the equation section. The use of the integer function prevents dymola from differentiating this model when conducting index reduction. The new formulation uses a when-then construct instead of the integer function.

With the new formulation, the command
simulateModel("Buildings.BoundaryConditions.WeatherData.Examples.ReaderTMY3", startTime=-8.64e+06, stopTime=6.3072e+07, method="dassl", resultFile="ReaderTMY3");

yields
The following error was detected at time: 108864

Model error - Modelica.Math.log (0.00366099212886692*weaDat.TBlaSky.TDewPoiK) = Modelica.Math.log (-0.262373)

The stack of functions is:
Buildings.Utilities.Math.Functions.smoothMin(weaDat.TBlaSky.TDryBul, weaDat.TBlaSky.TDewPoi, 0.1)

---

Also, the old formulation was not robust, as the command
simulateModel("Buildings.BoundaryConditions.WeatherData.Examples.ReaderTMY3", startTime=-8.64e+06, stopTime=6.3072e+07, method="dassl", resultFile="ReaderTMY3");
caused
The following error was detected at time: 108864

Model error - Modelica.Math.log (0.00366099212886692*weaDat.TBlaSky.TDewPoiK) = Modelica.Math.log (-0.262373)

The stack of functions is:
Buildings.Utilities.Math.Functions.smoothMin(weaDat.TBlaSky.TDryBul, weaDat.TBlaSky.TDewPoi, 0.1)
Integration terminated before reaching "StopTime" at T = -3.46e+04

The new formulation should be fixed so that the data reader works for the above command. Please also test combinations of start times and end times that are below zero or below one year and above one year.

Radiation models

use the local civil instead of the clock time to compute the incident angle.

move scripts to Buildings\Resources\Scripts\Dymola

Move all scripts to {{{Buildings\Resources\Scripts\Dymola\package1\package2}}} and update annotation as in
{{{Modelica/Mechanics/Rotational/CoupledClutches.mo}}}:
{{{
annotation(
__Dymola_Commands(file="modelica://Modelica/Resources/Scripts/Dymola/Mechanics/Rotational/CoupledClutches.mos"
"Simulate and Plot"),
...)
}}}

Add a on/off option for EIR chillers

We need a On/Off switch to enable or disable the EIR chillers as we do for Carnot chiller.

Steady-state model of mover: Error: Singular inconsistent scalar system for der(sou.ports[2].m_flow) = .... = -8.34384e-23/0

The example Buildings.Fluid.Movers.Examples.ControlledFlowMachine
https://corbu.lbl.gov/svn/bie/branches/mwetter/dev-zeroFlow/bie/modelica/Buildings, revision 2486

has the error
Error: Singular inconsistent scalar system for der(sou.ports[2].m_flow) = .... = -8.34384e-23/0

See Dynasim ticket #13602

Buildings.HeatTransfer.Windows.Functions.glassPropertyUncoated

The function
{{{
Buildings.HeatTransfer.Windows.Functions.glassPropertyUncoated()
}}}
has two sections
{{{
annotation (Documentation(info="...
}}}
Delete one of them and fix the reference "Fuler et"

Also, consider removing the tables unless the equation numbers are needed. This will then automatically align the equations if the html markup
{{{

}}} is used.

add new model for DX coil

Add dynamic models, similar to
Single-Speed Electric DX Air Cooling Coil (but with ODE)
Multi-Speed Electric DX Air Cooling Coil (but with discrete switching between stages instead of !SpeedRatio)

DataReader

In the data reader:

• shift the time for the radiation data 30 min forth.
• output the local civil time in the data reader. This will be used later on in the radiation models.

create FMU generator in python

Implement a function in BuildingsPy that generates an FMU for co-simulation. The function can be similar to the currently implemented function that simulates a model.

This is needed for LearnGB.

In the room model, the convective internal heat gain has the wrong sign

When specifying the convective heat gain for the room model, a positive input causes the extraction of heat instead of the addition of heat.

Correct the Document for Carnot Chiller

Current doc for Carnot chiller needs to be corrected: "Chiller with performance curve adjusted based on Carnot efficiency".

verify epsilon-NTU heat exchanger for numerical robust implementation

Verify that {{{Buildings.Fluid.HeatExchangers.BaseClasses.PartialEffectiveness}}}
and the models that extend this model are numerically robust near zero mass flow rate.

In particular, verify the following item from https://corbu.lbl.gov/trac/bie/wiki/DevelopmentCheckList is satisfied (for Q_flow and the outlet temperatures):
Avoid equations where the first derivative with respect to another variable is zero, except at a single point. For example, if x, y are variables, and x = f(y), avoid y = 0 for x<0 and y=x^2^ otherwise. The reason is that if a simulator tries to solve 0=f(x), then any value of x <= 0 is a solution, which can cause instability in the solver.

Typo in Weather Data file

Typo in the comment line 17:

C7 Extraterrestrial direct normal radiation in Wh

Unit should be Wh/m2

Add Wet bulb temperature in weatherdata file reader

Add a wet bulb temperature into weather data file reader. In this case, we can use moisture air. To avoid the numerical Jacobian, we should simplify TWetBul_TDryBulXi by fixing the i_w = 1.

Source code:
parameter Integer i_w(min=1, fixed=false) "Index for water substance";

check for annoation structurallyIncomplete

Remove structurallyIncomplete annotation.

high window frame temperatures

When simulating
{{{
simulateModel("Buildings.RoomsBeta.Examples.TestConditionalConstructions.OnlyExteriorWallWithWindow",
startTime=1.82304e+07, stopTime=1.83168e+07,
method="radau", resultFile="OnlyExteriorWallWithWindow");
}}}
with the surface area of the window set to A=0.004 m2 (in order to minimize the solar heat gains that enter the room model), the maximum surface temperatures of the frame are, as obtained from {{{roo.conExtWin[*].win.frame.port_{a,b}.T}}}

• 96 degC for port a of the ceiling
• 68 degC for port b of the ceiling
• 40 degC for port a of the floor
• 33 degC for port b of the floor

The room air temperature is around 20 deg C. The solar absorptivity is 0.5.

These temperatures seem high and need to be verified.

run experiment with water density as a function of T only

In Buildings.Media.Interfaces.PartialSimpleMedium, try to use

d = d_const * (1+kT_(T-T0)/T0);
Compare the size of coupled equations and the run-time compared to
d = if constantDensity then d_const else d_const * (1+kappa_const_(p-p0));
for both settings of constantDensity

use of BaseProperties

Translating large models is time consuming. It is not clear if the use of medium functions as opposed to the use of the BaseProperties would speed up the translation because Dymola differentiates the equations in the BaseProperties during translation.

This task should compare translation time and the size of coupled equations of large models with and without the use of BaseProperties.

wrong surface tilt for radiation at exterior surfaces of floors and ceilings

The package {{{Buildings.HeatTransfer.Types.Tilt}}} defines
{{{
constant Modelica.SIunits.Angle Ceiling=0 "Tilt for ceiling";
constant Modelica.SIunits.Angle Wall = Modelica.Constants.pi/2 "Tilt for wall";
constant Modelica.SIunits.Angle Floor = Modelica.Constants.pi "Tilt for floor";
}}}

The model {{{Buildings.RoomsBeta.MixedAir}}} assigns the parameter
{{{
til=Modelica.Constants.pi*ones(nConExt) - datConExt.til
}}}
in the instances bouConExt and bouConExtWin.
This correctly changes the tilt for the convective heat transfer coefficient since the exterior surface of a floor becomes a ceiling.
However, for the radiation balance, this switch must not be made, as the implementation in {{{Buildings.BoundaryConditions}}} is such that the tilt of a ceiling is 0 degree, and the tilt of a roof is 180 degree.

bug in ConvertRelativeHumidity

The model ConvertRelativeHumidity declares the input and output as having units "1", but it uses
relHumOut = Buildings.Utilities.Math.Functions.smoothLimit(
relHumIn/100,
relHumMin,
relHumMax,
delta/10);
Why is the division by 100? Relative humidity must be between 0 and 1, and be converted as soon as possible if it comes in units of 100 from the weather file. This needs to be fixed and verified with the epw file before the library can be released.

Modelica.Blocks.Interfaces.RealInput relHumIn(unit="1")
"Input relative humidity data in percentage"
annotation (Placement(transformation(extent={{-140,-20},{-100,20}})));
Modelica.Blocks.Interfaces.RealOutput relHumOut(unit="1")
"Relative humidity in (0, 1)"
annotation (Placement(transformation(extent={{100,-10},{120,10}})));

constant Real delta=0.01 "Smoothing parameter";
protected
constant Real relHumMin=delta "Lower bound";
constant Real relHumMax=1 - delta "Upper bound";
equation
relHumOut = Buildings.Utilities.Math.Functions.smoothLimit(
relHumIn/100,
relHumMin,
relHumMax,
delta/10);