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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
//! Derived first-derivative stencil coefficients to arbitrary even order.
//!
//! # The stencils
//!
//! Both families write the derivative as a sum over `N = half_order` tap
//! pairs, and differ only in where the taps sit.
//!
//! Staggered (Yee) — the derivative is evaluated halfway between samples, so
//! the taps sit at the half-points `a_n = n − ½`:
//!
//! ```text
//! ∂f/∂x |_{i+1/2} ≈ (1/Δx) Σ_{n=1..N} c_n · ( f_{i+n} − f_{i−n+1} )
//! ```
//!
//! Collocated — the taps sit at whole points `a_n = n`:
//!
//! ```text
//! ∂f/∂x |_i ≈ (1/Δx) Σ_{n=1..N} c_n · ( f_{i+n} − f_{i−n} )
//! ```
//!
//! Both are accurate to order `2N`. `N = 1` gives the familiar
//! `(f_{i+1} − f_i)/Δx` and `(f_{i+1} − f_{i−1})/2Δx` respectively.
//!
//! # Why derived rather than tabulated
//!
//! Expanding about the evaluation point, `f(+a) − f(−a)` is odd, so only odd
//! derivatives survive:
//!
//! ```text
//! (1/Δx) Σ_n c_n [f(+a_n Δx) − f(−a_n Δx)]
//! = 2 Σ_n c_n [ a_n f′ + a_n³ Δx² f‴/6 + a_n⁵ Δx⁴ f⁽⁵⁾/120 + … ]
//! ```
//!
//! Matching `f′` and annihilating the next `N−1` odd derivatives gives the
//! square linear system
//!
//! ```text
//! Σ_n c_n a_n^{2m+1} = ½·δ_{m,0}, m = 0 … N−1
//! ```
//!
//! solved here through the crate's own LU. A new order is then a parameter
//! rather than a hand-entered constant table to get wrong, and the derivation
//! is checked against the published values for orders 2 to 8 plus a measured
//! order-of-accuracy test.
//!
//! # Precision
//!
//! The linear system is solved in `f64` and its solution converted to `T`.
//! The coefficients are analytical constants of the stencil, not field
//! arithmetic: solving an ill-conditioned Vandermonde-like system in a reduced
//! precision would return noise for a quantity that does not depend on the
//! field's precision at all. Every subsequent operation on field data executes
//! in `T`.
//!
//! # References
//!
//! - Fornberg, B. (1988). "Generation of finite difference formulas on
//! arbitrarily spaced grids." *Mathematics of Computation* 51(184), 699-706.
//! DOI: 10.1090/S0025-5718-1988-0935077-0
//! - Levander, A. R. (1988). "Fourth-order finite-difference P-SV seismograms."
//! *Geophysics* 53(11), 1425-1436. (The staggered fourth-order 9/8, −1/24.)
use ;
use ;
use cratelu_decompose;
/// Largest supported half-order, so the largest supported accuracy order is
/// `2 · MAX_HALF_ORDER`.
///
/// The Vandermonde-like system is increasingly ill-conditioned in `N`. At
/// `N = 4` (eighth order — the highest a wave solver here profitably uses) the
/// coefficients match the published rationals to `1e-13` relative. By `N = 8`
/// the high Taylor moments cancel terms of order `10^12` against each other and
/// the residual is only about `1e-11` of the summed magnitude — still far
/// tighter than any discretization error, but no longer exact. The cap keeps
/// the derivation inside its verified range rather than silently returning
/// noise.
pub const MAX_HALF_ORDER: usize = 8;
/// Tap coefficients `c_1 … c_N` of a first-derivative stencil, in units of
/// `1/Δx`.
///
/// Inline storage keeps the owning operator `Copy` and its kernels
/// allocation-free: the derivation allocates once at construction, the sweep
/// never does.
/// Derive the staggered first-derivative taps for accuracy order
/// `2 · half_order`.
///
/// # Errors
///
/// Returns [`LetoError::InvalidInput`] when `half_order` is zero or exceeds
/// [`MAX_HALF_ORDER`], or when the derived system is singular (which cannot
/// occur for the well-posed offsets used here, but is surfaced rather than
/// silently producing garbage).
///
/// # Examples
///
/// ```
/// use leto_ops::staggered_first_derivative_coefficients;
///
/// // Second order: the plain half-grid difference.
/// let c = staggered_first_derivative_coefficients::<f64>(1).unwrap();
/// assert!((c.taps()[0] - 1.0).abs() < 1e-14);
///
/// // Fourth order: Levander's 9/8 and -1/24.
/// let c = staggered_first_derivative_coefficients::<f64>(2).unwrap();
/// assert!((c.taps()[0] - 9.0 / 8.0).abs() < 1e-14);
/// assert!((c.taps()[1] + 1.0 / 24.0).abs() < 1e-14);
/// ```
/// Derive the collocated central first-derivative taps for accuracy order
/// `2 · half_order`.
///
/// The taps are antisymmetric by construction, which is what makes the
/// operator skew-symmetric — and therefore energy-conserving in a leapfrog —
/// once out-of-range taps are treated as zero rather than replaced by a
/// one-sided formula.
///
/// # Errors
///
/// See [`staggered_first_derivative_coefficients`].
///
/// # Examples
///
/// ```
/// use leto_ops::central_first_derivative_coefficients;
///
/// let c = central_first_derivative_coefficients::<f64>(1).unwrap();
/// assert!((c.taps()[0] - 0.5).abs() < 1e-14);
///
/// let c = central_first_derivative_coefficients::<f64>(2).unwrap();
/// assert!((c.taps()[0] - 2.0 / 3.0).abs() < 1e-14);
/// assert!((c.taps()[1] + 1.0 / 12.0).abs() < 1e-14);
/// ```
/// Shared derivation: solve `Σ_n c_n a_n^{2m+1} = ½·δ_{m,0}` for the given tap
/// offsets. Staggered and collocated stencils differ only in where the taps
/// sit, so the linear system and its solve are the same.