# Enhanced software and platform for the Town Energy Balance (TEB) model

D. Meyer, Robert Schoetter, Valéry Masson, S. Grimmond

► To cite this version:

D. Meyer, Robert Schoetter, Valéry Masson, S. Grimmond. Enhanced software and platform for the Town Energy Balance (TEB) model. Journal of Open Source Software, 2020, 5 (50), pp.2008. 10.21105/joss.02008. meteo-03981081

HAL Id: meteo-03981081

https://meteofrance.hal.science/meteo-03981081

Submitted on 10 Feb 2023

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
# Enhanced software and platform for the Town Energy Balance (TEB) model

D. Meyer¹, ², R. Schoetter³, V. Masson³, and S. Grimmond¹

1 Department of Meteorology, University of Reading, Reading, UK 2 Department of Civil and Environmental Engineering, Imperial College London, London, UK 3 CNRM UMR 3589, Université Fédérale de Toulouse, Météo-France/CNRS, Toulouse, France

DOI: 10.21105/joss.02008

## Software

- Review ⚙️

- Repository ⚙️

- Archive ⚙️

Editor: Matthew Sottile ⚙️

## Reviewers:

- @ethan-nelson

- @jayten

Submitted: 04 December 2019

Published: 09 June 2020

## License

Authors of papers retain copyright and release the work under a Creative Commons Attribution 4.0 International License (CC BY 4.0).

## Summary

The Town Energy Balance (TEB) model (Masson, 2000) is a physically based single layer Urban Canopy Model (UCM) to calculate the urban surface energy balance at neighborhood scale assuming a simplified canyon geometry. It includes several capabilities (Table 1) that have been extensively evaluated offline with flux observations (Lemonsu, Grimmond, & Masson, 2004; Leroyer, Mailhot, Bélair, Lemonsu, & Strachan, 2010; Masson, Grimmond, & Oke, 2002; Pigeon, Moscicki, Voogt, & Masson, 2008) and online coupled to atmospheric models such as ALARO (Gerard, Piriou, Brožková, Geleyn, & Banciu, 2009) in ALARO-TEB (Hamdi, Degrauwe, & Termonia, 2012), the Global Environmental Multiscale (GEM; Côté et al. (1998)) in GEM-TEB (Lemonsu, Belair, & Mailhot, 2009), Meso-NH (Lac et al., 2018; Lafore et al., 1998) in TEB-MesoNH (Lemonsu & Masson, 2002), the Regional Atmospheric Modeling System (RAMS; Pielke et al. (1992)) in RAMS-TEB (Freitas, Rozoff, Cotton, & Dias, 2007), the Advanced Regional Prediction System (ARPS; Xue et al., (2000)) in ARPS-TEB (Rozoff, Cotton, & Adegoke, 2003), and the Weather Research and Forecasting (WRF; Skamarock et al. (2019)) in WRF-TEB (Meyer et al., 2020).

Here, we present an enhanced software and platform for the TEB model to help scientists and practitioners wishing to use the TEB model in their research as a standalone software application or as a library in their own software. This includes several features such as cross-platform support for Windows, Linux, and macOS using CMake (Kitware Inc., 2020), static and dynamic library generation for integration with other software/models, namelist-based configuration, integration with MinimalDX (Meyer & Raustad, 2019) and PsychroLib (Meyer & Thevenard, 2019) to improve the modelling of air conditioners (AC) and psychrometric calculations respectively, a thin interface used in the coupling with WRF-CMake (Riechert & Meyer, 2019), helper functions for Python for pre- and post-processing inputs and outputs files, and a tutorial in Jupyter Notebook to allow users to quickly become familiar with the general TEB modeling workflow. In the new platform we implement testing at every code commit through continuous integration (CI) and automate the generation of documentation. The project is developed as a free, open source, community-driven project on GitHub (https://github.com/teb-model/teb) to support existing and new model applications with enhanced functionality. We welcome contributions and encourage users to provide feedback, bug reports and feature requests, via GitHub's issue system at https://github.com/teb-model/teb/issues.
<table><caption>**Table 1:** Main capabilities available in the Town Energy Balance (TEB) model (Masson, 2000). The number of features available in TEB has increased since its first version published in 2000. (*) Capability not currently available in the TEB software.</caption><thead><tr><td>Modeling capability</td><td>Reference</td></tr></thead><tbody><tr><td>Urban Surface Energy Balance and Snow</td><td>Masson (2000)</td></tr><tr><td>Building Energy Model (BEM)</td><td>Bueno et al. (2012), Pigeon et al. (2014)</td></tr><tr><td>In-canyon urban vegetation and variable road orientation</td><td>Lemonsu et al. (2012)</td></tr><tr><td>Green roofs, irrigation of green roofs, gardens and watering of roads</td><td>de Munck et al. (2013)</td></tr><tr><td>Solar panels for hot water and/or photo-voltaic (PV)</td><td>Masson et al. (2014)</td></tr><tr><td>Human behavior related to building energy consumption*</td><td>Schoetter et al. (2017)</td></tr><tr><td>Calculation of urban carbon dioxide fluxes*</td><td>Goret et al. (2019)</td></tr><tr><td>Urban trees*</td><td>Redon et al. (2017; 2020)</td></tr></tbody></table>

## Acknowledgments

We acknowledge the researchers who contributed to the scientific development of the TEB code: from CNRM: Aude Lemonsu, Grégoire Pigeon, Cécile de Munck, Bruno Bueno, Marine Goret, Emilie Redon; from IFSTTAR Katia Chancibaul, Xenia Stavropulos-Laffaille; and from Environnement and Changement Climatique Canada (ECCC): Sylvie Leroyer.

## References

* Bueno, B., Pigeon, G., Norford, L. K., Zibouche, K., & Marchadier, C. (2012). Development and evaluation of a building energy model integrated in the TEB scheme. *Geoscientific Model Development*, 5(2), 433–448. doi:10.5194/gmd-5-433-2012

* Côté, J., Gravel, S., Méthot, A., Patoine, A., Roch, M., & Staniforth, A. (1998). The Operational CMCMRB Global Environmental Multiscale (GEM) Model. Part I: Design Considerations and Formulation. *Monthly Weather Review*. doi:10.1175/1520-0493(1998)126<1373:TOCMGE>2.0.CO;2

* de Munck, C., Pigeon, G., Masson, V., Meunier, F., Bousquet, P., Tréméac, B., Merchat, M., et al. (2013). How much can air conditioning increase air temperatures for a city like Paris, France? *International Journal of Climatology*, 33(1), 210–227. doi:10.1002/joc.3415

* Freitas, E. D., Rozoff, C. M., Cotton, W. R., & Dias, P. L. S. (2007). Interactions of an urban heat island and sea-breeze circulations during winter over the metropolitan area of São Paulo, Brazil. *Boundary-Layer Meteorology*, 122(1), 43–65. doi:10.1007/s10546-006-9091-3

* Gerard, L., Piriou, J.-M., Brožková, R., Geleyn, J.-F., & Banciu, D. (2009). Cloud and Precipitation Parameterization in a Meso-Gamma-Scale Operational Weather Prediction Model. *Monthly Weather Review*, 137(11), 3960–3977. doi:10.1175/2009MWR2750.1

* Goret, M., Masson, V., Schoetter, R., & Moine, M.-P. (2019). Inclusion of CO2 flux modelling in an urban canopy layer model and an evaluation over an old European city centre. *Atmospheric Environment*: X, 3, 100042. doi:10.1016/j.aeaoa.2019.100042
Hamdi, R., Degrauwe, D., & Termonia, P. (2012). Coupling the Town Energy Balance (TEB) Scheme to an Operational Limited-Area NWP Model: Evaluation for a Highly Urbanized Area in Belgium. *Weather and Forecasting*, 27(2), 323–344. doi:10.1175/WAF-D-11-00064.1

Kitware Inc. (2020). CMake. Retrieved from https://cmake.org/

Lac, C., Chaboureau, J.-P., Masson, V., Pinty, J.-P., Tulet, P., Escobar, J., Leriche, M., et al. (2018). Overview of the Meso-NH model version 5.4 and its applications. *Geoscientific Model Development*, 11(5), 1929–1969. doi:10.5194/gmd-11-1929-2018

Lafore, J. P., Stein, J., Asencio, N., Bougeault, P., Ducrocq, V., Duron, J., Fischer, C., et al. (1998). The Meso-NH Atmospheric Simulation System. Part I: Adiabatic formulation and control simulations. *Annales Geophysicae*, 20. doi:10.1007/s00585-997-0090-6

Lemonsu, A., Belair, S., & Mailhot, J. (2009). The New Canadian Urban Modelling System: Evaluation for Two Cases from the Joint Urban 2003 Oklahoma City Experiment. *Boundary-Layer Meteorology*, 133(1), 47–70. doi:10.1007/s10546-009-9414-2

Lemonsu, A., Grimmond, C. S. B., & Masson, V. (2004). Modeling the Surface Energy Balance of the Core of an Old Mediterranean City: Marseille. *Journal of Applied Meteorology*, 43, 16. doi:10.1175/1520-0450(2004)043<0312:MTSEBO>2.0.CO;2

Lemonsu, A., & Masson, V. (2002). Simulation of a Summer Urban Breeze Over Paris. *Boundary-Layer Meteorology*, 104(3), 463–490. doi:10.1023/A:1016509614936

Lemonsu, A., Masson, V., Shashua-Bar, L., Erell, E., & Pearlmutter, D. (2012). Inclusion of vegetation in the Town Energy Balance model for modelling urban green areas. *Geoscientific Model Development*, 5(6), 1377–1393. doi:10.5194/gmd-5-1377-2012

Leroyer, S., Mailhot, J., Bélair, S., Lemonsu, A., & Strachan, I. B. (2010). Modeling the Surface Energy Budget during the Thawing Period of the 2006 Montreal Urban Snow Experiment. *Journal of Applied Meteorology and Climatology*, 49(1), 68–84. doi:10.1175/2009JAMC2153.1

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

Masson, V., Bonhomme, M., Salagnac, J.-L., Briottet, X., & Lemonsu, A. (2014). Solar panels reduce both global warming and urban heat island. *Frontiers in Environmental Science*, 2. doi:10.3389/fenvs.2014.00014

Masson, V., Grimmond, C. S. B., & Oke, T. R. (2002). Evaluation of the town energy balance (teb) scheme with direct measurements from dry districts in two cities. *Journal of Applied Meteorology*, 41(10), 1011–1026. doi:10.1175/1520-0450(2002)041<1011: EOTTEB>2.0.CO;2

Meyer, D., & Raustad, R. (2019). *MinimalDX*. Zenodo. doi:10.5281/zenodo.3562310

Meyer, D., Schoetter, R., Riechert, M., Verrelle, A., Tewari, M., Dudhia, J., Masson, V., et al. (2020). WRF-TEB: Implementation and evaluation of the coupled Weather Research and Forecasting (WRF) and Town Energy Balance (TEB) model. *Journal of Advances in Modeling Earth Systems*. doi:10.1029/2019MS001961

Meyer, D., & Thevenard, D. (2019). *PsychroLib: A library of psychrometric functions to calculate thermodynamic properties of air*. *Journal of Open Source Software*, 4(33), 1137. doi:10.21105/joss.01137

Pielke, R. A., Cotton, W. R., Walko, R. L., Tremback, C. J., Lyons, W. A., Grasso, L. D., Nicholls, M. E., et al. (1992). A comprehensive meteorological modeling system RAMS. *Meteorology and Atmospheric Physics*, 49(1-4), 69–91. doi:10.1007/BF01025401
Pigeon, G., Moscicki, M. A., Voogt, J. A., & Masson, V. (2008). Simulation of fall and winter surface energy balance over a dense urban area using the TEB scheme. *Meteorology and Atmospheric Physics*, 102(3-4), 159-171. doi:10.1007/s00703-008-0320-9

Pigeon, G., Zibouche, K., Bueno, B., Bras, J. L., & Masson, V. (2014). Improving the capabilities of the town energy balance model with up-to-date building energy simulation algorithms: An application to a set of representative buildings in Paris. *Energy and Buildings*, 76, 1-14. doi:10.1016/j.enbuild.2013.10.038

Redon, E. C., Lemonsu, A., Masson, V., Morille, B., & Musy, M. (2017). Implementation of street trees within the solar radiative exchange parameterization of TEB in SURFEX v8.0. *Geoscientific Model Development*, 10(1), 385-411. doi:10.5194/gmd-10-385-2017

Redon, E., Lemonsu, A., & Masson, V. (2020). An urban trees parameterization for modeling microclimatic variables and thermal comfort conditions at street level with the town energy balance model (TEB-SURFEX v8.0). *Geoscientific Model Development*, 13(2), 385-399. doi:10.5194/gmd-13-385-2020

Riechert, M., & Meyer, D. (2019). WRF-CMake: Integrating CMake support into the Advanced Research WRF (ARW) modelling system. *Journal of Open Source Software*, 4(41), 1468. doi:10.21105/joss.01468

Rozoff, C. M., Cotton, W. R., & Adegoke, J. O. (2003). Simulation of St. Louis, Missouri, land use impacts on thunderstorms. *Journal of Applied Meteorology*, 42(6), 716-738. doi:10.1175/1520-0450(2003)042<0716:SOSLML>2.0.CO;2

Schoetter, R., Masson, V., Bourgeois, A., Pellegrino, M., & Lévy, J.-P. (2017). Parametrization of the variety of human behaviour related to building energy consumption in the Town Energy Balance (SURFEX-TEB v. 8.2). *Geoscientific Model Development*, 10(7), 2801-2831. doi:10.5194/gmd-10-2801-2017

Skamarock, W. C., Klemp, J. B., Dudhia, J., Gill, D. O., Liu, Z., Berner, J., Wang, W., et al. (2019). A Description of the Advanced Research WRF Model Version 4. *NCAR Technical Note NCAR/TN-556+STR*, 145. doi:10.5065/1dfh-6p97

Xue, M., Droegemeier, K. K., & Wong, V. (2000). The Advanced Regional Prediction System (ARPS) – a multi-scale nonhydrostatic atmospheric simulation and prediction model. Part I: Model dynamics and verification. *Meteorology and Atmospheric Physics*, 75(3), 161-193. doi:10.1007/s007030070003