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, freq_s, …) 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.

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_epw(path_epw) 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.
sim_ohm(ser_qn, a1, a2, a3) Calculate QS using OHM (Objective Hysteresis Model).

Surface Conductance

cal_gs_mod(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(path_nml) 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