Configuration

Configuration file format

pySTAMPS supports YAML and JSON files. If --config is omitted, defaults are used.

Copyruntime:
  io_workers: 8
  cpu_workers: 0
  backend: auto
  stage2_kernel_backend: auto
  stage2_patch_backend_overrides: {}
  kernel_backend_overrides: {}
  stage2_native_threads: 0
  stage7_chunk_ps: 100000
  stage8_chunk_edges: 200000
  enable_mat_stage_cache: true
  stage2_checkpoint_mode: final
  stage2_checkpoint_interval: 1
  stage2_debug: false
  stage4_debug: false

tolerance:
  rtol: 1e-5
  atol: 1e-7
  wrap_equivalence: true
  wrap_period: 6.283185307179586
  wrap_keys:
    - ph_uw
    - ph
    - dph_noise
    - dph_space_uw

tools:
  triangle: triangle
  snaphu: snaphu

compat:
  strict_reference: false
  reference_root: null

Optimized kernel selection

Use pystamps describe-backends to inspect the providers registered on the current machine. The main kernel backend names are python, native, and cuda.

Copyuv run pystamps describe-backends

To require the Rust/CPU kernels where they are available:

Copyruntime:
  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

• runtime.backend accepts auto, threads, processes, gpu, or native.
• stage2_kernel_backend accepts auto, python, or native.
• kernel_backend_overrides pins individual kernels without changing the rest of the runtime.
• stage2_native_threads: 0 lets pySTAMPS use the detected CPU budget for each stage-2 patch.
• Use python overrides when you need the reference path for parity debugging.
• Stages whose expected artifacts already exist are skipped; use an incomplete run copy or benchmark script when you need to time actual kernel execution.

Environment variables

Config precedence and defaults

• Default values come from dataclass defaults in RuntimeConfig, ToleranceConfig, ExternalToolsConfig, and CompatibilityConfig.
• CLI overrides runtime values directly for workers in command handlers before run begins.
• runtime.cpu_workers values <= 0 are replaced by auto-selection in executor initialization.
• runtime.stage2_checkpoint_mode defaults to final, which writes pm1.mat once after convergence to reduce stage-2 I/O without changing the final artifact contract.
• Use periodic with runtime.stage2_checkpoint_interval for restart-friendly snapshots, or always to preserve the older per-iteration checkpoint pattern.

Security considerations

• Config file path passed via CLI is opened directly and parsed as plain YAML/JSON.
• Invalid paths produce ConfigError and terminate command execution.
• Reference replay mode in compatibility config can read another dataset root; verify permissions when using untrusted directories.

Strict reference mode copies all merged and patch-stage artifacts from a trusted root. Use only approved locations.