Overview

This enhanced software and platform for TEB (Town Energy Balance; Masson, 2000 and subsequent papers), is intended to help scientists and practitioners wishing to use the TEB model in their research as a standalone software application or as a library (e.g. WRF-TEB) to calculate the urban surface energy balance at neighborhood scale assuming a simplified canyon geometry.

Prerequisites

• Git >= 2
• CMake >= 3.1
• A Recent version of GNU/Intel/Cray Fortran compiler
• Python >= 3.7 [Optional for testing and tutorial]

Installation

To build the Town Energy Balance (TEB) executable and library on Windows, Linux and macOS, clone this repository and run the following commands from your command prompt:

mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Release .. cmake --build .

By default, we set the real type to an 8 byte wide. This behavior is controlled by the optional USE_REAL8 flag (default ON). Ninja support is avalable and can be specified with the generator flag -G at configure time (e.g. cmake -GNinja -DCMAKE_BUILD_TYPE=Release ..).

Documentation

This section includes links to software and model documentation. If you are new to TEB and simply looking to easily get started, please refer to the example application instead.

Software

See software documentation for a general overview. For configuration options available at runtime please refer to namelist options.

Scientific

The complete scientific documentation is included in the SURFEX scientific documentation.

Code browser

The code browser is available at https://teb-model.github.io/teb.

Example application

To get started with TEB, see examples/CAPITOUL/README.md. The folder contains a simple tutorial in Jupyter Notebook to estimate the buildings' power demand for cooling using TEB and data and parameters from the CAPITOUL (Canopy and Aerosol Particles Interactions in TOulouse Urban Layer; Masson et al., 2008) campaign.

Testing

Tests are run using the CAPITOUL data provided in examples/CAPITOUL. Tests are found in tests/tests.py and an overview is given in tests/README.md. All tests are automatically run at every commit using Continuos Integration. If you are looking to run your tests locally on Linux or macOS, first make sure you have installed all the prerequisites, then from the command prompt:

bash python -m pip install -r requirements.txt python tests/test.py --build_type=<BUILD_TYPE> --case=<TEST_CASE>

where <BUILD_TYPE> is either Debug or Release and <TEST_CASE> is the test case currently supported in tests/test.py -- see tests/README.md for more information. The output files are written to temp. Plots are written to plots.

E.g.

bash python -m pip install -r requirements.txt python tests/test.py --build_type=Debug --case=integration

How to cite

When using the TEB software, please cite both model, and software (with version) as follows:

| Physical model | This software | Version* | | ------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------- | | Masson, 2000 | Meyer et al., 2020 | see Zenodo |

The corresponding reference list should be as follows:

Masson, V., 2000: A Physically-Based Scheme For The Urban Energy Budget In Atmospheric Models. Boundary-Layer Meteorology, 94, 357–397, https://doi.org/10.1023/A:1002463829265.

Meyer, D., Schoetter, R., Masson, V., Grimmond, S., 2020: Enhanced software and platform for the Town Energy Balance (TEB) model. Journal of Open Source Software, 5(50), 2008. https://doi.org/10.21105/joss.02008.

*please make sure to cite the same version you are using with the correct DOI. For a list of all available versions see the list of versions on Zenodo.

Contributing

Please see the CONTRIBUTING.md file.

Copyright and license

Copyright stated at the top of source files. Software released under CeCILL version 2.1.