stilt.config.VariantConfig

class stilt.config.VariantConfig(*, grid: stilt.config.spatial.Grid | None = None, geometry: Optional[Annotated[stilt.config.geometry.FileGeometrySpec | stilt.config.geometry.H3GeometrySpec | stilt.config.geometry.WindowsGeometrySpec, FieldInfo(annotation=NoneType, required=True, discriminator='kind')]] = None, cells_per_target: Annotated[float, Gt(gt=0)] = 4.0, geometry_hash: str | None = None, smooth_factor: float = 1.0, time_integrate: bool = False, transforms: list[Any] = <factory>, 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, ziscale: float | list[float] | list[list[float]] = 1.0, n_hours: int = -24, numpar: int = 200, hnf_plume: bool = True, rm_dat: bool = True, timeout: int | None = None, exe_dir: pathlib.Path | None = None, 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>, name: str, group: str, met: str, realization: int | None = None, derived_from: str | None = None) → None

The full settings of one variant: its met, transport, and footprint.

Built by resolve_variants(). name is the name its simulations run under and group the name declared in config.yaml. They differ only for realizations: hrrr-err with realizations: 3 gives hrrr-err-0 to hrrr-err-2.

Parameters

Parameter	Description	Default
grid	Domain and resolution of the footprint. Leaving it unset with no geometry gives a run that produces trajectories only.	None
geometry	Polygons the footprint will be aggregated to (kind of file, h3, or windows). Used to derive grid when it is unset, and stored with the footprint.	None
cells_per_target	Grid cells across the smallest geometry cell when grid is derived.	4.0
geometry_hash	Hash of the built geometry (Mesh.hash), used to tell whether the geometry changed after a footprint was made. Filled in automatically when geometry is set.	None
smooth_factor	Factor on the width of the Gaussian smoothing kernel. 0 turns smoothing off.	1.0
time_integrate	Sum the footprint over time into a single layer instead of hourly layers.	False
transforms	Particle transforms applied in order before the footprint is computed. Each entry’s kind is a built-in name (averaging_kernel, pressure_weighting, first_order_lifetime) or the import path of your own class.	[]
siguverr	Standard deviation of the horizontal wind error, in m/s.	None
tluverr	Correlation timescale of the horizontal wind error, in minutes.	None
zcoruverr	Vertical correlation length of the horizontal wind error, in meters.	None
horcoruverr	Horizontal correlation length of the horizontal wind error, in km.	None
sigzierr	Standard deviation of the mixed-layer height error, in percent.	None
tlzierr	Correlation timescale of the mixed-layer height error, in minutes.	None
horcorzierr	Horizontal correlation length of the mixed-layer height error, in km.	None
capemin	Convection option. -1 turns convection off, -2 uses the Grell scheme, and a positive value mixes vertically when CAPE exceeds it, in J/kg.	-1.0
cmass	Compute grid concentrations (0) or grid mass (1).	0
conage	Particle age at which particles and puffs convert, in hours.	48
cpack	Packing of the binary concentration grid.	1
delt	Integration time step, in minutes. 0 lets HYSPLIT choose; a negative value sets the minimum step.	1
dxf	Horizontal x-grid offset factor for ensemble runs.	1
dyf	Horizontal y-grid offset factor for ensemble runs.	1
dzf	Vertical offset factor for ensemble runs (0.01 is about 250 m).	0.01
efile	Name of a time-varying emissions file. Blank uses none.	''
emisshrs	Duration of the particle release, in hours.	0.01
frhmax	Maximum horizontal puff-rounding parameter.	3.0
frhs	Horizontal puff-rounding fraction for merging.	1.0
frme	Mass-rounding fraction for enhanced merging.	0.1
frmr	Mass-removal fraction for 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
ichem	HYSPLIT chemistry and output mode. 8 is the STILT emulation mode.	8
idsp	Particle dispersion scheme: 1 for HYSPLIT, 2 for STILT.	2
initd	Initial distribution as particles, puffs, or a mix. 0 is 3D particles.	0
k10m	Use the 10 m winds and 2 m temperature as the lowest meteorology level (1) or skip them (0).	1
kagl	Write trajectory heights above ground (1) or above sea level (0).	1
kbls	Derive boundary-layer stability from surface fluxes (1) or from wind and temperature profiles (2).	1
kblt	Boundary-layer turbulence scheme: 1 Beljaars, 2 Kantha-Clayson, 3 TKE, 4 measured variances, 5 Hanna.	5
kdef	Horizontal turbulence from vertical mixing (0) or wind deformation (1).	0
khinp	Age, in hours, given to particles read from pinpf. 0 keeps their own age.	0
khmax	Maximum particle or trajectory age, in hours.	9999
kmix0	Minimum mixed-layer depth, in meters.	150
kmixd	Mixed-layer depth source: 0 from the meteorology, 1 from the temperature profile, 2 from the TKE profile, 3 from a modified Richardson number.	3
kmsl	Read release heights as above ground (0) or above sea level (1). Unset takes it from each receptor’s altitude_ref, and a value that disagrees with a receptor is an error.	None
kpuff	Horizontal puff growth: linear (0) or empirical (1).	0
krand	How HYSPLIT draws the random numbers for turbulence. 0 picks 2 when numpar is 5000 or less and 1 otherwise. 1 uses a precomputed table. 2 draws them during the run and is the only mode that uses seed. 3 uses no random numbers (a diagnostic mode). 4 draws them during the run from a clock-based seed, so every run differs; there are about 5000 possible seeds. 10 to 13 are modes 0 to 3 with a random initial seed. HYSPLIT does not check this value and other values silently break the turbulence, so PYSTILT rejects them.	4
seed	Random seed for a reproducible run. Different seeds give different runs. Requires krand: 2. The bundled hycs_std ignores the seed under krand 4 and 10 to 13, and under 1 uses it only for the initial turbulent velocity. PYSTILT writes it to SETUP.CFG as -(abs(seed) + 1), because HYSPLIT reseeds its generator only from a negative value and gives every SEED of 0 or more the same stream. Realization k of a variant runs with seed + k, so realization 0 shares the unperturbed run’s seed, as STILT-R’s error run does.	None
krnd	Enhanced-merging interval, in hours.	6
kspl	Standard puff-splitting interval, in hours.	1
kwet	Precipitation from the meteorology (1) or from an external ARL file (2).	1
kzmix	Vertical mixing adjustment: 0 none, 1 a single PBL-average value, 2 scale by tvmix.	0
maxdim	Maximum number of pollutant species carried on one particle.	1
maxpar	Maximum number of particles in a simulation. Unset uses numpar.	None
mgmin	Minimum meteorological subgrid size, in grid points.	10
mhrs	Trajectory restart duration limit, in hours.	9999
nbptyp	Number of particle-size bins per pollutant type.	1
ncycl	Cycle time of the particle dump file, in hours.	0
ndump	Interval between particle dumps, in hours. 0 writes none.	0
ninit	Particle initialization from pinpf: 0 none, 1 once at the start, 2 add every hour, 3 replace every hour.	1
nstr	Trajectory restart interval, in hours.	0
nturb	Turbulence on (0) or off (1).	0
nver	Trajectory vertical split number.	0
outdt	Interval between particle outputs in PARTICLE_STILT.DAT, in minutes. 0 writes every time step and a negative value writes none.	0
p10f	Dust threshold velocity sensitivity factor.	1
pinbc	Particle input file for time-varying boundary conditions.	''
pinpf	Particle input file for initialization or boundary-condition runs.	''
poutf	Particle output file name.	''
qcycle	Emission cycling period, in hours. 0 turns cycling off.	0
rhb	Relative humidity that defines a cloud base, in percent.	80.0
rht	Relative humidity that defines a cloud top, in percent.	60.0
splitf	Factor for the automatic horizontal splitting size. A negative value turns the automatic sizing off.	1
tkerd	Ratio w’²/(u’²+v’²) of TKE components when unstable.	0.18
tkern	Ratio w’²/(u’²+v’²) of TKE components when stable.	0.18
tlfrac	Fraction of the vertical Lagrangian timescale used as the time step of the STILT dispersion scheme.	0.1
tout	Trajectory output interval, in minutes.	0.0
tratio	Advection stability ratio (fraction of a grid cell per time step).	0.75
tvmix	Vertical mixing scale factor, used by the kzmix scaling modes.	1.0
veght	Height below which a particle’s time counts toward the footprint. A value of 1 or less is a fraction of the mixed-layer height; a larger value is meters above ground.	0.5
vscale	Vertical Lagrangian timescale, in seconds.	200
vscaleu	Vertical Lagrangian timescale in an unstable boundary layer, in seconds.	200
vscales	Vertical Lagrangian timescale in a stable boundary layer, in seconds. -1 uses the Hanna timescale, which varies with the turbulence, and then vscaleu is not used.	-1
w_option	Vertical motion method: 0 the meteorology’s vertical velocity, 1 isobaric, 2 isentropic, 3 constant density, 4 constant sigma.	0
wbbh	Height at which the fixed vertical velocity switches from rise to fall, in meters. Used by vertical motion option 9.	0
wbwf	Fixed fall velocity, in m/s. Used by vertical motion options 9 and 10.	0
wbwr	Fixed rise velocity, in m/s. Used by vertical motion option 9.	0
wvert	Interpolate WRF fields vertically with the WRF scheme instead of HYSPLIT’s.	False
z_top	Top of the model domain, in meters above ground.	25000.0
ziscale	Factor applied to the mixed-layer height, written to HYSPLIT’s ZICONTROL file. 1.0 leaves it unscaled. A single value applies to every hour of the run. A list gives one factor per hour from the release (at most 150), and later hours are unscaled. HYSPLIT applies kmix0 after the factor, so the mixed layer never drops below kmix0. A negative value uses the meteorology’s own PBL height where the met files carry one.	1.0
n_hours	Length of each simulation, in hours. Negative runs backward in time.	-24
numpar	Number of particles released per simulation. More particles give a less noisy footprint and take longer to run.	200
hnf_plume	Apply a vertical Gaussian plume model to particles in the hyper near-field. This shrinks their effective dilution depth and raises the influence of fluxes close to the receptor. Requires varsiwant to include dens, tlgr, sigw, foot, mlht, and samt.	True
rm_dat	Delete HYSPLIT’s particle files (PARTICLE_STILT.DAT and PARTICLE.DAT) once they have been read, to save disk space.	True
timeout	Time limit for one hycs_std run, in seconds. A run that exceeds it is stopped and recorded as a failed simulation, and the worker moves on to the next one. Unset waits indefinitely, so a hung HYSPLIT process can hold a batch worker until its job ends.	None
exe_dir	Directory holding a custom hycs_std build to run in place of the one bundled with PYSTILT. It is saved with each trajectory’s parameters. A build that writes release-time (t = 0) rows to PARTICLE_STILT.DAT gives exact release heights for multipoint and slant receptors.	None
varsiwant	Particle variables hycs_std writes to the trajectory output. The default is the set footprints need, plus pres for pressure weighting.	['time', 'indx', 'long', 'lati', 'zagl', 'foot', 'mlht', 'pres', 'dens', 'samt', 'sig...
name	Variant name its simulations run under, also their directory name.	Required
group	Variant name as declared in config.yaml.	Required
met	Name of the meteorology this variant runs with.	Required
realization	Realization number within group. None for a single run.	None
derived_from	Variant whose trajectories this one computes its footprint from, instead of running HYSPLIT (from: in config.yaml). Only footprint fields may differ from it.	None

Methods

realization_seed(realization)	Return the seed for one realization of a variant.
record()	Return this variant as stored in the project's record.
setup_entries()	Return the SETUP.CFG namelist entries, leaving out unset fields.
setup_seed(seed)	Return the SEED value written to SETUP.CFG for a user seed.
stilt_params()	Return the transport parameters alone, as stored with a trajectory.