Reference

Use this page when you need ownership, not guesswork.

This reference is organized by module responsibility. It prioritizes the public and practical surface of pySTAMPS and groups very large helper-heavy modules by responsibility rather than listing every private helper with equal weight.

CLI and top-level control

Object	Role	Why you use it
`pystamps.cli.main()`	Main CLI entrypoint	Dispatches the status, run, verify, and list-legacy commands.
`pystamps.cli._cmd_status()`	Status command handler	Formats discovered dataset stage information as JSON.
`pystamps.cli._cmd_run()`	Run command handler	Builds a pipeline context, applies worker overrides, invokes the scheduler, and emits stage results.
`pystamps.cli._cmd_verify()`	Verify command handler	Runs golden-dataset comparison and summarizes failures.
`pystamps.cli._cmd_list_legacy()`	Legacy discovery handler	Lists discoverable legacy StaMPS scripts from a checkout root.

Configuration and typed execution state

Object	Role	Notes
`pystamps.config.RunConfig`	Top-level runtime configuration	Bundles runtime, tolerance, external-tool, and compatibility settings.
`pystamps.config.load_config()`	Config loader	Reads YAML or JSON and returns a typed RunConfig.
`pystamps.pipeline.types.PipelineContext`	Execution context	Holds dataset path, selected stage range, dry-run state, and the loaded config.
`pystamps.pipeline.types.PipelineReport`	Pipeline result container	Stores per-stage results and an aggregated failure list.
`pystamps.pipeline.types.StageResult`	Per-stage report item	Records stage id, scope, target, status, details, and duration.

Dataset discovery and status

Object	Role	When to use
`pystamps.io.dataset.discover_dataset()`	Dataset layout discovery	Use when you need a structured view of patch directories and root-level artifacts.
`pystamps.io.dataset.infer_patch_stage()`	Patch stage inference	Determines how far a patch has progressed by inspecting artifacts.
`pystamps.io.dataset.infer_merged_stage()`	Merged stage inference	Determines the latest merged-stage artifact visible at the dataset root.
`pystamps.status.collect_status()`	CLI-friendly status collection	Builds the structured status payload printed by pystamps status.

Verification and parity tooling

Object	Role	Why it matters
`pystamps.verify.verify_run_against_golden()`	Primary verification entrypoint	Compares a run directory against a golden directory using tolerance-aware numeric checks.
`pystamps.verify.classify_failures()`	Mismatch classification	Groups failures into more interpretable debugging categories.
`pystamps.verify.summarize_failures()`	Summary builder	Produces a compact failure digest that is easier to act on than raw comparisons alone.
`pystamps.parity_contract.build_parity_contract()`	Audit contract builder	Defines the supported parity datasets, workflows, and expected audit metadata.
`pystamps.parity_contract.discover_golden_datasets()`	Golden dataset discovery	Finds dataset directories under the configured inputs root.

Pipeline orchestration

Object	Role	Notes
`pystamps.pipeline.stages.run_pipeline()`	Main scheduler	Discovers the dataset, selects stages, skips existing artifacts when appropriate, and aggregates results.
`pystamps.pipeline.stages._selected_stages()`	Stage-range resolver	Maps start_step and end_step onto the concrete stage definitions executed by the scheduler.
`pystamps.pipeline.stages._run_patch_stage()`	Patch-stage executor	Runs one patch-scoped stage and records its outcome.
`pystamps.pipeline.stages._run_merged_stage()`	Merged-stage executor	Runs one merged-stage function against the dataset root.
`pystamps.pipeline.stages._replay_from_reference()`	Compatibility helper	Copies artifacts from a reference tree when strict reference replay is enabled.

Ported stage implementations

The pystamps.pipeline.ported module is intentionally large because it contains stage implementations plus many scientific and data-shaping helpers. The most important functions are the stage entrypoints:

stage1_load_initial(): load initial patch inputs and early metadata.
stage2_estimate_gamma(): estimate stability/coherence-like quantities and produce pm1.mat.
stage3_select_ps(): select persistent-scatterer candidates.
stage4_weed_ps(): weed or prune candidates using additional constraints.
stage5_correct_and_promote(): promote patch outputs into stage-5 corrected artifacts.
stage5_merge_and_ifgstd(): merge patch outputs and calculate merged statistics.
stage6_unwrap(): perform temporal unwrap workflow.
stage7_calc_scla(): estimate raw SCLA and write the smoothed scla_smooth2.mat envelope.
stage8_filter_scn(): follow the wrapper-backed rerun path and write mean_v.mat plus the final space-time filtering result.

Reading tip: use the stage entrypoints and the grouped helper families as your map. Do not start by reading every private helper in file order.

For a stage-by-stage implementation map, read Stages and Code Paths.

Runtime and kernels

Object	Role	Why it exists
`pystamps.runtime.executor.HybridExecutor`	Concurrency abstraction	Provides a consistent interface for thread and process pools.
`pystamps.kernels.describe_backend_matrix()`	Kernel capability report	Lists registered providers and per-kernel python, native, and cuda coverage.
`pystamps.kernels.run_stage7_scla_kernel()`	Stage-7 kernel dispatch	Selects the reference Python, Rust/native, or CUDA implementation for SCLA-related calculations.
`pystamps.kernels.run_stage8_edge_noise_kernel()`	Stage-8 kernel dispatch	Selects the reference Python, Rust/native, or CUDA implementation for edge-noise calculations.
`pystamps.kernels.BackendUnavailableError`	Backend capability error	Signals that a requested kernel backend is unavailable.

Direct optimized-kernel example

uv run python - <<'PY'
from pathlib import Path
import numpy as np

from pystamps.io.mat import read_mat
from pystamps.kernels import describe_backend_matrix, run_stage8_edge_noise_kernel

print(describe_backend_matrix()["kernels"]["stage8_edge_noise"]["available_backends"])

root = Path("inputs_and_outputs/InSAR_dataset_test_stage8diag")
uw_grid = read_mat(root / "uw_grid.mat")
uw_interp = read_mat(root / "uw_interp.mat")
uw_ph = np.asarray(uw_grid["ph"][:1000, :8], dtype=np.complex64)
edges = np.asarray(uw_interp["edgs"], dtype=np.int64)
node_a = edges[:, 1] - 1
node_b = edges[:, 2] - 1
valid = (node_a >= 0) & (node_b >= 0) & (node_a < uw_ph.shape[0]) & (node_b < uw_ph.shape[0])
out = run_stage8_edge_noise_kernel(uw_ph, node_a[valid][:2000], node_b[valid][:2000], backend="native")
print(out["dph_noise"].shape)
PY