On Your Computer

Running locally is the default. With no execution section in config.yaml, simulations run one after another on your machine. Use it for notebooks, scripts, and anything that finishes in a reasonable time on one computer.

Use several CPU cores

To run several receptors at once, set n_workers:

execution:
  backend: local
  n_workers: 4

Or set it for a single run from the command line:

stilt run ./my_project --n-workers 4

Each worker is a separate process. It runs one receptor at a time, with all of that receptor’s variants. Set n_workers no higher than the number of CPU cores you have.

From Python or a notebook

import stilt

model = stilt.Model(
    project="./my_project",
    receptors=receptors,
    mets={"hrrr": {"directory": "/data/hrrr", "file_format": "%Y%m%d_%H", "file_tres": "6h"}},
    grid={"xmin": -114, "xmax": -111, "ymin": 39, "ymax": 42, "xres": 0.01, "yres": 0.01},
    execution={"backend": "local", "n_workers": 4},
)

model.run()

model.run() does the same as stilt run. It saves config.yaml and receptors.csv to the project folder, runs every unfinished simulation, and returns when they are done.

Then check on the results:

model.status()                          # one row per simulation, with a "complete" column
footprints = model.simulations.footprint.load()   # {simulation id: Footprint}

Python or the command line?

Use Python when you’re exploring in a notebook, generating receptors in code, or want to analyze results right after the run.

Use the command line when the project is already set up on disk, or when running from a batch script.

Both read and write the same project folder, so you can mix them. For example, run with stilt run and then analyze in a notebook with stilt.Model(project=...).

Save now, run later

model.register() saves the settings and receptors to the project folder without running anything. It returns the receptor IDs:

receptor_ids = model.register()

Any machine that can see the folder can then run the project with stilt run. From Python, stilt.execution.run_receptors() runs every variant of the receptors you give it.