Physics Methods

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.

4.3.33. Physics Methods#

Model physics configuration options.

Public selector forms

The scalar {value: ...} form remains valid for each selector. The forms below are the public YAML names and nested families accepted by the configuration validators; they are folded to the existing method-code fields before SUEWS runs. Registered selector tokens are case-insensitive; citation-style choices are shown in their preferred case.

Method dependency graph

The main method interactions are:

  • snow_use -> net_radiation -> storage_heat -> energy_balance

  • emissions -> ohm_inc_qf -> storage_heat

  • storage_heat -> stebbs -> stebbs.capacitance

  • roughness_length_momentum -> roughness_length_heat -> stability -> roughness_sublayer -> roughness_sublayer_level -> surface_conductance

Conditional compatibility checks enforce the critical branches: EHC storage heat requires SPARTACUS net radiation, STEBBS storage heat requires STEBBS enabled, and non-default STEBBS capacitance choices require the STEBBS branch.

Table 4.1 Net radiation#

Public path

Choices

Notes

net_radiation

forcing / observed; nested narp; nested spartacus

Selects observed net all-wave radiation, or a nested NARP/SPARTACUS form.

net_radiation.narp.ldown

observed; cloud; air

Longwave-down source for NARP.

net_radiation.narp.variant

standard; surface; zenith

Optional NARP variant; standard is the default.

net_radiation.spartacus.ldown

observed; cloud; air

Longwave-down source for SPARTACUS-Surface.
Table 4.2 Emissions#

Public path

Choices

Notes

emissions.heat

observed; L11; J11; L11_updated

Observed QF cannot be combined with CO2 axes; use modelled heat when CO2 is enabled.

emissions.co2.anthropogenic

none; qf_linked; detailed

Anthropogenic CO2 branch; use none only when biogenic is also none.

emissions.co2.biogenic

none; rectangular; bellucco_local; bellucco_general; conductance

Biogenic CO2 family; a family requires anthropogenic qf_linked or detailed.
Table 4.3 Storage heat#

Public path

Choices

Notes

storage_heat

observed; ohm; anohm; estm; ehc; dyohm; stebbs

Storage heat source or model family.

storage_heat.ohm.include_qf

true / false; include / exclude

Public home for the OHM QF-inclusion switch.
Table 4.4 Observed/modelled source selectors#

Public path

Choices

Notes

soil_moisture_deficit

modelled; observed

Selects water-balance SMD or forcing-file soil moisture.

water_use

modelled; observed

Selects modelled irrigation/water use or forcing-file values.

leaf_area_index

observed; modelled

Public alias for the LAI method selector.

frontal_area_index

observed; modelled

Selects observed or modelled frontal area index.

snow

disabled; enabled

Public alias for the snow-process switch.
Table 4.5 Other method selectors#

Public path

Choices

Notes

roughness_length_momentum

fixed; variable; macdonald / M98; lambdap_dependent / GO99; alternative

Momentum roughness-length method.

roughness_length_heat

brutsaert / B82; kawai / K09; voogt_grimmond / VG00; kanda / K07; adaptive

Heat roughness-length method.

stability

not_used; not_used2; hoegstrom; CN98; BH71

Atmospheric stability correction method.

roughness_sublayer

most; rst / T19; variable

Roughness sublayer treatment.

roughness_sublayer_level

none; basic; detailed

Roughness sublayer detail level.

surface_conductance

J11; W16

Surface conductance method.
Table 4.6 STEBBS#

Public path

Choices

Notes

stebbs.enabled

false; true

Master STEBBS switch.

stebbs.parameter_source

default; provided

Public alias for the STEBBS parameter-source selector.

stebbs.capacitance

default; provided; parameterise

Reading/STEBBS public selector name for the RC-method choice.

stebbs.setpoint

constant; dependent; scheduled

Space-heating/cooling setpoint method.

stebbs.same_albedo_wall; stebbs.same_albedo_roof

disabled; enabled

Wall and roof albedo assumptions.

stebbs.same_emissivity_wall; stebbs.same_emissivity_roof

disabled; enabled

Wall and roof emissivity assumptions.

Note

The generated parameter list below still includes implementation field names where they differ from public aliases. In user YAML, prefer leaf_area_index over laimethod, snow over snow_use, storage_heat.ohm.include_qf over flat ohm_inc_qf, and stebbs.parameter_source over stebbs.parameters.

Parameters:

net_radiation#

Method for calculating net all-wave radiation (Q*).

Options:
0 (OBSERVED) = Uses observed Q* values from forcing file
1 (LDOWN_OBSERVED) = Models Q* using NARP (Net All-wave Radiation Parameterization
2 (LDOWN_CLOUD) = Models Q* using NARP with L↓ estimated from cloud cover fraction
3 (LDOWN_AIR) = Models Q* using NARP with L↓ estimated from air temperature and relative humidity
Default:

3 (LDOWN_AIR)

Method Interactions

Values above 1000 activate SPARTACUS-Surface and provide facet radiation required by EHC storage heat.

Depends on: snow_use Provides to: storage_heat

emissions#

Method for calculating anthropogenic heat flux (QF) and CO2 emissions.

Note

Some options below are marked as experimental. While scientifically validated, users should verify results for their specific applications.

Options:
0 (OBSERVED) = Uses observed QF values from forcing file (set to zero to exclude QF from energy balance)
1 (L11) = Loridan et al. (2011) SAHP method with air temperature and population density
2 (J11) = Järvi et al. (2011) SAHP_2 method with heating/cooling degree days
4 (J19) = Detailed anthropogenic heat branch with L11 heat basis
11 (BIOGEN_RECT_L11) = Rectangular hyperbola biogenic CO2 + QF-linked anthropogenic CO2 + L11 heat (experimental)
12 (BIOGEN_RECT_J11) = Rectangular hyperbola biogenic CO2 + QF-linked anthropogenic CO2 + J11 heat (experimental)
13 (BIOGEN_RECT_L11_UPDATED) = Rectangular hyperbola biogenic CO2 + QF-linked anthropogenic CO2 + L11_UPDATED heat (experimental)
14 (BIOGEN_RECT_L11_DETAILED) = Rectangular hyperbola biogenic CO2 + detailed anthropogenic CO2 + L11 heat (experimental)
15 (BIOGEN_RECT_J11_DETAILED) = Rectangular hyperbola biogenic CO2 + detailed anthropogenic CO2 + J11 heat (experimental)
16 (BIOGEN_RECT_L11_UPDATED_DETAILED) = Rectangular hyperbola biogenic CO2 + detailed anthropogenic CO2 + L11_UPDATED heat (experimental)
21 (BIOGEN_BELLUCCO_LOCAL_L11) = Bellucco local biogenic CO2 + QF-linked anthropogenic CO2 + L11 heat (experimental)
22 (BIOGEN_BELLUCCO_LOCAL_J11) = Bellucco local biogenic CO2 + QF-linked anthropogenic CO2 + J11 heat (experimental)
23 (BIOGEN_BELLUCCO_LOCAL_L11_UPDATED) = Bellucco local biogenic CO2 + QF-linked anthropogenic CO2 + L11_UPDATED heat (experimental)
24 (BIOGEN_BELLUCCO_LOCAL_L11_DETAILED) = Bellucco local biogenic CO2 + detailed anthropogenic CO2 + L11 heat (experimental)
25 (BIOGEN_BELLUCCO_LOCAL_J11_DETAILED) = Bellucco local biogenic CO2 + detailed anthropogenic CO2 + J11 heat (experimental)
26 (BIOGEN_BELLUCCO_LOCAL_L11_UPDATED_DETAILED) = Bellucco local biogenic CO2 + detailed anthropogenic CO2 + L11_UPDATED heat (experimental)
31 (BIOGEN_BELLUCCO_GENERAL_L11) = Bellucco general biogenic CO2 + QF-linked anthropogenic CO2 + L11 heat (experimental)
32 (BIOGEN_BELLUCCO_GENERAL_J11) = Bellucco general biogenic CO2 + QF-linked anthropogenic CO2 + J11 heat (experimental)
33 (BIOGEN_BELLUCCO_GENERAL_L11_UPDATED) = Bellucco general biogenic CO2 + QF-linked anthropogenic CO2 + L11_UPDATED heat (experimental)
34 (BIOGEN_BELLUCCO_GENERAL_L11_DETAILED) = Bellucco general biogenic CO2 + detailed anthropogenic CO2 + L11 heat (experimental)
35 (BIOGEN_BELLUCCO_GENERAL_J11_DETAILED) = Bellucco general biogenic CO2 + detailed anthropogenic CO2 + J11 heat (experimental)
36 (BIOGEN_BELLUCCO_GENERAL_L11_UPDATED_DETAILED) = Bellucco general biogenic CO2 + detailed anthropogenic CO2 + L11_UPDATED heat (experimental)
41 (BIOGEN_CONDUCTANCE_L11) = Conductance-based biogenic CO2 + QF-linked anthropogenic CO2 + L11 heat (experimental)
42 (BIOGEN_CONDUCTANCE_J11) = Conductance-based biogenic CO2 + QF-linked anthropogenic CO2 + J11 heat (experimental)
43 (BIOGEN_CONDUCTANCE_L11_UPDATED) = Conductance-based biogenic CO2 + QF-linked anthropogenic CO2 + L11_UPDATED heat (experimental)
44 (BIOGEN_CONDUCTANCE_L11_DETAILED) = Conductance-based biogenic CO2 + detailed anthropogenic CO2 + L11 heat (experimental)
45 (BIOGEN_CONDUCTANCE_J11_DETAILED) = Conductance-based biogenic CO2 + detailed anthropogenic CO2 + J11 heat (experimental)
46 (BIOGEN_CONDUCTANCE_L11_UPDATED_DETAILED) = Conductance-based biogenic CO2 + detailed anthropogenic CO2 + L11_UPDATED heat (experimental)
Default:

2 (J11)

Method Interactions

Determines anthropogenic heat flux (QF) used by the energy balance and OHM QF-inclusion switch.

Provides to: ohm_inc_qf, energy_balance

storage_heat#

Method for calculating storage heat flux (ΔQS).

Options:
0 (OBSERVED) = Uses observed ΔQS values from forcing file
1 (OHM_WITHOUT_QF) = Objective Hysteresis Model using Q* only (use with OhmIncQf=0)
5 (EHC) = Explicit Heat Conduction model with separate roof/wall/ground temperatures
6 (DyOHM) = Dynamic Objective Hysteresis Model (Liu et al., 2025) with dynamic coefficients
7 (STEBBS) = use STEBBS storage heat flux for building, others use OHM
Default:

1 (OHM_WITHOUT_QF)

Method Interactions

EHC (5) requires SPARTACUS net radiation; STEBBS storage heat (7) requires STEBBS enabled; OHM-like paths use OhmIncQf.

Depends on: net_radiation, ohm_inc_qf, snow_use, stebbs Provides to: energy_balance

ohm_inc_qf#

Controls inclusion of anthropogenic heat flux in OHM storage heat calculations.

Options:
0 (EXCLUDE) = Use Q* only (required when StorageHeatMethod=1)
1 (INCLUDE) = Use Q*+QF (for other OHM-based storage heat methods)
Example:

0 (EXCLUDE)

Method Interactions

Controls whether QF from emissions is added to Q* in OHM-based storage heat calculations.

Depends on: emissions, storage_heat Provides to: storage_heat

roughness_length_momentum#

Method for calculating momentum roughness length (z0m).

Options:
1 (FIXED) = Fixed roughness length from site parameters
2 (VARIABLE) = Variable based on vegetation LAI using rule of thumb (Grimmond & Oke 1999)
3 (MACDONALD) = MacDonald et al. (1998) morphometric method based on building geometry
4 (LAMBDAP_DEPENDENT) = Varies with plan area fraction λp (Grimmond & Oke 1999)
Default:

2 (VARIABLE)

Method Interactions

Calculates momentum roughness length (z0m), which feeds heat roughness length and stability corrections.

Provides to: roughness_length_heat, stability

roughness_length_heat#

Method for calculating thermal roughness length (z0h).

Options:
1 (BRUTSAERT) = Brutsaert (1982) z0h = z0m/10 (see Grimmond & Oke 1986)
2 (KAWAI) = Kawai et al. (2009) formulation
3 (VOOGT_GRIMMOND) = Voogt and Grimmond (2000) formulation
4 (KANDA) = Kanda et al. (2007) formulation
5 (ADAPTIVE) = Adaptively using z0m based on pervious coverage: if fully pervious, use method 1
Default:

2 (KAWAI)

Method Interactions

Calculates heat roughness length (z0h) from z0m for stability corrections.

Depends on: roughness_length_momentum Provides to: stability

stability#

Atmospheric stability correction functions for momentum and heat fluxes.

Options:
3 (CAMPBELL_NORMAN) = Campbell & Norman (1998) formulations for both momentum and heat
Default:

3 (CAMPBELL_NORMAN)

Method Interactions

Provides stability correction functions used by roughness-length and roughness_sublayer calculations.

Provides to: roughness_length_momentum, roughness_length_heat, roughness_sublayer

soil_moisture_deficit#

Method for determining soil moisture deficit (SMD).

Options:
0 (MODELLED) = SMD calculated from water balance using soil parameters
1 (OBSERVED_VOLUMETRIC) = Uses observed volumetric soil moisture content (m³/m³) from forcing file
2 (OBSERVED_GRAVIMETRIC) = Uses observed gravimetric soil moisture content (kg/kg) from forcing file
Example:

0 (MODELLED)

water_use#

Method for determining external water use (irrigation).

Options:
0 (MODELLED) = Water use calculated based on soil moisture deficit and irrigation parameters
1 (OBSERVED) = Uses observed water use values from forcing file
Default:

0 (MODELLED)

laimethod#

Method for determining leaf area index (LAI).

Options:
0 (OBSERVED) = Uses observed LAI values from the forcing file (lai column)
1 (MODELLED) = LAI modelled internally from growing-degree-day (GDD) and senescence-degree-day (SDD) thresholds.
Example:

1 (MODELLED)

Method Interactions

Set to 0 (OBSERVED) to prescribe LAI from the lai column of the meteorological forcing.

roughness_sublayer#

Roughness Sublayer (RSL) method for calculating near-surface meteorological diagnostics (2m temperature, 2m humidity, 10m wind speed).

Options:
2 (VARIABLE) = Automatically selects between MOST and RST based on surface morphology (plan area index, frontal area index, and roughness element heights)
Default:

2 (VARIABLE)

Method Interactions

Determines how near-surface values (2m temp, 10m wind) are calculated from forcing data

Depends on: stability Provides to: roughness_sublayer_level

frontal_area_index#

Method for calculating frontal area index (FAI) - the ratio of frontal area to plan area.

Options:
1 (MODELLED) = Calculate FAI using simple scheme based on surface fractions and heights (see issue #192)
Example:

0 (OBSERVED)

roughness_sublayer_level#

Method for incorporating local environmental feedbacks on surface processes, particularly vegetation phenology and evapotranspiration responses to urban heat island effects.

Options:
0 (NONE) = No local climate adjustments
1 (BASIC) = Simple adjustments for urban temperature effects on leaf area index (LAI) and growing degree days
2 (DETAILED) = Comprehensive feedbacks including moisture stress, urban CO2 dome effects, and modified phenology cycles
Default:

0 (NONE)

Method Interactions

Uses near-surface values from roughness_sublayer to modify vegetation processes

Depends on: roughness_sublayer Provides to: surface_conductance

surface_conductance#

Stomatal conductance parameterisation method for vegetation surfaces.

Options:
1 (JARVI) = Original parameterisation (Järvi et al. 2011) based on environmental controls
2 (WARD) = Updated parameterisation (Ward et al. 2016) with improved temperature and VPD responses
Example:

2 (WARD)

Method Interactions

Stomatal conductance model influenced by roughness_sublayer_level adjustments

Depends on: roughness_sublayer_level

snow_use#

Controls snow process calculations (Järvi et al. 2014).

Options:
0 (DISABLED) = Snow processes not included
1 (ENABLED) = Snow accumulation, melt, and albedo effects included
Default:

0 (DISABLED)

Method Interactions

Controls snow processes that affect radiation dispatch, storage heat, and near-surface conductance adjustments.

Provides to: net_radiation, storage_heat, roughness_sublayer_level

stebbs#

STEBBS physics switches (gh#1456): master toggle (enabled + parameters), capacitance method, setpoint method, and the same-albedo / same-emissivity wall/roof switches.

Method Interactions

When storage_heat selects STEBBS (7), this block enables and parameterises the STEBBS contribution to storage heat.

Depends on: storage_heat Provides to: stebbs.capacitance

The stebbs parameter group is defined by the STEBBS Physics Methods structure.

ref#

The ref parameter group is defined by the Reference Info structure.