Articles | Volume 12, issue 7
Development and technical paper
09 Jul 2019
Development and technical paper |  | 09 Jul 2019

A Python-enhanced urban land surface model SuPy (SUEWS in Python, v2019.2): development, deployment and demonstration

Ting Sun and Sue Grimmond

Accurate and agile modelling of cities weather, climate, hydrology and air quality is essential for integrated urban services. The Surface Urban Energy and Water balance Scheme (SUEWS) is a state-of-the-art widely used urban land surface model (ULSM) which simulates urban–atmospheric interactions by quantifying the energy, water and mass fluxes. Using SUEWS as the computation kernel, SuPy (SUEWS in Python) uses a Python-based data stack to streamline the pre-processing, computation and post-processing that are involved in the common modelling-centred urban climate studies. This paper documents the development of SuPy, including the SUEWS interface modification, F2PY (Fortran to Python) configuration and Python front-end implementation. In addition, the deployment of SuPy via PyPI (Python Package Index) is introduced along with the automated workflow for cross-platform compilation. This makes SuPy available for all mainstream operating systems (Windows, Linux and macOS). Three online tutorials in Jupyter Notebook are provided to users of different levels to become familiar with SuPy urban climate modelling. The SuPy package represents a significant enhancement that supports existing and new model applications, reproducibility and enhanced functionality.

1 Introduction

Cities need to be resilient to weather, climate, hydrological and air quality hazards given their large and ever-increasing populations (Baklanov et al., 2018). One prerequisite to building resilience is information at various spatio-temporal scales, e.g. to understand energy partitioning over urban surfaces (D. Li et al., 2015; Sun et al., 2017; Wang et al., 2015; Ward and Grimmond, 2017; Zhao et al., 2014), pedestrian level meteorology to diagnose thermal comfort (Bar et al., 2011; Erell et al., 2013; Krayenhoff et al., 2018; Sun et al., 2016; Tan et al., 2009), or ambient radiation and wind conditions to assist building design (Chen, 2004; Jentsch et al., 2013; B. Li et al., 2015; Lindberg and Grimmond, 2011; Reinhart and Cerezo Davila, 2016; Santamouris et al., 2001). To obtain such information, accurate and agile modelling capacity of the urban weather and climate are essential.

Urban land surface models (ULSMs) are widely used to simulate urban–atmosphere interactions by quantifying the energy, water and mass fluxes between the surface and urban atmosphere (Best and Grimmond, 2015; Chen et al., 2011; Wang et al., 2012). These models require information on urban morphology (e.g. heights, spacings of buildings, etc.) and anthropogenic dynamics (e.g. building-operation-related heat release, emissions of heat by traffic) to be included.

One widely used and tested ULSM, the Surface Urban Energy and Water balance Scheme (SUEWS; Table 1), requires basic meteorological data and surface information to characterize essential urban features (i.e. urban surface heterogeneity and anthropogenic dynamics). SUEWS enables long-term urban climate simulations without specialized computing facilities (Järvi et al., 2011, 2014; Ward et al., 2016). SUEWS is regularly enhanced (Grimmond et al., 1991, 1986; Grimmond and Oke, 1991; Järvi et al., 2011, 2014, 2019; Offerle et al., 2003; Ward et al., 2016) and tested in cities under a range of climates worldwide (Table 1). Although operationally simple and scientifically robust, SUEWS still requires some skill for application (e.g. computing environment setup, parameter configuration), which may limit uptake for broader applications in urban planning and design.

Table 1Recent studies using SUEWS. D&E – development and evaluation. n/a – not applicable

Download Print Version | Download XLSX

Reproducibility and open science principles are increasingly important (Peng, 2011). Although climate scientists by convention publish detailed model configurations used in their research, minor inconsistencies or lack of transparency of code often hampers efforts to reproduce simulation results. In addition, new users may lack prerequisite knowledge in low-level compilation and scripting to undertake initial model runs and interpretation of simulation results (Lin, 2012).

Today Python is used extensively by the atmospheric sciences community for data analyses and numerical modelling (Lin, 2012; Perkel, 2015) thanks to its simplicity and the large scientific Python ecosystem (e.g. PyData community:, last access: 12 June 2019). Recent Python-based endeavours include global climate system models (Monteiro et al., 2018), stochastic geological models (de la Varga et al., 2019) and hydrological models (Hamman et al., 2018) to cite just a few.

In this paper, we present a Python-enhanced urban climate system based on the popular Fortran-coded SUEWS – SuPy (SUEWS in Python). The development of SuPy (Sect. 2), the essential workflow in its cross-platform deployment (Sect. 3), and three demonstration tutorials for users of different levels (Sect. 4) are presented.

2 Development

The following are considered within the design process of SuPy:

  1. Data preparation. Climate simulations typically require extensive pre-processing of data (loading input data, reformatting to conform with standards, etc.) and post-processing (conversion of output, graphical and cartographic plotting, etc.). Python has a vast array of utilities to support this; notably, NumPy (the fundamental package for scientific computing with Python,, last access: 12 June 2019) and pandas (a tabular-format-centred data analysis tool) are two cornerstone libraries in Python-based scientific computing.

  2. Performance. Python, as a scripting language, has poorer performance than compiled languages (e.g. C, Fortran; Kouatchou, 2018). For this reason, Fortran is used extensively for weather and climate-related software (e.g. WRF – Skamarock and Klemp, 2008; GFDL AM3 – Donner et al., 2011; etc.). Therefore, by using different languages their individual strengths can be utilized.

  3. Cross-platform ability. Given the range of computer environments, it is important that software can be easily used across operating systems with ease. Python and Fortran are both easily used on most operating systems. However, for performance reasons as noted, it is preferable to have a compiled back end for intensive simulations, where platform-specific compilations are mandatory. Thus, we adopt the Microsoft Azure Pipelines to allow for a cross-platform ability for SuPy (Sect. 3.1).

  4. Extendibility. It is desirable, possibly even essential, for the scientific model to interact with other models and data sources to extend the overall capacity and to explore questions related to urban climate beyond the climate science.

To address these four considerations, SuPy's architecture uses Python's data processing and Fortran's computational efficiency. SuPy consists of three parts (Fig. 1):

  1. SuPy. A Python-based front-end processor based on the pandas DataFrame with functionality for data analysis and simulation management (Appendix A).

  2. SuPy_driver. Calculation kernel compiled by F2PY (Fortran to Python, part of the NumPy package) (Peterson, 2009) to facilitate the transfer of SUEWS' Fortran modelling ability to Python and guarantee the computational performance.

  3. SUEWS. A Fortran-coded local-scale urban land surface model of moderate complexity that can simulate the urban surface energy balance in combination with the complete urban hydrological cycle, considering irrigation and runoff processes (Grimmond and Oke, 1986, 1991; Järvi et al., 2011, 2014; Offerle et al., 2003; Ward et al., 2016).

Figure 1SuPy's three major components (left to right): (a) SuPy, a Python-based front-end processor; (b) SuPy_driver, the calculation kernel compiled by F2PY; (c) SUEWS, a Fortran-coded local-scale urban land surface model. Note that not all physics schemes are listed.


Development of SuPy (Sun, 2019) started with SUEWS v2017b (Ward and Grimmond, 2017). SUEWS has three distinct groups of subroutines: model physics, input and output (I/O). To help generalize coupling, the use of Fortran modules to pass variables and parameters has been reduced and there has been a return to further use of Fortran subroutine arguments with explicitly stated intent (e.g. in, out). The modified physics subroutines are called from two subroutines, suews_cal_main and suews_cal_multistep (Fig. 1a), depending on the model time step (single or multi). This structure constitutes the SUEWS v2018c calculation kernel (Fig. 1a) and enables efficient communication between SUEWS and other models (e.g. WRF) through an explicit and unified interface.

The SUEWS kernel (v2018c) is compiled by F2PY to generate the Python-compliant SuPy_driver package. Using the two subroutines allows better computational performance. The SuPy_driver calls the two subroutines depending on time-step simulation type: single- (sd_cal_tstep) or multi-time-step mode (sd_cal_multitstep, Fig. 1b). The former is useful in flexible manipulation of SuPy runtime behaviours (application in Sect. 4.3), while the latter has much better performance because of the much lower computational overheads with the F2PY wrapper. Therefore, sd_cal_multitstep is the default executer in run_supy, the SuPy core processor performing simulations, for regular runs without runtime manipulation.

In addition to run_supy, SuPy uses pandas DataFrame as the central data structure to simplify the pre- and post-processing as required by the original SUEWS. The overall data structures used in SuPy are described in the documentation (, last access: 12 June 2019). The pre-processor is designed to load existing SUEWS input files, which consists of the following (Appendix A):

  1. init_supy. This loads surface characteristics (e.g. albedo, emissivity, land cover fractions; full details given in the SUEWS documentation:, last access: 12 June 2019) and model configurations (e.g. stability correction option chosen;, last access: 12 June 2019). The data go into df_state_init (a pandas DataFrame;, last access: 12 June 2019). Two auxiliary json files are used with the look-up hierarchies for loading this information from SUEWS library files (, last access: 12 June 2019) in a consistent file-code-variable way.

  2. load_forcing. Meteorological and other external forcing information are loaded into df_forcing (a pandas DataFrame;, last access: 12 June 2019) to drive the SuPy simulations with time-step size inferred from its DatetimeIndex (i.e. the freq attribute). SUEWS should be run at short time steps (e.g. 5 min) as precipitation or irrigation runoff from impervious surfaces becomes too large if the water arrives as one large hourly (or longer) amount (Grimmond and Oke, 1991; Ward et al., 2018). As such, load_forcing is implemented with the ability to downscale the raw forcing data to finer time steps (5 min by default). The temporal resolution of raw forcing data can be between 5 and 360 min, with 30–60 min being the most common.

Detailed guidance is provided in SUEWS documentation for preparing input files (, last access: 12 June 2019) and in the Urban Multi-scale Environmental Predictor (UMEP) documentation ( Prepare.html, last access: 12 June 2019). SUEWS uses multiple ASCII text and namelist files (, last access: 12 June 2019), and UMEP (Lindberg et al., 2018) provides a QGIS/Python interface that is designed to aid the derivation of the spatial parameters from geodata. As SuPy can use the files prepared by the other two approaches, existing SUEWS files are usable via the init_supy and load_forcing functions for SuPy.

For new users without experience of other versions, a helper function, load_SampleData, is provided to get the sample input DataFrames (i.e. df_state_init and df_forcing) ready to run simulations. Once users understand the SUEWS/SuPy variables, the sample DataFrames provide a template to work with to meet their next specific needs. Examples using the sample datasets are provided as tutorials (Sect. 4).

As the F2PY-compiled kernel, SuPy_driver, relies on NumPy ndarray for data input and output, two SuPy post-processors, pack_state and pack_output, are embedded in run_supy to pack the (1) ndarray output of model final states into df_state_final (a pandas DataFrame;, last access: 12 June 2019) and (2) simulation results to df_output (a pandas DataFrame;, last access: 12 June 2019). To facilitate reuse of model runs (e.g. for model spin-up), df_state_final has the same data structure as df_state_init (dashed line, SuPy panel, Fig. 1a).

3 Deployment

To achieve cross-platform compatibility, SuPy has two parts:

  1. SuPy_driver (calculation kernel): the F2PY generated binaries of SUEWS are platform-dependent because of compilation being necessary for assurance of performance.

  2. SuPy (front-end processor): this platform-independent Python code allows rapid iteration in functionality enhancement and bug fixing thanks to the powerful ecosystem of Python utilities.

As software compilation can be frustrating and/or prone to operator errors, this procedure is automated using two online services: Microsoft Azure Pipeline (, last access: 12 June 2019) for continuous integration (CI) and PyPI (Python Package Index;, last access: 12 June 2019) for distribution. Microsoft Azure Pipeline has good cross-platform support (, last access: 1 July 2019) and easy connection with code repositories (e.g. GitHub:, last access: 12 June 2019; Bitbucket:, last access: 12 June 2019) and supports automated compilation for different platforms. The Azure Pipeline build workflow permits a variety of functionalities to facilitate compilation and publishing to other online services (e.g. PyPI, GitHub pages, etc.). Currently, this is set up for three major platforms (Windows, macOS and Linux) with three Python 3 configurations (3.5, 3.6 and 3.7) to conduct automated compilation of SuPy back-end files: SUEWS binaries and SuPy_driver, the product of which is directly pushed to PyPI and released in real time.

To build the SuPy_driver two crucial steps to allow cross-platform deployment (full details refer to configuration file in SuPy_driver) are the following.

  1. Static linking: to eliminate the issue of missing dynamic libraries, the calculation kernels are pre-built using static linking and therefore run directly after downloading.

  2. manylinux tagging: given the many Linux distributions and their different runtime libraries that often require distribution-specific compilation, we use the manylinux docker image (for details refer to to compile SuPy_driver.

In addition to the cross-platform compilation, to guarantee delivery quality we perform automatic code tests of four preset configurations for every build:

  1. Connectivity between SuPy and SuPy_driver: checks if the front-end processor and back-end calculation core can communicate with correct input and output.

  2. Success in single-time-step mode: checks SuPy can produce correct simulation results in the single-time-step mode.

  3. Success in multi-time-step mode: checks SuPy can produce correct simulation results in the multi-time-step mode and does a quick benchmark of computation speed.

  4. Compare simulation results between single- and multi-time-steps modes: checks SuPy can produce identical simulation results as designed.

All build and test output is logged in detail (see all logs here:, last access: 12 June 2019) and the results are reported to developers in real time. This feature is used for all code and underpins a commitment for timely support to SuPy development.

The Python Package Index (PyPI:, last access: 12 June 2019) is the official third-party software repository for Python. As it is supported by the pip toolchain it provides Python users easy worldwide access to packages and frees Python developers from maintaining indexing and distribution servers. By using the PyPI channel, SuPy can be easily installed by users with a one-line input in a command line tool on any desktop/server system (Listing 1).

Listing 1Command line code for SuPy installation using pip. Note 64-bit Python 3.5+ is required for SuPy installation.


4 Demonstration: SuPy tutorials

To familiarize users with SuPy urban climate modelling and to demonstrate the functionality of SuPy, we provide three tutorials (Table 2, access at, last access: 12 June 2019) in Jupyter notebooks (, last access: 12 June 2019).

Table 2Three SuPy tutorials. Note that the website links redirect to online Jupyter notebooks for SuPy simulation without any configuration by users.

Download Print Version | Download XLSX

They can run in browsers (e.g. desktop, tablet) either by local configuration or on remote servers with preset environments (e.g. Google Colaboratory,, last access: 12 June 2019; Microsoft Azure Notebooks,, last access: 12 June 2019). As Jupyter notebooks allow source code to be incorporated with detailed notes, users can organize their analyses (Shen, 2014). Jupyter notebooks can be installed with pip on any desktop/server system and open .ipynb notebook files locally (Listing 2). We note that running SuPy in browsers is not implemented by SuPy per se but allowed by the Jupyter environment where Python 3 is supported. The reason for running SuPy (and many other python applications) on mobile devices (e.g. mobile phone, tablet) is simple: working seamlessly across different devices is a natural need.

Listing 2Command line code for installing Jupyter Notebook with pip and open an existing local .ipynb notebook file (i.e. path_to_your_notebook).


Figure 2Intra-annual (2012) variation in forcing variables in the sample dataset (from top to bottom): incoming solar radiation, air temperature, relative humidity, air pressure, wind speed and rainfall in central London All variables are hourly averages except for total hourly rainfall (source of data: Kotthaus and Grimmond, 2014; gap filled: Ward et al., 2016).


These are made available to SUEWS by calling the load_SampleData function. This produces pandas DataFrames with the initial model state (df_state_init) and the forcing variables (df_forcing). These are used in all three tutorials.

Table 3Default settings in the sample dataset provided with SuPy for (a) physics scheme and (b) basic site characteristics. For full SuPy variable setting details refer to the online documentation: (last access: 12 June 2019).

Download Print Version | Download XLSX

4.1 SuPy quick-start

In this tutorial, we demonstrate the key steps in using SuPy to undertake the core task to simulate energy and water balance in an urban context using SUEWS. Here the runs are for a central London area in 2012.

The urban surface energy balance (SEB) can be expressed as

(1) Q + Q F = Q H + Q E + Δ Q S ,

where the flux densities (W m−2) are Q net all-wave radiation, QF anthropogenic heat, QH turbulent sensible heat, QE latent heat and ΔQS the net storage heat flux. Through QE, the SEB characteristics can be linked to the water balance:

(2) P + I = E + R + Δ S ,

where each term is a depth of water per unit of time (e.g. mm d−1). P is precipitation, I irrigation, E evapotranspiration (=QE/Lv where Lv is the latent heat of vaporization), R runoff and ΔS the net change in water storage.

The fundamental steps to use SuPy after the software environment has been installed (see Listings 1, 2) are (1) load input, (2) run a simulation and (3) examine the results. With everything ready, three lines of python code are needed.

Listing 3Python code for a minimal SuPy simulation with comments (green).


SuPy is run by calling run_supy after df_state_init and df_forcing have been loaded. After the simulation the two DataFrames provide major SUEWS outputs (df_output) and the model state (df_state_final) at the end of the run. The latter can be used as initial conditions for other SuPy runs. The post-processing uses pandas functions to resample, plot and write out the model output. The default output DataFrame of 5 min resolution can be upscaled to the month for an overview of intra-annual dynamics of surface energy and water balances (Fig. 3).

Figure 3SuPy simulated monthly (a) surface energy and (b) water balance for London 2012. Assuming no irrigation.


This workflow using SuPy for urban climate modelling can be easily adapted to existing SUEWS tutorials under the UMEP framework (, last access: 12 June 2019) by replacing the conventional SUEWS binary executable with the python SuPy package. Given the central role of Python in the UMEP framework, it is expected the adoption of SuPy will further streamline the workflows for urban climate simulations in UMEP.

4.2 Impacts of the urban area on local climate

A major application of urban climate models is to study the impacts on urban climate from design scenarios that change surface characteristics or the climate (atmospheric forcing). In this tutorial both scenario types are explored: we provide one example of modification of albedo for surface characteristics, while another of air temperature alteration for climate conditions.

Technically, this requires several configuration files to be prepared for a suite of independent model runs. These could be run consecutively (i.e. no interactions between runs are needed) or in parallel, so-called “embarrassingly parallel computation” (Bailey et al., 1991), with multiple independent runs with sufficient CPUs. In this tutorial, we first demonstrate how SuPy can be easily set up to efficiently complete multiple simulations in parallel.

We use dask (, last access: 12 June 2019) to parallelize the SuPy simulations given its close coherence with NumPy and pandas, in particular its almost identical DataFrame interfaces as pandas. Specifically, we use the apply method of dask.DataFrame to improve the simulation performance by distributing the SuPy computations across different configurations. Compared with the serial mode, the dask-based parallel mode takes only ∼30 % of the execution time of the serial mode for simulations longer than 1000 d for 12 grids (Fig. 4). The parallel configuration for running SuPy, run_supy_mgrids, is then used in the following two cases for more efficient parallel simulations.

Figure 4Comparison of execution times (seconds) between serial and parallel modes when 12 grids are simulated for different periods (days): 30, 90, 120, 150, 180, 270, 365, 730 and 1095. Simulations performed with macOS 10.14.3 running on 2.9 GHz Intel Core i9 with 32 GB memory. The model configuration is the same as Quick-start SuPy (Table 2).


To explore the effect of changes to surface properties, the DataFrame df_state_init needs to be modified. The surface albedo of different materials impacts the outgoing shortwave (solar) radiation and thus the surface energy balance fluxes and other atmospheric variables. Modifying roof albedo has been suggested extensively as a method to cool urban areas (e.g. Santamouris et al., 2011; Li et al., 2014; Ramamurthy et al., 2015). In the example, we conduct simulations from January 2012 to July 2012 with the first 6 months as the spin-up period. The building roof albedo is incrementally increased from 0.1 to 0.8 (e.g. a change from a very dark to a very light surface). The near-surface temperature T2, an indicator of thermal state at pedestrian level, is analysed using the monthly maximum, mean and minimum (Fig. 5). It would be expected that the maximum and mean values of T2 are greatly reduced as they are directly influenced by the altered net solar radiation, while impacts on the minimum T2 might be expected to be minimal.

In this tutorial we demonstrate some starting cases rather than a complete research cycle. Notably, limitations are imposed in the configuration used (e.g. length of the model run, spin-up period, feedbacks permitted) and thus the relations shown should be interpreted with caution.

Figure 5Impacts of increasing building roof albedo α (from 0.1) on near-surface temperature T2 considering monthly maximum, mean and minimum temperatures at 2 m for July 2012 based on 5 min output.


To explore changes in atmospheric forcing, the DataFrame df_forcing is modified. In this example, we investigate the impact of increased local-scale (constant flux layer) air temperature Ta on the near-surface air temperature T2. Air temperature Ta is increased over 24 runs from 0 C (no change) to +2C. The upper limit (+2C) represents a highly possible average global warming scenario for the near future (IPCC, 2014). The SuPy simulations are conducted from January to July 2012 and July data are analysed. The T2 results indicate the increased Ta has different impacts on the T2 metrics (minimum, mean and maximum) but all increase linearly with Ta. The maximum T2 has the stronger response compared to the other metrics (Fig. 6).

This tutorial demonstrates the simplicity of using SuPy to conduct impact studies of both surface characteristics and background climates. These can be easily adapted by users to their specific application interests. Thus, as various effects are combined the net impacts becomes more realistic.

Figure 6Impacts of increasing background (constant flux layer) air temperature Ta on near-surface maximum, mean and minimum (same methods as Fig. 5) temperatures at 2 m T2. Albedo is 0.1 and land cover characteristics are as in Table 2b. Note that in this example only one variable is modified.


4.3 Interaction between SuPy and external models

SUEWS can be coupled to other models that provide or require forcing data using the SuPy single-time-step running mode (Sect. 2). We demonstrate this feature with a simple online anthropogenic heat flux model.

Anthropogenic heat flux (QF) is an additional term to the surface energy balance in urban areas associated with human activities (Gabey et al., 2018; Grimmond, 1992; Nie et al., 2014, 2016; Sailor, 2011). In most cities, the largest emission source is from buildings (Hamilton et al., 2009; Iamarino et al., 2011; Sailor, 2011) and is highly dependent on outdoor ambient air temperature. For demonstration purposes we have created a very simple model instead of using the SUEWS QF (Järvi et al., 2011) with feedback from outdoor air temperature (Fig. 7). The simple QF model considers only building heating and cooling:

(3) Q F = T 2 - T C × C B , T 2 > T C ; T H - T 2 × H B , T 2 < T H ; Q F 0 ,

where TC (TH) is the cooling (heating) threshold temperature of buildings, CB (HB) is the building cooling (heating) rate and QF0 is the baseline anthropogenic heat. The parameters used are TC (TH) set as 20C (10C), CB (HB) set as 1.5 W m−2 K−1 (3 W m−2 K−1) and QF0 is set as 0 W m−2, implying other building activities (e.g. lightning, water heating, computers) are zero and therefore do not change the temperature or change with temperature.

Figure 7A simple anthropogenic heat flux (QF) model as a linear function of air temperature T2.


The coupling between the simple QF model and SuPy is done via the low-level function suews_cal_tstep, which is an interface function in charge of communications between the SuPy front end and the calculation kernel. By setting SuPy to receive external QF as forcing, at each time step, the simple QF model is driven by the SuPy output T2 and provides SuPy with QF, which thus forms a two-way coupled loop.

Here we replace the SUEWS QF (Table 2) with the simpler QF model (Fig. 7, Eq. 3) to explore the question of the impact of QF on T2 and its feedback on QF. The simulation using SuPy coupled is performed for London in 2012. The data analysed are a summer (July) and a winter (December) month. Initially, QF is 0 W m−2 and the T2 is determined and used to determine QF[1], which in turn modifies T2[1] and therefore modifies QF[2] and the diagnosed T2[2]. Results indicate a positive feedback, as QF is increases T2 is elevated but with different magnitudes (Fig. 8). Of particular note is the positive-feedback loop under warm air temperatures: the anthropogenic heat emissions increase, which in turn elevates the outdoor air temperature causing yet more anthropogenic heat release (Fig. 8). Note that London is relatively cool (cf. air temperature in Fig. 2) so the enhancement is much less than it would be in warmer cities.

In this case the anthropogenic heat flux model is simple, but a more complex model could be coupled to SUEWS in the same way. This can facilitate development of climate service tools that are both agile and responsive.

Figure 8Impacts of QF produced by an external simple anthropogenic heat model on the near-surface air temperature T2 for 2 months: summer (July 2012, orange) and winter (December 2012, blue). Linear regression lines (dashed lines) show the overall seasonal trends. ΔQF=QF2-QF1, see text for definitions and the corresponding temperatures, ΔT2=T22-T21.


5 Concluding remarks

The development and delivery of a Python-enhanced urban climate model SuPy is introduced with tutorials (Table 2) to demonstrate typical applications and some new SUEWS features (e.g. surface diagnostics calculation). The Python code and tutorials are freely and openly available online (Appendix B). Users are encouraged to explore more intriguing urban-climate-related questions with SuPy. Notable features of SuPy include the following:

  1. Version consistency via PyPI: SuPy is distributed via the well managed Python package repository PyPI with all history versions stored. This allows for clear version consistency for reproducing simulation results.

  2. Simplicity in input/output sharing: SuPy uses pandas DataFrame as its core data structure and thus draws on a powerful data analysis toolchain, which can facilitate the ease with which urban climate research outcomes can be communicated.

  3. Ease of scientific development: given the importance of meteorological forcing data in running climate simulations, SuPy will shortly be equipped with the ability to retrieve forcing variables from global reanalysis datasets. We anticipate data analyses and model development will be added more conveniently within the Python data ecosystem.

  4. An open source tool: we welcome all kinds of contributions, e.g. incorporation of a new feature (pull requests), submission of issues or development of new tutorials.

In addition to SuPy in data analysis and communication features, the computation kernel is SUEWS so all physics schemes development will remain in the Fortran stack for computational performance and compatibility with a large cohort of scientific code. In one application software, UMEP (Lindberg et al., 2018) written in Python, the SUEWS binary executable will shortly be updated to SuPy for better connectivity to other UMEP components.

We expect SuPy will help guide future development of SUEWS (and similar urban climate models) and enable new applications of the model. For example, the parallel set up of SuPy will allow large-scale simulations of urban climate across larger domains with greater surface heterogeneity. Moreover, the improvement in the SUEWS model structure and deployment process introduced by the development of SuPy paves the way to a more robust workflow of SUEWS for its sustainable success.

Code availability

Appendices B and C describe the locations and licence information for SuPy (; Sun, 2019) and SUEWS (; Sun et al., 2019), respectively.

Appendix A: SuPy functions

The utility of the six SuPy functions are

  • init_supy. Initialize SuPy by loading initial model states.

  • load_forcing_grid. Load forcing data for a specific grid included in the index of df_state_init.

  • run_supy. Perform SuPy simulation.

  • save_supy. Save SuPy run results to files.

  • load_SampleData. Load sample data for quickly starting a demo run.

  • show_version. Print supy and supy_driver version information.

For detailed usage of the included functions see: (last access: 1 July 2019).

Appendix B: SuPy model source code and documentation

Code repository

Versioned documentation

  • Name: ReadTheDocs

  • Identifier:
    (last access: 12 June 2019)

  • Licence: GNU GPL v3.0

  • Date published: 10 February 2019

Appendix C: SUEWS model source code and documentation

Code repository

Versioned documentation

Author contributions

TS led the development of SuPy and core enhancements of SUEWS since v2017b. SG provided overall oversight of the SUEWS development. TS and SG wrote the paper.

Competing interests

The authors declare that they have no conflict of interest.


We thank the two anonymous reviewers and the editor Tim Butler for their constructive comments. We appreciate the numerous people who have and continue to contribute to the development of SUEWS and the users who identify issues. We thank all those who have contributed to the field observations maintenance, analysis, provided sites, access and funding.

Financial support

This research has been supported by NERC Independent Research Fellowship (grant no. NE/P018637/1; Ting Sun); Newton Fund/Met Office CSSP China (Sue Grimmond, Ting Sun), RS Newton Mobility funding (Sue Grimmond, Ting Sun) and EPSRC LoHCool (grant no. EP/N009797/1) (Sue Grimmond, Ting Sun). Field observations have been funded by grants from NERC (grant no. NE/H003231/1), European Commission, FP7 (grant no. 211345), the European Commission, H2020-EO-2014 (UrbanFluxes (grant no. 637519)), EPSRC (grant nos. EP/I00159X/1, EP/I00159X/2), KCL (Sue Grimmond), Belmont Forum (grant nos. TRUC NE/L008971/1, G8MUREFU3FP-2201-075), Newton Fund and the Met Office (CSSP grant).

Review statement

This paper was edited by Tim Butler and reviewed by two anonymous referees.


Alexander, P. J., Bechtel, B., Chow, W. T. L., Fealy, R., and Mills, G.: Linking urban climate classification with an urban energy and water budget model: Multi-site and multi-seasonal evaluation, Urban Climate, 17, 196–215,, 2016. 

Alexander, P. J., Mills, G., and Fealy, R.: Using LCZ data to run an urban energy balance model, Urban Climate, 13, 14–37,, 2015. 

Ao, X., Grimmond, C., Chang, Y., Liu, D., Tang, Y., Hu, P., Wang, Y., Zou, J., and Tan, J.: Heat, water and carbon exchanges in the tall megacity of Shanghai: challenges and results, Int. J. Climatol., 36, 4608–4624,, 2016. 

Ao, X., Grimmond, C., Ward, H. C., Gabey, A. M., Tan, J., Yang, X.-Q., Liu, D., Zhi, X., Liu, H., and Zhang, N.: Evaluation of the Surface Urban Energy and Water balance Scheme (SUEWS) at a dense urban site in Shanghai: Sensitivity to anthropogenic heat and irrigation, J. Hydrometeorol., 19, 1983–2005,, 2018. 

Bailey, D. H., Barszcz, E., Barton, J. T., Browning, D. S., Carter, R. L., Dagum, L., Fatoohi, R. A., Frederickson, P. O., Lasinski, T. A., Schreiber, R. S., Simon, H. D., Venkatakrishnan, V., and Weeratunga, S. K.: The Nas Parallel Benchmarks, International Journal of Supercomputing Applications, 5, 63–73,, 1991. 

Baklanov, A., Grimmond, C. S. B., Carlson, D., Terblanche, D., Tang, X., Bouchet, V., Lee, B., Langendijk, G., Kolli, R. K., and Hovsepyan, A.: From urban meteorology, climate and environment research to integrated city services, Urban Climate, 23, 330–341,, 2018. 

Bar, L. S., Pearlmutter, D., and Erell, E.: The influence of trees and grass on outdoor thermal comfort in a hot-arid environment, Int. J. Climatol., 31, 1498–1506,, 2011. 

Best, M. J. and Grimmond, C.: Key Conclusions of the First International Urban Land Surface Model Comparison Project, B. Am. Meteorol. Soc., 96, 805–819,, 2015. 

Campbell, G. S. and Norman, J. M.: An Introduction to Environmental Biophysics, Springer New York, New York, NY, 1998. 

Chen, F., Kusaka, H., Bornstein, R., Ching, J., Grimmond, C., Grossman-Clarke, S., Loridan, T., Manning, K. W., Martilli, A., Miao, S., Sailor, D. J., Salamanca, F. P., Taha, H., Tewari, M., Wang, X., Wyszogrodzki, A. A., and Zhang, C.: The integrated WRF/urban modelling system: development, evaluation, and applications to urban environmental problems, Int. J. Climatol., 31, 273–288,, 2011. 

Chen, Q. Y.: Using computational tools to factor wind into architectural environment design, Energ. Buildings, 36, 1197–1209,, 2004. 

de la Varga, M., Schaaf, A., and Wellmann, F.: GemPy 1.0: open-source stochastic geological modeling and inversion, Geosci. Model Dev., 12, 1–32,, 2019. 

Demuzere, M., Harshan, S., Järvi, L., Roth, M., Grimmond, C., Masson, V., Oleson, K. W., Velasco, E., and Wouters, H.: Impact of urban canopy models and external parameters on the modelled urban energy balance in a tropical city, Q. J. Roy. Meteor. Soc., 143, 1581–1596,, 2017. 

Donner, L. J., Wyman, B. L., Hemler, R. S., Horowitz, L. W., Ming, Y., Zhao, M., Golaz, J.-C., Ginoux, P., Lin, S. J., Schwarzkopf, M. D., Austin, J., Alaka, G., Cooke, W. F., Delworth, T. L., Freidenreich, S. M., Gordon, C. T., Griffies, S. M., Held, I. M., Hurlin, W. J., Klein, S. A., Knutson, T. R., Langenhorst, A. R., Lee, H.-C., Lin, Y., Magi, B. I., Malyshev, S. L., Milly, P. C. D., Naik, V., Nath, M. J., Pincus, R., Ploshay, J. J., Ramaswamy, V., Seman, C. J., Shevliakova, E., Sirutis, J. J., Stern, W. F., Stouffer, R. J., Wilson, R. J., Winton, M., Wittenberg, A. T., and Zeng, F.: The Dynamical Core, Physical Parameterizations, and Basic Simulation Characteristics of the Atmospheric Component AM3 of the GFDL Global Coupled Model CM3, J. Climate, 24, 3484–3519,, 2011. 

Erell, E., Pearlmutter, D., Boneh, D. and Kutiel, P. B.: Effect of high-albedo materials on pedestrian heat stress in urban street canyons, Urban Climate, 10, 367–386,, 2013. 

Gabey, A. M., Grimmond, C., and Capel-Timms, I.: Anthropogenic heat flux: advisable spatial resolutions when input data are scarce, Theor. Appl. Climatol., 31, 1–17,, 2018. 

Grimmond, C.: The suburban energy balance: Methodological considerations and results for a mid-latitude west coast city under winter and spring conditions, Int. J. Climatol., 12, 481–497,, 1992. 

Grimmond, C. and Oke, T. R.: Urban Water Balance: 2. Results From a Suburb of Vancouver, British Columbia, Water Resour. Res., 22, 1404–1412,, 1986. 

Grimmond, C. and Oke, T. R.: An evapotranspiration-interception model for urban areas, Water Resour. Res., 27, 1739–1755,, 1991. 

Grimmond, C. and Oke, T. R.: Aerodynamic properties of urban areas derived, from analysis of surface form, J. Appl. Meteorol. Clim., 38, 1262–1292,<1262:APOUAD>2.0.CO;2, 1999. 

Grimmond, C., Oke, T. R., and Steyn, D. G.: Urban Water Balance: 1. A Model for Daily Totals, Water Resour. Res., 22, 1397–1403,, 1986. 

Grimmond, C., Cleugh, H. A., and Oke, T. R.: An objective urban heat storage model and its comparison with other schemes, Atmos. Environ., 25, 311–326,, 1991. 

Hamilton, I. G., Davies, M., Steadman, P., Stone, A., Ridley, I., and Evans, S.: The significance of the anthropogenic heat emissions of London's buildings: A comparison against captured shortwave solar radiation, Build. Environ., 44, 807–817,, 2009. 

Hamman, J. J., Nijssen, B., Bohn, T. J., Gergel, D. R., and Mao, Y.: The Variable Infiltration Capacity model version 5 (VIC-5): infrastructure improvements for new applications and reproducibility, Geosci. Model Dev., 11, 3481–3496,, 2018. 

Iamarino, M., Beevers, S., and Grimmond, C.: High-resolution (space, time) anthropogenic heat emissions: London 1970–2025, Int. J. Climatol., 32, 1754–1767,, 2011. 

IPCC: Climate Change 2013: The Physical Science Basis, Cambridge University Press, 2014. 

Järvi, L., Grimmond, C., and Christen, A.: The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver, J. Hydrol., 411, 219–237,, 2011. 

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

Järvi, L., Grimmond, C., McFadden, J. P., Christen, A., Strachan, I. B., Taka, M., Warsta, L., and Heimann, M.: Warming effects on the urban hydrology in cold climate regions, Sci. Rep., 7, 216,, 2017. 

Järvi, L., Havu, M., Ward, H., Bellucco, V., McFadden, J., Toivonen, T., Heikinheimo, V., and Grimmond, C.: Spatial modelling of biogenic 20 and anthropogenic carbon dioxide emissions in Helsinki, J. Geogr. Res.-Atmos., 124,, online first, 2019. 

Jentsch, M. F., James, P. A. B., Bourikas, L., and Bahaj, A. S.: Transforming existing weather data for worldwide locations to enable energy and building performance simulation under future climates, Renew. Energ., 55, 514–524,, 2013. 

Karsisto, P., Fortelius, C., Demuzere, M., Grimmond, C., Oleson, K. W., Kouznetsov, R., Masson, V., and Järvi, L.: Seasonal surface urban energy balance and wintertime stability simulated using three land-surface models in the high-latitude city Helsinki, Q. J. Roy. Meteor. Soc., 142, 401–417,, 2015. 

Kawai, T., Ridwan, M. K., and Kanda, M.: Evaluation of the Simple Urban Energy Balance Model Using Selected Data from 1-yr Flux Observations at Two Cities, J. Appl. Meteorol. Climatol., 48, 693–715,, 2009. 

Kokkonen, T. V., Grimmond, C., Christen, A., Oke, T. R., and Järvi, L.: Changes to the Water Balance Over a Century of Urban Development in Two Neighborhoods: Vancouver, Canada, Water Resour. Res., 54, 6625–6642,, 2018. 

Kokkonen, T. V., Grimmond, S., Murto, S., Liu, H., Sundström, A.-M., and Järvi, L.: Simulation of the radiative effect of haze on the urban hydrological cycle using reanalysis data in Beijing, Atmos. Chem. Phys., 19, 7001–7017,, 2019. 

Kotthaus, S. and Grimmond, C.: Energy exchange in a dense urban environment Part I: Temporal variability of long-term observations in central London, Urban Climate, 10, 261–280,, 2014. 

Kouatchou, J.: NASA Modeling Guru: Basic Comparison of Python, Julia, Matlab, IDL and Java (2018 Edition), available at: (last access: 12 June 2019), 2018. 

Krayenhoff, E. S., Moustaoui, M., Broadbent, A. M., Gupta, V., and Georgescu, M.: Diurnal interaction between urban expansion, climate change and adaptation in US cities, Nat. Clim. Change, 8, 1097–1103,, 2018. 

Li, B., Luo, Z., Sandberg, M., and Liu, J.: Revisiting the “Venturi effect” in passage ventilation between two non-parallel buildings, Build. Environ., 94, 714–722,, 2015. 

Li, D., Bou-Zeid, E., and Oppenheimer, M.: The effectiveness of cool and green roofs as urban heat island mitigation strategies, Environ. Res. Lett., 9, 055002,, 2014. 

Li, D., Sun, T., Liu, M., Yang, L., Wang, L., and Gao, Z.: Contrasting responses of urban and rural surface energy budgets to heat waves explain synergies between urban heat islands and heat waves, Environ. Res. Lett., 10, 054009,, 2015. 

Lin, J. W.-B.: Why Python Is the Next Wave in Earth Sciences Computing, B. Am. Meteorol. Soc., 93, 1823–1824,, 2012. 

Lindberg, F. and Grimmond, C.: The influence of vegetation and building morphology on shadow patterns and mean radiant temperatures in urban areas: model development and evaluation, Theor. Appl. Climatol., 105, 311–323,, 2011. 

Lindberg, F., Grimmond, C., Gabey, A., Huang, B., Kent, C. W., Sun, T., Theeuwes, N. E., Järvi, L., Ward, H. C., Capel-Timms, I., Chang, Y., Jonsson, P., Krave, N., Liu, D., Meyer, D., Olofson, K. F. G., Tan, J., Wästberg, D., Xue, L., and Zhang, Z.: Urban Multi-scale Environmental Predictor (UMEP): An integrated tool for city-based climate services, Environ. Modell. Softw., 99, 70–87,, 2018. 

Loridan, T., Grimmond, C., Offerle, B. D., Young, D. T., Smith, T. E. L., Järvi, L., and Lindberg, F.: Local-Scale Urban Meteorological Parameterization Scheme (LUMPS): Longwave Radiation Parameterization and Seasonality-Related Developments, J. Appl. Meteorol. Clim., 50, 185–202,, 2011. 

Monteiro, J. M., McGibbon, J., and Caballero, R.: sympl (v. 0.4.0) and climt (v. 0.15.3) – towards a flexible framework for building model hierarchies in Python, Geosci. Model Dev., 11, 3781–3794,, 2018. 

Nie, W.-S., Sun, T., and Ni, G.-H.: Spatiotemporal characteristics of anthropogenic heat in an urban environment: A case study of Tsinghua Campus, Build. Environ., 82, 675–686,, 2014. 

Nie, W.-S., Zaitchik, B. F., Ni, G.-H., and Sun, T.: Impacts of Anthropogenic Heat on Summertime Rainfall in Beijing, J. Hydrometeorol., 18, 693–712,, 2016. 

Offerle, B. D., Grimmond, C., and Oke, T. R.: Parameterization of net all-wave radiation for urban areas, J. Appl. Meteorol. Clim., 42, 1157–1173,<1157:PONARF>2.0.CO;2, 2003. 

Onomura, S., Grimmond, C., Lindberg, F., Holmer, B., and Thorsson, S.: Meteorological forcing data for urban outdoor thermal comfort models from a coupled convective boundary layer and surface energy balance scheme, Urban Climate, 11, 1–23,, 2015. 

Peng, R. D.: Reproducible Research in Computational Science, Science, 334, 1226–1227,, 2011. 

Perkel, J. M.: Programming: Pick up Python, Nature News, 518, 125–126,, 2015. 

Peterson, P.: F2PY: a tool for connecting Fortran and Python programs, International Journal of Computational Science and Engineering, 4, 296,, 2009. 

Rafael, S., Martins, H., Marta-Almeida, M., Sá, E., Coelho, S., Rocha, A., Borrego, C., and Lopes, M.: Quantification and mapping of urban fluxes under climate change: Application of WRF-SUEWS model to Greater Porto area (Portugal), Environ. Res., 155, 321–334,, 2017. 

Ramamurthy, P., Sun, T., Rule, K., and Bou-Zeid, E.: The joint influence of albedo and insulation on roof performance: A modeling study, Energ. Buildings, 102, 317–327,, 2015. 

Reinhart, C. F. and Cerezo Davila, C.: Urban building energy modeling A review of a nascent field, Build. Environ., 97, 196–202,, 2016. 

Sailor, D. J.: A review of methods for estimating anthropogenic heat and moisture emissions in the urban environment, Int. J. Climatol., 31, 189–199,, 2011. 

Santamouris, M., Papanikolaou, N., Livada, I., Koronakis, I., Georgakis, C., Argiriou, A., and Assimakopoulos, D. N.: On the impact of urban climate on the energy consumption of buildings, Sol. Energy, 70, 201–216,, 2001. 

Santamouris, M., Synnefa, A., and Karlessi, T.: Using advanced cool materials in the urban built environment to mitigate heat islands and improve thermal comfort conditions, Sol. Energy, 85, 3085–3102,, 2011. 

Skamarock, W. C. and Klemp, J. B.: A time-split nonhydrostatic atmospheric model for weather research and forecasting applications, J. Comput. Phys., 227, 3465–3485,, 2008. 

Sun, T.: SuPy (SUEWS in Python): 2019.2 Release,, 2019. 

Sun, T., Grimmond, C., and Ni, G.-H.: How do green roofs mitigate urban thermal stress under heat waves?, J. Geophys. Res.-Atmos., 121, 5320–5335,, 2016. 

Sun, T., Kotthaus, S., Li, D., Ward, H. C., Gao, Z., Ni, G.-H., and Grimmond, C.: Attribution and mitigation of heat wave-induced urban heat storage change, Environ. Res. Lett., 12, 114007,, 2017. 

Sun, T., Jarvi, L., Grimmond, D., Lindberg, F., Li, Z., Tang, Y., and Ward, H. C.: Urban-Meteorology-Reading/SUEWS: 2018c Release (Version 2018c), Zenodo,, 2019. 

Tan, J., Zheng, Y., Tang, X., Guo, C., Li, L., Song, G., Zhen, X., Yuan, D., Kalkstein, A. J., Li, F., and Chen, H.: The urban heat island and its impact on heat waves and human health in Shanghai, Int. J. Biometeorol., 54, 75–84,, 2009. 

Wang, L., Gao, Z., Miao, S., Guo, X., Sun, T., Liu, M., and Li, D.: Contrasting characteristics of the surface energy balance between the urban and rural areas of Beijing, Adv. Atmos. Sci., 32, 505–514,, 2015. 

Wang, Z.-H., Bou-Zeid, E., and Smith, J. A.: A coupled energy transport and hydrological model for urban canopies evaluated using a wireless sensor network, Q. J. Roy. Meteor. Soc., 139, 1643–1657,, 2012. 

Ward, H. C. and Grimmond, C.: Assessing the impact of changes in surface cover, human behaviour and climate on energy partitioning across Greater London, Landscape Urban Plan., 165, 142–161,, 2017. 

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

Ward, H. C., Tan, Y. S., Gabey, A. M., Kotthaus, S., and Grimmond, C.: Impact of temporal resolution of precipitation forcing data on modelled urban-atmosphere exchanges and surface conditions, Int. J. Climatol., 38, 649–662,, 2018. 

Zhao, L., Lee, X., Smith, R. B., and Oleson, K.: Strong contributions of local background climate to urban heat islands, Nature, 511, 216–219,, 2014. 

Short summary
A Python-enhanced urban land surface model, SuPy (SUEWS in Python), is presented with its development (the SUEWS interface modification, F2PY configuration and Python frontend implementation), cross-platform deployment (PyPI, Python Package Index) and demonstration (online tutorials in Jupyter notebooks for users of different levels). SuPy represents a significant enhancement that supports existing and new model applications, reproducibility and enhanced functionality.