Stage guide

Every stage has a scope, an artifact contract, and a code entrypoint.

This page connects the user-facing stage numbers to the implementation. Use it when you need to know what a stage reads, what it writes, why it may skip, and which Python or Rust function owns the work.

Read stages Read code paths Run native CLI

Stage Map

Stages 1 through 5 run inside each patch. Stage 5 also creates merged dataset products. Stages 6 through 8 run once at the dataset root.

Jump To A Stage

Stage 1Initial load Stage 2Gamma Stage 3Select PS Stage 4Weed Stage 5Promote + merge Stage 6Unwrap Stage 7SCLA Stage 8Filter SCN

How The Code Runs A Stage Range

1. CLI Builds Context

pystamps.cli parses run, loads config, and creates a PipelineContext with dataset root, start/end steps, and dry-run mode.

2. Dataset Is Discovered

pystamps.io.dataset.discover_dataset() resolves the root, reads patch.list when present, and orders PATCH_* folders.

3. Scheduler Selects Stages

pystamps.pipeline.stages.run_pipeline() walks the selected StageDef records and sends patch or merged work to the hybrid executor.

4. Artifacts Decide Skips

expected_stage_artifact() and merged bundles decide whether a stage is planned, completed, or skipped_existing.

from pathlib import Path

from pystamps.config import RunConfig
from pystamps.pipeline.stages import run_pipeline
from pystamps.pipeline.types import PipelineContext

context = PipelineContext(
    dataset_root=Path("/path/to/run_dataset"),
    run_config=RunConfig(),
    start_step=1,
    end_step=8,
    dry_run=True,
)
report = run_pipeline(context)

Implementation Files To Read First

File	Why It Matters
`pystamps/pipeline/stages.py`	Stage definitions, artifact skips, patch/merged dispatch, strict reference replay, and result timing.
`pystamps/pipeline/ported.py`	Python stage entrypoints and scientific helpers for stages 1 through 8.
`pystamps/io/dataset.py`	Dataset discovery plus expected artifact mapping used by status and scheduling.
`pystamps/kernels/accelerated.py`	Backend dispatch for hot kernels in stages 2, 4, 7, and 8.
`crates/pystamps-core/src/bin/pystamps-native.rs`	Standalone Rust CLI argument parsing and native stage dispatch.
`crates/pystamps-stages/src/lib.rs`	Native readiness inventory and parity certification details for each stage scope.

1 Initial Load

Scope: patchProgress: ps1.matNative: parity certified

Stage 1 turns patch inputs and metadata into consistent early MAT artifacts. Later stages rely on these files instead of re-reading raw source folders.

Python entrypoint: stage1_load_initial(). Rust entrypoint: native_stage1::run_stage1_native.

Main outputs: ps1.mat, ph1.mat, bp1.mat, da1.mat, hgt1.mat, la1.mat, psver.mat.

2 Estimate Gamma

Scope: patchProgress: pm1.matNative: parity certified

Stage 2 estimates phase-model and coherence-like terms for each candidate. This is the hot patch stage and owns several optimized kernels.

Python entrypoint: stage2_estimate_gamma(). Rust entrypoint: native_stage2::run_stage2_native.

Optimized kernels: stage2_grid_accumulate, stage2_histogram, stage2_topofit, stage2_topofit_row_invariant, stage2_topofit_coh_row_invariant.

3 Select PS Pixels

Scope: patchProgress: select1.matNative: parity certified

Stage 3 chooses persistent-scatterer candidates from the stage-2 quality terms. It writes the selection mask and related metadata used by weeding.

Python entrypoint: stage3_select_ps(). Rust entrypoint: native_stage3::run_stage3_native.

Main output: select1.mat.

4 Weed Adjacent Pixels

Scope: patchProgress: weed1.matNative: parity certified

Stage 4 removes weak, redundant, or geometry-conflicting candidates before patch products are promoted. The edge-stat kernel has Python and native implementations.

Python entrypoint: stage4_weed_ps(). Rust entrypoint: native_stage4::run_stage4_native.

Optimized kernel: stage4_edge_stats. Main output: weed1.mat.

5 Correct Phase And Merge

Scope: patch + mergedProgress: ph2.mat / ifgstd2.matNative: parity certified

Stage 5 is the transition point. It promotes each patch to corrected stage-2 products, then merges patch outputs into root-level dataset artifacts.

Python entrypoints: stage5_correct_and_promote() and stage5_merge_and_ifgstd(). Rust entrypoints: native_stage5::run_stage5_patch_native and native_stage5::run_stage5_merge_native.

Main outputs: patch ps2.mat, ph2.mat, pm2.mat, bp2.mat, plus merged ifgstd2.mat.

6 Unwrap Phase

Scope: mergedProgress: phuw2.matNative: parity certified

Stage 6 unwraps merged phase products and writes the graph/grid support files used by later correction and filtering stages.

Python entrypoint: stage6_unwrap(). Rust entrypoint: native_stage6::run_stage6_native.

Main outputs: phuw2.mat, uw_phaseuw.mat, uw_grid.mat, uw_interp.mat.

7 Calculate SCLA

Scope: mergedProgress: scla2.matNative: parity certified

Stage 7 estimates spatially correlated look-angle error products and smoothed correction artifacts from unwrapped merged phase.

Python entrypoint: stage7_calc_scla(). Rust entrypoint: native_stage7::run_stage7_native.

Optimized kernel: stage7_scla. Main outputs: scla2.mat, scla_smooth2.mat.

8 Filter SCN

Scope: mergedProgress: uw_space_time.matNative: parity certified

Stage 8 applies final space-time filtering, edge-noise calculations, and exports the final mean velocity and space-time products.

Python entrypoint: stage8_filter_scn(). Rust entrypoint: native_stage8::run_stage8_native.

Optimized kernel: stage8_edge_noise. Main outputs: mean_v.mat, uw_space_time.mat.

Direct Stage Commands

Use direct native commands when you are validating or debugging one stage scope. Patch stages need --patch; merged stages need --dataset.

target/release/pystamps-native stage 1 --patch "$RUN_DATASET/PATCH_1"
target/release/pystamps-native stage 2 --patch "$RUN_DATASET/PATCH_1"
target/release/pystamps-native stage 5 --dataset "$RUN_DATASET"
target/release/pystamps-native stage 8 --dataset "$RUN_DATASET"

Stage Result Statuses

Status	Meaning
`planned`	Dry-run selected the stage but did not write artifacts.
`completed`	The stage executed, or strict reference replay copied the expected bundle.
`skipped_existing`	The expected artifact or merged bundle already exists.
`skipped`	No expected artifact mapping exists for that stage/scope combination.
`failed`	The stage raised an execution error. The details field contains the message.