Please report issues with this page on the GitHub page.

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[, path_epw, ratio_dif_dir]) 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_k, rh, pa, smd, lai, g_cst) Model surface conductance/resistance using phenology and atmospheric forcing conditions.
cal_gs_obs(qh, qe, ta, rh, pa) Calculate surface conductance based on observations, notably turbulent fluxes.
calib_g(df_fc_suews[, g_max, lai_max, s1, …]) 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[, fig, ax]) Produce a scatter plot with linear regression line to compare simulation results and observations.
plot_day_clm(df_var[, fig, ax]) Produce a ensemble diurnal climatologies with uncertainties shown in inter-quartile ranges.

Command-Line Tools