pySTAMPS

Python-first STA(MPS)-style runtime for staged InSAR/PS processing, verification, and deterministic audit checks.

Run staged pipelines, inspect dataset progress, and validate outputs against a reference dataset.

Install

From source:

git clone git@github.com:sirbastiano/pystamps.git
cd pystamps
uv sync
uv run pystamps describe-backends

Editable install:

python -m pip install -e .
python -m pip install -e "[dev]"

cargo is required only for editable/source installs that build the Rust extension. Wheels from PyPI may avoid local compilation.

Run by stage

Set a local dataset path and always work on a writeable copy:

export DATASET_SOURCE=/path/to/original_dataset
export DATASET_COPY=/path/to/dataset_copy
cp -a "$DATASET_SOURCE" "$DATASET_COPY"

First, check status and verify what can execute:

uv run pystamps status --dataset "$DATASET_COPY"

Run a single stage or stage range:

uv run pystamps run --dataset "$DATASET_COPY" --start-step 1 --end-step 1      # stage 1 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 2 --end-step 2      # stage 2 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 3 --end-step 3      # stage 3 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 4 --end-step 4      # stage 4 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 5 --end-step 5      # stage 5 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 6 --end-step 6      # stage 6 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 7 --end-step 7      # stage 7 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 8 --end-step 8      # stage 8 only
uv run pystamps run --dataset "$DATASET_COPY" --start-step 1 --end-step 8          # full pipeline

Use --dry-run to preview actions without writing:

uv run pystamps run --dataset "$DATASET_COPY" --start-step 1 --end-step 8 --dry-run

Verify a run

export RUN_COPY=/path/to/run_copy
export GOLDEN_DATASET=/path/to/golden_dataset
uv run pystamps verify --run "$RUN_COPY" --golden "$GOLDEN_DATASET"

Stage-backend profile (optional)

uv run pystamps describe-backends

Create native-kernels.yaml and pass it with --config:

cat > native-kernels.yaml <<'YAML'
runtime:
  backend: auto
  stage2_kernel_backend: native
  stage2_native_threads: 0
  kernel_backend_overrides:
    stage2_grid_accumulate: native
    stage2_histogram: native
    stage2_topofit: native
    stage2_topofit_row_invariant: native
    stage2_topofit_coh_row_invariant: native
    stage4_edge_stats: native
    stage7_scla: native
    stage8_edge_noise: native
  io_workers: 8
  cpu_workers: 0
  stage7_chunk_ps: 100000
  stage8_chunk_edges: 200000
YAML

uv run pystamps --config native-kernels.yaml run --dataset "$DATASET_COPY" --start-step 2 --end-step 8

Use python backends for reference behavior in debugging, and native for the compiled Rust/CPU path.

Benchmarking and audit checkpoints

make benchmark
make audit

make audit reads the manifest in pystamps/data/audited_workflow_manifest.json.

Notes

• Do not point docs or examples at a fixed repository dataset path.
• Always treat outputs in your run tree as authoritative; avoid running on your only source copy.
• Optional repo assets are kept for parity and offline reproducibility, not required for runtime usage.

Read the docs

• Pipeline and science guide
• Quick Start
• Getting Started
• Usage
• Configuration
• Architecture
• Verification
• API Reference
• Release workflow

Notebooks

• notebooks/start_here.ipynb
• notebooks/00_pystamps_beginner_walkthrough.ipynb