stilt.simulation

Classes

Control(**data)	HYSPLIT control parameters.
Footprint(simulation_id, receptor, data, ...)	STILT footprint.
FootprintCollection(simulation)
Output(simulation_id, receptor, data)	Abstract base class for STILT model outputs.
Simulation(config)
Trajectory(simulation_id, receptor, data, ...)	STILT trajectory.

class stilt.simulation.Control(**data)

HYSPLIT control parameters.

receptor: Receptor

emisshrs: float

n_hours: int

w_option: int

z_top: float

met_files: list[Path]

class Config

arbitrary_types_allowed = True

to_file(path)

classmethod from_path(path)

Build Control object from HYSPLIT control file.

Returns:

Control object with parsed parameters.

Return type:

Control

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class stilt.simulation.Output(simulation_id, receptor, data)

Abstract base class for STILT model outputs.

__init__(simulation_id, receptor, data)

abstract property id: str

class stilt.simulation.Trajectory(simulation_id, receptor, data, n_hours, met_files, params)

STILT trajectory.

__init__(simulation_id, receptor, data, n_hours, met_files, params)

property id: str

Generate the ID for the trajectory.

property is_error: bool

Determine if the trajectory has errors based on the wind error flag.

classmethod calculate(simulation_dir, control, namelist, timeout=3600, rm_dat=True, file=None)

classmethod from_path(path)

static read_parquet(path, r_time, outdt=0, **kwargs)

Return type:

DataFrame

class stilt.simulation.Footprint(simulation_id, receptor, data, xmin, xmax, ymin, ymax, xres, yres, projection='+proj=longlat', smooth_factor=1.0, time_integrate=False)

STILT footprint.

__init__(simulation_id, receptor, data, xmin, xmax, ymin, ymax, xres, yres, projection='+proj=longlat', smooth_factor=1.0, time_integrate=False)

property resolution: str

property id: str

property time_range: tuple[datetime, datetime]

Get time range of footprint data.

Returns:

Time range of footprint data.

Return type:

tuple[pd.Timestamp, pd.Timestamp]

classmethod from_path(path, **kwargs)

Create Footprint object from netCDF file.

Parameters:

• path (str | Path) – Path to netCDF file.

• **kwargs (dict) – Additional keyword arguments for xr.open_dataset.

Returns:

Footprint object.

Return type:

Footprint

static get_res_from_file(file)

Extract resolution from the file name.

Parameters:

file (str | Path) – Path to the footprint netCDF file.

Returns:

resolution.

Return type:

str

classmethod calculate(particles, xmin, xmax, ymin, ymax, xres, yres, projection='+proj=longlat', smooth_factor=1.0, time_integrate=False, file=None)

Return type:

Self

static read_netcdf(file, parse_receptor=True, **kwargs)

Read netCDF file and return xarray Dataset.

Parameters:

• file (str | Path) – Path to netCDF file.

• parse_receptor (bool, optional) – Whether to parse receptor coordinates. Default is True.

• **kwargs (dict) – Additional keyword arguments for xr.open_dataset.

Returns:

Footprint data as an xarray Dataset.

Return type:

xr.Dataset

integrate_over_time(start=None, end=None)

Integrate footprint over time.

Parameters:

• start (datetime, optional) – Start time of integration. The default is None.

• end (datetime, optional) – End time of integration. The default is None.

Returns:

Time-integrated footprint

Return type:

xr.DataArray

class stilt.simulation.FootprintCollection(simulation)

__init__(simulation)

get(resolution)

Get footprint for a specific resolution.

Parameters:

resolution (str) – Resolution string (e.g., ‘1x1’).

Returns:

Footprint object if available, else None.

Return type:

Footprint | None

class stilt.simulation.Simulation(config)

PATHS = {'config': 'config.yaml', 'control': 'CONTROL', 'error': 'error.parquet', 'footprints': '*_foot.nc', 'log': 'stilt.log', 'params': 'CONC.CFG', 'receptors': 'receptors.csv', 'setup': 'SETUP.CFG', 'trajectory': 'trajec.parquet', 'winderr': 'WINDERR', 'zicontrol': 'ZICONTROL', 'zierr': 'ZIERR'}

FAILURE_PHRASES = {'Fortran runtime error': 'FORTRAN_RUNTIME_ERROR', 'Insufficient number of meteorological files found': 'MISSING_MET_FILES', 'PARTICLE_STILT.DAT does not contain any trajectory data': 'NO_TRAJECTORY_DATA', 'meteorological data time interval varies': 'VARYING_MET_INTERVAL'}

__init__(config)

property paths: dict[str, Path | dict[str, Path]]

classmethod from_path(path)

Load simulation from a directory containing config.yaml.

Parameters:

path (str | Path) – Path to the simulation directory.

Returns:

Instance of the simulation.

Return type:

Self

property is_backward: bool

Check if the simulation is backward in time.

property time_range: tuple[datetime, datetime]

Get time range of simulation.

Returns:

Time range of simulation.

Return type:

TimeRange

property status: str | None

Get the status of the simulation.

Returns:

Status of the simulation.

Return type:

str

property meteorology: Meteorology

property met_files: list[Path]

property control: Control

property setup: Namelist

Setup namelist.

write_xyerr(path)

Write the XY error parameters to a file.

Return type:

None

write_zierr(path)

Return type:

None

property trajectory: Trajectory | None

STILT particle trajectories.

property error: Trajectory | None

STILT particle error trajectories.

property footprints: FootprintCollection

Dictionary of STILT footprints.

Returns:

Collection of Footprint objects.

Return type:

FootprintCollection

property footprint: Footprint | None

Load the default footprint from the simulation directory.

The default footprint is the one with the highest resolution if multiple footprints exist, otherwise it is the only footprint.

Returns:

Footprint object.

Return type:

Footprint

property log: str

STILT log.

Returns:

STILT log contents.

Return type:

str

static identify_failure_reason(path)

Identify reason for simulation failure.

Parameters:

path (str | Path) – Path to the STILT simulation directory.

Returns:

Reason for simulation failure.

Return type:

str

static get_sim_id_from_path(path)

Extract simulation ID from the path.

Parameters:

path (str | Path) – Path within the STILT output directory.

Returns:

Simulation ID.

Return type:

str

static is_sim_path(path)

Check if the path is a valid STILT simulation directory.

Parameters:

path (str | Path) – Path to check.

Returns:

True if the path is a valid STILT simulation directory, False otherwise.

Return type:

bool