hyperdd 0.1__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. hyperdd-0.2.0/LICENSE +21 -0
  2. hyperdd-0.2.0/PKG-INFO +21 -0
  3. hyperdd-0.2.0/README.md +53 -0
  4. hyperdd-0.2.0/hyperdd/__init__.py +3 -0
  5. hyperdd-0.2.0/hyperdd/config.py +186 -0
  6. hyperdd-0.2.0/hyperdd/core/__init__.py +0 -0
  7. hyperdd-0.2.0/hyperdd/core/cluster.py +65 -0
  8. hyperdd-0.2.0/hyperdd/core/datatypes.py +66 -0
  9. hyperdd-0.2.0/hyperdd/core/dtres.py +35 -0
  10. hyperdd-0.2.0/hyperdd/core/jacobian.py +157 -0
  11. hyperdd-0.2.0/hyperdd/core/kernels.py +71 -0
  12. hyperdd-0.2.0/hyperdd/core/partials_obs.py +238 -0
  13. hyperdd-0.2.0/hyperdd/core/partition.py +158 -0
  14. hyperdd-0.2.0/hyperdd/core/skip.py +79 -0
  15. hyperdd-0.2.0/hyperdd/core/weighting.py +104 -0
  16. hyperdd-0.2.0/hyperdd/geodesy/__init__.py +0 -0
  17. hyperdd-0.2.0/hyperdd/geodesy/coordinates.py +286 -0
  18. hyperdd-0.2.0/hyperdd/geodesy/delaz_vec.py +65 -0
  19. hyperdd-0.2.0/hyperdd/hypoDD.py +1252 -0
  20. hyperdd-0.2.0/hyperdd/io/__init__.py +0 -0
  21. hyperdd-0.2.0/hyperdd/io/inputs.py +148 -0
  22. hyperdd-0.2.0/hyperdd/io/ph2dt.py +819 -0
  23. hyperdd-0.2.0/hyperdd/io/readers.py +316 -0
  24. hyperdd-0.2.0/hyperdd/io/readers_csv.py +132 -0
  25. hyperdd-0.2.0/hyperdd/io/writers.py +153 -0
  26. hyperdd-0.2.0/hyperdd/metrics.py +74 -0
  27. hyperdd-0.2.0/hyperdd/models/__init__.py +0 -0
  28. hyperdd-0.2.0/hyperdd/models/eikonal.py +234 -0
  29. hyperdd-0.2.0/hyperdd/models/velocity.py +451 -0
  30. hyperdd-0.2.0/hyperdd/models/velocity_numba.py +249 -0
  31. hyperdd-0.2.0/hyperdd/parallel/__init__.py +7 -0
  32. hyperdd-0.2.0/hyperdd/parallel/blocks.py +322 -0
  33. hyperdd-0.2.0/hyperdd/parallel/cli.py +88 -0
  34. hyperdd-0.2.0/hyperdd/parallel/graph.py +104 -0
  35. hyperdd-0.2.0/hyperdd/parallel/pairing.py +99 -0
  36. hyperdd-0.2.0/hyperdd/solvers/__init__.py +0 -0
  37. hyperdd-0.2.0/hyperdd/solvers/_cholmod.py +28 -0
  38. hyperdd-0.2.0/hyperdd/solvers/covariance.py +112 -0
  39. hyperdd-0.2.0/hyperdd/solvers/lsqr.py +371 -0
  40. hyperdd-0.2.0/hyperdd/solvers/schur.py +132 -0
  41. hyperdd-0.2.0/hyperdd/solvers/sparse_chol.py +247 -0
  42. hyperdd-0.2.0/hyperdd/solvers/stats.py +116 -0
  43. hyperdd-0.2.0/hyperdd/solvers/svd.py +304 -0
  44. hyperdd-0.2.0/hyperdd.egg-info/PKG-INFO +21 -0
  45. hyperdd-0.2.0/hyperdd.egg-info/SOURCES.txt +54 -0
  46. hyperdd-0.2.0/hyperdd.egg-info/entry_points.txt +3 -0
  47. hyperdd-0.2.0/hyperdd.egg-info/requires.txt +15 -0
  48. hyperdd-0.2.0/hyperdd.egg-info/top_level.txt +1 -0
  49. hyperdd-0.2.0/pyproject.toml +32 -0
  50. hyperdd-0.2.0/tests/test_covariance.py +45 -0
  51. hyperdd-0.2.0/tests/test_eikonal.py +56 -0
  52. hyperdd-0.2.0/tests/test_inputs.py +32 -0
  53. hyperdd-0.2.0/tests/test_native_vs_fortran.py +55 -0
  54. hyperdd-0.2.0/tests/test_solvers.py +42 -0
  55. hyperdd-0.1/PKG-INFO +0 -3
  56. hyperdd-0.1/hyperdd.egg-info/PKG-INFO +0 -3
  57. hyperdd-0.1/hyperdd.egg-info/SOURCES.txt +0 -5
  58. hyperdd-0.1/hyperdd.egg-info/top_level.txt +0 -1
  59. hyperdd-0.1/setup.py +0 -13
  60. {hyperdd-0.1 → hyperdd-0.2.0}/hyperdd.egg-info/dependency_links.txt +0 -0
  61. {hyperdd-0.1 → hyperdd-0.2.0}/setup.cfg +0 -0
hyperdd-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AI4EPS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
hyperdd-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,21 @@
1
+ Metadata-Version: 2.4
2
+ Name: hyperdd
3
+ Version: 0.2.0
4
+ Summary: Scalable double-difference earthquake relocation with sparse graph optimization
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/AI4EPS/HyperDD
7
+ Requires-Python: >=3.10
8
+ License-File: LICENSE
9
+ Requires-Dist: numpy>=1.22
10
+ Requires-Dist: scipy>=1.8
11
+ Requires-Dist: numba>=0.56
12
+ Requires-Dist: pandas>=1.5
13
+ Requires-Dist: pyarrow>=10
14
+ Provides-Extra: fast
15
+ Requires-Dist: scikit-sparse>=0.4; extra == "fast"
16
+ Provides-Extra: metis
17
+ Requires-Dist: pymetis>=2023.1; extra == "metis"
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest>=7.0; extra == "test"
20
+ Requires-Dist: pymetis>=2023.1; extra == "test"
21
+ Dynamic: license-file
@@ -0,0 +1,53 @@
1
+ # HyperDD
2
+
3
+ HyperDD is a Python implementation of HypoDD for double-difference earthquake relocation. It reads HypoDD's input files (`hypoDD.inp`, `event.sel`, `station.sel`, `dt.ct`, `dt.cc`), writes HypoDD's output files, and follows the Fortran code's algorithm. Besides HypoDD's SVD and LSQR, it solves the linear system with sparse solvers (sparse Cholesky, LSMR, or a Schur-complement solver), and the travel times and partial derivatives are compiled with numba.
4
+
5
+ ## Install
6
+
7
+ ```
8
+ pip install git+https://github.com/AI4EPS/HyperDD.git
9
+ ```
10
+
11
+ Optional extras: `.[fast]` adds CHOLMOD (scikit-sparse; needs SuiteSparse installed), `.[metis]` adds METIS graph partitioning (pymetis), `.[test]` adds pytest.
12
+
13
+ ## Run
14
+
15
+ In a directory with a HypoDD input file and the files it names:
16
+
17
+ ```
18
+ hyperdd hypoDD.inp
19
+ ```
20
+
21
+ or `python -m hyperdd.hypoDD hypoDD.inp`. The relocations are written to the file named in `hypoDD.inp` (usually `hypoDD.reloc`), in HypoDD's format.
22
+
23
+ ## Differences from Fortran HypoDD
24
+
25
+ - **Damping.** A negative `DAMP` in `hypoDD.inp` is read as μ = −DAMP, and the damping applied is DAMP = sqrt(μ · N), where N is the number of differential times. The same μ therefore gives the same regularization at any catalog size, whereas a fixed DAMP weakens as the catalog grows. A positive `DAMP` is used as in HypoDD.
26
+ - **Airquakes (`IAQ`).** 0 and 1 are as in HypoDD (0: an event that would move above depth 0 keeps its depth for that iteration; 1: such events are removed and the iteration is repeated). **2** turns the test off: the top layer of the velocity model extends upward, and events may move above sea level. Station elevations (the fourth column of `station.sel`, in metres) should be given, since depths are measured from sea level. Fortran HypoDD reads any value other than 0 as 1.
27
+ - **Solver.** `ISOLV = 1` (SVD) and `2` (LSQR) are HypoDD's. `ISOLV = 3` selects HyperDD's sparse solvers, sparse Cholesky of the normal equations by default.
28
+
29
+ The parameters and the values used in our tests are described in [`docs/parameters.md`](docs/parameters.md).
30
+
31
+ ## Tests
32
+
33
+ ```
34
+ pip install -e ".[test]"
35
+ pytest tests
36
+ ```
37
+
38
+ The tests relocate four example data sets (`tests/data`) and compare the relocations with Fortran HypoDD's output on the same files (`tests/reference_output`).
39
+
40
+ ```
41
+ python tests/plot_examples.py # tests/figures/examples.png
42
+ python tests/uncertainty_examples.py # tests/figures/uncertainty.png (needs the fast extra)
43
+ ```
44
+
45
+ `examples.png` draws HyperDD over Fortran HypoDD with each example's own `hypoDD.inp` (SVD for example 1, LSQR for the others), the comparison the tests make. `uncertainty.png` compares location uncertainty estimates on the examples: the errors HypoDD's solvers report, the covariance of the solution, and station and observation bootstraps, relative (pairs of events) and absolute (each event). Example 4 is synthetic with its true locations; its delay times were computed for stations at the surface, not at the elevations of its station file, so the Fortran comparison uses its inputs as they are and the uncertainty figure relocates it with the stations at the surface (see `tests/test_native_vs_fortran.py`). The figures as published come with the benchmarks' results release (`python benchmarks/download.py --results`).
46
+
47
+ ## Benchmarks
48
+
49
+ Comparison with Fortran HypoDD and GrowClust, scaling to a million events, and location uncertainty: `benchmarks/README.md`. The real California catalog (4.2 M events, 2000–2025) relocated statewide with catalog times, cross-correlation times and both: `scripts/california/README.md`.
50
+
51
+ ## License
52
+
53
+ MIT (see `LICENSE`).
@@ -0,0 +1,3 @@
1
+ """HyperDD: Scalable double-difference earthquake relocation."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,186 @@
1
+ """Parse hypoDD.inp control files (v1 and v2 formats).
2
+
3
+ Returns a HypoDDConfig dataclass with all parameters needed to run hypoDD.
4
+ """
5
+
6
+ import numpy as np
7
+
8
+ from .core.datatypes import HypoDDConfig, VelocityModel1D
9
+
10
+
11
+ def _read_noncomment_lines(filepath):
12
+ """Read all non-comment lines from a hypoDD input file.
13
+
14
+ Lines starting with '*' are treated as comments and skipped.
15
+ Blank lines are preserved as empty strings (they can represent
16
+ empty file names). Leading/trailing whitespace is stripped.
17
+ """
18
+ lines = []
19
+ with open(filepath) as f:
20
+ for line in f:
21
+ stripped = line.strip()
22
+ if not stripped.startswith('*'):
23
+ lines.append(stripped)
24
+ return lines
25
+
26
+
27
+ def parse_inp(filepath):
28
+ """Parse a hypoDD.inp control-parameter file.
29
+
30
+ Supports both the v1 format (used by hypoDD 1.x) and the v2 format
31
+ whose first non-comment line is ``hypoDD_2``.
32
+
33
+ Parameters
34
+ ----------
35
+ filepath : str or path-like
36
+ Path to the hypoDD.inp file.
37
+
38
+ Returns
39
+ -------
40
+ HypoDDConfig
41
+ Populated configuration dataclass.
42
+ """
43
+ all_lines = _read_noncomment_lines(filepath)
44
+ cfg = HypoDDConfig()
45
+
46
+ idx = 0
47
+ version = 2 if all_lines[0].startswith('hypoDD') else 1
48
+ if version == 2:
49
+ idx = 1
50
+
51
+ # ---- Input files (blank line = no file) ----
52
+ cfg.fn_cc = all_lines[idx]; idx += 1
53
+ cfg.fn_ct = all_lines[idx]; idx += 1
54
+ cfg.fn_eve = all_lines[idx]; idx += 1
55
+ cfg.fn_sta = all_lines[idx]; idx += 1
56
+
57
+ # ---- Output files (blank line = no file) ----
58
+ cfg.fn_loc = all_lines[idx]; idx += 1
59
+ cfg.fn_reloc = all_lines[idx]; idx += 1
60
+ cfg.fn_stares = all_lines[idx]; idx += 1
61
+ cfg.fn_res = all_lines[idx]; idx += 1
62
+ cfg.fn_srcpar = all_lines[idx]; idx += 1
63
+
64
+ # From here on, skip blank lines (only file names can be blank)
65
+ lines = [l for l in all_lines[idx:] if l]
66
+ idx = 0
67
+
68
+ # ---- Data type selection ----
69
+ parts = lines[idx].split(); idx += 1
70
+ cfg.idata = int(parts[0])
71
+ cfg.iphase = int(parts[1])
72
+ cfg.maxdist = float(parts[2])
73
+
74
+ # ---- Event clustering ----
75
+ # v1: OBSCC OBSCT (2 values)
76
+ # v2: OBSCC OBSCT MINDIST MAXDIST MAXGAP (5 values)
77
+ parts = lines[idx].split(); idx += 1
78
+ cfg.minobs_cc = int(parts[0])
79
+ cfg.minobs_ct = int(parts[1])
80
+ if version == 2 and len(parts) >= 5:
81
+ cfg.minds = float(parts[2])
82
+ cfg.maxds = float(parts[3])
83
+ cfg.maxgap = float(parts[4])
84
+
85
+ # ---- Solution control ----
86
+ # v1: ISTART ISOLV NSET (3 values, no IAQ)
87
+ # v2: ISTART ISOLV IAQ NSET (4 values)
88
+ parts = lines[idx].split(); idx += 1
89
+ cfg.istart = int(parts[0])
90
+ cfg.isolv = int(parts[1])
91
+ if version == 2:
92
+ cfg.iaq = int(parts[2])
93
+ cfg.nset = int(parts[3])
94
+ else:
95
+ cfg.iaq = 0
96
+ cfg.nset = int(parts[2])
97
+
98
+ # ---- Iteration parameters (one line per set) ----
99
+ # NITER WTCCP WTCCS WRCC WDCC WTCTP WTCTS WRCT WDCT DAMP [label]
100
+ for _s in range(cfg.nset):
101
+ parts = lines[idx].split(); idx += 1
102
+ cfg.niter.append(int(parts[0]))
103
+ cfg.wt_ccp.append(float(parts[1]))
104
+ cfg.wt_ccs.append(float(parts[2]))
105
+ cfg.wrcc.append(float(parts[3]))
106
+ cfg.wdcc.append(float(parts[4]))
107
+ cfg.wt_ctp.append(float(parts[5]))
108
+ cfg.wt_cts.append(float(parts[6]))
109
+ cfg.wrct.append(float(parts[7]))
110
+ cfg.wdct.append(float(parts[8]))
111
+ cfg.damp.append(float(parts[9]))
112
+
113
+ # ---- Velocity model ----
114
+ if version == 2:
115
+ # v2 has an explicit IMOD line
116
+ cfg.imod = int(lines[idx]); idx += 1
117
+ else:
118
+ # v1 has no IMOD line; the model is always imod=0
119
+ cfg.imod = 0
120
+
121
+ if cfg.imod == 0:
122
+ # Fixed Vp/Vs: NLAY RATIO, then TOP values, then VEL values
123
+ parts = lines[idx].split(); idx += 1
124
+ nlay = int(parts[0])
125
+ ratio = float(parts[1])
126
+ top = list(map(float, lines[idx].split())); idx += 1
127
+ vel = list(map(float, lines[idx].split())); idx += 1
128
+ cfg.vel_model = VelocityModel1D(
129
+ nl=nlay,
130
+ v=np.array(vel[:nlay], dtype=np.float32),
131
+ top=np.array(top[:nlay], dtype=np.float32),
132
+ ratio=np.array([ratio] * nlay, dtype=np.float32),
133
+ )
134
+ elif cfg.imod == 1:
135
+ # Variable Vp/Vs: TOP vals -9, VEL vals -9, RATIO vals -9
136
+ vals = list(map(float, lines[idx].split())); idx += 1
137
+ top = [v for v in vals if v != -9]
138
+ vals = list(map(float, lines[idx].split())); idx += 1
139
+ vel = [v for v in vals if v != -9]
140
+ vals = list(map(float, lines[idx].split())); idx += 1
141
+ ratios = [v for v in vals if v != -9]
142
+ nlay = len(top)
143
+ cfg.vel_model = VelocityModel1D(
144
+ nl=nlay,
145
+ v=np.array(vel, dtype=np.float32),
146
+ top=np.array(top, dtype=np.float32),
147
+ ratio=np.array(ratios, dtype=np.float32),
148
+ )
149
+ elif cfg.imod == 5:
150
+ # Constant velocity: same format as imod=0 OR individual lines
151
+ # Try NLAY RATIO format first; if only 1 value, it's individual lines
152
+ parts = lines[idx].split()
153
+ if len(parts) >= 2:
154
+ # NLAY RATIO format
155
+ idx += 1
156
+ nlay = int(parts[0])
157
+ ratio = float(parts[1])
158
+ top_vals = list(map(float, lines[idx].split())); idx += 1
159
+ vel_vals = list(map(float, lines[idx].split())); idx += 1
160
+ else:
161
+ # Individual lines: TOP, VEL, RATIO (one value each)
162
+ top_vals = list(map(float, lines[idx].split())); idx += 1
163
+ vel_vals = list(map(float, lines[idx].split())); idx += 1
164
+ ratio_vals = list(map(float, lines[idx].split())); idx += 1
165
+ nlay = len(top_vals)
166
+ ratio = ratio_vals[0]
167
+ cfg.vel_model = VelocityModel1D(
168
+ nl=nlay,
169
+ v=np.array(vel_vals[:nlay], dtype=np.float32),
170
+ top=np.array(top_vals[:nlay], dtype=np.float32),
171
+ ratio=np.array([ratio] * nlay, dtype=np.float32),
172
+ )
173
+
174
+ # ---- Cluster / event selection ----
175
+ if idx < len(lines):
176
+ parts = lines[idx].split(); idx += 1
177
+ cfg.iclust = int(parts[0])
178
+
179
+ # Event IDs (optional, may span multiple lines)
180
+ cusps = []
181
+ while idx < len(lines):
182
+ parts = lines[idx].split(); idx += 1
183
+ cusps.extend([int(p) for p in parts])
184
+ cfg.icusp = np.array(cusps, dtype=np.int32) if cusps else np.array([], dtype=np.int32)
185
+
186
+ return cfg
File without changes
@@ -0,0 +1,65 @@
1
+ import numpy as np
2
+
3
+
4
+ def cluster_events(nev, ev_cusp, ndt, dt_c1, dt_c2, dt_idx, idata, minobs_cc, minobs_ct):
5
+ """Cluster events based on shared observations.
6
+
7
+ Matches Fortran cluster1.f: counts total observations per event pair,
8
+ then links pairs with total >= (minobs_cc + minobs_ct).
9
+
10
+ Returns list of clusters, each a list of event indices (0-indexed).
11
+ """
12
+ # Adjust thresholds by data type (Fortran cluster1.f lines 70-71)
13
+ if idata == 0 or idata == 1:
14
+ minobs_ct = 0
15
+ if idata == 0 or idata == 2:
16
+ minobs_cc = 0
17
+ min_total = minobs_cc + minobs_ct
18
+
19
+ # Count total observations per event pair (Fortran: apair_n)
20
+ pair_count = {}
21
+ for i in range(ndt):
22
+ ic1_cusp = int(dt_c1[i])
23
+ ic2_cusp = int(dt_c2[i])
24
+ key = (min(ic1_cusp, ic2_cusp), max(ic1_cusp, ic2_cusp))
25
+ pair_count[key] = pair_count.get(key, 0) + 1
26
+
27
+ # Union-Find
28
+ parent = list(range(nev))
29
+
30
+ def find(x):
31
+ while parent[x] != x:
32
+ parent[x] = parent[parent[x]]
33
+ x = parent[x]
34
+ return x
35
+
36
+ def union(x, y):
37
+ px, py = find(x), find(y)
38
+ if px != py:
39
+ parent[px] = py
40
+
41
+ # Build cusp -> index map
42
+ cusp_to_idx = {}
43
+ for i in range(nev):
44
+ cusp_to_idx[int(ev_cusp[i])] = i
45
+
46
+ # Merge events with sufficient links (Fortran cluster1.f line 82)
47
+ for (c1, c2), n_obs in pair_count.items():
48
+ if c1 not in cusp_to_idx or c2 not in cusp_to_idx:
49
+ continue
50
+ if n_obs >= min_total:
51
+ union(cusp_to_idx[c1], cusp_to_idx[c2])
52
+
53
+ # Collect clusters
54
+ clusters = {}
55
+ for i in range(nev):
56
+ root = find(i)
57
+ if root not in clusters:
58
+ clusters[root] = []
59
+ clusters[root].append(i)
60
+
61
+ # Sort by size (largest first), filter singletons
62
+ result = sorted(clusters.values(), key=len, reverse=True)
63
+ result = [c for c in result if len(c) > 1]
64
+
65
+ return result
@@ -0,0 +1,66 @@
1
+ """Data structures for hypodd, corresponding to Fortran common blocks and parameters."""
2
+
3
+ from dataclasses import dataclass, field
4
+
5
+ import numpy as np
6
+
7
+
8
+ @dataclass
9
+ class VelocityModel1D:
10
+ """1D velocity model corresponding to the MOD structure in hypoDD."""
11
+
12
+ nl: int # number of layers
13
+ v: np.ndarray # P velocities (km/s), shape (nl,)
14
+ top: np.ndarray # layer tops (km), shape (nl,)
15
+ ratio: np.ndarray # Vp/Vs per layer, shape (nl,)
16
+
17
+
18
+ @dataclass
19
+ class HypoDDConfig:
20
+ """Configuration parameters for hypoDD, corresponding to hypoDD.inp."""
21
+
22
+ # Input files
23
+ fn_cc: str = ""
24
+ fn_ct: str = ""
25
+ fn_eve: str = ""
26
+ fn_sta: str = ""
27
+ # Output files
28
+ fn_loc: str = ""
29
+ fn_reloc: str = ""
30
+ fn_res: str = ""
31
+ fn_stares: str = ""
32
+ fn_srcpar: str = ""
33
+ # Parameters
34
+ idata: int = 0 # 1=CC, 2=CT, 3=both
35
+ iphase: int = 0 # 1=P, 2=S, 3=P&S
36
+ maxdist: float = 0.0 # max station-cluster distance
37
+ minobs_cc: int = 0
38
+ minobs_ct: int = 0
39
+ minds: float = -999.0
40
+ maxds: float = -999.0
41
+ maxgap: float = -999.0
42
+ istart: int = 0 # 1=single source, 2=catalog
43
+ isolv: int = 0 # 1=SVD, 2=LSQR
44
+ iaq: int = 0 # airquakes: 0 = held at depth 0, 1 = removed (HypoDD), 2 = no test, events move above sea level
45
+ nset: int = 0 # number of iteration sets
46
+ imod: int = 0 # velocity model type
47
+ iclust: int = 0 # cluster to relocate (0=all)
48
+ icusp: np.ndarray = field(default_factory=lambda: np.array([], dtype=np.int32))
49
+ vel_model: VelocityModel1D = None
50
+ # Iteration parameters (lists, one per set)
51
+ niter: list = field(default_factory=list)
52
+ wt_ccp: list = field(default_factory=list)
53
+ wt_ccs: list = field(default_factory=list)
54
+ wrcc: list = field(default_factory=list)
55
+ wdcc: list = field(default_factory=list)
56
+ wt_ctp: list = field(default_factory=list)
57
+ wt_cts: list = field(default_factory=list)
58
+ wrct: list = field(default_factory=list)
59
+ wdct: list = field(default_factory=list)
60
+ damp: list = field(default_factory=list)
61
+ # GraphDD extensions
62
+ gnc_kernel: str = "" # "" = off, "tls", "huber", "cauchy"
63
+ gnc_threshold: float = 3.0 # MAD multiplier for kernel threshold
64
+ solver_backend: str = "lsqr" # "lsqr", "lsmr", "cholesky", "pcg", "schur"
65
+ robust_loss: str = None # None, "huber", "cauchy", "tukey"
66
+ max_partition_size: int = 5000 # max events per Schur partition
@@ -0,0 +1,35 @@
1
+ import numpy as np
2
+
3
+
4
+ def compute_residuals(ndt, nsrc, dt_dt, dt_idx, dt_ista, dt_ic1, dt_ic2,
5
+ src_t, pp):
6
+ """Compute double-difference residuals (vectorized).
7
+
8
+ dt_dt: observed differential times
9
+ dt_idx: phase type (1=cc-P, 2=cc-S, 3=ct-P, 4=ct-S)
10
+ dt_ista, dt_ic1, dt_ic2: station and event pair indices (0-indexed)
11
+ src_t: source origin time corrections in milliseconds
12
+ pp: the travel times of the observed (station, event) pairs (PairPartials)
13
+
14
+ Returns: dt_cal, dt_res arrays
15
+ """
16
+ dt_cal = np.zeros(ndt, dtype=np.float32)
17
+ dt_res = np.zeros(ndt, dtype=np.float32)
18
+
19
+ if nsrc == 1:
20
+ dt_res[:ndt] = dt_dt[:ndt]
21
+ else:
22
+ ista = dt_ista[:ndt]
23
+ ic1 = dt_ic1[:ndt]
24
+ ic2 = dt_ic2[:ndt]
25
+ idx = dt_idx[:ndt]
26
+
27
+ s_mask = (idx == 2) | (idx == 4)
28
+
29
+ tt1 = pp.travel_time(s_mask, pp.k1) - src_t[ic1] / 1000.0
30
+ tt2 = pp.travel_time(s_mask, pp.k2) - src_t[ic2] / 1000.0
31
+ dt_cal[:ndt] = tt1 - tt2
32
+
33
+ dt_res[:ndt] = dt_dt[:ndt] - dt_cal[:ndt]
34
+
35
+ return dt_cal, dt_res
@@ -0,0 +1,157 @@
1
+ """Sparse Jacobian assembly for the DD system.
2
+
3
+ Builds the weighted sparse Jacobian matrix J and data vector d from
4
+ observation arrays and partial derivatives. This is the core matrix
5
+ that all solver backends (LSQR, Cholesky, PCG) operate on.
6
+
7
+ Factored out from sparse_chol.py so it can be shared across solvers. The partials
8
+ arrive per observed (station, event) pair (PairPartials); there are no nsta x nsrc arrays.
9
+ """
10
+
11
+ import numpy as np
12
+ from scipy.sparse import csr_matrix
13
+
14
+
15
+ # Constraint weights for fixed events (from Fortran hypoDD)
16
+ _FIX_WEIGHTS = {
17
+ 1: {2: 100.0},
18
+ 2: {2: 100.0, 3: 100.0},
19
+ 3: {0: 10.0, 1: 10.0, 2: 10.0},
20
+ 4: {0: 100.0, 1: 100.0, 2: 100.0, 3: 100.0},
21
+ 5: {3: 1000.0},
22
+ 6: {0: 100.0, 1: 100.0},
23
+ }
24
+
25
+
26
+ def build_dd_system(ndt, nev, nsrc, dt_res, dt_wt, dt_ista, dt_ic1, dt_ic2, dt_idx,
27
+ pp, ev_fix, use_float32=True):
28
+ """Build weighted sparse Jacobian G and data vector d for the DD system.
29
+
30
+ Returns
31
+ -------
32
+ G : csr_matrix, shape (nndt, 4*nev)
33
+ Weighted, column-scaled sparse Jacobian.
34
+ d_vec : ndarray, shape (nndt,)
35
+ Weighted data vector (residuals in ms).
36
+ norm : ndarray, shape (4*nev,)
37
+ Column scaling factors (for unscaling solution).
38
+ xp1, yp1, zp1, xp2, yp2, zp2 : ndarray, shape (ndt,)
39
+ Per-observation unweighted partials (for residual update).
40
+ """
41
+ ncol = 4 * nev
42
+ wt = dt_wt[:ndt].copy()
43
+
44
+ # Count constraint entries
45
+ n_fix_entries = 0
46
+ for i in range(nev):
47
+ fix = ev_fix[i]
48
+ if fix in _FIX_WEIGHTS:
49
+ n_fix_entries += len(_FIX_WEIGHTS[fix])
50
+
51
+ # n_meanshift = 4 * nev # 4 constraint rows, nev entries each
52
+ # max_nnz = 8 * ndt + n_meanshift + n_fix_entries
53
+ max_nnz = 8 * ndt + n_fix_entries
54
+ rows = np.empty(max_nnz, dtype=np.int32)
55
+ cols = np.empty(max_nnz, dtype=np.int32)
56
+ vals = np.empty(max_nnz, dtype=np.float64)
57
+
58
+ nndt = ndt
59
+ # max_rows = ndt + 4 + n_fix_entries # +4 for mean-shift constraints
60
+ max_rows = ndt + n_fix_entries
61
+ d = np.zeros(max_rows, dtype=np.float64)
62
+ d[:ndt] = dt_res[:ndt] * 1000.0 * wt
63
+
64
+ idx = np.arange(ndt)
65
+ ic1 = dt_ic1[:ndt]
66
+ ic2 = dt_ic2[:ndt]
67
+ ista = dt_ista[:ndt]
68
+
69
+ s_mask = (dt_idx[:ndt] == 2) | (dt_idx[:ndt] == 4)
70
+
71
+ # The partials of each observation's two (station, event) pairs
72
+ xp1, yp1, zp1 = pp.partials(s_mask, pp.k1)
73
+ xp2, yp2, zp2 = pp.partials(s_mask, pp.k2)
74
+
75
+ # Fill 8 blocks (weighted)
76
+ ptr = 0
77
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic1*4+0; vals[ptr:ptr+ndt] = xp1*wt; ptr += ndt
78
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic1*4+1; vals[ptr:ptr+ndt] = yp1*wt; ptr += ndt
79
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic1*4+2; vals[ptr:ptr+ndt] = zp1*wt; ptr += ndt
80
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic1*4+3; vals[ptr:ptr+ndt] = wt; ptr += ndt
81
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic2*4+0; vals[ptr:ptr+ndt] = -xp2*wt; ptr += ndt
82
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic2*4+1; vals[ptr:ptr+ndt] = -yp2*wt; ptr += ndt
83
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic2*4+2; vals[ptr:ptr+ndt] = -zp2*wt; ptr += ndt
84
+ rows[ptr:ptr+ndt] = idx; cols[ptr:ptr+ndt] = ic2*4+3; vals[ptr:ptr+ndt] = -wt; ptr += ndt
85
+
86
+ # Mean-shift constraint rows: sum(dx)=0, sum(dy)=0, sum(dz)=0, sum(dt)=0
87
+ # Matches SVD solver (svd.py lines 194-202). Prevents centroid drift.
88
+ # NOTE: commented out for now -- complicates Schur partition (dense coupling).
89
+ # Damping provides a soft centroid constraint instead.
90
+ # for p in range(4):
91
+ # row_idx = nndt
92
+ # d[row_idx] = 0.0
93
+ # for j in range(nev):
94
+ # rows[ptr] = row_idx
95
+ # cols[ptr] = j * 4 + p
96
+ # vals[ptr] = 1.0
97
+ # ptr += 1
98
+ # nndt += 1
99
+
100
+ # Add ev_fix constraint rows
101
+ k = 0
102
+ for i in range(nev):
103
+ fix = ev_fix[i]
104
+ if fix == 0 or fix not in _FIX_WEIGHTS:
105
+ continue
106
+ for off, weight in _FIX_WEIGHTS[fix].items():
107
+ row_idx = nndt + k
108
+ d[row_idx] = 0.0
109
+ rows[ptr] = row_idx
110
+ cols[ptr] = i * 4 + off
111
+ vals[ptr] = weight
112
+ ptr += 1
113
+ k += 1
114
+ nndt += k
115
+ total_nnz = ptr
116
+
117
+ # Build sparse G
118
+ _dtype = np.float32 if use_float32 else np.float64
119
+ G = csr_matrix(
120
+ (vals[:total_nnz].astype(_dtype), (rows[:total_nnz], cols[:total_nnz])),
121
+ shape=(nndt, ncol), dtype=_dtype,
122
+ )
123
+ d_vec = d[:nndt].astype(_dtype)
124
+
125
+ # Column scaling (same as LSQR: norm = sqrt(sum(G[:,j]^2) / ndt))
126
+ col_sq_sums = np.array(G.power(2).sum(axis=0)).ravel()
127
+ norm = np.sqrt(col_sq_sums / ndt)
128
+ norm[norm == 0] = 1.0
129
+
130
+ from scipy.sparse import diags
131
+ G_scaled = G @ diags(1.0 / norm)
132
+
133
+ return G_scaled, d_vec, norm, xp1, yp1, zp1, xp2, yp2, zp2
134
+
135
+
136
+ def update_residuals(ndt, dt_res, x, ic1, ic2, xp1, yp1, zp1, xp2, yp2, zp2):
137
+ """Update residuals after solve: dt_res -= J_unweighted @ x / 1000."""
138
+ idx = np.arange(ndt)
139
+ ncol = len(x)
140
+
141
+ nnz_data = 8 * ndt
142
+ rows_uw = np.empty(nnz_data, dtype=np.int32)
143
+ cols_uw = np.empty(nnz_data, dtype=np.int32)
144
+ vals_uw = np.empty(nnz_data, dtype=np.float64)
145
+ p = 0
146
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic1*4+0; vals_uw[p:p+ndt] = xp1; p += ndt
147
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic1*4+1; vals_uw[p:p+ndt] = yp1; p += ndt
148
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic1*4+2; vals_uw[p:p+ndt] = zp1; p += ndt
149
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic1*4+3; vals_uw[p:p+ndt] = 1.0; p += ndt
150
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic2*4+0; vals_uw[p:p+ndt] = -xp2; p += ndt
151
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic2*4+1; vals_uw[p:p+ndt] = -yp2; p += ndt
152
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic2*4+2; vals_uw[p:p+ndt] = -zp2; p += ndt
153
+ rows_uw[p:p+ndt] = idx; cols_uw[p:p+ndt] = ic2*4+3; vals_uw[p:p+ndt] = -1.0; p += ndt
154
+
155
+ G_uw = csr_matrix((vals_uw, (rows_uw, cols_uw)), shape=(ndt, ncol), dtype=np.float64)
156
+ dd = G_uw @ x
157
+ dt_res[:ndt] -= dd / 1000.0
@@ -0,0 +1,71 @@
1
+ """Robust kernels and GNC (Graduated Non-Convexity) schedule for GraphDD."""
2
+
3
+ import numpy as np
4
+
5
+
6
+ def kernel_weights(residuals, c, kernel="tls", mu=None):
7
+ """Compute IRLS weights for robust kernels.
8
+
9
+ Parameters
10
+ ----------
11
+ residuals : ndarray
12
+ Residual values.
13
+ c : float
14
+ Kernel threshold parameter.
15
+ kernel : str
16
+ One of "l2", "huber", "cauchy", "tls".
17
+ mu : float or None
18
+ GNC surrogate parameter (1.0=convex/L2, 0.0=target kernel).
19
+ If None, use the target kernel directly.
20
+
21
+ Returns
22
+ -------
23
+ w : ndarray
24
+ Per-observation weights in [0, 1].
25
+ """
26
+ r = np.abs(residuals)
27
+
28
+ if mu is not None and kernel == "tls":
29
+ if mu >= 1.0:
30
+ return np.ones_like(r, dtype=np.float64)
31
+ if mu > 0.0:
32
+ return _gnc_tls_weights(r, c, mu)
33
+
34
+ if kernel == "l2":
35
+ return np.ones_like(r, dtype=np.float64)
36
+ elif kernel == "huber":
37
+ w = np.ones_like(r, dtype=np.float64)
38
+ mask = r > c
39
+ w[mask] = c / r[mask]
40
+ return w
41
+ elif kernel == "cauchy":
42
+ return 1.0 / (1.0 + (r / c) ** 2)
43
+ elif kernel == "tls":
44
+ w = np.ones_like(r, dtype=np.float64)
45
+ w[r > c] = 0.0
46
+ return w
47
+ else:
48
+ raise ValueError(f"Unknown kernel: {kernel}")
49
+
50
+
51
+ def _gnc_tls_weights(r, c, mu):
52
+ """GNC surrogate weights for TLS kernel."""
53
+ w = np.ones_like(r, dtype=np.float64)
54
+ r_thresh = c * np.sqrt(mu / (1.0 + mu))
55
+
56
+ outlier = r > r_thresh
57
+ if np.any(outlier):
58
+ r_out = r[outlier]
59
+ w[outlier] = np.clip((c ** 2 * mu) / (r_out ** 2 * (1.0 + mu)), 0.0, 1.0)
60
+
61
+ return w
62
+
63
+
64
+ def gnc_mu(iteration, total_iterations):
65
+ """Compute GNC mu for a given iteration.
66
+
67
+ mu transitions linearly from 1.0 (iteration 1) to 0.0 (last iteration).
68
+ """
69
+ if total_iterations <= 1:
70
+ return 0.0
71
+ return max(0.0, 1.0 - iteration / (total_iterations - 1))