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.

show_version([mode, as_json])

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: QN_Ser: The first independent variable (Net all wave radiation). Pandas Series. 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¶

cal_z0zd(ser_qh, ser_ustar, ser_ta_c, ...[, ...])

Calculates surface roughness and zero plane displacement height.

cal_neutral(ser_qh, ser_ustar, ser_ta_c, ...)

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

Command-Line Tools¶

Key Data Structures¶