-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathfunction-reference.html
More file actions
167 lines (155 loc) · 12.9 KB
/
Copy pathfunction-reference.html
File metadata and controls
167 lines (155 loc) · 12.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Function Reference - pySTAMPS Docs</title>
<link rel="stylesheet" href="assets/styles.css" />
<script defer src="assets/scripts.js"></script>
</head>
<body>
<div class="site">
<aside class="sidebar">
<div class="logo"><img class="brand-logo" src="assets/pystamps-logo.svg" alt="pySTAMPS logo" /><h1>pySTAMPS Docs</h1></div>
<small>Formal module and function guide.</small>
<nav>
<div class="nav-group"><h2>Guide</h2><ul class="nav-list"><li><a href="index.html">Introduction</a></li><li><a href="stages.html">Stages and Code Paths</a></li><li><a href="pipeline-science-guide.html">Pipeline Guide</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="installation.html">Installation</a></li><li><a href="quickstart.html">Quick Start</a></li><li><a href="architecture.html">Architecture</a></li><li><a href="configuration.html">Configuration</a></li><li><a href="usage.html">Usage</a></li><li><a href="testing.html">Testing</a></li><li><a href="verification.html">Verification</a></li><li><a href="contributing.html">Contributing</a></li><li><a href="faq.html">FAQ</a></li></ul></div>
<div class="nav-group"><h2>Reference</h2><ul class="nav-list"><li><a class="active" href="function-reference.html">Function Reference</a></li><li><a href="api/pystamps.html">Package API</a></li><li><a href="api/cli.html">cli</a></li><li><a href="api/configuration.html">config</a></li><li><a href="api/status.html">status</a></li><li><a href="api/verify.html">verify</a></li><li><a href="api/io_dataset.html">io.dataset</a></li><li><a href="api/io_mat.html">io.mat</a></li><li><a href="api/runtime.html">runtime</a></li><li><a href="api/kernels.html">kernels</a></li><li><a href="api/pipeline_types.html">pipeline.types</a></li><li><a href="api/pipeline_stages.html">pipeline.stages</a></li><li><a href="api/pipeline_ported.html">pipeline.ported</a></li></ul></div>
</nav>
</aside>
<main class="content">
<div class="breadcrumb">Home / Function Reference</div>
<section class="hero">
<span class="badge">Reference</span>
<h1>Use this page when you need ownership, not guesswork.</h1>
<p>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.</p>
</section>
<section class="card">
<h2>CLI and top-level control</h2>
<div class="table-wrap">
<table>
<thead><tr><th>Object</th><th>Role</th><th>Why you use it</th></tr></thead>
<tbody>
<tr><td><code>pystamps.cli.main()</code></td><td>Main CLI entrypoint</td><td>Dispatches the <span class="code-inline">status</span>, <span class="code-inline">run</span>, <span class="code-inline">verify</span>, and <span class="code-inline">list-legacy</span> commands.</td></tr>
<tr><td><code>pystamps.cli._cmd_status()</code></td><td>Status command handler</td><td>Formats discovered dataset stage information as JSON.</td></tr>
<tr><td><code>pystamps.cli._cmd_run()</code></td><td>Run command handler</td><td>Builds a pipeline context, applies worker overrides, invokes the scheduler, and emits stage results.</td></tr>
<tr><td><code>pystamps.cli._cmd_verify()</code></td><td>Verify command handler</td><td>Runs golden-dataset comparison and summarizes failures.</td></tr>
<tr><td><code>pystamps.cli._cmd_list_legacy()</code></td><td>Legacy discovery handler</td><td>Lists discoverable legacy StaMPS scripts from a checkout root.</td></tr>
</tbody>
</table>
</div>
</section>
<section class="card">
<h2>Configuration and typed execution state</h2>
<div class="table-wrap">
<table>
<thead><tr><th>Object</th><th>Role</th><th>Notes</th></tr></thead>
<tbody>
<tr><td><code>pystamps.config.RunConfig</code></td><td>Top-level runtime configuration</td><td>Bundles runtime, tolerance, external-tool, and compatibility settings.</td></tr>
<tr><td><code>pystamps.config.load_config()</code></td><td>Config loader</td><td>Reads YAML or JSON and returns a typed <span class="code-inline">RunConfig</span>.</td></tr>
<tr><td><code>pystamps.pipeline.types.PipelineContext</code></td><td>Execution context</td><td>Holds dataset path, selected stage range, dry-run state, and the loaded config.</td></tr>
<tr><td><code>pystamps.pipeline.types.PipelineReport</code></td><td>Pipeline result container</td><td>Stores per-stage results and an aggregated failure list.</td></tr>
<tr><td><code>pystamps.pipeline.types.StageResult</code></td><td>Per-stage report item</td><td>Records stage id, scope, target, status, details, and duration.</td></tr>
</tbody>
</table>
</div>
</section>
<section class="card">
<h2>Dataset discovery and status</h2>
<div class="table-wrap">
<table>
<thead><tr><th>Object</th><th>Role</th><th>When to use</th></tr></thead>
<tbody>
<tr><td><code>pystamps.io.dataset.discover_dataset()</code></td><td>Dataset layout discovery</td><td>Use when you need a structured view of patch directories and root-level artifacts.</td></tr>
<tr><td><code>pystamps.io.dataset.infer_patch_stage()</code></td><td>Patch stage inference</td><td>Determines how far a patch has progressed by inspecting artifacts.</td></tr>
<tr><td><code>pystamps.io.dataset.infer_merged_stage()</code></td><td>Merged stage inference</td><td>Determines the latest merged-stage artifact visible at the dataset root.</td></tr>
<tr><td><code>pystamps.status.collect_status()</code></td><td>CLI-friendly status collection</td><td>Builds the structured status payload printed by <span class="code-inline">pystamps status</span>.</td></tr>
</tbody>
</table>
</div>
</section>
<section class="card">
<h2>Verification and parity tooling</h2>
<div class="table-wrap">
<table>
<thead><tr><th>Object</th><th>Role</th><th>Why it matters</th></tr></thead>
<tbody>
<tr><td><code>pystamps.verify.verify_run_against_golden()</code></td><td>Primary verification entrypoint</td><td>Compares a run directory against a golden directory using tolerance-aware numeric checks.</td></tr>
<tr><td><code>pystamps.verify.classify_failures()</code></td><td>Mismatch classification</td><td>Groups failures into more interpretable debugging categories.</td></tr>
<tr><td><code>pystamps.verify.summarize_failures()</code></td><td>Summary builder</td><td>Produces a compact failure digest that is easier to act on than raw comparisons alone.</td></tr>
<tr><td><code>pystamps.parity_contract.build_parity_contract()</code></td><td>Audit contract builder</td><td>Defines the supported parity datasets, workflows, and expected audit metadata.</td></tr>
<tr><td><code>pystamps.parity_contract.discover_golden_datasets()</code></td><td>Golden dataset discovery</td><td>Finds dataset directories under the configured inputs root.</td></tr>
</tbody>
</table>
</div>
</section>
<section class="card">
<h2>Pipeline orchestration</h2>
<div class="table-wrap">
<table>
<thead><tr><th>Object</th><th>Role</th><th>Notes</th></tr></thead>
<tbody>
<tr><td><code>pystamps.pipeline.stages.run_pipeline()</code></td><td>Main scheduler</td><td>Discovers the dataset, selects stages, skips existing artifacts when appropriate, and aggregates results.</td></tr>
<tr><td><code>pystamps.pipeline.stages._selected_stages()</code></td><td>Stage-range resolver</td><td>Maps <span class="code-inline">start_step</span> and <span class="code-inline">end_step</span> onto the concrete stage definitions executed by the scheduler.</td></tr>
<tr><td><code>pystamps.pipeline.stages._run_patch_stage()</code></td><td>Patch-stage executor</td><td>Runs one patch-scoped stage and records its outcome.</td></tr>
<tr><td><code>pystamps.pipeline.stages._run_merged_stage()</code></td><td>Merged-stage executor</td><td>Runs one merged-stage function against the dataset root.</td></tr>
<tr><td><code>pystamps.pipeline.stages._replay_from_reference()</code></td><td>Compatibility helper</td><td>Copies artifacts from a reference tree when strict reference replay is enabled.</td></tr>
</tbody>
</table>
</div>
</section>
<section class="card">
<h2>Ported stage implementations</h2>
<p>The <span class="code-inline">pystamps.pipeline.ported</span> module is intentionally large because it contains stage implementations plus many scientific and data-shaping helpers. The most important functions are the stage entrypoints:</p>
<ul>
<li><code>stage1_load_initial()</code>: load initial patch inputs and early metadata.</li>
<li><code>stage2_estimate_gamma()</code>: estimate stability/coherence-like quantities and produce <span class="code-inline">pm1.mat</span>.</li>
<li><code>stage3_select_ps()</code>: select persistent-scatterer candidates.</li>
<li><code>stage4_weed_ps()</code>: weed or prune candidates using additional constraints.</li>
<li><code>stage5_correct_and_promote()</code>: promote patch outputs into stage-5 corrected artifacts.</li>
<li><code>stage5_merge_and_ifgstd()</code>: merge patch outputs and calculate merged statistics.</li>
<li><code>stage6_unwrap()</code>: perform temporal unwrap workflow.</li>
<li><code>stage7_calc_scla()</code>: estimate raw SCLA and write the smoothed <span class="code-inline">scla_smooth2.mat</span> envelope.</li>
<li><code>stage8_filter_scn()</code>: follow the wrapper-backed rerun path and write <span class="code-inline">mean_v.mat</span> plus the final space-time filtering result.</li>
</ul>
<div class="callout info"><strong>Reading tip:</strong> use the stage entrypoints and the grouped helper families as your map. Do not start by reading every private helper in file order.</div>
<p>For a stage-by-stage implementation map, read <a href="stages.html">Stages and Code Paths</a>.</p>
</section>
<section class="card">
<h2>Runtime and kernels</h2>
<div class="table-wrap">
<table>
<thead><tr><th>Object</th><th>Role</th><th>Why it exists</th></tr></thead>
<tbody>
<tr><td><code>pystamps.runtime.executor.HybridExecutor</code></td><td>Concurrency abstraction</td><td>Provides a consistent interface for thread and process pools.</td></tr>
<tr><td><code>pystamps.kernels.describe_backend_matrix()</code></td><td>Kernel capability report</td><td>Lists registered providers and per-kernel <span class="code-inline">python</span>, <span class="code-inline">native</span>, and <span class="code-inline">cuda</span> coverage.</td></tr>
<tr><td><code>pystamps.kernels.run_stage7_scla_kernel()</code></td><td>Stage-7 kernel dispatch</td><td>Selects the reference Python, Rust/native, or CUDA implementation for SCLA-related calculations.</td></tr>
<tr><td><code>pystamps.kernels.run_stage8_edge_noise_kernel()</code></td><td>Stage-8 kernel dispatch</td><td>Selects the reference Python, Rust/native, or CUDA implementation for edge-noise calculations.</td></tr>
<tr><td><code>pystamps.kernels.BackendUnavailableError</code></td><td>Backend capability error</td><td>Signals that a requested kernel backend is unavailable.</td></tr>
</tbody>
</table>
</div>
<h3>Direct optimized-kernel example</h3>
<pre><button class="copy-btn">Copy</button><code class="language-bash">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</code></pre>
</section>
<p class="footer">For command examples, continue with <a href="usage.html">Usage</a>. For the generated API pages, see the <a href="api/pystamps.html">Package API</a>.</p>
</main>
</div>
</body>
</html>