Skip to main content

gamlss_spline/
lib.rs

1#![forbid(unsafe_code)]
2//! Spline bases, prepared and on-demand predictor designs, and penalties.
3//!
4//! Reusable `*Basis` and `*Spec` metadata can be applied to new coordinates.
5//! Named prepared designs cache compact row geometry where that improves
6//! repeated model passes; [`OnDemandSplineDesign`] retains only coordinates
7//! and metadata. Linear designs share [`SplineRowBasis`],
8//! [`gamlss_core::PredictorBlock`], and
9//! [`gamlss_core::LinearPredictorGeometry`] contracts.
10
11pub use basis::SplineBasis1d;
12pub use bspline::{BSplineBasis, BSplineDesign, pspline_design};
13pub use cyclic::{CyclicSplineDesign, CyclicSplineSpec};
14pub use error::{FourierError, SplineError};
15pub use fourier::{FourierBasis, FourierDesign};
16pub use ispline::{ISplineBasis, ISplineDesign};
17pub use monotone::{MonotoneDirection, MonotoneISplineDesign};
18pub use mspline::{MSplineBasis, MSplineDesign};
19pub use natural::{NaturalCubicSplineBasis, NaturalCubicSplineDesign};
20pub use on_demand::OnDemandSplineDesign;
21pub use open_uniform::{OpenUniformSplineBasis, OpenUniformSplineDesign};
22pub use order::SplineOrder;
23pub use penalty::{
24    CyclicDifferencePenalty, DifferencePenalty, EdgeMonotonicPenalty,
25    PreparedCyclicDifferencePenalty, PreparedDifferencePenalty, SlopeLimitPenalty,
26};
27pub use periodic::{PeriodicSplineDesign, PeriodicSplineSpec};
28pub use row_basis::{CsrParts, SplineRowBasis, SplineRowBasisExt, TripletParts};
29pub use tensor::TensorSplineDesign;
30pub use truncated_power::{TruncatedPowerBasis, TruncatedPowerDesign};
31
32pub mod basis;
33pub mod bspline;
34pub mod cyclic;
35pub mod error;
36pub mod fourier;
37mod geometry;
38pub mod ispline;
39mod local;
40pub mod monotone;
41pub mod mspline;
42pub mod natural;
43pub mod on_demand;
44pub mod open_uniform;
45pub mod order;
46pub mod penalty;
47pub mod periodic;
48mod prepared;
49pub mod row_basis;
50pub mod tensor;
51pub mod truncated_power;
52mod validation;
53
54/// Most commonly used imports from `gamlss-spline`.
55pub mod prelude {
56    pub use crate::{
57        BSplineBasis, BSplineDesign, CsrParts, CyclicDifferencePenalty, CyclicSplineDesign,
58        CyclicSplineSpec, DifferencePenalty, EdgeMonotonicPenalty, FourierBasis, FourierDesign,
59        FourierError, ISplineBasis, ISplineDesign, MSplineBasis, MSplineDesign, MonotoneDirection,
60        MonotoneISplineDesign, NaturalCubicSplineBasis, NaturalCubicSplineDesign,
61        OnDemandSplineDesign, OpenUniformSplineBasis, OpenUniformSplineDesign,
62        PeriodicSplineDesign, PeriodicSplineSpec, PreparedCyclicDifferencePenalty,
63        PreparedDifferencePenalty, SlopeLimitPenalty, SplineBasis1d, SplineError, SplineOrder,
64        SplineRowBasis, SplineRowBasisExt, TensorSplineDesign, TripletParts, TruncatedPowerBasis,
65        TruncatedPowerDesign, pspline_design,
66    };
67}
68
69#[cfg(test)]
70mod tests {
71    use approx::assert_relative_eq;
72    use gamlss_core::{
73        LinearPredictorBlock, LinearPredictorGeometry, MatrixPenalty, ModelError, Penalty,
74        PredictorBlock, ProductBlock,
75    };
76
77    use super::{
78        BSplineBasis, CyclicDifferencePenalty, CyclicSplineDesign, CyclicSplineSpec,
79        DifferencePenalty, EdgeMonotonicPenalty, FourierBasis, FourierDesign, FourierError,
80        ISplineBasis, MSplineBasis, MonotoneDirection, MonotoneISplineDesign,
81        NaturalCubicSplineBasis, OnDemandSplineDesign, OpenUniformSplineBasis,
82        OpenUniformSplineDesign, PeriodicSplineDesign, PeriodicSplineSpec,
83        PreparedCyclicDifferencePenalty, PreparedDifferencePenalty, SlopeLimitPenalty,
84        SplineBasis1d, SplineError, SplineOrder, SplineRowBasisExt, TensorSplineDesign,
85        TruncatedPowerBasis,
86    };
87
88    #[test]
89    fn open_uniform_bspline_partitions_unity_inside_range() {
90        let x = [0.0, 0.25, 0.5, 0.75, 1.0];
91        let basis = BSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
92
93        for value in x {
94            assert_nonnegative_partition_of_unity(&basis.evaluate(value));
95        }
96    }
97
98    #[test]
99    fn open_uniform_bspline_has_expected_endpoint_rows() {
100        let x = [0.0, 0.25, 0.5, 0.75, 1.0];
101        let basis = BSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
102        let left = basis.evaluate(0.0);
103        let right = basis.evaluate(1.0);
104
105        assert_single_active_endpoint_basis(&left, 0);
106        assert_single_active_endpoint_basis(&right, basis.n_basis() - 1);
107    }
108
109    #[test]
110    fn bspline_sparse_visitor_matches_full_evaluation_for_general_knots() {
111        let cases = [
112            (0, vec![-1.0, 0.0, 0.5, 2.0]),
113            (2, vec![0.0, 0.0, 0.0, 0.4, 1.0, 1.0, 1.0]),
114            (2, vec![-1.0, 0.0, 0.5, 1.5, 2.0, 3.0]),
115            (3, vec![0.0, 0.0, 0.0, 0.0, 0.5, 0.5, 1.0, 1.0, 1.0, 1.0]),
116        ];
117
118        for (degree, knots) in cases {
119            let basis = BSplineBasis::new(degree, knots.clone()).unwrap();
120            let mut points = vec![-2.0, 4.0];
121            for knot in knots {
122                points.extend([knot.next_down(), knot, knot.next_up()]);
123            }
124
125            for x in points {
126                let expected = basis.evaluate(x);
127                let mut actual = vec![0.0; basis.n_basis()];
128                basis.for_each_basis(x, |index, weight| actual[index] = weight);
129                assert_eq!(
130                    actual,
131                    expected,
132                    "degree={degree}, knots={:?}, x={x:?}",
133                    basis.knots()
134                );
135            }
136        }
137    }
138
139    #[test]
140    fn difference_penalty_gradient_matches_finite_difference() {
141        let penalty = DifferencePenalty::new_unchecked(0.7, 2);
142        let beta = vec![0.2, -0.4, 0.9, 1.1, -0.3];
143        assert_penalty_gradient_matches_finite_difference(&penalty, &beta);
144    }
145
146    #[test]
147    fn zero_lambda_difference_penalties_are_noops() {
148        let beta = vec![f64::INFINITY, f64::NAN, f64::NEG_INFINITY];
149
150        assert_zero_lambda_penalty_is_noop(&DifferencePenalty::new_unchecked(0.0, 2), &beta);
151        assert_zero_lambda_penalty_is_noop(&CyclicDifferencePenalty::new_unchecked(0.0, 2), &beta);
152    }
153
154    #[test]
155    fn difference_penalty_matrix_matches_gradient_convention() {
156        let penalty = DifferencePenalty::new_unchecked(0.7, 2);
157        let beta = vec![0.2, -0.4, 0.9, 1.1, -0.3];
158        assert_penalty_matrix_matches_gradient(&penalty, &beta);
159    }
160
161    #[test]
162    fn prepared_difference_penalty_matches_unprepared() {
163        let beta = [0.2, -0.4, 0.9, 1.1, -0.3];
164
165        for order in 1..=2 {
166            let unprepared = DifferencePenalty::new_unchecked(0.7, order);
167            let prepared = PreparedDifferencePenalty::new_unchecked(0.7, order);
168            assert_matrix_penalty_matches(&prepared, &unprepared, &beta);
169            assert_penalty_gradient_matches_finite_difference(&prepared, &beta);
170        }
171    }
172
173    #[test]
174    #[allow(clippy::float_cmp)]
175    fn difference_penalty_try_new_validates_inputs() {
176        let penalty = DifferencePenalty::try_new(0.0, 1).unwrap();
177        assert_eq!(penalty.lambda(), 0.0);
178        assert_eq!(penalty.order(), 1);
179
180        let prepared = PreparedDifferencePenalty::try_new(0.5, 2).unwrap();
181        assert_eq!(prepared.lambda(), 0.5);
182        assert_eq!(prepared.order(), 2);
183        assert_eq!(prepared.coefficients(), &[1.0, -2.0, 1.0]);
184        assert_eq!(
185            DifferencePenalty::try_new(f64::NAN, 1).unwrap_err(),
186            ModelError::InvalidParameter {
187                parameter: "penalty lambda",
188                expected: "finite and >= 0",
189            }
190        );
191        assert_eq!(
192            DifferencePenalty::try_new(-1.0, 1).unwrap_err(),
193            ModelError::InvalidParameter {
194                parameter: "penalty lambda",
195                expected: "finite and >= 0",
196            }
197        );
198        assert_eq!(
199            DifferencePenalty::try_new(1.0, 0).unwrap_err(),
200            ModelError::InvalidParameter {
201                parameter: "difference penalty order",
202                expected: "> 0",
203            }
204        );
205        assert_eq!(
206            DifferencePenalty::try_new(1.0, usize::MAX).unwrap_err(),
207            ModelError::ArithmeticOverflow {
208                context: "difference penalty coefficients",
209            }
210        );
211        assert_eq!(
212            PreparedDifferencePenalty::try_new(1.0, usize::MAX).unwrap_err(),
213            ModelError::ArithmeticOverflow {
214                context: "difference penalty coefficients",
215            }
216        );
217    }
218
219    #[test]
220    #[allow(clippy::float_cmp)]
221    fn preparing_difference_penalty_revalidates_source() {
222        let prepared =
223            PreparedDifferencePenalty::try_from(DifferencePenalty::new_unchecked(0.5, 2)).unwrap();
224        assert_eq!(prepared.lambda(), 0.5);
225        assert_eq!(prepared.order(), 2);
226        assert_eq!(prepared.coefficients(), &[1.0, -2.0, 1.0]);
227
228        assert_eq!(
229            PreparedDifferencePenalty::try_from(DifferencePenalty::new_unchecked(1.0, 0))
230                .unwrap_err(),
231            ModelError::InvalidParameter {
232                parameter: "difference penalty order",
233                expected: "> 0",
234            }
235        );
236    }
237
238    #[test]
239    fn open_uniform_basis_visitor_matches_design_row_basis() {
240        let x = [-0.25, 0.0, 0.2, 0.75, 1.25];
241        let basis = OpenUniformSplineBasis::new(0.0, 1.0, 6, SplineOrder::Cubic).unwrap();
242        let design = basis.design(&x).unwrap();
243
244        for (row, value) in x.iter().copied().enumerate() {
245            let mut from_design = Vec::new();
246            let mut from_basis = Vec::new();
247
248            super::SplineRowBasis::for_each_row_basis(&design, row, |index, weight| {
249                from_design.push((index, weight));
250            });
251            basis
252                .for_each_value_basis(value, |index, weight| {
253                    from_basis.push((index, weight));
254                })
255                .unwrap();
256
257            assert_eq!(from_basis.len(), from_design.len());
258            for ((basis_index, basis_weight), (design_index, design_weight)) in
259                from_basis.iter().zip(&from_design)
260            {
261                assert_eq!(basis_index, design_index);
262                assert_relative_eq!(basis_weight, design_weight, epsilon = 1.0e-12);
263            }
264        }
265    }
266
267    #[test]
268    fn open_uniform_basis_visitor_rejects_non_finite_input() {
269        let basis = OpenUniformSplineBasis::new(0.0, 1.0, 6, SplineOrder::Cubic).unwrap();
270        let err = basis.for_each_value_basis(f64::NAN, |_, _| {}).unwrap_err();
271
272        assert_eq!(err, SplineError::NonFiniteValue);
273    }
274
275    #[test]
276    fn cyclic_basis_visitor_matches_prepared_design() {
277        let phi = [-1.0, -0.25, 0.0, 0.4, 1.0, 1.75];
278        let spec = CyclicSplineSpec::new(6, SplineOrder::Cubic).unwrap();
279        let design = spec.design(&phi).unwrap();
280
281        for (row, value) in phi.iter().copied().enumerate() {
282            let mut from_design = Vec::new();
283            let mut from_spec = Vec::new();
284
285            super::SplineRowBasis::for_each_row_basis(&design, row, |index, weight| {
286                from_design.push((index, weight));
287            });
288            spec.for_each_value_basis(value, |index, weight| {
289                from_spec.push((index, weight));
290            })
291            .unwrap();
292
293            assert_eq!(from_spec, from_design);
294        }
295    }
296
297    #[test]
298    fn cyclic_basis_visitor_rejects_non_finite_input() {
299        let spec = CyclicSplineSpec::new(6, SplineOrder::Cubic).unwrap();
300
301        assert_eq!(
302            spec.for_each_value_basis(f64::NAN, |_, _| {}).unwrap_err(),
303            SplineError::NonFiniteValue
304        );
305    }
306
307    #[test]
308    fn on_demand_local_designs_match_compact_prepared_designs() {
309        let x = [-0.25, 0.0, 0.2, 0.75, 1.0, 1.25];
310        let scores = [0.3, 0.0, -0.7, 0.2, 1.1, -0.4];
311
312        let open_basis = OpenUniformSplineBasis::new(0.0, 1.0, 6, SplineOrder::Cubic).unwrap();
313        let open_prepared = open_basis.design(&x).unwrap();
314        let open_on_demand = open_basis.on_demand_design(&x).unwrap();
315        let open_beta = [0.2, -0.4, 0.7, 0.1, -0.3, 0.8];
316        assert_spline_predictors_match(&open_prepared, &open_on_demand, &open_beta, &scores);
317
318        let row_weights = [0.5, 0.0, -0.25, 0.7, 1.1, 0.2];
319        assert_linear_geometry_matches(&open_prepared, &open_on_demand, &row_weights, &scores);
320        for row in 0..x.len() {
321            assert_relative_eq!(
322                open_prepared.eta_derivative_row(row, &open_beta),
323                open_on_demand.eta_derivative_row(row, &open_beta),
324                epsilon = 1.0e-12
325            );
326        }
327
328        let cyclic_spec = CyclicSplineSpec::new(6, SplineOrder::Cubic).unwrap();
329        let cyclic_prepared = cyclic_spec.design(&x).unwrap();
330        let cyclic_on_demand = cyclic_spec.on_demand_design(&x).unwrap();
331        let cyclic_beta = [-0.2, 0.5, 0.1, -0.6, 0.9, 0.3];
332        assert_spline_predictors_match(&cyclic_prepared, &cyclic_on_demand, &cyclic_beta, &scores);
333        assert_linear_geometry_matches(&cyclic_prepared, &cyclic_on_demand, &row_weights, &scores);
334        for row in 0..x.len() {
335            assert_relative_eq!(
336                cyclic_prepared.eta_derivative_row(row, &cyclic_beta),
337                cyclic_on_demand.eta_derivative_row(row, &cyclic_beta),
338                epsilon = 1.0e-12
339            );
340        }
341    }
342
343    #[test]
344    fn on_demand_bspline_matches_prepared_dense_design() {
345        let x = [0.0, 0.1, 0.4, 0.75, 1.0];
346        let basis = BSplineBasis::open_uniform_from_data(&x, 7, 3).unwrap();
347        let dense = basis.design_matrix(&x).unwrap();
348        let dense_predictor = LinearPredictorBlock::new(&dense);
349        let prepared = basis.design(&x).unwrap();
350        let on_demand = basis.on_demand_design(&x).unwrap();
351        let borrowed = OnDemandSplineDesign::new(&x, &basis).unwrap();
352        let beta = [0.2, -0.3, 0.7, 0.1, -0.5, 0.8, 0.4];
353        let scores = [0.5, -0.2, 0.0, 0.9, -0.4];
354
355        assert_eq!(on_demand.to_row_major_values().unwrap(), dense.values());
356        assert_eq!(prepared.to_row_major_values().unwrap(), dense.values());
357        assert_eq!(borrowed.to_row_major_values().unwrap(), dense.values());
358        assert_spline_predictors_match(&prepared, &on_demand, &beta, &scores);
359        assert_spline_predictors_match(&dense_predictor, &on_demand, &beta, &scores);
360
361        let weights = [0.2, -0.5, 0.0, 0.7, 1.1];
362        let mut dense_gram = vec![0.0; beta.len() * beta.len()];
363        let mut on_demand_gram = dense_gram.clone();
364        dense_predictor
365            .add_weighted_gram(&weights, &mut dense_gram)
366            .unwrap();
367        on_demand
368            .add_weighted_gram(&weights, &mut on_demand_gram)
369            .unwrap();
370        for (dense, on_demand) in dense_gram.iter().zip(on_demand_gram) {
371            assert_relative_eq!(*dense, on_demand, epsilon = 1.0e-12);
372        }
373        assert_linear_geometry_matches(&prepared, &on_demand, &weights, &scores);
374    }
375
376    #[test]
377    fn prepared_m_and_i_splines_match_on_demand_designs() {
378        let training = [0.0, 0.25, 0.5, 0.75, 1.0];
379        let x = [-0.1, 0.0, 0.2, 0.55, 1.0, 1.1];
380        let beta = [0.2, -0.3, 0.7, 0.1, -0.5, 0.8, 0.4];
381        let scores = [0.5, -0.2, 0.0, 0.9, -0.4, 0.3];
382        let weights = [0.2, -0.5, 0.0, 0.7, 1.1, -0.3];
383
384        let m_basis = MSplineBasis::open_uniform_from_data(&training, beta.len(), 3).unwrap();
385        let m_prepared = m_basis.design(&x).unwrap();
386        let m_on_demand = m_basis.on_demand_design(&x).unwrap();
387        assert_spline_predictors_match(&m_prepared, &m_on_demand, &beta, &scores);
388        assert_linear_geometry_matches(&m_prepared, &m_on_demand, &weights, &scores);
389        for (row, value) in x.iter().copied().enumerate() {
390            let mut expected = 0.0;
391            m_basis.for_each_derivative_basis(value, |index, weight| {
392                expected = beta[index].mul_add(weight, expected);
393            });
394            assert_relative_eq!(
395                m_prepared.eta_derivative_row(row, &beta),
396                expected,
397                epsilon = 1.0e-12
398            );
399        }
400
401        let i_basis = ISplineBasis::open_uniform_from_data(&training, beta.len(), 3).unwrap();
402        let i_prepared = i_basis.design(&x).unwrap();
403        let i_on_demand = i_basis.on_demand_design(&x).unwrap();
404        assert_spline_predictors_match(&i_prepared, &i_on_demand, &beta, &scores);
405        assert_linear_geometry_matches(&i_prepared, &i_on_demand, &weights, &scores);
406    }
407
408    #[test]
409    fn prepared_i_spline_handles_degenerate_supports() {
410        let basis =
411            ISplineBasis::new(vec![0.0, 0.0, 0.0, 0.0, 0.0, 0.5, 1.0, 1.0, 1.0, 1.0], 3).unwrap();
412        let x = [-0.1, 0.0, 0.2, 0.7, 1.0, 1.1];
413        let beta = [0.2, -0.3, 0.7, 0.1, -0.5, 0.8];
414        let scores = [0.5, -0.2, 0.0, 0.9, -0.4, 0.3];
415        let weights = [0.2, -0.5, 0.0, 0.7, 1.1, -0.3];
416        let prepared = basis.design(&x).unwrap();
417        let on_demand = basis.on_demand_design(&x).unwrap();
418
419        assert_relative_eq!(basis.evaluate_one(0, 0.5), 0.0, epsilon = f64::EPSILON);
420        assert_spline_predictors_match(&prepared, &on_demand, &beta, &scores);
421        assert_linear_geometry_matches(&prepared, &on_demand, &weights, &scores);
422        assert_predictor_gradient_matches_finite_difference(&prepared, &beta, &scores);
423    }
424
425    #[test]
426    fn prepared_natural_spline_matches_on_demand_design() {
427        let x = [-0.2, 0.0, 0.2, 0.55, 1.0, 1.2];
428        let basis = NaturalCubicSplineBasis::new(vec![0.0, 0.25, 0.5, 0.75, 1.0]).unwrap();
429        let prepared = basis.design(&x).unwrap();
430        let on_demand = basis.on_demand_design(&x).unwrap();
431        let beta = [0.2, -0.3, 0.7, 0.1, -0.5];
432        let scores = [0.5, -0.2, 0.0, 0.9, -0.4, 0.3];
433        let weights = [0.2, -0.5, 0.0, 0.7, 1.1, -0.3];
434
435        assert_spline_predictors_match(&prepared, &on_demand, &beta, &scores);
436        assert_linear_geometry_matches(&prepared, &on_demand, &weights, &scores);
437        for (row, value) in x.iter().copied().enumerate() {
438            let mut expected = 0.0;
439            basis.for_each_derivative_basis(value, |index, weight| {
440                expected = beta[index].mul_add(weight, expected);
441            });
442            assert_relative_eq!(
443                prepared.eta_derivative_row(row, &beta),
444                expected,
445                epsilon = 1.0e-12
446            );
447        }
448    }
449
450    #[test]
451    #[allow(clippy::cast_precision_loss)]
452    fn prepared_natural_spline_large_basis_uses_correct_geometry_fallback() {
453        let training = [0.0, 1.0];
454        let x = [-0.2, 0.0, 0.2, 0.55, 1.0, 1.2];
455        let basis = NaturalCubicSplineBasis::uniform_from_data(&training, 65).unwrap();
456        let prepared = basis.design(&x).unwrap();
457        let on_demand = basis.on_demand_design(&x).unwrap();
458        let beta = (0..basis.n_basis())
459            .map(|index| (index % 11) as f64 / 10.0 - 0.5)
460            .collect::<Vec<_>>();
461        let scores = [0.5, -0.2, 0.0, 0.9, -0.4, 0.3];
462        let weights = [0.2, -0.5, 0.0, 0.7, 1.1, -0.3];
463
464        assert_spline_predictors_match(&prepared, &on_demand, &beta, &scores);
465        assert_linear_geometry_matches(&prepared, &on_demand, &weights, &scores);
466    }
467
468    #[test]
469    fn on_demand_periodic_design_matches_compact_prepared_design() {
470        let x = [-12.0, 0.0, 3.0, 12.0, 15.0];
471        let spec = PeriodicSplineSpec::new(6, SplineOrder::Cubic, 12.0, 1.5).unwrap();
472        let prepared = spec.design(&x).unwrap();
473        let on_demand = spec.on_demand_design(&x).unwrap();
474        let beta = [0.2, -0.1, 0.7, 0.4, -0.3, 0.9];
475        let scores = [0.5, 0.0, -0.2, 0.7, -0.4];
476
477        assert_spline_predictors_match(&prepared, &on_demand, &beta, &scores);
478        assert_linear_geometry_matches(&prepared, &on_demand, &[0.4, 0.0, -0.2, 0.7, 1.1], &scores);
479        for row in 0..x.len() {
480            assert_relative_eq!(
481                prepared.eta_derivative_row(row, &beta),
482                on_demand.eta_derivative_row(row, &beta),
483                epsilon = 1.0e-12
484            );
485        }
486
487        let overflowing =
488            PeriodicSplineSpec::new(6, SplineOrder::Cubic, f64::MIN_POSITIVE, 0.0).unwrap();
489        assert_eq!(
490            overflowing.design(&[f64::MAX]).unwrap_err(),
491            SplineError::NonFiniteValue
492        );
493        assert_eq!(
494            overflowing.on_demand_design(&[f64::MAX]).unwrap_err(),
495            SplineError::NonFiniteValue
496        );
497    }
498
499    #[test]
500    fn allocating_and_buffer_basis_evaluation_match() {
501        let x = [0.0, 0.25, 0.5, 0.75, 1.0];
502        let b = BSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
503        let m = MSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
504        let i = ISplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
505        let natural = NaturalCubicSplineBasis::new(vec![0.0, 0.5, 1.0]).unwrap();
506
507        let mut buffer = vec![0.0; b.n_basis()];
508        b.evaluate_into(0.4, &mut buffer);
509        assert_eq!(buffer, b.evaluate(0.4));
510
511        buffer.resize(m.n_basis(), 0.0);
512        m.evaluate_into(0.4, &mut buffer);
513        assert_eq!(buffer, m.evaluate(0.4));
514        m.evaluate_derivative_into(0.4, &mut buffer);
515        assert_eq!(buffer, m.evaluate_derivative(0.4));
516
517        buffer.resize(i.n_basis(), 0.0);
518        i.evaluate_into(0.4, &mut buffer);
519        assert_eq!(buffer, i.evaluate(0.4));
520
521        buffer.resize(natural.n_basis(), 0.0);
522        natural.evaluate_into(0.4, &mut buffer);
523        assert_eq!(buffer, natural.evaluate(0.4));
524
525        natural.evaluate_derivative_into(0.4, &mut buffer);
526        assert_eq!(buffer, natural.evaluate_derivative(0.4));
527    }
528
529    #[test]
530    fn spline_row_basis_visitors_match_allocating_evaluate_values() {
531        let x = [0.0, 0.25, 0.5, 0.75, 1.0];
532        let m = MSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
533        let i = ISplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
534        let natural = NaturalCubicSplineBasis::new(vec![0.0, 0.5, 1.0]).unwrap();
535
536        assert_row_basis_matches_evaluate(&m.design(&x).unwrap(), |row| m.evaluate(x[row]));
537        assert_row_basis_matches_evaluate(&i.design(&x).unwrap(), |row| i.evaluate(x[row]));
538        assert_row_basis_matches_evaluate(&natural.design(&x).unwrap(), |row| {
539            natural.evaluate(x[row])
540        });
541    }
542
543    #[test]
544    fn row_basis_ext_exports_dense_triplets_and_csr() {
545        let design =
546            OpenUniformSplineDesign::with_range(&[0.0, 0.5, 1.0], 0.0, 1.0, 5, SplineOrder::Cubic)
547                .unwrap();
548        let dense = design.to_row_major_values().unwrap();
549        let dense_design = design.to_dense_design().unwrap();
550        let (rows, cols, values) = design.to_triplets();
551        let (row_offsets, csr_cols, csr_values) = design.to_csr_parts().unwrap();
552
553        assert_eq!(dense.len(), design.nrows() * design.nparams());
554        assert_eq!(dense_design.values(), dense);
555        assert_eq!(row_offsets.len(), design.nrows() + 1);
556        assert_eq!(cols, csr_cols);
557        assert_eq!(values, csr_values);
558        assert_eq!(rows.len(), values.len());
559
560        for ((row, col), value) in rows.iter().zip(&cols).zip(&values) {
561            assert_relative_eq!(
562                dense[row * design.nparams() + col],
563                *value,
564                epsilon = 1.0e-12
565            );
566        }
567    }
568
569    #[test]
570    fn row_basis_ext_rejects_wrong_dense_output_length() {
571        let design =
572            OpenUniformSplineDesign::with_range(&[0.0, 1.0], 0.0, 1.0, 4, SplineOrder::Cubic)
573                .unwrap();
574        let err = design.fill_row_major(&mut [0.0; 7]).unwrap_err();
575
576        assert_eq!(
577            err,
578            SplineError::Model(ModelError::DesignSize {
579                expected_values: 8,
580                actual_values: 7,
581            })
582        );
583    }
584
585    #[test]
586    fn spline_basis_1d_matches_existing_evaluation_methods() {
587        let x = [0.0, 0.25, 0.5, 0.75, 1.0];
588        let bspline = BSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
589        let open = OpenUniformSplineBasis::from_data(&x, 6, SplineOrder::Cubic).unwrap();
590        let cyclic = CyclicSplineSpec::new(6, SplineOrder::Cubic).unwrap();
591        let fourier = FourierBasis::new(1.0, 3, true).unwrap();
592        let mspline = MSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
593        let ispline = ISplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
594        let natural = NaturalCubicSplineBasis::new(vec![0.0, 0.5, 1.0]).unwrap();
595        let truncated =
596            TruncatedPowerBasis::uniform_from_data(&x, 2, SplineOrder::Cubic, true).unwrap();
597
598        assert_eq!(
599            SplineBasis1d::evaluate(&bspline, 0.4).unwrap(),
600            bspline.evaluate(0.4)
601        );
602
603        let open_values = SplineBasis1d::evaluate(&open, 0.4).unwrap();
604        let mut open_visitor_values = vec![0.0; open.n_basis()];
605        open.for_each_value_basis(0.4, |index, weight| {
606            open_visitor_values[index] = weight;
607        })
608        .unwrap();
609        assert_eq!(open_values, open_visitor_values);
610
611        let cyclic_values = SplineBasis1d::evaluate(&cyclic, 1.4).unwrap();
612        let mut cyclic_visitor_values = vec![0.0; cyclic.n_basis()];
613        cyclic
614            .for_each_value_basis(1.4, |index, weight| {
615                cyclic_visitor_values[index] = weight;
616            })
617            .unwrap();
618        assert_eq!(cyclic_values, cyclic_visitor_values);
619
620        let fourier_values = SplineBasis1d::evaluate(&fourier, 0.4).unwrap();
621        let mut fourier_visitor_values = vec![0.0; fourier.n_basis()];
622        fourier
623            .for_each_value_basis(0.4, |index, weight| {
624                fourier_visitor_values[index] = weight;
625            })
626            .unwrap();
627        assert_eq!(fourier_values, fourier_visitor_values);
628
629        assert_eq!(
630            SplineBasis1d::evaluate(&mspline, 0.4).unwrap(),
631            mspline.evaluate(0.4)
632        );
633        assert_eq!(
634            SplineBasis1d::evaluate(&ispline, 0.4).unwrap(),
635            ispline.evaluate(0.4)
636        );
637        assert_eq!(
638            SplineBasis1d::evaluate(&natural, 0.4).unwrap(),
639            natural.evaluate(0.4)
640        );
641        assert_eq!(
642            SplineBasis1d::evaluate(&truncated, 0.4).unwrap(),
643            truncated.evaluate(0.4)
644        );
645    }
646
647    #[test]
648    fn spline_basis_1d_rejects_non_finite_input_and_wrong_output_length() {
649        let basis = OpenUniformSplineBasis::new(0.0, 1.0, 4, SplineOrder::Cubic).unwrap();
650
651        assert_eq!(
652            SplineBasis1d::evaluate(&basis, f64::NAN).unwrap_err(),
653            SplineError::NonFiniteValue
654        );
655        assert_eq!(
656            SplineBasis1d::evaluate_into(&basis, 0.5, &mut [0.0; 3]).unwrap_err(),
657            SplineError::Model(ModelError::DesignSize {
658                expected_values: 4,
659                actual_values: 3,
660            })
661        );
662    }
663
664    #[test]
665    fn data_derived_bases_reject_overflowing_finite_ranges() {
666        let x = [f64::MIN, f64::MAX];
667
668        assert_eq!(
669            BSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap_err(),
670            SplineError::InvalidRange
671        );
672        assert_eq!(
673            MSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap_err(),
674            SplineError::InvalidRange
675        );
676        assert_eq!(
677            OpenUniformSplineBasis::from_data(&x, 6, SplineOrder::Cubic).unwrap_err(),
678            SplineError::InvalidRange
679        );
680        assert_eq!(
681            NaturalCubicSplineBasis::uniform_from_data(&x, 4).unwrap_err(),
682            SplineError::InvalidRange
683        );
684        assert_eq!(
685            TruncatedPowerBasis::uniform_from_data(&x, 2, SplineOrder::Cubic, true).unwrap_err(),
686            SplineError::InvalidRange
687        );
688    }
689
690    #[test]
691    fn transformed_coordinate_overflow_is_rejected_by_both_design_modes() {
692        let basis = OpenUniformSplineBasis::new(f64::MIN, 0.0, 6, SplineOrder::Cubic).unwrap();
693
694        assert_eq!(
695            basis.design(&[f64::MAX]).unwrap_err(),
696            SplineError::NonFiniteValue
697        );
698        assert_eq!(
699            basis.on_demand_design(&[f64::MAX]).unwrap_err(),
700            SplineError::NonFiniteValue
701        );
702    }
703
704    #[test]
705    fn cyclic_spline_design_wraps_and_partitions_unity() {
706        let design =
707            CyclicSplineDesign::new(&[0.0, 0.25, 1.0, -0.25], 8, SplineOrder::Cubic).unwrap();
708        let beta = vec![1.0; design.nparams()];
709
710        for row in 0..design.nrows() {
711            assert_relative_eq!(design.eta_row(row, &beta), 1.0, epsilon = 1.0e-12);
712        }
713
714        let ramp = (0..8).map(f64::from).collect::<Vec<_>>();
715        assert_relative_eq!(design.eta_row(0, &ramp), design.eta_row(2, &ramp));
716    }
717
718    #[test]
719    #[allow(clippy::cast_precision_loss)]
720    fn periodic_spline_design_is_equal_at_periodic_coordinates() {
721        let spec = PeriodicSplineSpec::new(8, SplineOrder::Cubic, 1.0, 0.0).unwrap();
722        let design = spec.design(&[-0.25, 0.0, 0.75, 1.0, 1.75]).unwrap();
723        let beta = (0..design.nparams())
724            .map(|index| (index as f64).mul_add(0.25, -0.5))
725            .collect::<Vec<_>>();
726
727        assert_relative_eq!(
728            design.eta_row(0, &beta),
729            design.eta_row(2, &beta),
730            epsilon = 1.0e-12
731        );
732        assert_relative_eq!(
733            design.eta_row(1, &beta),
734            design.eta_row(3, &beta),
735            epsilon = 1.0e-12
736        );
737        assert_relative_eq!(
738            design.eta_row(2, &beta),
739            design.eta_row(4, &beta),
740            epsilon = 1.0e-12
741        );
742    }
743
744    #[test]
745    #[allow(clippy::suboptimal_flops)]
746    fn fourier_design_evaluates_harmonics_without_materialized_matrix() {
747        let design = FourierDesign::new(&[0.0, 0.25, 0.5, 1.25], 1.0, 2, true).unwrap();
748        let beta = [0.5, 1.0, 2.0, -0.25, 0.75];
749
750        assert_eq!(design.nrows(), 4);
751        assert_eq!(design.nparams(), 5);
752        assert_eq!(design.order(), 2);
753        assert_relative_eq!(design.period(), 1.0, epsilon = 1.0e-12);
754        assert!(design.include_intercept());
755
756        for row in 0..design.nrows() {
757            let x = design.x()[row];
758            let phase1 = std::f64::consts::TAU * x;
759            let phase2 = 2.0 * std::f64::consts::TAU * x;
760            let expected = beta[0]
761                + beta[1] * phase1.sin()
762                + beta[2] * phase1.cos()
763                + beta[3] * phase2.sin()
764                + beta[4] * phase2.cos();
765
766            assert_relative_eq!(design.eta_row(row, &beta), expected, epsilon = 1.0e-12);
767        }
768
769        assert_relative_eq!(
770            design.eta_row(1, &beta),
771            design.eta_row(3, &beta),
772            epsilon = 1.0e-12
773        );
774    }
775
776    #[test]
777    #[allow(clippy::suboptimal_flops)]
778    fn fourier_design_without_intercept_uses_two_coefficients_per_harmonic() {
779        let design = FourierDesign::new(&[1.0], 4.0, 1, false).unwrap();
780        let beta = [2.0, 3.0];
781        let phase = std::f64::consts::TAU * 1.0 / 4.0;
782
783        assert_eq!(design.nparams(), 2);
784        assert_relative_eq!(
785            design.eta_row(0, &beta),
786            beta[0] * phase.sin() + beta[1] * phase.cos(),
787            epsilon = 1.0e-12
788        );
789    }
790
791    #[test]
792    fn fourier_row_basis_matches_eta_unit_coefficients() {
793        let design = FourierDesign::new(&[0.0, 0.2, 0.7], 1.0, 3, true).unwrap();
794
795        for row in 0..design.nrows() {
796            let mut basis = vec![0.0; design.nparams()];
797            crate::SplineRowBasis::for_each_row_basis(&design, row, |index, weight| {
798                basis[index] = weight;
799            });
800
801            for index in 0..design.nparams() {
802                let mut beta = vec![0.0; design.nparams()];
803                beta[index] = 1.0;
804                assert_relative_eq!(basis[index], design.eta_row(row, &beta), epsilon = 1.0e-12);
805            }
806        }
807    }
808
809    #[test]
810    fn fourier_basis_reuses_metadata_and_matches_shared_geometry_contract() {
811        let x = [0.0, 0.2, 0.7, 1.4];
812        let basis = FourierBasis::new(1.0, 3, true).unwrap();
813        let design = basis.design(&x).unwrap();
814        let generic = basis.on_demand_design(&x).unwrap();
815        let beta = [0.3, -0.5, 1.2, 0.4, -0.8, 0.9, 0.1];
816        let scores = [0.7, -1.1, 0.0, 1.4];
817        let weights = [0.2, 0.0, -0.5, 0.9];
818
819        assert_eq!(*design.basis(), basis);
820        assert_eq!(design.n_basis(), beta.len());
821        assert_spline_predictors_match(&design, &generic, &beta, &scores);
822
823        let dense = design.to_dense_design().unwrap();
824        let dense_predictor = LinearPredictorBlock::new(&dense);
825        assert_linear_geometry_matches(&design, &dense_predictor, &weights, &scores);
826
827        let prediction = design.basis().design(&[2.0, 2.25]).unwrap();
828        assert_eq!(*prediction.basis(), basis);
829        assert_relative_eq!(
830            prediction.eta_row(0, &beta),
831            design.eta_row(0, &beta),
832            epsilon = 1.0e-12
833        );
834    }
835
836    #[test]
837    fn fourier_design_rejects_invalid_inputs() {
838        assert_eq!(
839            FourierDesign::new(&[f64::NAN], 1.0, 1, true).unwrap_err(),
840            FourierError::NonFiniteValue
841        );
842        assert_eq!(
843            FourierDesign::new(&[0.0], 0.0, 1, true).unwrap_err(),
844            FourierError::InvalidPeriod
845        );
846        assert_eq!(
847            FourierDesign::new(&[0.0], 1.0, 0, true).unwrap_err(),
848            FourierError::InvalidOrder
849        );
850        assert_eq!(
851            FourierDesign::new(&[0.0], 1.0, usize::MAX, true).unwrap_err(),
852            FourierError::CoefficientOverflow
853        );
854        assert_eq!(
855            FourierBasis::new(f64::MIN_POSITIVE, 1, true).unwrap_err(),
856            FourierError::InvalidPeriod
857        );
858        assert_eq!(
859            FourierBasis::new(1.0, 1, true)
860                .unwrap()
861                .design(&[f64::MAX])
862                .unwrap_err(),
863            FourierError::NonFiniteValue
864        );
865    }
866
867    #[test]
868    fn fourier_design_gradient_matches_finite_difference() {
869        let design = FourierDesign::new(&[0.0, 0.2, 0.7, 1.4], 1.0, 3, true).unwrap();
870        let beta = vec![0.3, -0.5, 1.2, 0.4, -0.8, 0.9, 0.1];
871        let scores = vec![0.7, -1.1, 0.2, 1.4];
872        let eps = 1.0e-6;
873        let mut grad = vec![0.0; design.nparams()];
874
875        design.add_gradient(&scores, &beta, &mut grad);
876
877        for index in 0..beta.len() {
878            let mut plus = beta.clone();
879            plus[index] += eps;
880            let mut minus = beta.clone();
881            minus[index] -= eps;
882
883            let objective = |candidate: &[f64]| {
884                (0..design.nrows())
885                    .map(|row| scores[row] * design.eta_row(row, candidate))
886                    .sum::<f64>()
887            };
888            let finite_difference = (objective(&plus) - objective(&minus)) / (2.0 * eps);
889
890            assert_relative_eq!(grad[index], finite_difference, epsilon = 1.0e-6);
891        }
892    }
893
894    #[test]
895    fn open_uniform_spline_design_handles_boundaries_and_extrapolation() {
896        let design = OpenUniformSplineDesign::with_range(
897            &[-0.5, 0.0, 0.5, 1.0, 1.5],
898            0.0,
899            1.0,
900            6,
901            SplineOrder::Cubic,
902        )
903        .unwrap();
904        let beta = vec![1.0; design.nparams()];
905
906        for row in 0..design.nrows() {
907            assert_relative_eq!(design.eta_row(row, &beta), 1.0, epsilon = 1.0e-12);
908        }
909    }
910
911    #[test]
912    fn spline_gradient_skips_multiplier_for_zero_score_rows() {
913        let design =
914            OpenUniformSplineDesign::with_range(&[0.0, 0.5, 1.0], 0.0, 1.0, 6, SplineOrder::Cubic)
915                .unwrap();
916        let scores = [1.0, 0.0, 2.0];
917        let mut expected = vec![0.0; design.nparams()];
918        let mut weighted = vec![0.0; design.nparams()];
919
920        design.add_gradient(&scores, &[], &mut expected);
921        design.add_weighted_gradient(&scores, &[1.0, f64::NAN, 1.0], &[], &mut weighted);
922
923        assert_eq!(weighted, expected);
924        assert!(weighted.iter().all(|value| value.is_finite()));
925    }
926
927    #[test]
928    fn open_uniform_spline_geometry_matches_dense_products() {
929        let design = OpenUniformSplineDesign::with_range(
930            &[0.0, 0.2, 0.6, 1.0],
931            0.0,
932            1.0,
933            6,
934            SplineOrder::Cubic,
935        )
936        .unwrap();
937        let weights: [f64; 4] = [0.5, -0.25, 0.0, 2.0];
938        let scores: [f64; 4] = [0.3, -0.7, 0.0, 1.2];
939        let nparams = design.nparams();
940        let mut expected_gram = vec![1.0; nparams * nparams];
941        let mut expected_transpose = vec![1.0; nparams];
942
943        for row in 0..design.nrows() {
944            let mut basis = vec![0.0; nparams];
945            crate::SplineRowBasis::for_each_row_basis(&design, row, |index, value| {
946                basis[index] = value;
947            });
948            for j in 0..nparams {
949                expected_transpose[j] = scores[row].mul_add(basis[j], expected_transpose[j]);
950                for k in 0..nparams {
951                    let index = j * nparams + k;
952                    expected_gram[index] =
953                        (weights[row] * basis[j]).mul_add(basis[k], expected_gram[index]);
954                }
955            }
956        }
957
958        let mut gram = vec![1.0; nparams * nparams];
959        let mut transpose = vec![1.0; nparams];
960        design.add_weighted_gram(&weights, &mut gram).unwrap();
961        design.add_t_mul_vec(&scores, &mut transpose).unwrap();
962
963        for (actual, expected) in gram.iter().zip(expected_gram) {
964            assert_relative_eq!(*actual, expected, epsilon = 1.0e-12);
965        }
966        for (actual, expected) in transpose.iter().zip(expected_transpose) {
967            assert_relative_eq!(*actual, expected, epsilon = 1.0e-12);
968        }
969    }
970
971    #[test]
972    fn product_open_uniform_spline_geometry_scales_rows_lazily() {
973        let design =
974            OpenUniformSplineDesign::with_range(&[0.0, 0.5, 1.0], 0.0, 1.0, 6, SplineOrder::Cubic)
975                .unwrap();
976        let nparams = design.nparams();
977        let product = ProductBlock::try_new(vec![2.0, 5.0, -3.0], design.clone()).unwrap();
978        let mut gram = vec![0.0; nparams * nparams];
979        let mut transpose = vec![0.0; nparams];
980        let mut expected_gram = vec![0.0; nparams * nparams];
981        let mut expected_transpose = vec![0.0; nparams];
982
983        product
984            .add_weighted_gram(&[0.5, 0.0, 2.0], &mut gram)
985            .unwrap();
986        product
987            .add_t_mul_vec(&[0.25, 0.0, -1.0], &mut transpose)
988            .unwrap();
989        design
990            .add_weighted_gram(
991                &[0.5 * 2.0_f64.powi(2), 0.0, 2.0 * (-3.0_f64).powi(2)],
992                &mut expected_gram,
993            )
994            .unwrap();
995        design
996            .add_t_mul_vec(&[0.5, 0.0, 3.0], &mut expected_transpose)
997            .unwrap();
998
999        assert_eq!(gram, expected_gram);
1000        assert_eq!(transpose, expected_transpose);
1001        assert!(gram.iter().all(|value| value.is_finite()));
1002        assert!(transpose.iter().all(|value| value.is_finite()));
1003    }
1004
1005    #[test]
1006    fn open_uniform_spline_geometry_validates_lengths() {
1007        let design =
1008            OpenUniformSplineDesign::with_range(&[0.0, 0.5], 0.0, 1.0, 4, SplineOrder::Cubic)
1009                .unwrap();
1010
1011        assert_eq!(
1012            design
1013                .add_weighted_gram(&[1.0], &mut [0.0; 16])
1014                .unwrap_err(),
1015            ModelError::WeightLength {
1016                expected: 2,
1017                actual: 1,
1018            }
1019        );
1020        assert_eq!(
1021            design
1022                .add_weighted_gram(&[1.0, 1.0], &mut [0.0; 15])
1023                .unwrap_err(),
1024            ModelError::DesignSize {
1025                expected_values: 16,
1026                actual_values: 15,
1027            }
1028        );
1029        assert_eq!(
1030            design
1031                .add_t_mul_vec(&[1.0, 1.0], &mut [0.0; 3])
1032                .unwrap_err(),
1033            ModelError::GradientLength {
1034                expected: 4,
1035                actual: 3,
1036            }
1037        );
1038    }
1039
1040    #[test]
1041    fn open_uniform_spline_basis_reuses_training_range_for_new_data() {
1042        let train = [0.0, 0.5, 1.0];
1043        let basis = OpenUniformSplineBasis::from_data(&train, 6, SplineOrder::Cubic).unwrap();
1044        let train_design = basis.design(&train).unwrap();
1045        let new_design = basis.design(&[-0.25, 0.25, 1.25]).unwrap();
1046
1047        assert_eq!(train_design.basis(), basis);
1048        assert_eq!(new_design.nparams(), train_design.nparams());
1049        assert_relative_eq!(basis.min(), 0.0, epsilon = 1.0e-12);
1050        assert_relative_eq!(basis.max(), 1.0, epsilon = 1.0e-12);
1051
1052        let beta = vec![1.0; new_design.nparams()];
1053        for row in 0..new_design.nrows() {
1054            assert_relative_eq!(new_design.eta_row(row, &beta), 1.0, epsilon = 1.0e-12);
1055        }
1056    }
1057
1058    #[test]
1059    fn cyclic_spline_spec_reuses_basis_shape_for_new_data() {
1060        let spec = CyclicSplineSpec::new(6, SplineOrder::Cubic).unwrap();
1061        let train_design = spec.design(&[0.0, 0.5]).unwrap();
1062        let new_design = spec.design(&[0.25, 1.25]).unwrap();
1063
1064        assert_eq!(train_design.spec(), spec);
1065        assert_eq!(new_design.nparams(), train_design.nparams());
1066
1067        let beta = vec![1.0; new_design.nparams()];
1068        for row in 0..new_design.nrows() {
1069            assert_relative_eq!(new_design.eta_row(row, &beta), 1.0, epsilon = 1.0e-12);
1070        }
1071    }
1072
1073    #[test]
1074    fn cyclic_difference_penalty_gradient_matches_finite_difference() {
1075        let penalty = CyclicDifferencePenalty::new_unchecked(0.7, 2);
1076        let beta = vec![0.2, -0.4, 0.9, 1.1, -0.3];
1077        assert_penalty_gradient_matches_finite_difference(&penalty, &beta);
1078    }
1079
1080    #[test]
1081    fn cyclic_difference_penalty_matrix_matches_gradient_convention() {
1082        let penalty = CyclicDifferencePenalty::new_unchecked(0.7, 2);
1083        let beta = vec![0.2, -0.4, 0.9, 1.1, -0.3];
1084        assert_penalty_matrix_matches_gradient(&penalty, &beta);
1085    }
1086
1087    #[test]
1088    fn prepared_cyclic_difference_penalty_matches_unprepared() {
1089        let beta = [0.2, -0.4, 0.9, 1.1, -0.3];
1090
1091        for order in 1..=2 {
1092            let unprepared = CyclicDifferencePenalty::new_unchecked(0.7, order);
1093            let prepared = PreparedCyclicDifferencePenalty::new_unchecked(0.7, order);
1094            assert_matrix_penalty_matches(&prepared, &unprepared, &beta);
1095            assert_penalty_gradient_matches_finite_difference(&prepared, &beta);
1096        }
1097    }
1098
1099    #[test]
1100    fn difference_penalties_use_documented_scale_conventions() {
1101        let beta = [0.0, 1.0, 3.0, 6.0, 10.0];
1102        let non_cyclic = DifferencePenalty::new_unchecked(2.0, 1);
1103        let cyclic = CyclicDifferencePenalty::new_unchecked(2.0, 1);
1104
1105        assert_relative_eq!(non_cyclic.value(&beta), 15.0, epsilon = 1.0e-12);
1106        assert_relative_eq!(cyclic.value(&beta), 52.0, epsilon = 1.0e-12);
1107    }
1108
1109    #[test]
1110    #[allow(clippy::float_cmp)]
1111    fn cyclic_difference_penalty_try_new_validates_inputs() {
1112        let penalty = CyclicDifferencePenalty::try_new(0.5, 2).unwrap();
1113        assert_eq!(penalty.lambda(), 0.5);
1114        assert_eq!(penalty.order(), 2);
1115
1116        let prepared = PreparedCyclicDifferencePenalty::try_new(0.5, 2).unwrap();
1117        assert_eq!(prepared.lambda(), 0.5);
1118        assert_eq!(prepared.order(), 2);
1119        assert_eq!(prepared.coefficients(), &[1.0, -2.0, 1.0]);
1120        assert_eq!(
1121            CyclicDifferencePenalty::try_new(f64::INFINITY, 2).unwrap_err(),
1122            ModelError::InvalidParameter {
1123                parameter: "penalty lambda",
1124                expected: "finite and >= 0",
1125            }
1126        );
1127        assert_eq!(
1128            CyclicDifferencePenalty::try_new(1.0, 0).unwrap_err(),
1129            ModelError::InvalidParameter {
1130                parameter: "difference penalty order",
1131                expected: "> 0",
1132            }
1133        );
1134        assert_eq!(
1135            CyclicDifferencePenalty::try_new(1.0, usize::MAX).unwrap_err(),
1136            ModelError::ArithmeticOverflow {
1137                context: "difference penalty coefficients",
1138            }
1139        );
1140        assert_eq!(
1141            PreparedCyclicDifferencePenalty::try_new(1.0, usize::MAX).unwrap_err(),
1142            ModelError::ArithmeticOverflow {
1143                context: "difference penalty coefficients",
1144            }
1145        );
1146    }
1147
1148    #[test]
1149    #[allow(clippy::float_cmp)]
1150    fn preparing_cyclic_difference_penalty_revalidates_source() {
1151        let prepared = PreparedCyclicDifferencePenalty::try_from(
1152            CyclicDifferencePenalty::new_unchecked(0.5, 2),
1153        )
1154        .unwrap();
1155        assert_eq!(prepared.lambda(), 0.5);
1156        assert_eq!(prepared.order(), 2);
1157        assert_eq!(prepared.coefficients(), &[1.0, -2.0, 1.0]);
1158
1159        assert_eq!(
1160            PreparedCyclicDifferencePenalty::try_from(CyclicDifferencePenalty::new_unchecked(
1161                1.0, 0
1162            ))
1163            .unwrap_err(),
1164            ModelError::InvalidParameter {
1165                parameter: "difference penalty order",
1166                expected: "> 0",
1167            }
1168        );
1169    }
1170
1171    #[test]
1172    fn edge_monotonic_penalty_gradient_matches_finite_difference() {
1173        let penalty = EdgeMonotonicPenalty::new(3.0);
1174        let beta = vec![0.2, 0.8, 0.4, -0.1];
1175        assert_penalty_gradient_matches_finite_difference(&penalty, &beta);
1176    }
1177
1178    #[test]
1179    #[allow(clippy::float_cmp)]
1180    fn edge_monotonic_penalty_try_new_validates_weight() {
1181        assert_eq!(EdgeMonotonicPenalty::try_new(2.0).unwrap().weight(), 2.0);
1182        assert_eq!(
1183            EdgeMonotonicPenalty::try_new(f64::NAN).unwrap_err(),
1184            ModelError::InvalidParameter {
1185                parameter: "penalty weight",
1186                expected: "finite and > 0",
1187            }
1188        );
1189    }
1190
1191    #[test]
1192    fn slope_limit_penalty_gradient_matches_finite_difference() {
1193        let penalty = SlopeLimitPenalty::try_new(5.0, 2.0, Some(0.4), Some(0.3)).unwrap();
1194        let beta = vec![0.6, 0.1, -0.1, 0.4];
1195        assert_penalty_gradient_matches_finite_difference(&penalty, &beta);
1196    }
1197
1198    #[test]
1199    #[allow(clippy::float_cmp)]
1200    fn slope_limit_penalty_try_new_validates_inputs() {
1201        let penalty = SlopeLimitPenalty::try_new(5.0, 2.0, Some(0.4), None).unwrap();
1202        assert_eq!(penalty.weight(), 5.0);
1203        assert_eq!(penalty.scale(), 2.0);
1204        assert_eq!(penalty.cold_limit(), Some(0.4));
1205        assert_eq!(penalty.warm_limit(), None);
1206        assert_eq!(
1207            SlopeLimitPenalty::try_new(0.0, 2.0, Some(0.4), None).unwrap_err(),
1208            ModelError::InvalidParameter {
1209                parameter: "penalty weight",
1210                expected: "finite and > 0",
1211            }
1212        );
1213        assert_eq!(
1214            SlopeLimitPenalty::try_new(5.0, f64::NAN, Some(0.4), None).unwrap_err(),
1215            ModelError::InvalidParameter {
1216                parameter: "penalty scale",
1217                expected: "finite and > 0",
1218            }
1219        );
1220        assert_eq!(
1221            SlopeLimitPenalty::try_new(5.0, 2.0, Some(-0.4), None).unwrap_err(),
1222            ModelError::InvalidParameter {
1223                parameter: "cold penalty limit",
1224                expected: "finite and >= 0",
1225            }
1226        );
1227    }
1228
1229    #[test]
1230    fn natural_cubic_validates_knots_and_has_linear_edges() {
1231        assert_eq!(
1232            NaturalCubicSplineBasis::new(vec![0.0]).unwrap_err(),
1233            SplineError::NotEnoughKnots { min: 2 }
1234        );
1235        assert_eq!(
1236            NaturalCubicSplineBasis::new(vec![0.0, f64::NAN]).unwrap_err(),
1237            SplineError::InvalidKnots
1238        );
1239
1240        let basis = NaturalCubicSplineBasis::new(vec![0.0, 0.5, 1.0]).unwrap();
1241        let left = basis.evaluate_derivative(-0.25);
1242        let at_left = basis.evaluate_derivative(0.0);
1243        let right = basis.evaluate_derivative(1.25);
1244        let at_right = basis.evaluate_derivative(1.0);
1245
1246        for index in 0..basis.n_basis() {
1247            assert_relative_eq!(left[index], at_left[index], epsilon = 1.0e-12);
1248            assert_relative_eq!(right[index], at_right[index], epsilon = 1.0e-12);
1249        }
1250    }
1251
1252    #[test]
1253    fn natural_cubic_design_gradient_matches_finite_difference() {
1254        let design = NaturalCubicSplineBasis::new(vec![0.0, 0.4, 0.7, 1.0])
1255            .unwrap()
1256            .design(&[0.0, 0.2, 0.8, 1.1])
1257            .unwrap();
1258        assert_predictor_gradient_matches_finite_difference(
1259            &design,
1260            &[0.4, -0.2, 0.7, 1.1],
1261            &[0.3, -0.8, 0.5, 1.0],
1262        );
1263    }
1264
1265    #[test]
1266    fn truncated_power_basis_uses_documented_column_order() {
1267        let basis = TruncatedPowerBasis::new(vec![0.25, 0.75], SplineOrder::Cubic, true).unwrap();
1268        let values = basis.evaluate(1.25);
1269
1270        assert_eq!(basis.n_basis(), 6);
1271        assert_eq!(basis.order(), SplineOrder::Cubic);
1272        assert!(basis.include_intercept());
1273        assert_relative_eq!(values[0], 1.0, epsilon = 1.0e-12);
1274        assert_relative_eq!(values[1], 1.25, epsilon = 1.0e-12);
1275        assert_relative_eq!(values[2], 1.25_f64.powi(2), epsilon = 1.0e-12);
1276        assert_relative_eq!(values[3], 1.25_f64.powi(3), epsilon = 1.0e-12);
1277        assert_relative_eq!(values[4], 1.0, epsilon = 1.0e-12);
1278        assert_relative_eq!(values[5], 0.5_f64.powi(3), epsilon = 1.0e-12);
1279    }
1280
1281    #[test]
1282    fn truncated_power_basis_validates_inputs_and_builds_uniform_knots() {
1283        assert_eq!(
1284            TruncatedPowerBasis::new(vec![0.0, 0.0], SplineOrder::Linear, true).unwrap_err(),
1285            SplineError::InvalidKnots
1286        );
1287        assert_eq!(
1288            TruncatedPowerBasis::uniform_from_data(&[0.0, f64::NAN], 1, SplineOrder::Linear, true)
1289                .unwrap_err(),
1290            SplineError::NonFiniteValue
1291        );
1292
1293        let basis =
1294            TruncatedPowerBasis::uniform_from_data(&[0.0, 0.5, 1.0], 2, SplineOrder::Linear, false)
1295                .unwrap();
1296        assert_relative_eq!(basis.knots()[0], 1.0 / 3.0, epsilon = 1.0e-12);
1297        assert_relative_eq!(basis.knots()[1], 2.0 / 3.0, epsilon = 1.0e-12);
1298        assert_eq!(basis.n_basis(), 3);
1299    }
1300
1301    #[test]
1302    fn truncated_power_buffer_evaluation_clears_stale_values() {
1303        let basis = TruncatedPowerBasis::new(vec![0.25, 0.75], SplineOrder::Cubic, true).unwrap();
1304        let mut values = vec![42.0; basis.n_basis()];
1305
1306        basis.evaluate_into(0.0, &mut values);
1307
1308        assert_relative_eq!(values[0], 1.0, epsilon = 1.0e-12);
1309        for value in &values[1..] {
1310            assert_relative_eq!(*value, 0.0, epsilon = 1.0e-12);
1311        }
1312    }
1313
1314    #[test]
1315    fn truncated_power_design_gradient_matches_finite_difference() {
1316        let design = TruncatedPowerBasis::new(vec![0.25, 0.75], SplineOrder::Cubic, true)
1317            .unwrap()
1318            .design(&[-0.2, 0.1, 0.5, 1.2])
1319            .unwrap();
1320        assert_predictor_gradient_matches_finite_difference(
1321            &design,
1322            &[0.2, -0.4, 0.7, 0.1, -0.3, 0.9],
1323            &[0.3, -0.8, 0.5, 1.0],
1324        );
1325        let generic = design.basis().on_demand_design(design.x()).unwrap();
1326        let scores = [0.3, -0.8, 0.5, 1.0];
1327        assert_eq!(design, generic);
1328        let dense = design.to_dense_design().unwrap();
1329        let dense_predictor = LinearPredictorBlock::new(&dense);
1330        assert_linear_geometry_matches(&design, &dense_predictor, &[0.2, 0.0, -0.4, 0.7], &scores);
1331        assert_row_basis_matches_evaluate(&design, |row| design.basis().evaluate(design.x()[row]));
1332
1333        let mut visited = Vec::new();
1334        crate::SplineRowBasis::for_each_row_basis(&design, 1, |index, weight| {
1335            visited.push((index, weight));
1336        });
1337        assert_eq!(visited.len(), 4);
1338        for ((actual_index, actual_weight), (expected_index, expected_weight)) in visited
1339            .iter()
1340            .zip([(0, 1.0), (1, 0.1), (2, 0.01), (3, 0.001)])
1341        {
1342            assert_eq!(*actual_index, expected_index);
1343            assert_relative_eq!(*actual_weight, expected_weight, epsilon = 1.0e-12);
1344        }
1345    }
1346
1347    #[test]
1348    fn spline_derivatives_match_finite_difference() {
1349        let x = [0.1, 0.25, 0.6, 0.9];
1350        let beta = vec![0.1, -0.4, 0.7, 0.2, -0.1, 0.5];
1351        assert_eta_derivative_matches_coordinate_difference(
1352            |points| {
1353                OpenUniformSplineDesign::with_range(points, 0.0, 1.0, 6, SplineOrder::Cubic)
1354                    .unwrap()
1355            },
1356            super::open_uniform::OpenUniformSplineDesign::eta_derivative_row,
1357            &x,
1358            &beta,
1359        );
1360
1361        let cyclic = CyclicSplineDesign::new(&x, 6, SplineOrder::Cubic).unwrap();
1362        assert_eta_derivative_matches_coordinate_difference(
1363            |points| CyclicSplineDesign::new(points, 6, SplineOrder::Cubic).unwrap(),
1364            super::cyclic::CyclicSplineDesign::eta_derivative_row,
1365            &x,
1366            &beta,
1367        );
1368
1369        let natural = NaturalCubicSplineBasis::new(vec![0.0, 0.4, 0.7, 1.0])
1370            .unwrap()
1371            .design(&x)
1372            .unwrap();
1373        let natural_beta = vec![0.1, -0.4, 0.7, 0.2];
1374        assert_eta_derivative_matches_coordinate_difference(
1375            |points| {
1376                NaturalCubicSplineBasis::new(vec![0.0, 0.4, 0.7, 1.0])
1377                    .unwrap()
1378                    .design(points)
1379                    .unwrap()
1380            },
1381            super::natural::NaturalCubicSplineDesign::eta_derivative_row,
1382            &x,
1383            &natural_beta,
1384        );
1385
1386        let m_basis = MSplineBasis::open_uniform_from_data(&[0.0, 1.0], 6, 3).unwrap();
1387        assert_eta_derivative_matches_coordinate_difference(
1388            |points| m_basis.design(points).unwrap(),
1389            super::mspline::MSplineDesign::eta_derivative_row,
1390            &x,
1391            &beta,
1392        );
1393
1394        let truncated = TruncatedPowerBasis::new(vec![0.3, 0.7], SplineOrder::Cubic, true)
1395            .unwrap()
1396            .design(&x)
1397            .unwrap();
1398        let truncated_beta = vec![0.1, -0.4, 0.7, 0.2, -0.1, 0.5];
1399        assert_eta_derivative_matches_coordinate_difference(
1400            |points| {
1401                TruncatedPowerBasis::new(vec![0.3, 0.7], SplineOrder::Cubic, true)
1402                    .unwrap()
1403                    .design(points)
1404                    .unwrap()
1405            },
1406            super::truncated_power::TruncatedPowerDesign::eta_derivative_row,
1407            &x,
1408            &truncated_beta,
1409        );
1410
1411        assert!(cyclic.eta_derivative_row(0, &beta).is_finite());
1412        assert!(natural.eta_derivative_row(0, &natural_beta).is_finite());
1413        assert!(truncated.eta_derivative_row(0, &truncated_beta).is_finite());
1414    }
1415
1416    #[test]
1417    fn periodic_spline_wraps_physical_coordinates_and_rejects_invalid_period() {
1418        assert_eq!(
1419            PeriodicSplineSpec::new(6, SplineOrder::Cubic, 0.0, 0.0).unwrap_err(),
1420            SplineError::InvalidPeriod
1421        );
1422
1423        let design =
1424            PeriodicSplineDesign::new(&[0.0, 12.0, 3.0, 15.0], 6, SplineOrder::Cubic, 12.0, 0.0)
1425                .unwrap();
1426        let beta = vec![0.2, -0.1, 0.7, 0.4, -0.3, 0.9];
1427
1428        assert_relative_eq!(
1429            design.eta_row(0, &beta),
1430            design.eta_row(1, &beta),
1431            epsilon = 1.0e-12
1432        );
1433        assert_relative_eq!(
1434            design.eta_row(2, &beta),
1435            design.eta_row(3, &beta),
1436            epsilon = 1.0e-12
1437        );
1438        assert!(design.eta_derivative_row(2, &beta).is_finite());
1439    }
1440
1441    #[test]
1442    #[allow(clippy::suboptimal_flops, clippy::cast_precision_loss)]
1443    fn tensor_spline_matches_rowwise_kronecker_and_gradient() {
1444        let x = [0.0, 0.3, 0.8];
1445        let left =
1446            OpenUniformSplineDesign::with_range(&x, 0.0, 1.0, 4, SplineOrder::Cubic).unwrap();
1447        let right = CyclicSplineDesign::new(&x, 5, SplineOrder::Cubic).unwrap();
1448        let tensor = TensorSplineDesign::new(left.clone(), right.clone()).unwrap();
1449        let beta = (0..tensor.nparams())
1450            .map(|index| index as f64 / 10.0)
1451            .collect::<Vec<_>>();
1452
1453        let row = 1;
1454        let mut expected = 0.0;
1455        for left_index in 0..left.nparams() {
1456            let mut left_unit = vec![0.0; left.nparams()];
1457            left_unit[left_index] = 1.0;
1458            let left_weight = left.eta_row(row, &left_unit);
1459            for right_index in 0..right.nparams() {
1460                let mut right_unit = vec![0.0; right.nparams()];
1461                right_unit[right_index] = 1.0;
1462                let right_weight = right.eta_row(row, &right_unit);
1463                expected +=
1464                    beta[left_index * right.nparams() + right_index] * left_weight * right_weight;
1465            }
1466        }
1467
1468        assert_relative_eq!(tensor.eta_row(row, &beta), expected, epsilon = 1.0e-12);
1469        assert_predictor_gradient_matches_finite_difference(&tensor, &beta, &[0.5, -0.2, 0.9]);
1470        assert_eq!(tensor.n_basis(), beta.len());
1471
1472        let dense = tensor.to_dense_design().unwrap();
1473        let dense_predictor = LinearPredictorBlock::new(&dense);
1474        assert_linear_geometry_matches(
1475            &tensor,
1476            &dense_predictor,
1477            &[0.2, 0.0, -0.4],
1478            &[0.5, -0.2, 0.9],
1479        );
1480
1481        let short = CyclicSplineDesign::new(&[0.0], 5, SplineOrder::Cubic).unwrap();
1482        assert_eq!(
1483            TensorSplineDesign::new(left, short).unwrap_err(),
1484            SplineError::RowMismatch {
1485                expected: 3,
1486                actual: 1
1487            }
1488        );
1489    }
1490
1491    #[test]
1492    fn m_and_i_splines_are_nonnegative_monotone_and_differentiable() {
1493        let x = [0.0, 0.2, 0.5, 0.8, 1.0];
1494        let m = MSplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
1495        let i = ISplineBasis::open_uniform_from_data(&x, 6, 3).unwrap();
1496
1497        for value in [0.1, 0.35, 0.7] {
1498            for weight in m.evaluate(value) {
1499                assert!(weight >= -1.0e-12);
1500            }
1501        }
1502
1503        for basis_index in 0..i.n_basis() {
1504            let a = i.evaluate(0.25)[basis_index];
1505            let b = i.evaluate(0.75)[basis_index];
1506            assert!(a <= b + 1.0e-12);
1507            assert_relative_eq!(i.evaluate(-0.1)[basis_index], 0.0, epsilon = 1.0e-12);
1508            assert_relative_eq!(i.evaluate(1.1)[basis_index], 1.0, epsilon = 1.0e-9);
1509        }
1510
1511        let point = 0.43;
1512        let eps = 1.0e-6;
1513        for basis_index in 0..m.n_basis() {
1514            let finite = (m.evaluate(point + eps)[basis_index]
1515                - m.evaluate(point - eps)[basis_index])
1516                / (2.0 * eps);
1517            assert_relative_eq!(
1518                m.evaluate_derivative(point)[basis_index],
1519                finite,
1520                epsilon = 1.0e-5
1521            );
1522        }
1523
1524        for basis_index in 0..i.n_basis() {
1525            let finite = (i.evaluate(point + eps)[basis_index]
1526                - i.evaluate(point - eps)[basis_index])
1527                / (2.0 * eps);
1528            assert_relative_eq!(
1529                i.evaluate_derivative(point)[basis_index],
1530                finite,
1531                epsilon = 1.0e-5
1532            );
1533        }
1534    }
1535
1536    #[test]
1537    fn monotone_i_spline_is_hard_monotone_and_gradient_matches_finite_difference() {
1538        let x = [0.0, 0.2, 0.5, 0.8, 1.0];
1539        let basis = ISplineBasis::open_uniform_from_data(&x, 5, 2).unwrap();
1540        let design =
1541            MonotoneISplineDesign::new(&x, basis.clone(), MonotoneDirection::Increasing).unwrap();
1542        let beta = vec![0.1, -1.0, 0.2, -0.4, 0.7, 1.0];
1543
1544        for row in 1..design.nrows() {
1545            assert!(design.eta_row(row - 1, &beta) <= design.eta_row(row, &beta) + 1.0e-12);
1546            assert!(design.eta_derivative_row(row, &beta) >= -1.0e-10);
1547        }
1548
1549        assert_predictor_gradient_matches_finite_difference(
1550            &design,
1551            &beta,
1552            &[0.2, -0.3, 0.5, 0.7, -0.1],
1553        );
1554
1555        let decreasing =
1556            MonotoneISplineDesign::new(&x, basis, MonotoneDirection::Decreasing).unwrap();
1557        for row in 1..decreasing.nrows() {
1558            assert!(decreasing.eta_row(row - 1, &beta) >= decreasing.eta_row(row, &beta) - 1.0e-12);
1559        }
1560    }
1561
1562    fn assert_penalty_gradient_matches_finite_difference<P>(penalty: &P, beta: &[f64])
1563    where
1564        P: Penalty,
1565    {
1566        let eps = 1.0e-6;
1567        let mut grad = vec![0.0; beta.len()];
1568
1569        penalty.add_gradient(beta, &mut grad);
1570
1571        for index in 0..beta.len() {
1572            let mut plus = beta.to_vec();
1573            plus[index] += eps;
1574            let mut minus = beta.to_vec();
1575            minus[index] -= eps;
1576            let finite_difference = (penalty.value(&plus) - penalty.value(&minus)) / (2.0 * eps);
1577
1578            assert_relative_eq!(grad[index], finite_difference, epsilon = 1.0e-6);
1579        }
1580    }
1581
1582    fn assert_zero_lambda_penalty_is_noop<P>(penalty: &P, beta: &[f64])
1583    where
1584        P: Penalty,
1585    {
1586        let mut grad = vec![1.0, -2.0, 3.0];
1587
1588        assert_relative_eq!(penalty.value(beta), 0.0, epsilon = 0.0);
1589        penalty.add_gradient(beta, &mut grad);
1590        assert_eq!(grad, vec![1.0, -2.0, 3.0]);
1591    }
1592
1593    fn assert_nonnegative_partition_of_unity(values: &[f64]) {
1594        let sum = values.iter().sum::<f64>();
1595        assert_relative_eq!(sum, 1.0, epsilon = 1.0e-12);
1596        for &basis_value in values {
1597            assert!(
1598                basis_value >= -1.0e-14,
1599                "basis value {basis_value} is negative"
1600            );
1601        }
1602    }
1603
1604    fn assert_single_active_endpoint_basis(values: &[f64], active_index: usize) {
1605        for (index, &value) in values.iter().enumerate() {
1606            let expected = if index == active_index { 1.0 } else { 0.0 };
1607            assert_relative_eq!(value, expected, epsilon = 1.0e-12);
1608        }
1609    }
1610
1611    fn assert_penalty_matrix_matches_gradient<P>(penalty: &P, beta: &[f64])
1612    where
1613        P: MatrixPenalty,
1614    {
1615        let dim = beta.len();
1616        let mut grad = vec![0.0; dim];
1617        let mut matrix = vec![0.0; dim * dim];
1618
1619        penalty.add_gradient(beta, &mut grad);
1620        penalty.add_penalty_matrix(dim, &mut matrix);
1621
1622        for (row, row_values) in matrix.chunks_exact(dim).enumerate() {
1623            let actual = row_values
1624                .iter()
1625                .copied()
1626                .zip(beta.iter().copied())
1627                .map(|(matrix_value, beta_value)| matrix_value * beta_value)
1628                .sum::<f64>();
1629            assert_relative_eq!(actual, grad[row], epsilon = 1.0e-12);
1630        }
1631    }
1632
1633    fn assert_matrix_penalty_matches<Actual, Expected>(
1634        actual: &Actual,
1635        expected: &Expected,
1636        beta: &[f64],
1637    ) where
1638        Actual: MatrixPenalty,
1639        Expected: MatrixPenalty,
1640    {
1641        let dim = beta.len();
1642        let mut actual_grad = vec![0.0; dim];
1643        let mut expected_grad = vec![0.0; dim];
1644        let mut actual_matrix = vec![0.0; dim * dim];
1645        let mut expected_matrix = vec![0.0; dim * dim];
1646
1647        actual.add_gradient(beta, &mut actual_grad);
1648        expected.add_gradient(beta, &mut expected_grad);
1649        actual.add_penalty_matrix(dim, &mut actual_matrix);
1650        expected.add_penalty_matrix(dim, &mut expected_matrix);
1651
1652        assert_relative_eq!(actual.value(beta), expected.value(beta), epsilon = 1.0e-12);
1653        for (actual, expected) in actual_grad.iter().zip(&expected_grad) {
1654            assert_relative_eq!(actual, expected, epsilon = 1.0e-12);
1655        }
1656        for (actual, expected) in actual_matrix.iter().zip(&expected_matrix) {
1657            assert_relative_eq!(actual, expected, epsilon = 1.0e-12);
1658        }
1659    }
1660
1661    fn assert_predictor_gradient_matches_finite_difference<P>(
1662        predictor: &P,
1663        beta: &[f64],
1664        scores: &[f64],
1665    ) where
1666        P: PredictorBlock,
1667    {
1668        let eps = 1.0e-6;
1669        let mut grad = vec![0.0; beta.len()];
1670
1671        predictor.add_gradient(scores, beta, &mut grad);
1672
1673        let split = predictor.nrows() / 2;
1674        let mut tiled_grad = vec![0.0; beta.len()];
1675        predictor.add_gradient_range(0..split, &scores[..split], beta, &mut tiled_grad);
1676        predictor.add_gradient_range(
1677            split..predictor.nrows(),
1678            &scores[split..],
1679            beta,
1680            &mut tiled_grad,
1681        );
1682        for (actual, expected) in tiled_grad.iter().zip(&grad) {
1683            assert_relative_eq!(actual, expected, epsilon = 1.0e-12);
1684        }
1685
1686        for index in 0..beta.len() {
1687            let mut plus = beta.to_vec();
1688            plus[index] += eps;
1689            let mut minus = beta.to_vec();
1690            minus[index] -= eps;
1691
1692            let objective = |candidate: &[f64]| {
1693                (0..predictor.nrows())
1694                    .map(|row| scores[row] * predictor.eta_row(row, candidate))
1695                    .sum::<f64>()
1696            };
1697            let finite_difference = (objective(&plus) - objective(&minus)) / (2.0 * eps);
1698
1699            assert_relative_eq!(grad[index], finite_difference, epsilon = 1.0e-6);
1700        }
1701    }
1702
1703    #[allow(clippy::cast_precision_loss)]
1704    fn assert_linear_geometry_matches<Prepared, OnDemand>(
1705        prepared: &Prepared,
1706        on_demand: &OnDemand,
1707        row_weights: &[f64],
1708        row_scores: &[f64],
1709    ) where
1710        Prepared: LinearPredictorGeometry,
1711        OnDemand: LinearPredictorGeometry,
1712    {
1713        assert_eq!(prepared.nrows(), on_demand.nrows());
1714        assert_eq!(prepared.nparams(), on_demand.nparams());
1715        assert_eq!(prepared.nrows(), row_weights.len());
1716        assert_eq!(prepared.nrows(), row_scores.len());
1717        let nparams = prepared.nparams();
1718
1719        let mut prepared_gram = vec![0.5; nparams * nparams];
1720        let mut on_demand_gram = prepared_gram.clone();
1721        prepared
1722            .add_weighted_gram(row_weights, &mut prepared_gram)
1723            .unwrap();
1724        on_demand
1725            .add_weighted_gram(row_weights, &mut on_demand_gram)
1726            .unwrap();
1727        for (prepared, on_demand) in prepared_gram.iter().zip(&on_demand_gram) {
1728            assert_relative_eq!(*prepared, on_demand, epsilon = 1.0e-12);
1729        }
1730
1731        let mut prepared_transpose = vec![-0.25; nparams];
1732        let mut on_demand_transpose = prepared_transpose.clone();
1733        prepared
1734            .add_t_mul_vec(row_scores, &mut prepared_transpose)
1735            .unwrap();
1736        on_demand
1737            .add_t_mul_vec(row_scores, &mut on_demand_transpose)
1738            .unwrap();
1739        for (prepared, on_demand) in prepared_transpose.iter().zip(&on_demand_transpose) {
1740            assert_relative_eq!(*prepared, on_demand, epsilon = 1.0e-12);
1741        }
1742
1743        let multipliers = row_weights
1744            .iter()
1745            .zip(row_scores)
1746            .enumerate()
1747            .map(|(row, (&weight, &score))| {
1748                if weight == 0.0 && score == 0.0 {
1749                    f64::NAN
1750                } else {
1751                    0.5 + row as f64
1752                }
1753            })
1754            .collect::<Vec<_>>();
1755
1756        prepared_gram.fill(0.75);
1757        on_demand_gram.fill(0.75);
1758        prepared
1759            .add_weighted_gram_by(row_weights, multipliers.as_slice(), &mut prepared_gram)
1760            .unwrap();
1761        on_demand
1762            .add_weighted_gram_by(row_weights, multipliers.as_slice(), &mut on_demand_gram)
1763            .unwrap();
1764        for (prepared, on_demand) in prepared_gram.iter().zip(on_demand_gram) {
1765            assert_relative_eq!(*prepared, on_demand, epsilon = 1.0e-12);
1766        }
1767
1768        prepared_transpose.fill(-0.75);
1769        on_demand_transpose.fill(-0.75);
1770        prepared
1771            .add_t_mul_vec_by(row_scores, multipliers.as_slice(), &mut prepared_transpose)
1772            .unwrap();
1773        on_demand
1774            .add_t_mul_vec_by(row_scores, multipliers.as_slice(), &mut on_demand_transpose)
1775            .unwrap();
1776        for (prepared, on_demand) in prepared_transpose.iter().zip(on_demand_transpose) {
1777            assert_relative_eq!(*prepared, on_demand, epsilon = 1.0e-12);
1778        }
1779    }
1780
1781    #[allow(clippy::cast_precision_loss)]
1782    fn assert_spline_predictors_match<Prepared, OnDemand>(
1783        prepared: &Prepared,
1784        on_demand: &OnDemand,
1785        beta: &[f64],
1786        scores: &[f64],
1787    ) where
1788        Prepared: PredictorBlock,
1789        OnDemand: PredictorBlock,
1790    {
1791        assert_eq!(prepared.nrows(), on_demand.nrows());
1792        assert_eq!(prepared.nparams(), on_demand.nparams());
1793        assert_eq!(prepared.nrows(), scores.len());
1794        assert_eq!(prepared.nparams(), beta.len());
1795
1796        for row in 0..prepared.nrows() {
1797            assert_relative_eq!(
1798                prepared.eta_row(row, beta),
1799                on_demand.eta_row(row, beta),
1800                epsilon = 1.0e-12
1801            );
1802        }
1803
1804        let mut prepared_gradient = vec![0.25; beta.len()];
1805        let mut on_demand_gradient = prepared_gradient.clone();
1806        prepared.add_gradient(scores, beta, &mut prepared_gradient);
1807        on_demand.add_gradient(scores, beta, &mut on_demand_gradient);
1808        for (prepared, on_demand) in prepared_gradient.iter().zip(&on_demand_gradient) {
1809            assert_relative_eq!(*prepared, on_demand, epsilon = 1.0e-12);
1810        }
1811
1812        let multipliers = scores
1813            .iter()
1814            .copied()
1815            .enumerate()
1816            .map(|(row, score)| {
1817                if score == 0.0 {
1818                    f64::NAN
1819                } else {
1820                    0.5 + row as f64
1821                }
1822            })
1823            .collect::<Vec<_>>();
1824        prepared_gradient.fill(-0.5);
1825        on_demand_gradient.fill(-0.5);
1826        prepared.add_weighted_gradient(scores, &multipliers, beta, &mut prepared_gradient);
1827        on_demand.add_weighted_gradient(scores, &multipliers, beta, &mut on_demand_gradient);
1828        for (prepared, on_demand) in prepared_gradient.iter().zip(&on_demand_gradient) {
1829            assert_relative_eq!(*prepared, on_demand, epsilon = 1.0e-12);
1830        }
1831    }
1832
1833    fn assert_eta_derivative_matches_coordinate_difference<P>(
1834        build: impl Fn(&[f64]) -> P,
1835        derivative: impl Fn(&P, usize, &[f64]) -> f64,
1836        x: &[f64],
1837        beta: &[f64],
1838    ) where
1839        P: PredictorBlock,
1840    {
1841        let eps = 1.0e-6;
1842        let design = build(x);
1843        for row in 0..x.len() {
1844            let mut plus_x = x.to_vec();
1845            plus_x[row] += eps;
1846            let plus = build(&plus_x);
1847            let mut minus_x = x.to_vec();
1848            minus_x[row] -= eps;
1849            let minus = build(&minus_x);
1850            let finite_difference =
1851                (plus.eta_row(row, beta) - minus.eta_row(row, beta)) / (2.0 * eps);
1852
1853            assert_relative_eq!(
1854                derivative(&design, row, beta),
1855                finite_difference,
1856                epsilon = 1.0e-5
1857            );
1858        }
1859    }
1860
1861    fn assert_row_basis_matches_evaluate<B>(basis: &B, evaluate: impl Fn(usize) -> Vec<f64>)
1862    where
1863        B: super::SplineRowBasis,
1864    {
1865        for row in 0..basis.nrows() {
1866            let expected = evaluate(row);
1867            let mut actual = vec![0.0; basis.nparams()];
1868            basis.for_each_row_basis(row, |index, weight| {
1869                actual[index] = weight;
1870            });
1871            for (actual, expected) in actual.iter().zip(expected) {
1872                assert_relative_eq!(*actual, expected, epsilon = 1.0e-12);
1873            }
1874        }
1875    }
1876}