Tip

1. Need help? Please let us know in the UMEP 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.1. SUEWSSimulation Class

The SUEWSSimulation class provides a simplified object-oriented interface for running SUEWS simulations.

6.1.1. Key Features

• YAML Configuration: Load configurations from YAML files

• Configuration Updates: Update configuration with dictionaries or YAML files

• Forcing Management: Load single files, lists of files, or DataFrames

• Simple API: Clean interface focused on essential functionality

• Format Support: Save results in txt or parquet formats via OutputConfig

For usage examples and tutorials, see SUEWSSimulation Tutorial.

6.1.2. Class Reference

6.1.2.1. Core Properties

Access simulation configuration, forcing data, results, and status checks.

config	Access to simulation configuration.
forcing	Access to forcing data DataFrame.
results	Access to simulation results DataFrame.
is_ready	Check if simulation is configured and ready to run.
is_complete	Check if simulation has been run successfully.

6.1.2.2. Advanced Properties

For spin-up runs, state continuation, and deep model inspection.

state_init	Initial state DataFrame for simulation.
state_final	Final state DataFrame after simulation.

6.1.2.3. Setup Methods

Configure simulations, load forcing data, and initialise from various sources.

update_config	Update simulation configuration.
update_forcing	Update meteorological forcing data.
from_sample_data	Create SUEWSSimulation instance with built-in sample data.
from_state	Create SUEWSSimulation from saved state for continuation runs.

6.1.2.4. Execution Methods

Run simulations and reset state for re-execution with different parameters.

run	Run SUEWS simulation.
reset	Reset simulation to initial state, clearing results.

6.1.2.5. Output Methods

Save results to files and extract specific variables from output groups.

save	Save simulation results according to OutputConfig settings.
get_variable	Extract specific variable from simulation results.

6.1.2.6. Full Class Reference

class supy.SUEWSSimulation(config: str | Path | dict | Any = None)

Bases: object

Simplified SUEWS simulation class for urban climate modelling.

This class provides a clean interface for: - Loading and updating configuration - Managing forcing data - Running simulations - Saving results

Examples

Basic usage:

>>> sim = SUEWSSimulation("config.yaml")
>>> sim.update_forcing("forcing.txt")
>>> sim.run()
>>> sim.save("output_dir/")

Updating configuration:

>>> sim.update_config({"model": {"control": {"tstep": 600}}})
>>> sim.reset()
>>> sim.run()

classmethod from_sample_data()

Create SUEWSSimulation instance with built-in sample data.

This factory method provides a quick way to create a simulation object pre-loaded with sample configuration and forcing data, ideal for tutorials, testing, and learning the SUEWS workflow.

Returns:

Simulation instance ready to run with sample data loaded.

Return type:

SUEWSSimulation

Examples

Quick start with sample data:

>>> from supy import SUEWSSimulation
>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.run()
>>> results = sim.results

classmethod from_state(state: str | Path | DataFrame)

Create SUEWSSimulation from saved state for continuation runs.

Load a previously saved model state to continue simulation from where it left off. Useful for multi-period runs or scenario testing with different forcing data.

Parameters:

state (str, Path, or pandas.DataFrame) –

State to load for continuation. Can be:

• Path to CSV file: df_state.csv or df_state_{site}.csv

• Path to Parquet file: {site}_SUEWS_state_final.parquet

• DataFrame: df_state_final from previous simulation

Returns:

Simulation instance initialised with loaded state, ready for new forcing data and run.

Return type:

SUEWSSimulation

Warning

If the saved state was created with a different SUEWS version, a warning is issued about potential compatibility issues.

Examples

Continue from saved file:

>>> # Period 1
>>> sim1 = SUEWSSimulation("config.yaml")
>>> sim1.update_forcing("forcing_2023.txt")
>>> sim1.run()
>>> paths = sim1.save("output/")

>>> # Period 2 - continue from saved state
>>> sim2 = SUEWSSimulation.from_state("output/df_state.csv")
>>> sim2.update_forcing("forcing_2024.txt")
>>> sim2.run()

Continue from DataFrame directly:

>>> # In-memory continuation without saving to file
>>> sim1 = SUEWSSimulation.from_sample_data()
>>> sim1.run()
>>> df_state_final = sim1.state_final
>>>
>>> # Continue with new forcing
>>> sim2 = SUEWSSimulation.from_state(df_state_final)
>>> sim2.update_forcing("forcing_2024.txt")
>>> sim2.run()

Load from Parquet format:

>>> sim2 = SUEWSSimulation.from_state(
...     "output/TestSite_SUEWS_state_final.parquet"
... )

See also

save

Save simulation results and state

reset

Clear results and reset to initial state

state_final

Access final state from completed simulation

get_variable(var_name: str, group: str | None = None, site: int | str | None = None) → DataFrame

Extract specific variable from simulation results.

Convenience method to extract variables from the MultiIndex column structure without needing to understand the internal data layout.

Parameters:

• var_name (str) – Variable name to extract (e.g., ‘QH’, ‘QE’, ‘Tair’).

• group (str, optional) – Output group name if variable appears in multiple groups. If None and variable is in multiple groups, raises ValueError.

• site (int or str, optional) – Site index or name. If None, returns all sites.

Returns:

DataFrame with selected variable(s), indexed by time.

Return type:

pandas.DataFrame

Raises:

• RuntimeError – If simulation hasn’t been run yet.

• ValueError – If variable name not found in results, or if variable is ambiguous (appears in multiple groups) and no group specified.

Examples

Extract sensible heat flux:

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.run()
>>> qh = sim.get_variable("QH")
>>> qh.plot()  # Quick visualisation

Handle variables in multiple groups:

>>> # If 'Tair' appears in both 'forcing' and 'output' groups:
>>> tair = sim.get_variable("Tair", group="output")

See also

results

Full simulation output DataFrame

is_complete() → bool

Check if simulation has been run successfully.

Returns:

True if simulation has completed and results are available.

Return type:

bool

Examples

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.is_complete()
False

>>> sim.run()
>>> sim.is_complete()
True

is_ready() → bool

Check if simulation is configured and ready to run.

Returns:

True if both configuration and forcing data are loaded.

Return type:

bool

Examples

>>> sim = SUEWSSimulation()
>>> sim.is_ready()
False

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.is_ready()
True

reset() → SUEWSSimulation

Reset simulation to initial state, clearing results.

Returns:

Self, for method chaining.

Return type:

SUEWSSimulation

Examples

>>> sim.run()
>>> sim.reset().run()  # Re-run with same configuration

run(start_date=None, end_date=None, **run_kwargs) → DataFrame

Run SUEWS simulation.

Parameters:

• start_date (str, optional) – Start date for simulation (inclusive).

• end_date (str, optional) – End date for simulation (inclusive).

• run_kwargs (dict) –

  Note: Additional keyword arguments are currently not supported due to underlying function signature constraints. This parameter is reserved for future use.

  In a future version, the following options may be supported: - save_state: bool - Save state at each timestep (planned) - chunk_day: int - Days per chunk for memory efficiency (planned)

  For now, simulations use default settings: - save_state=False (states not saved at each step) - chunk_day=3660 (approximately 10 years per chunk)

Returns:

Simulation results with MultiIndex columns (group, variable).

Return type:

pandas.DataFrame

Raises:

RuntimeError – If configuration or forcing data is missing.

Notes

The simulation runs with fixed internal settings. For advanced control over simulation parameters, consider using the lower-level functional API (though it is deprecated).

save(output_path: str | Path | None = None, **save_kwargs) → list[str]

Save simulation results according to OutputConfig settings.

Parameters:

• output_path (str or Path, optional) – Output directory path. If None, uses current directory.

• save_kwargs (dict) –

  Additional keyword arguments for customising output.

  Currently supported kwargs:

  • formatstr

    Output format: ‘txt’ (default) or ‘parquet’. Note: This overrides config file settings.

  Not currently supported (due to internal constraints):

  • freq_s: Controlled by config.model.control.output_file.freq

  • site: Derived from config.sites[0].name

  • save_tstep: Not configurable via OOP interface

  • output_level: Not configurable via OOP interface

  These parameters are determined by the configuration object. To change them, update your configuration file or use update_config() before running the simulation.

Returns:

List of paths to saved files.

Return type:

list

Raises:

RuntimeError – If no simulation results are available.

Examples

Save with default settings from config:

>>> sim.run()
>>> paths = sim.save()

Save to specific directory with custom format:

>>> sim.run()
>>> paths = sim.save("output/", format="parquet")

update_config(config: str | Path | dict | SUEWSConfig, auto_load_forcing: bool = True) → SUEWSSimulation

Update simulation configuration.

Can accept full or partial configuration updates.

Parameters:

• config (str, Path, dict, or SUEWSConfig) – Configuration source: - Path to YAML file - Dictionary with parameters (can be partial) - SUEWSConfig object

• auto_load_forcing (bool, optional) –

  If True (default), automatically load forcing data specified in the config file. If False, forcing must be loaded explicitly using update_forcing().

  Set to False when: - You want explicit control over forcing data loading - Forcing file paths in config are placeholders - You plan to provide forcing data programmatically

Returns:

Self, for method chaining.

Return type:

SUEWSSimulation

Examples

>>> sim.update_config("new_config.yaml")
>>> sim.update_config({"model": {"control": {"tstep": 300}}})
>>> sim.update_config("config.yaml").update_forcing("forcing.txt")

Explicit forcing control:

>>> sim.update_config("config.yaml", auto_load_forcing=False)
>>> sim.update_forcing("custom_forcing.txt")

update_forcing(forcing_data: str | Path | list | DataFrame) → SUEWSSimulation

Update meteorological forcing data.

Parameters:

forcing_data (str, Path, list of paths, or pandas.DataFrame) – Forcing data source: - Path to a single forcing file - List of paths to forcing files (concatenated in order) - Path to directory containing forcing files (deprecated) - DataFrame with forcing data

Returns:

Self, for method chaining.

Return type:

SUEWSSimulation

Examples

>>> sim.update_forcing("forcing_2023.txt")
>>> sim.update_forcing(["forcing_2023.txt", "forcing_2024.txt"])
>>> sim.update_forcing(df_forcing)
>>> sim.update_config(cfg).update_forcing(forcing).run()

property config: SUEWSConfig | None

Access to simulation configuration.

Returns:

Complete SUEWS configuration object. None if no configuration loaded.

Return type:

SUEWSConfig or None

See also

update_config

Load or update configuration

state_init

Access initial state derived from configuration

property forcing: DataFrame | None

Access to forcing data DataFrame.

Returns:

Meteorological forcing data with required variables. None if no forcing loaded.

Return type:

pandas.DataFrame or None

See also

df_forcing variables

Complete forcing data structure and variable descriptions

update_forcing

Load forcing data from files or DataFrames

property results: DataFrame | None

Access to simulation results DataFrame.

Returns:

Complete simulation output with all variable groups. None if simulation hasn’t been run yet.

Return type:

pandas.DataFrame or None

See also

df_output variables

Complete output data structure and variable descriptions

get_variable

Extract specific variables from output groups

save

Save results to files

property state_final: DataFrame | None

Final state DataFrame after simulation.

Available only after running simulation. Contains evolved state variables that can be used to continue simulation.

Returns:

Final state after simulation run. None if simulation hasn’t been run yet.

Return type:

pandas.DataFrame or None

See also

df_state variables

Complete state data structure and variable descriptions

state_init

Initial state before simulation

reset

Clear results and reset to initial state

from_state

Create new simulation from this final state

Examples

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.run()
>>> sim.state_final is not None
True

property state_init: DataFrame | None

Initial state DataFrame for simulation.

Returns:

Initial state with surface characteristics and parameters. None if no configuration loaded.

Return type:

pandas.DataFrame or None

See also

df_state variables

Complete state data structure and variable descriptions

state_final

Final state after simulation

from_state

Create simulation from existing state

Examples

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.state_init.shape
(1, 1423)

6.1.3. Quick Example

from supy import SUEWSSimulation

# Create and run simulation
sim = SUEWSSimulation('config.yml')
sim.update_forcing('forcing_data.txt')
sim.run()

# Access results - use get_variable() for safe extraction
qh = sim.get_variable('QH')              # Sensible heat flux
qe = sim.get_variable('QE')              # Latent heat flux

# For variables in multiple groups, specify which one
albedo = sim.get_variable('AlbSnow', group='SUEWS')

# Save results
sim.save('output_dir/')

# Update configuration and re-run
sim.update_config({'model': {'control': {'tstep': 600}}})
sim.reset()
sim.run()

Note

Some variables appear in multiple output groups (e.g., AlbSnow in both SUEWS and DailyState). Use the get_variable() method with the group parameter to disambiguate. See the tutorial for details.

6.1.4. Related Documentation

• SUEWSSimulation Tutorial - Comprehensive tutorial with examples

• YAML Configuration Format - YAML configuration guide

• df_forcing variables - Forcing data format

• df_output variables - Output data format