Run flow

Copy the dataset, inspect it, dry-run, then execute.

This is the shortest practical path through pySTAMPS. Each command is safe to run on a writable dataset copy and can be narrowed to one stage when you are debugging.

Native Rust commands Stage details Verify outputs

Step 1: make a run copy

pySTAMPS writes outputs into the dataset tree. Keep the source dataset untouched.

export SOURCE_DATASET=/path/to/original_dataset
export RUN_DATASET=/path/to/run_dataset

rm -rf "$RUN_DATASET"
cp -a "$SOURCE_DATASET" "$RUN_DATASET"

Step 2: inspect and dry-run

These commands do not write stage outputs. Use them to confirm what pySTAMPS sees and what it plans to execute.

uv run pystamps status --dataset "$RUN_DATASET"

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

Step 3: run the Python CLI

Run the full pipeline or narrow the stage range while debugging.

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

uv run pystamps run --dataset "$RUN_DATASET" --start-step 6 --end-step 8

For debugging, shorten the range. If the copied dataset already has outputs, completed stages can report skipped_existing.

Step 4: run the native Rust CLI

Use this when you want the standalone Rust runner instead of the Python wrapper.

cargo build --release -p pystamps-core --bin pystamps-native

target/release/pystamps-native run \
  --native-only \
  --dataset "$RUN_DATASET" \
  --start-step 1 \
  --end-step 8 \
  --backend native \
  --stage2-kernel-backend native \
  --cpu-workers 0 \
  --stage2-native-threads 0

0 worker values mean auto-use the CPUs visible to the process. Set positive values to cap resources.

Step 5: validate and benchmark

Verification compares your run copy to a reference dataset. The native full-chain gate also records JSON reports for coverage, timings, and parity.

uv run pystamps verify --run /path/to/run_dataset --golden /path/to/reference_dataset
make native-full-chain-verify

Need worker tuning?

uv run pystamps run --dataset DATASET_DIR --start-step 1 --end-step 8 --io-workers 12 --cpu-workers 4

Need a config file?

runtime:
  backend: auto
  stage2_kernel_backend: auto
  stage2_native_threads: 0
  io_workers: 8
  cpu_workers: 0
  stage7_chunk_ps: 100000
  stage8_chunk_edges: 200000
  enable_mat_stage_cache: true
  stage2_checkpoint_mode: final
  stage2_checkpoint_interval: 1

Need the execution map?

Use the copy-first flow above, then read Stages and Code Paths when you need to understand artifacts or narrow execution to one stage.

Execution Map

Short sequence: copy, status, optional --dry-run, stage execution, verify, and native gate reports when needed.

pySTAMPS execution workflow from dataset copy through verification

CLI flags by command

status: --dataset
run: --dataset, --start-step, --end-step, --dry-run, --io-workers, --cpu-workers
verify: --run, --golden
describe-backends: no flags
list-legacy: --stamps-root or STAMPS_ROOT