stilt

PYSTILT

A python implementation of the STILT model.

class stilt.ModelConfig(**data)

receptors: list[Receptor]

classmethod from_path(path)

Load STILT configuration from a YAML file.

Return type:

Self

to_file()

build_simulation_configs()

Build a list of SimulationConfig objects, one for each receptor.

Return type:

list[SimulationConfig]

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

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

class stilt.Meteorology(path, format, tres)

Meteorological data files for STILT simulations.

__init__(path, format, tres)

property available_files: list[Path]

get_files(r_time, n_hours)

Return type:

list[Path]

calc_subgrids(files, out_dir, exe_dir, projection, xmin, xmax, ymin, ymax, levels=None, buffer=0.1)

Return type:

Self

class stilt.Model(project, **kwargs)

__init__(project, **kwargs)

static initialize(project, **kwargs)

Return type:

ModelConfig

property simulations: SimulationCollection | None

Load all simulations from the output working directory.

run()

stilt.stilt_init(project, branch=None, repo=None)

Initialize STILT project

Python implementation of Rscript -e “uataq::stilt_init(‘project’)”

Parameters:

• project (str) – Name/path of STILT project. If path is not provided, project will be created in current working directory.

• branch (str, optional) – Branch of STILT project repo. The default is jmineau.

• repo (str, optional) – URL of STILT project repo. The default is jmineau/stilt.

class stilt.Receptor(time, location)

__init__(time, location)

A receptor that wraps a geometric object (Point, MultiPoint, etc.) and associates it with a timestamp.

Parameters:

• time (datetime) – The timestamp associated with the receptor.

• location (Location) – A location object representing the receptor’s spatial position.

property geometry: Geometry

Receptor geometry.

property timestr: str

Get the time as an ISO formatted string.

Returns:

Time in ‘YYYYMMDDHHMM’ format.

Return type:

str

property id: str

abstract property is_vertical: bool

static build(time, longitude, latitude, height)

Build a receptor object from time, latitude, longitude, and height.

Parameters:

• time (datetime) – Timestamp of the receptor.

• longitude (float | list[float]) – Longitude(s) of the receptor.

• latitude (float | list[float]) – Latitude(s) of the receptor.

• height (float | list[float]) – Height(s) above ground level of the receptor.

Returns:

The constructed receptor object.

Return type:

Receptor

static load_receptors_from_csv(path)

Load receptors from a CSV file.

Return type:

list[Receptor]

class stilt.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

class stilt.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.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

Modules

config
meteorology
model	Stochastic Time-Inverted Lagrangian Transport (STILT) Model.
receptors
simulation