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.

Completion is read from the outputs by key; the registry is the manifest. A Postgres work queue (model.queue) is used only for pull/serve workers, exposed through the CLI and stilt.execution.pull_simulations().

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 completion counts grouped by registered scene.
status([scene_id])	Return completion counts (total/completed/pending) from the registry.

Attributes

config	Project ModelConfig, loaded from config.yaml if not provided at construction.
footprints	Footprint accessor namespace for named footprint outputs.
manifest	Registry of registered simulations (.stilt/manifest.parquet).
mets	Named met streams, resolved from config.
plot	Plotting namespace for this model (e.g. model.plot.availability()).
queue	Postgres work queue, present only when a DB URL is configured.
receptors	Sequence-like receptor accessor for this project.
simulations	Lazy simulation collection for registered simulations.
trajectories	Trajectory accessor for querying and loading simulation outputs.