Library logo

Buildings.UsersGuide

User's Guide

Information

The Buildings library is a free open-source library for modeling of building energy and control systems. Many models are based on models from the package Modelica.Fluid and use the same ports to ensure compatibility with models from that library.

The web page for this library is http://simulationresearch.lbl.gov/modelica. We welcome contributions from different users to further advance this library, whether it is through collaborative model development, through model use and testing or through requirements definition or by providing feedback regarding the model applicability to solve specific problems.

The library has the following User's Guides:

  1. General information about the use of the Buildings library is available at http://simulationresearch.lbl.gov/modelica/userGuide. This web site covers general information that is not specific to the use of individual packages or models. Discussed topics include how to get started, best practices, how to post-process results using Python, work-around for problems and how to develop models.
  2. Some packages have their own User's Guides that can be accessed by the links below. These User's Guides are explaining items that are specific to the particular package.
    Airflow.Multizone Package for multizone airflow and contaminant transport.
    BoundaryConditions Package for computing boundary conditions, such as solar irradiation.
    Controls.OBC Package with the Control Description Language (CDL) and with control sequences that are implemented using CDL.
    Fluid Package for one-dimensional fluid in piping networks with heat exchangers, valves, etc.
    Fluid.Actuators Package with valves and air dampers.
    Fluid.FMI Package with blocks to export thermofluid flow models as Functional Mockup Units.
    Fluid.HeatExchangers.ActiveBeams Package with active beams.
    Fluid.HeatExchangers.DXCoils Package with direct evaporative cooling coils.
    Fluid.HeatExchangers.RadiantSlabs Package with radiant slabs.
    Fluid.Movers Package with fans and pumps.
    Fluid.Sensors Package with sensors.
    Fluid.Storage Package with storage tanks and an expansion vessel.
    Fluid.SolarCollectors Package with solar collectors.
    Fluid.Interfaces Base models that can be used by developers to implement new models.
    HeatTransfer Package for heat transfer in building constructions.
    ThermalZones.Detailed.UsersGuide.MixedAir Package for heat transfer in rooms and through the building envelope with the room air being modeled using the mixed air assumption.
    ThermalZones.Detailed.UsersGuide.CFD Package for heat transfer in rooms and through the building envelope with the room air being modeled using computational fluid dynamics.
    ThermalZones.Detailed.Examples.FFD.UsersGuide Package with examples that use the Fast Fluid Dynamics program for the computational fluid dynamics.
    ThermalZones.EnergyPlus.UsersGuide Package for Spawn of EnergyPlus with models that use EnergyPlus to simulate one or several building envelope models.
    Utilities.IO.Python_3_8 Package to call Python functions from Modelica.
    Utilities.Plotters Package that allow writing time series and scatter plots to an html output file.

  3. There are also tutorials available at Buildings.Examples.Tutorial. These tutorials contain step by step instructions for how to build system models.

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

Package Content

Name Description
Buildings.UsersGuide.Conventions Conventions Conventions
Buildings.UsersGuide.ReleaseNotes ReleaseNotes Release notes
Buildings.UsersGuide.Contact Contact Contact
Buildings.UsersGuide.Acknowledgements Acknowledgements Acknowledgements
Buildings.UsersGuide.License License License

Buildings.UsersGuide.Conventions Buildings.UsersGuide.Conventions

Conventions

Information

The Buildings library uses the following conventions, which largely are based on the conventions of the Modelica Standard Library.

Package structure

Packages have usually the following subpackages:

Naming

  1. Class names of models, blocks and packages should start with an upper-case letter and be a noun or a noun with a combination of adjectives and nouns. Use camel-case notation to combine multiple words, such as HeatTransfer. Don't repeat higher level package names, for example, rather than Chillers.CarnotChiller, use Chillers.Carnot.
  2. Instance names should be a combination of the first three characters of a word, such as preDro for pressure drop model. Where applicable, a single character can be used if this is generally understood, such as T for temperature, p for pressure, u for control input and y for control output signal. As needed, these can be augmented, for example a controller that outputs a control signal for a valve and a damper may output yVal and yDam.
  3. The following variables are frequently used for physical quantities:
    • T for temperature,
    • p for pressure,
    • dp for pressure difference,
    • P for power,
    • E for energy (or Q for thermal energy),
    • X for mass fraction,
    • Q_flow for heat flow rate
    • m_flow for mass flow rate and
    • H_flow for enthalpy flow rate.
  4. The nomenclature used in the package Buildings.Utilities.Psychrometrics is as follows,
    • Uppercase X denotes mass fraction per total mass.
    • Lowercase x denotes mass fraction per mass of dry air.
    • The notation z_xy denotes that the function or block has output z and inputs x and y.
    • The symbol pW denotes water vapor pressure, TDewPoi denotes dew point temperature, TWetBul denotes wet bulb temperature, and TDryBul (or simply T) denotes dry bulb temperature.
  5. Control input signals usually start with u and control output signals usually start with y, unless use of the physical quantity is clearer.
  6. The following strings are frequently used:
  7. The two connectors of a domain that have identical declarations and different icons are usually distinguished by _a, _b or _p, _n. Examples are fluid ports port_a and port_b or electrical connectors terminal_p and terminal_n.

Documentation

  1. In the html documentation, start additional headings with h4. (The headings h1, h2, h3 must not be used, because they are utilized from the automatically generated documentation.)
  2. Comments must be added to each class (package, model, function etc.).
  3. The first character should be upper case.
  4. For one-line comments of parameters, variables and classes, no period should be used at the end of the comment.

Graphical display

  1. The instance name of a component is always displayed in its icon (using the text string "%name") in blue color.
  2. A connector class has the instance name definition in the diagram layer and usually not in the icon layer, unless this helps with usability.
  3. The value of main parameters, such as nominal capacity, are displayed in the icon in black color in a smaller font size as the instance name if this helps with usability.

Miscellaneous

  1. Where applicable, all variable must have units, also if the variable is protected.
  2. Each class (i.e., model, block and function) must be used in an example or validation case.

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

Modelica definition

class Conventions "Conventions" extends Modelica.Icons.Information; end Conventions;

Buildings.UsersGuide.Contact Buildings.UsersGuide.Contact

Contact

Information

Contact

The development of the Buildings library is organized by
Michael Wetter
Lawrence Berkeley National Laboratory (LBNL)
One Cyclotron Road
Bldg. 90-3147
Berkeley, CA 94720
USA
email: MWetter@lbl.gov

Extends from Modelica.Icons.Contact (Icon for contact information).

Modelica definition

class Contact "Contact" extends Modelica.Icons.Contact; end Contact;

Buildings.UsersGuide.Acknowledgements Buildings.UsersGuide.Acknowledgements

Acknowledgements

Information

Acknowledgements

The development of this library was supported by:

The core of this library is the Modelica IBPSA library, a free open-source library with basic models that codify best practices for the implementation of models for building and community energy and control systems. The development of the IBPSA library is organized through the IBPSA Project 1 of the International Building Performance Simulation Association (IBPSA). From 2012 to 2017, the development was organized through the Annex 60 project of the Energy in Buildings and Communities Programme of the International Energy Agency (IEA EBC).

The package for multizone airflow modeling and the model for thermal comfort was contributed by the United Technologies Research Center, which also contributed to the validation of the room heat transfer model.

We thank Dietmar Winkler from Telemark University College for the various feedback that helped improve the organization and structure of the library.

The following people have directly contributed to the implementation of the Buildings library (many others have contributed by other means than model implementation):

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

Modelica definition

class Acknowledgements "Acknowledgements" extends Modelica.Icons.Information; end Acknowledgements;

Buildings.UsersGuide.License Buildings.UsersGuide.License

License

Information

License

Modelica Buildings Library. Copyright (c) 1998-2024 Modelica Association, International Building Performance Simulation Association (IBPSA), The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy) and contributors. All rights reserved.

NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit other to do so.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the names of the Modelica Association, International Building Performance Simulation Association (IBPSA), the University of California, Lawrence Berkeley National Laboratory, U.S. Dept. of Energy, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You are under no obligation whatsoever to provide any bug fixes, patches, or upgrades to the features, functionality or performance of the source code ("Enhancements") to anyone; however, if you choose to make your Enhancements available either publicly, or directly to Lawrence Berkeley National Laboratory, without imposing a separate written license agreement for such Enhancements, then you hereby grant the following license: a non-exclusive, royalty-free perpetual license to install, use, modify, prepare derivative works, incorporate into other computer software, distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form.

Note: The license is a revised 3 clause BSD license with an ADDED paragraph at the end that makes it easy to accept improvements.

Third Party License

To parse weather file, the function getTimeSpan.c uses third party code that uses the following license:

Copyright (c) 2011 The NetBSD Foundation, Inc.
All rights reserved.

This code is derived from software contributed to The NetBSD Foundation by Christos Zoulas.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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

Modelica definition

class License "License" extends Modelica.Icons.Information; end License;