stilt.config.ModelConfig#

class stilt.config.ModelConfig(*, siguverr: float | None = None, tluverr: float | None = None, zcoruverr: float | None = None, horcoruverr: float | None = None, sigzierr: float | None = None, tlzierr: float | None = None, horcorzierr: float | None = None, capemin: float = -1.0, cmass: int = 0, conage: int = 48, cpack: int = 1, delt: int = 1, dxf: int = 1, dyf: int = 1, dzf: float = 0.01, efile: str = '', emisshrs: float = 0.01, frhmax: float = 3.0, frhs: float = 1.0, frme: float = 0.1, frmr: float = 0.0, frts: float = 0.1, frvs: float = 0.01, hscale: int = 10800, ichem: int = 8, idsp: int = 2, initd: int = 0, k10m: int = 1, kagl: int = 1, kbls: int = 1, kblt: int = 5, kdef: int = 0, khinp: int = 0, khmax: int = 9999, kmix0: int = 150, kmixd: int = 3, kmsl: Optional[Literal[0, 1]] = None, kpuff: int = 0, krand: int = 4, seed: int | None = None, krnd: int = 6, kspl: int = 1, kwet: int = 1, kzmix: int = 0, maxdim: int = 1, maxpar: int | None = None, mgmin: int = 10, mhrs: int = 9999, nbptyp: int = 1, ncycl: int = 0, ndump: int = 0, ninit: int = 1, nstr: int = 0, nturb: int = 0, nver: int = 0, outdt: int = 0, p10f: int = 1, pinbc: str = '', pinpf: str = '', poutf: str = '', qcycle: int = 0, rhb: float = 80.0, rht: float = 60.0, splitf: int = 1, tkerd: float = 0.18, tkern: float = 0.18, tlfrac: float = 0.1, tout: float = 0.0, tratio: float = 0.75, tvmix: float = 1.0, veght: float = 0.5, vscale: int = 200, vscaleu: int = 200, vscales: int = -1, w_option: int = 0, wbbh: int = 0, wbwf: int = 0, wbwr: int = 0, wvert: bool = False, z_top: float = 25000.0, zicontroltf: int = 0, ziscale: float | list[float] | list[list[float]] = 1.0, n_hours: int = -24, numpar: int = 200, hnf_plume: bool = True, rm_dat: bool = True, varsiwant: list[typing.Literal['time', 'indx', 'long', 'lati', 'zagl', 'sigw', 'tlgr', 'zsfc', 'icdx', 'temp', 'samt', 'foot', 'shtf', 'tcld', 'dmas', 'dens', 'rhfr', 'sphu', 'lcld', 'zloc', 'dswf', 'wout', 'mlht', 'rain', 'crai', 'pres', 'whtf', 'temz', 'zfx1']] = <factory>, footprints: dict[str, stilt.config.footprint.FootprintConfig] = <factory>, grids: dict[str, stilt.config.spatial.Grid] = <factory>, mets: dict[str, stilt.config.meteorology.MetConfig] = <factory>, execution: dict[str, typing.Any] = <factory>, skip_existing: bool = True) → None[source]#

Project-level config: STILT params plus met and footprint definitions.

Parameters#

Parameter

Description

Default

siguverr

Standard deviation of horizontal wind error [m/s]

None

tluverr

Standard deviation of horiztontal wind error timescale [min]

None

zcoruverr

Vertical correlation length scale of horizontal wind error [m]

None

horcoruverr

Horizontal correlation length scale of horizontal wind error [km]

None

sigzierr

Standard deviation of mixed-layer height errors [%]

None

tlzierr

Standard deviation of mixed layer height timescale [min]

None

horcorzierr

Horizontal correlation length scale of mixed-layer height errors [km]

None

capemin

Minimum CAPE (J/kg) for convective mixing; -1 disables CAPE-triggered enhanced mixing.

-1.0

cmass

Compute grid output in concentration units (0) or mass units (1).

0

conage

Particle age in hours for puff/particle conversion handling.

48

cpack

Binary concentration-grid packing mode.

1

delt

Integration timestep in minutes; 0 lets HYSPLIT choose automatically.

1

dxf

Horizontal X-grid adjustment factor for ensemble runs.

1

dyf

Horizontal Y-grid adjustment factor for ensemble runs.

1

dzf

Vertical grid adjustment factor for ensemble runs.

0.01

efile

Temporal emissions file name; blank disables file-driven emissions.

''

emisshrs

Duration of emissions in fractional hours.

0.01

frhmax

Maximum horizontal puff-rounding value.

3.0

frhs

Standard horizontal puff-rounding fraction for merging.

1.0

frme

Mass-rounding fraction used by enhanced merging.

0.1

frmr

Mass-removal fraction used by enhanced merging.

0.0

frts

Temporal puff-rounding fraction.

0.1

frvs

Vertical puff-rounding fraction.

0.01

hscale

Horizontal Lagrangian timescale in seconds.

10800

initd

Initial particle distribution mode.

0

k10m

Use 10 m winds and 2 m temperatures as the lowest meteorology level when available.

1

kbls

PBL stability method: fluxes (1) or wind/temperature profiles (2).

1

kblt

PBL turbulence scheme; PYSTILT defaults to Hanna (5).

5

kdef

Horizontal turbulence from vertical mixing (0) or deformation (1).

0

khinp

Maximum particle age read from PARINIT during continuous restart runs.

0

khmax

Maximum particle or trajectory age in hours.

9999

kmix0

Minimum mixing depth in meters.

150

kmixd

Mixing-depth method: input, temperature, TKE, or modified Richardson.

3

kmsl

Interpret start altitudes as AGL (0) or MSL (1). When unset, PYSTILT derives this from each receptor’s altitude_ref.

None

kpuff

Horizontal puff-growth mode: linear (0) or empirical (1).

0

krand

Random-number mode for turbulence, repeatability, and diagnostic no-mixing runs.

4

seed

Optional HYSPLIT random-number seed written to SETUP.CFG. Use with krand values that preserve a fixed initial seed; krand=4 and 10-13 still randomize the initial seed.

None

krnd

Enhanced-merging interval in hours.

6

kspl

Standard particle-splitting interval in hours.

1

kwet

Use meteorological precipitation, or an external ARL rain file when set to 2.

1

kzmix

Vertical mixing adjustment mode; 0 none, 1 PBL-average, 2 TVMIX scaling.

0

maxdim

Maximum pollutant species carried on one particle, mainly for chemistry runs.

1

maxpar

Maximum number of particles allowed in a simulation.

None

mgmin

Minimum meteorological subgrid size.

10

mhrs

Trajectory restart duration limit in hours.

9999

nbptyp

Number of particle-size bins created around each pollutant size entry.

1

ninit

Particle initialization mode for restart, add, or replace workflows.

1

nstr

Trajectory restart interval in hours.

0

nturb

Turbulence mode selector; 0 is on/default, 1 disables turbulence.

0

nver

Trajectory vertical split number.

0

outdt

Minutes between STILT endpoint writes to PARTICLE.DAT; negative disables output.

0

p10f

Dust threshold-velocity sensitivity factor.

1

qcycle

Emission cycling period in hours; 0 disables cycling.

0

rhb

Relative-humidity threshold used to define cloud base.

80.0

rht

Relative-humidity threshold below which cloud top is considered to end.

60.0

splitf

Automatic horizontal split-size factor; negative disables auto sizing.

1

tkerd

Unstable TKE ratio w’²/(u’²+v’²).

0.18

tkern

Stable TKE ratio w’²/(u’²+v’²).

0.18

tlfrac

Fraction of the vertical Lagrangian timescale used to set the STILT timestep.

0.1

tout

Trajectory output interval in minutes.

0.0

tratio

Advection stability ratio.

0.75

tvmix

Scale factor applied to vertical mixing coefficients for selected KZMIX modes.

1.0

veght

Height threshold used to accumulate STILT footprint residence time.

0.5

vscale

Vertical Lagrangian timescale in seconds for neutral PBL conditions.

200

vscaleu

Vertical Lagrangian timescale in seconds for unstable PBL conditions.

200

vscales

Vertical Lagrangian timescale in seconds for stable PBL conditions.

-1

w_option

Vertical motion method; 0 met vertical velocity, 1 isob, 2 isen, 3 dens, 4 sigma.

0

wbbh

Height where fixed vertical motion switches from rise to fall.

0

wbwf

Fixed fall velocity used by vertical-motion options 9 or 10.

0

wbwr

Fixed rise velocity used by vertical-motion option 9.

0

wvert

Use the WRF vertical interpolation scheme for vertical velocity when true.

False

z_top

Top of model domain, in meters above ground level; defaults to 25000.0

25000.0

zicontroltf

Enable domain-wide PBL scaling from a ZICONTROL file.

0

ziscale

Manually scale the mixed-layer height. Scalars expand across the run; lists define shared hourly factors.

1.0

n_hours

Number of hours to run each simulation; negative indicates backward in time.

-24

numpar

Number of particles released per simulation. Higher values reduce stochastic noise in footprints at the cost of runtime and memory.

200

hnf_plume

If true, apply a vertical gaussian plume model to rescale the effective dilution depth for particles in the hyper near-field. This acts to scale up the influence of hyper-local fluxes on the receptor. If enabled, requires varsiwant to include a minimum of dens, tlgr, sigw, foot, mlht, samt. Default is enabled.

True

rm_dat

Remove HYSPLIT binary output files (*.dat) after parsing to save disk space.

True

varsiwant

hycs_std particle variables kept in trajectory output. Defaults to the minimum required variables including ‘time’, ‘indx’, ‘long’, ‘lati’, ‘zagl’, ‘foot’, ‘mlht’, ‘dens’, ‘samt’, ‘sigw’, ‘tlgr’.

['time', 'indx', 'long', 'lati', 'zagl', 'foot', 'mlht', 'pres', 'dens', 'samt', 'sig...

footprints

Named footprint products available for this model configuration.

{}

grids

Named grids referenced by footprint definitions.

{}

mets

Named meteorology streams available to the model.

{}

execution

Execution backend settings such as local, Slurm, or Kubernetes options.

{}

skip_existing

Skip simulations that already have output. Set False to force re-run all simulations. Can be overridden at call time via model.run(skip_existing=…).

True

Methods#

basic(*, mets[, n_hours, numpar, ...])

Build a science-facing config with the most common controls.

from_yaml(path)

Load a model config from a YAML file.

to_stilt_params()

Project this model config onto the pure STILT run-parameter surface.

to_yaml(path)

Write the model config to a YAML file.