SuPy: An urban land surface model for Pythonista

By: Ting Sun

Python is now extensively employed by the atmospheric sciences community for data analyses and numerical modelling thanks to its simplicity and the large scientific Python ecosystem (e.g., PyData community). Although I cherish Mathematica as my native programming language (like Mandarin as my mother tongue), I can see I have coded much more in Python than in Mathematica over the past year for my urban climate research.

One of the core tasks in urban climate research is to build climate resilience, where climate information at various spatiotemporal scales is an essential prerequisite. To obtain such climate information, accurate and agile modelling capacity of the urban climate is essential. Urban land surface models (ULSM) are widely used to simulate urban-atmospheric interactions by quantifying the energy, water and mass fluxes between the surface and urban atmosphere.

One widely used and tested ULSM, the Surface Urban Energy and Water balance Scheme (SUEWS) developed by Micromet@UoR, requires basic meteorological data and surface information to characterise essential urban features (i.e., urban surface heterogeneity and anthropogenic dynamics). SUEWS enables long-term urban climate simulations without specialised computing facilities (Järvi et al., 2011; 2014a; Ward et al., 2016). SUEWS is regularly enhanced and tested in cities under a range of climates worldwide.

Figure 1: SUEWS-Centred workflow for urban climate simulations

The typical workflow of conducting a SUEWS simulation may consist of a few steps (Figure 1), where several pre- and post-processing procedures can in fact be easily done by Python. However, one inevitable step that often bothers me is that the change of a single parameter may lead to another loop of the above workflow, which is somewhat annoying and tedious as you need to switch back and forth between numerous applications again and again.

Given the glue-like ability of Python, I started the project SuPy (SUEWS in Python) to use Python as a central tool to build a SUEWS-back-ended urban land surface model since the development of SUEWS v2017b. After several months of development and testing, I’m very pleased to release SuPy (Sun 2019; Sun and Grimmond 2019) via PyPI that allows the easy installation with the following one-liner for all desktop/server platforms (i.e., Linux, macOS and Windows) with Python 3.6+:

python3 -m pip install -U supy

Figure 2: SuPy-aided workflow for urban climate simulations

Figure 3: SuPy simulation results of surface energy balance.

And the whole workflow in Figure 1 can now be done in a much simpler way (Figure 2) with the following code in Python for one stop to quickly perform a simulation and produce a plot of its results (Figure 3):

import supy as sp
#load sample data
df_state_init, df_forcing = sp.load_SampleData()
grid = df_state_init.index[0]
#run supy/SUEWS simulation
df_output, df_state_end = sp.run_supy(df_forcing, df_state_init)
#plot results
res_plot = df_output.loc[grid,’SUEWS’].loc[‘2012 6 4′:’2012 6 6’, [‘QN’, ‘QF’, ‘QS’, ‘QE’, ‘QH’]].plot()

Along with the software, we also have a dedicated documentation site to provide more information of SuPy (e.g, installation, usage, API, etc). In particular, to familiarise users with SuPy urban climate modelling and to demonstrate the functionality of SuPy, we provide three tutorials in Jupyter notebooks. They can run in browsers (desktop, mobile) either by easy local configuration or on remote servers with pre-set environments (e.g., Google Colaboratory, Microsoft Azure Notebooks). Those impatient tasters of SuPy can even try out the package in an online Jupyter environment without any configuration by clicking here.

The SuPy package represents a significant enhancement that supports existing and new model applications, reproducibility, and functionality. We expect SuPy will help guide future development of SUEWS (and similar urban climate models) and enable new applications of the model. Moreover, the improvement in SUEWS model structure and deployment process introduced by the development of SuPy paved the way to a more robust workflow of SUEWS for its sustainable success. To foster the sustainable development of SuPy as an open source tool, we welcome all kinds of contributions – for example, incorporation of new feature (pull requests), submission of issues, and development of new tutorials.


Järvi, L., C. S. B. Grimmond, and A. Christen, 2011: The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver, J. Hydrol., 411(3-4), 219–237, doi:10.1016/j.jhydrol.2011.10.001

Järvi, L., C. S. B. Grimmond, M. Taka, A. Nordbo, H. Setälä and I. B. Strachan, 2014: Development of the Surface Urban Energy and Water Balance Scheme (SUEWS) for cold climate cities, Geosci Model Dev, 7(4), 1691–1711, doi:10.5194/gmd-7-1691-2014

Sun, T.: sunt05/SuPy: 2019.2 Release, doi:10.5281/zenodo.2574405, 2019.

Sun, T. and Grimmond, S.: A Python-enhanced urban land surface model SuPy (SUEWS in Python, v2019.2): development, deployment and demonstration, Geosci. Model Dev. Discuss.,, in review, 2019.

Ward, H. C., S. Kotthaus, L. Järvi, and C. S. B. Grimmond, 2016: Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites, Urban Climate, 18, 1–32, doi:10.1016/j.uclim.2016.05.001


This entry was posted in Boundary layer, Climate, Climate modelling, Urban meteorology. Bookmark the permalink.