Core Functions

Tip

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

  2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

  3. Please cite SUEWS with proper information from our Zenodo page.

6.2. Core Functions#

Deprecated since version 2025.11.20: The functional API is deprecated and will be removed in a future release. Please migrate to the object-oriented SUEWSSimulation interface. See SUEWSSimulation Class for the modern interface.

The core functions provide the primary interface for running SUEWS simulations using the legacy functional API.

6.2.1. Main Functions (Deprecated)#

init_supy(path_init[, force_reload, check_input])

Initialise supy by loading initial model states.

run_supy(df_forcing, df_state_init[, ...])

Perform supy simulation.

save_supy(df_output, df_state_final[, ...])

Save SuPy run results to files.

load_forcing_grid(path_init, grid[, ...])

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

load_sample_data()

Load sample data for quickly starting a demo run.

show_version([mode, as_json])

Display SUEWS version and system dependency information.

Note

All functions except show_version() are deprecated. Use SUEWSSimulation for new code.

6.2.2. Legacy Workflow Reference#

Warning

This workflow is deprecated. For new projects, use SUEWSSimulation instead.

The legacy functional API workflow consists of:

  1. Load initial conditions: init_supy() to set up model state (deprecated)

  2. Load forcing data: load_forcing_grid() to load meteorological inputs (deprecated)

  3. Run simulation: run_supy() to execute the model (deprecated)

  4. Save results: save_supy() to write outputs to disk (deprecated)

Recommended: See SUEWSSimulation Class for the modern object-oriented interface.

6.2.3. Logging Controls#

These functions are not deprecated; they control where SuPy writes its logs.

enable_file_logging([path])

Write SuPy log messages to a file (opt-in).

disable_file_logging()

Detach and close the opt-in file handler, if one is active.

By default SuPy logs only to the console; no SuPy.log file is created. Call enable_file_logging() to also write a log file (lazily created on the first message, so an unused logger leaves no stray file) and disable_file_logging() to stop it again:

import supy

supy.enable_file_logging()                  # writes SuPy.log in the current directory
supy.enable_file_logging("~/logs/run.log")  # a specific file (~ is expanded)
supy.disable_file_logging()                 # stop writing to the file

To log into a directory (created if needed), use the SUPY_LOG_DIR environment variable, which always writes SuPy.log inside it. File logging can be enabled entirely without code by setting an environment variable before importing supy:

export SUPY_LOGFILE=~/logs/run.log   # explicit file path
export SUPY_LOG_DIR=~/logs           # directory; file is SuPy.log inside it