SUEWSSimulation Class

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
Checkpoint Restarts: Continue YAML-based runs from typed checkpoint JSON
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 as SUEWSForcing object.
`results`	Access to simulation results DataFrame (raw).
`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`	Legacy final state DataFrame after simulation.
`checkpoint`	Typed checkpoint produced by the most recent run.
`state_checkpoint`	Alias for `checkpoint`.

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_checkpoint`	Create a continuation simulation from YAML config and checkpoint.
`continue_from`	Use a typed checkpoint as the initial runtime state.
`from_state`	Create SUEWSSimulation from legacy DFState.

6.1.2.4. Execution Methods#

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

`run`	Run SUEWS simulation using the Rust bridge backend.
`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 OutputControl settings.
`get_variable`	Extract specific variable from simulation results.

6.1.2.6. Run Output#

run() returns a SUEWSOutput object. Use its checkpoint property as the restart artefact for continuation runs; state_final is retained as a legacy/developer DataFrame view.

`checkpoint`	Typed checkpoint for restart/continuation runs.
`state_checkpoint`	Alias for `checkpoint`.
`state_final`	Legacy final model state DataFrame.

6.1.2.7. Full Class Reference#

class supy.SUEWSSimulation(config: str | Path | dict | Any = None)[source]#

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_checkpoint(config: str | Path | dict | SUEWSConfig, checkpoint: str | Path | SUEWSCheckpoint) → SUEWSSimulation[source]#: Create a continuation simulation from YAML config and checkpoint.

classmethod from_output(output: SUEWSOutput) → SUEWSSimulation[source]#

Create SUEWSSimulation from previous output for continuation runs.

Convenience method that extracts the final state from a SUEWSOutput object and creates a new simulation ready for continuation.

Parameters:: output (SUEWSOutput) – Output object from a previous simulation run.
Returns:: Simulation instance initialised with checkpoint from output, ready for new forcing data and run.
Return type:: SUEWSSimulation

Examples

Seamless continuation from previous run:

>>> # Run first period
>>> sim1 = SUEWSSimulation("config.yaml")
>>> sim1.update_forcing("forcing_2023.txt")
>>> output1 = sim1.run()

>>> # Continue from output checkpoint
>>> sim2 = SUEWSSimulation.from_output(output1)
>>> sim2.update_forcing("forcing_2024.txt")
>>> output2 = sim2.run()

See also

from_checkpoint: Create from YAML config and checkpoint
SUEWSOutput.checkpoint: Typed checkpoint property for restart

classmethod from_sample_data()[source]#

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)[source]#

Create SUEWSSimulation from legacy DFState.

This compatibility adapter reads older DFState CSV/parquet/DataFrame artifacts. New continuation workflows should use from_checkpoint(config, checkpoint).

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: model final states 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

Legacy import from saved file:

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

>>> # Period 2 - legacy DFState continuation
>>> sim2 = SUEWSSimulation.from_state("output/df_state.csv")
>>> sim2.update_forcing("forcing_2024.txt")
>>> sim2.run()

Legacy import 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

from_checkpoint: Create continuation from YAML config and checkpoint
save: Save simulation results and checkpoint
reset: Clear results and reset to initial state
checkpoint: Access typed checkpoint from completed simulation

continue_from(checkpoint: str | Path | SUEWSCheckpoint) → SUEWSSimulation[source]#: Use a typed checkpoint as the initial runtime state.

get_variable(var_name: str, group: str | None = None, site: int | str | None = None) → DataFrame[source]#

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[source]#

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[source]#

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[source]#

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, chunk_day: int = 3660, n_jobs: int = -1, **run_kwargs) → SUEWSOutput[source]#

Run SUEWS simulation using the Rust bridge backend.

Parameters:

start_date (str, optional) – Start date for simulation (inclusive).
end_date (str, optional) – End date for simulation (inclusive).
chunk_day (int, optional) – Chunk size in days for splitting long simulations, by default 3660 (~10 years). Smaller values reduce peak memory at a small overhead cost.
n_jobs (int, optional) – Parallel worker control for multi-grid runs. -1 (default) uses Rayon default parallelism, 1 forces serial execution, and values greater than 1 cap Rayon to that many threads.

Returns:

Simulation results wrapped in an OOP interface with analysis and plotting convenience methods. Access raw DataFrame via .to_dataframe() or .df.

Return type:

SUEWSOutput

Raises:

RuntimeError – If configuration or forcing data is missing.

Examples

>>> sim = SUEWSSimulation.from_sample_data()
>>> output = sim.run()
>>> output.QH  # Access sensible heat flux
>>> output.diurnal_average("QH")  # Get diurnal pattern
>>> output.to_dataframe()  # Get raw DataFrame

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

Save simulation results according to OutputControl 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.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[source]#

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 | SUEWSForcing) → SUEWSSimulation[source]#

Update meteorological forcing data.

Parameters:: forcing_data (str, Path, list of paths, pandas.DataFrame, or SUEWSForcing) – 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 - SUEWSForcing object
Returns:: Self, for method chaining.
Return type:: SUEWSSimulation

Notes

When loading from file paths, forcing data is resampled to match the model timestep from model.control.tstep in the configuration. If no configuration is loaded, defaults to 300 seconds (5 minutes).

Examples

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

property checkpoint: SUEWSCheckpoint | None#: Typed checkpoint produced by the most recent 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: SUEWSForcing | None#

Access to forcing data as SUEWSForcing object.

Returns:: Meteorological forcing data wrapped in OOP interface with validation and analysis methods. None if no forcing loaded.
Return type:: SUEWSForcing or None

See also

df_forcing variables: Complete forcing data structure and variable descriptions
update_forcing: Load forcing data from files or DataFrames

Examples

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.forcing.summary()  # Get forcing statistics
>>> sim.forcing.Tair  # Access air temperature
>>> sim.forcing.df  # Access raw DataFrame

property output: SUEWSOutput | None#

Access to simulation results as SUEWSOutput object.

Note

Preferred pattern is output = sim.run() which returns the same SUEWSOutput object. This property is provided for convenience when re-accessing results after simulation.

Returns:: Simulation results wrapped in OOP interface with analysis and plotting convenience methods. None if simulation hasn’t been run yet.
Return type:: SUEWSOutput or None

See also

run: Run simulation and return SUEWSOutput (preferred)
df_output variables: Complete output data structure

Examples

Preferred pattern - capture return value:

>>> sim = SUEWSSimulation.from_sample_data()
>>> output = sim.run()  # Capture output
>>> output.QH  # Access sensible heat flux

Alternative - use property after run:

>>> sim = SUEWSSimulation.from_sample_data()
>>> sim.run()
>>> sim.output.QH  # Re-access via property

property results: DataFrame | None#

Access to simulation results DataFrame (raw).

Deprecated since version 2025.1: Use output = sim.run() to get a SUEWSOutput object, then output.df for the raw DataFrame if needed.

Returns:: Complete simulation output with all variable groups. None if simulation hasn’t been run yet.
Return type:: pandas.DataFrame or None

See also

output: Access results as SUEWSOutput object with analysis methods
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_checkpoint: SUEWSCheckpoint | None#: Alias for checkpoint.

property state_final: DataFrame | None#

Legacy final state DataFrame after simulation.

Prefer checkpoint for restart/continuation workflows.

Returns:: Legacy 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
checkpoint: Typed restart artifact
from_checkpoint: Create new simulation from checkpoint

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
checkpoint: Typed checkpoint after simulation
from_checkpoint: Create simulation from checkpoint

Examples

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

6.1.3. Quick Example#

from supy import SUEWSSimulation

# Create and run simulation
sim = SUEWSSimulation('config.yml')
sim.update_forcing('forcing_data.txt')
output = 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/')

# Continue from the typed checkpoint and the next forcing period
output.checkpoint.to_file('output_dir/{site}_SUEWS_checkpoint.json')
sim_next = SUEWSSimulation.from_checkpoint(
    'config.yml',
    'output_dir/{site}_SUEWS_checkpoint.json',
)
sim_next.update_forcing('forcing_next_period.txt')
output_next = sim_next.run()

# 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.

SUEWSSimulation Class

Contents

6.1. SUEWSSimulation Class#

6.1.1. Key Features#

6.1.2. Class Reference#

6.1.2.1. Core Properties#

6.1.2.2. Advanced Properties#

6.1.2.3. Setup Methods#

6.1.2.4. Execution Methods#

6.1.2.5. Output Methods#

6.1.2.6. Run Output#

6.1.2.7. Full Class Reference#

6.1.3. Quick Example#

6.1.4. Related Documentation#

6.1. `SUEWSSimulation` Class#