The Town Energy Balance (TEB) model

Overview | Prerequisites | Installation | Documentation | Example application | Testing | How to cite | Contributing | Copyright and license

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 ..).

Make sure you have installed the Intel® Visual Studio Integration plugins or CMake will not be able to identify your compiler (No CMAKE_Fortran_COMPILER could be found error).
Make sure that you use Intel® Command-Line Window when launching CMake - The Intel® compiler provides a command-line window with the appropriate environment variables already set (see: Using the Intel® Command-Line Window).
You may also need to specify the generator flag -G in CMake; for example, if you are using Intel® Command-Line Window for Visual Studio 2017, then the CMake command should now be cmake -G "Visual Studio 15 2017 Win64" ... For more information on how to specify generators in CMake see cmake-generators

E.g. on Windows using Intel® Command-Line Window for Visual Studio 2017:

mkdir build && cd build
cmake -G "Visual Studio 15 2017 Win64" ..
cmake --build .

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:

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.

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:

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.