stilt.transport.hysplit.HysplitConfig

class stilt.transport.hysplit.HysplitConfig(*, n_hours: int = -24, hnf_plume: bool = True, veght: float = 0.5, seed: int | None = None, numpar: int = 200, exe_dir: pathlib.Path | None = None, data_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', 'zcfx']]=<factory>, capemin: float = -1.0, cmass: int = 0, conage: int = 48, cpack: int = 1, delt: float = 1.0, dxf: float = 1.0, dyf: float = 1.0, 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: float = 10800.0, 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, kpuff: int = 0, krand: Literal[0, 1, 2, 3, 4, 10, 11, 12, 13]=4, 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: float = 1.0, pinbc: str = '', pinpf: str = '', poutf: str = '', qcycle: float = 0.0, rhb: int = 80, rht: int = 60, splitf: float = 1.0, tkerd: float = 0.18, tkern: float = 0.18, tlfrac: float = 0.1, tout: int = 0, tratio: float = 0.75, tvmix: float = 1.0, vscale: float = 200.0, vscaleu: float = 200.0, vscales: float = -1.0, w_option: int = 0, wbbh: float = 0.0, wbwf: float = 0.0, wbwr: float = 0.0, wvert: bool = False, z_top: float = 25000.0, ziscale: float | list[float] = 1.0, 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) → None

HYSPLIT’s config: every setting that shapes the particles it makes.

In config.yaml they are flat, top-level keys when HYSPLIT is the project’s model, as it is by default, and a variant may override any of them. Most are HYSPLIT SETUP.CFG entries with HYSPLIT’s own names; see the HYSPLIT user guide for the full meaning of each. The wind-error group (siguverr, tluverr, zcoruverr, horcoruverr) perturbs the particles’ winds, and the mixed-layer group (sigzierr, tlzierr, horcorzierr) perturbs each particle’s footprint by a random mixed-layer height error. Each group is set in full or not at all.

Parameters

Parameter	Description	Default
n_hours	Length of each simulation, in hours. Negative runs backward in time.	-24
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. Needs the particle columns dens, tlgr, sigw, foot, mlht, and samt, and zsfc for a receptor above sea level.	True
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
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
numpar	Number of particles released per simulation. More particles give a less noisy footprint and take longer to run.	200
exe_dir	Directory holding a custom hycs_std build to run in place of the one bundled with PYSTILT, with a version file beside it. The version is recorded with each run, so runs of different builds are kept apart. A build that writes release-time (t = 0) rows to PARTICLE_STILT.DAT gives exact release heights for multipoint and slant receptors.	None
data_dir	Directory of HYSPLIT data tables (ASCDATA.CFG, LANDUSE.ASC, ROUGLEN.ASC, TERRAIN.ASC) to use in place of the bundled ones. A table it does not hold comes from the bundled set. The tables change the particles, so each table that differs from the bundled one is recorded with the run by its checksum.	None
varsiwant	Particle variables hycs_std writes to the trajectory output, by the lowercase four-letter names HYSPLIT reads. Each is a column of the particles under the same name, except indx, time, long, and lati. zcfx is the vertical displacement by convective flux along the trajectory, in m. The default is the set footprints need, plus pres for pressure weighting.	['time', 'indx', 'long', 'lati', 'zagl', 'foot', 'mlht', 'pres', 'dens', 'samt', 'sig...
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.0
dxf	Horizontal x-grid offset factor for ensemble runs.	1.0
dyf	Horizontal y-grid offset factor for ensemble runs.	1.0
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.0
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
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
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 gives every release location its full share: numpar for one location, n \* (numpar // n + 1) for n. A set value that stops a multipoint release before its last location fails the run.	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. Only at 0 does PYSTILT check where the particles of a run that stopped early ended, to tell met that ran out from particles that left the met’s domain.	0
p10f	Dust threshold velocity sensitivity factor.	1.0
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.0
rhb	Relative humidity that defines a cloud base, in percent.	80
rht	Relative humidity that defines a cloud top, in percent.	60
splitf	Factor for the automatic horizontal splitting size. A negative value turns the automatic sizing off.	1.0
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
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
vscale	Vertical Lagrangian timescale, in seconds.	200.0
vscaleu	Vertical Lagrangian timescale in an unstable boundary layer, in seconds.	200.0
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.0
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.0
wbwf	Fixed fall velocity, in m/s. Used by vertical motion options 9 and 10.	0.0
wbwr	Fixed rise velocity, in m/s. Used by vertical motion option 9.	0.0
wvert	Interpolate WRF fields vertically with the WRF scheme instead of HYSPLIT’s.	False
z_top	Top of HYSPLIT’s computational 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
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

Attributes

UNRECORDED

Fields left out of a run's recorded settings.

Methods

hourly_ziscale()	Return ziscale as one factor per hour: a single value repeated over the run, or the list as given.
maxpar_for(locations)	Return the MAXPAR HYSPLIT gets for a release from locations horizontal locations.
realizations(n)	Return n realizations of this config, realization k with seed + k.

Inherited

From TransportConfig: settings