FastSmoothBuildings

FastSmoothBuildings is a Modelica library of buildings and their heating, cooling and ventilation systems written as smooth, event-free, explicit ordinary differential equations:

• in closed loop, with its own smooth controllers, it follows the Modelica Buildings library: layered walls, windows with the angular optics and gas gaps of Buildings, long-wave and solar exchanges in the rooms, radiators, valves, pumps, boilers, heat pumps with their buffer, ventilation with heat recovery, photovoltaics;
• with the controls of its systems as inputs, rumoca translates it into a CasADi model, ready for model predictive control, state estimation and calibration with IPOPT.

It has no dependency, not even the Modelica Standard Library, and runs in OpenModelica, Dymola and rumoca alike.

Documentation: https://andoludo.github.io/FastSmoothBuildings/: the guide, a page per class, the validation against Buildings and the analysis behind the library.

The library was developed as the FastModel package of trano, which generates its models from a YAML description of a building; its history is in this repository. In trano's validation, the models it generates pass the 27 cases of ASHRAE Standard 140 (BESTEST), with heating and cooling loads within 1.1 % of Buildings on average, and follow Buildings within 0.02 to 0.10 K on the zone temperatures of a six-zone house (trano's validation).

Install

The Modelica library is the folder FastSmoothBuildings:

• OpenModelica: add the folder that holds it to MODELICAPATH and loadModel(FastSmoothBuildings), or loadFile("<path>/FastSmoothBuildings/package.mo");
• Dymola, OMEdit: open FastSmoothBuildings/package.mo.

The Python package fastsmoothbuildings carries the library and tells tools where it is:

pip install fastsmoothbuildings

import rumoca

import fastsmoothbuildings

session = rumoca.Session(roots=[str(fastsmoothbuildings.LIBRARY)])  # rumoca reads the library from its folder
model = session.loads(source, model="MyBuilding.building").to_casadi()

text = fastsmoothbuildings.bundle()  # or the whole library as one file, to embed it in a generated model

fastsmoothbuildings.LIBRARY is the folder of the library (rumoca reads every Modelica file below a root, so give it the library itself), fastsmoothbuildings.ROOT the folder that holds it, to put on MODELICAPATH, and fastsmoothbuildings.__version__ the version of the library (its version annotation).

The library

A model built from these classes stays an explicit ODE: no when, pre, sample or event-generating if; switches are regStep transitions whose width is a parameter. rumoca sizes arrays and evaluates subscripts from literal parameters only, so the records of the constructions carry their layer and node counts written out (see the User's Guide).

Examples

The Validation packages of Utilities, Envelope and Controls exercise the smooth functions, the schedules, the gas gaps, the overhangs and side fins, the hysteresis and the PI controller. Every example translates with rumoca, and its CasADi model integrated by CVODES follows the OpenModelica results within 0.01 K on the rooms.

Development

uv sync                          # Python environment with rumoca (built from its git commit) and CasADi
uv run pytest                    # structure, bundle and rumoca tests
uv run pytest -m openmodelica    # simulations of the examples in OpenModelica (Docker)
uv run ruff check . && uv run ruff format --check . && uv run mypy

The OpenModelica tests run the examples in the official image openmodelica/openmodelica:v1.26.9-ompython and compare them with FastSmoothBuildings/Resources/ReferenceResults/OpenModelica; uv run pytest -m openmodelica --update-references rewrites the references after a deliberate change. The rumoca tests integrate the CasADi models and compare them with the same references, without Docker.

The study against Buildings (study/) runs the models trano generates with both libraries in OpenModelica (uv sync --group study, Docker); its results are committed and rendered on the documentation site, which uv sync --group docs && uv run mkdocs serve builds locally. See Development.

Releasing

As in trano, every change merged into main is released once CI passes on it: the release workflow tags the version of FastSmoothBuildings/package.mo when it has no tag yet (the first release, or a version raised by hand in a pull request), and otherwise raises the minor version and commits it (python scripts/bump_version.py minor). The tag publishes the wheel and the sdist on PyPI and creates the GitHub release with the library as a zip for OpenModelica and Dymola; its notes are the section of the version in CHANGELOG.md, or the commits since the previous release. The workflow uses the repository secrets ACCESS_TOKEN (a personal access token that may push to the repository) and PYPI_API_TOKEN (a PyPI API token), as trano does.

License

BSD 3-Clause; the portions that follow the Modelica Buildings Library carry its license too (see LICENSE).