Project Layout And Output State#

PYSTILT separates three concepts that are often mixed together in older workflows:

project

The science-facing project root. This is where config.yaml and receptors.csv normally live.

output_dir

The output root. This is where the simulation index and simulation artifacts live. By default it is the same as project.

compute_root

A compute-local parent directory for worker scratch directories. This is especially useful when outputs live on object storage or a slower shared filesystem.

Default local layout#

When project and output roots are the same, PYSTILT uses:

project/
  config.yaml
  receptors.csv
  simulations/
    index.sqlite
    by-id/
      <sim_id>/

Separate input and output roots#

You can keep human-edited inputs in one place and output results in another:

model = stilt.Model(
    project="./inputs/wbb_july_case",
    output_dir="gs://my-bucket/wbb_july_case",
    compute_root="/scratch/$USER/pystilt",
)

This is the right model when:

  • project inputs are version-controlled locally

  • outputs belong in object storage

  • workers need fast local scratch space for staging meteorology and HYSPLIT files

How configuration is loaded#

Model.config is loaded lazily:

  • from the local project root when config.yaml is present

  • otherwise from output storage if the project has already been bootstrapped

The same rule applies to receptors. Model.register_pending() is the output boundary that publishes config and receptor inputs before simulations are registered in the index.

Simulation identity#

Each simulation ID has the form:

{met}_{YYYYMMDDHHMM}_{location_id}

For point receptors, location_id is a coordinate triple. For column receptors it ends in _X. For multipoint receptors, PYSTILT uses a stable hash-based location ID.

Status model#

The output index tracks aggregate counts and per-simulation output presence. In the current alpha, the useful mental model is:

  • trajectories move through pending, running, complete, or failed

  • footprints are tracked per footprint name

  • complete-empty is a successful terminal footprint outcome

  • skip_existing=True avoids rerunning complete work

Use stilt status or Model.status() to inspect project-level counts.