1. Need help? Please let us know in the UMEP Community.

  2. Find an issue within this page? Please report it in the GitHub issues.

  3. A good understanding of SUEWS is a prerequisite to the proper use of SuPy.

API reference

Top-level Functions

init_supy(path_init[, force_reload, check_input])

Initialise supy by loading initial model states.

load_forcing_grid(path_runcontrol, grid[, …])

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

run_supy(df_forcing, df_state_init[, …])

Perform supy simulation.

save_supy(df_output, df_state_final[, …])

Save SuPy run results to files


Load sample data for quickly starting a demo run.


print SuPy and supy_driver version information.

Utility Functions

ERA-5 Data Downloader

download_era5(lat_x, lon_x, start, end[, …])

Generate ERA-5 cdsapi-based requests and download data for area of interests.

gen_forcing_era5(lat_x, lon_x, start, end[, …])

Generate SUEWS forcing files using ERA-5 data.

Typical Meteorological Year

gen_epw(df_output, lat, lon[, tz, path_epw])

Generate an epw file of uTMY (urbanised Typical Meteorological Year) using SUEWS simulation results


Read in epw file as a DataFrame

Gap Filling

fill_gap_all(ser_to_fill[, freq])

Fill all gaps in a time series using data from neighbouring divisions of ‘freq’


derive_ohm_coef(ser_QS, ser_QN)

A function to linearly fit two independant variables to a dependent one. Input params: QS_Ser: The dependent variable QS (Surface heat storage). Pandas Series. QN_Ser: The first independent variable (Net all wave radiation). Pandas Series. dt: The time interval with which the rate of change of QN is calculated. Float (hours). Returns: a1, a2 coefficients and a3 (intercept).

sim_ohm(ser_qn, a1, a2, a3)

Calculate QS using OHM (Objective Hysteresis Model).

Surface Conductance

cal_gs_suews(kd, ta_c, rh, pa, smd, lai, …)

Model surface conductance/resistance using phenology and atmospheric forcing conditions.

cal_gs_obs(qh, qe, ta, rh, pa, ra)

Calculate surface conductance based on observations, notably turbulent fluxes.

calib_g(df_fc_suews, ser_ra, g_max, lai_max, …)

Calibrate parameters for modelling surface conductance over vegetated surfaces using LMFIT.



Extract reclassification info from path_nml as a DataFrame.

plot_reclassification(path_nml[, path_save, …])

Produce Sankey Diagram to visualise the reclassification specified in path_nml


plot_comp(df_var[, scatter_kws, kde_kws, …])

Produce a scatter plot with linear regression line to compare simulation results and observations.

plot_day_clm(df_var[, fig, ax, show_dif, …])

Produce a ensemble diurnal climatologies with uncertainties shown in inter-quartile ranges.

plot_rsl(df_output[, var, fig, ax])

Produce a quick plot of RSL results

Roughness Calculation

optimize_MO(df_val, z_meas, h_sfc)

Calculates surface roughness and zero plane displacement height.

cal_neutral(df_val, z_meas, h_sfc)

Calculates the rows associated with neutral condition (threshold=0.01)

Command-Line Tools

Key Data Structures