# User Guide

This user guide provides instructions for how to use the free open-source Modelica Buildings Library. The user guide covers how to

- get started,

- follow best practices when createing models and running simulations,

- fix common problems in translating or simulating models,

- automate pre- and post-processing of model inputs and outputs,

- develop and contribute new models to the library, and

- get help.

The following information can be found in the Modelica library documentation rather than in this documentation:

- User guides for individual packages of models, see https://simulationresearch.lbl.gov/modelica/releases/latest/help/Buildings_UsersGuide.html for the available user guides.

- The physical assumptions and the equations that the models are based on. See the respective model documentation.

- Advice as to which models may be used if multiple models may be available for similar equipment or physical phenomena. This is typically explained in the documentation of the model, the documentation of the package that contains the model, or the user guide of the respective package.

## Contents

- 1. Getting Started
  - 1.1. Literature for Users
  - 1.2. Training Videos
  - 1.3. Running the First Simulations
  - 1.4. Software Requirements
  - 1.5. Literature for Developers
  - 1.6. References
- 2. Best Practice
  - 2.1. Organization of packages
  - 2.2. Building large system models
  - 2.3. Propagating parameters and media packages
  - 2.4. Thermo-fluid systems
    - 2.4.1. Overdetermined initialization problem and inconsistent equations
    - 2.4.2. Modeling of fluid junctions
    - 2.4.3. Use of sensors in fluid flow systems
    - 2.4.4. Reference pressure for incompressible fluids such as water
    - 2.4.5. Nominal Values
  - 2.5. Controls
  - 2.6. Start values of iteration variables
- 3. Simulation Performance
  - 3.1. Unstable control loops
  - 3.2. Control input signal of equipment
  - 3.3. Fluid flow systems
    - 3.3.1. Breaking algebraic loops
    - 3.3.2. Reducing nonlinear equations of serially connected flow resistances
    - 3.3.3. Prescribed mass flow rate
    - 3.3.4. Avoiding events
  - 3.4. Examples for how to debug and correct slow simulations
    - 3.4.1. State events
    - 3.4.2. State variables that dominate the error control
  - 3.5. Numerical solvers
- 4. Pre- and Post-Processing
- 5. Development
  - 5.1. Contributing
  - 5.2. Guidelines for contributions
  - 5.3. Style guide
    - 5.3.1. General
    - 5.3.2. Type declarations
    - 5.3.3. Equations and algorithms
    - 5.3.4. Functions
    - 5.3.5. Package order
    - 5.3.6. Documentation
  - 5.4. Adding a new class
    - 5.4.1. Thermofluid flow device
    - 5.4.2. Pressure drop
    - 5.4.3. Control sequences using the Control Description Language
  - 5.5. HVAC and control templates
  - 5.6. Validation and unit tests
- 6. Help
- 7. Glossary
- 8. Acknowledgments
- 9. Disclaimers
- 10. Copyright and License

## Indices and tables

- Index

- Module Index

- Search Page