stilt.Model

class stilt.Model(project: str | pathlib.Path | None = None, receptors: stilt.receptors.Receptor | collections.abc.Iterable | str | pathlib.Path | None = None, config: stilt.config.model.ModelConfig | None = None, output_dir: str | pathlib.Path | None = None, compute_root: str | pathlib.Path | None = None, runtime: stilt.config.runtime.RuntimeSettings | None = None, **kwargs)

Science-facing STILT project interface.

Model is the primary Python entry point for configuring a STILT project, running one-off simulations, and loading simulation results. It also owns the output project index used by batch, HPC, and cloud execution.

Pull-mode workers and streaming consumers operate against the model’s output index directly when the configured index supports claims. Claim-worker control is exposed primarily through the CLI and stilt.execution.pull_simulations() for advanced Python use.

Parameters

projectstr or Path or None, optional

Local project root or cloud URI used to identify the model.

receptorsReceptor or iterable or str or Path or None, optional

In-memory receptors or a path to a receptor CSV.

configModelConfig or None, optional

In-memory project config. When omitted, config is loaded lazily from storage.

output_dirstr or Path or None, optional

Output root. Defaults to project.

compute_rootstr or Path or None, optional

Local parent directory where worker simulation directories are created.

runtimeRuntimeSettings or None, optional

Runtime-only deployment settings such as cache roots and DB URLs.

**kwargs

Forwarded to ModelConfig when config is not provided. Any valid ModelConfig field name is accepted (e.g. n_hours=-48, numpar=500). Mutually exclusive with config — passing both raises TypeError.

Methods

register_pending([receptors, scene_id])	Persist model inputs and register one batch of pending work.
run([executor, skip_existing, rebuild, wait])	Register pending work and start workers to drain it.
scene_counts()	Return grouped aggregate counts for each registered scene.
status([scene_id])	Return cheap aggregate counts for the current project registry.

Attributes

config	Project ModelConfig, loaded from config.yaml if not provided at construction.
footprints	Footprint accessor namespace for named footprint outputs.
index	Output simulation registry for this model.
mets	Named met streams, resolved from config.
plot	Plotting namespace for this model (e.g. model.plot.availability()).
receptors	Sequence-like receptor accessor for this project.
simulations	Lazy simulation collection for registered simulations.
trajectories	Trajectory accessor for querying and loading simulation outputs.