Module basis 

Spline / spatial / spherical basis construction, penalties, and the hyperparameter (ψ) derivative machinery that the smooth terms build on.

The module is decomposed into single-concern submodules. Shared crate imports live in prelude.rs and are pulled into this module’s namespace; every submodule re-imports them (together with the sibling re-exports below) through use super::*. The pub use <module>::* re-exports flatten each concern back onto the basis:: path so external callers keep referring to e.g. basis::CenterStrategy regardless of which submodule now owns the item.

Re-exports

pub use closed_form_operator::ClosedFormPenaltyOperator;

pub use ispline_boundary::*;

pub use ispline_ramp::*;

Modules

closed_form_operator

Operator form of the closed-form Duchon penalty.

closed_form_penalty

Closed-form scalar building blocks for Riesz, Matérn, and isotropic hybrid Duchon kernels.

input_loc_derivatives

Input-location derivatives of basis design columns.

ispline_boundary

What an I-spline basis does OUTSIDE its knot range, as a declared policy rather than as a convention each consumer re-derives.

ispline_ramp

The monotone I-spline ramp basis: one function on all of ℝ, for any knot vector, with every derivative order read off that same function.

matern_gradient

Streaming closed-form gradients for Matérn radial basis values.

radial_profile

Certified 1-D Chebyshev profile of the radial design scalars (φ, q, t).

sphere_gpu

GPU NVRTC Wahba intrinsic-S2 kernel matrix construction.

Structs

ActivePenalty

One atomic active penalty identity.

ActivePenaltyInfo

Metadata for one retained penalty coordinate.

AnisoBasisPsiDerivatives

Per-axis psi_a derivative package for anisotropic spatial terms.

AnisoPenaltyCrossProvider

AutoBSplineKnots

Result of auto-deriving a clamped B-spline knot vector from 1-D data.

BSplineBasisSpec

1D B-spline basis configuration.

BSplineBoundaryConditions

Left/right pair of B-spline endpoint constraints.

BasisBuildResult

Standardized basis build result for engine-level composition.

BasisOptions

Options for basis generation, controlling derivative order.

BasisPsiDerivativeBundle

BasisPsiDerivativeResult

BasisPsiSecondDerivativeResult

BasisWorkspace

Explicit per-run workspace for reusable basis-construction caches.

BsplineDerivativeWorkspace

Reusable scratch arena for the shared B-spline higher-derivative recurrence.

CanonicalPenaltyBlock

CollocationOperatorMatrices

ConstantCurvatureBasisSpec

Constant-curvature smooth configuration (curv(x, z, kappa = …)).

ConstantCurvatureKernelPsiJets

The (k, ∂k/∂ψ_a, ∂²k/∂ψ_a∂ψ_b) tower of the raw (pre-constraint) model kernel matrix in BOTH outer coordinates, ψ = (κ, η) with η = ln ℓ.

ConstantCurvaturePsiJets

Design and penalty jets of the realized constant-curvature smooth in BOTH outer coordinates, ψ = (κ, η) with η = ln ℓ (gam#2747).

ConstructiveQuadratic

A positive-semidefinite quadratic with a construction witness.

CubicRegressionBasis

Precomputed natural cubic regression spline geometry for a fixed knot set.

Dense

Marker type for dense basis matrix output.

DroppedPenaltyInfo

Diagnostic for one penalty candidate excluded from the optimizer layout. It is intentionally a different type from ActivePenaltyInfo so a dropped record cannot be used as an active matrix index.

DuchonBasisSpec

Duchon-like basis configuration with explicit low-frequency null-space control and explicit spectral power.

DuchonOperatorPenaltyMatrices

DuchonOperatorPenaltySpec

DuchonPartialFractionCoeffs

FilteredPenalties

ImplicitDesignPsiDerivative

Implicit representation of ∂X/∂ψ_d that supports matrix-vector products without materializing the full (n x p) derivative matrices.

IsplineFunctionPenalties

Exact function-space penalties for the anchored I-spline basis.

JointNullRotation

Joint-null absorption rotation, attached to a smooth’s basis when the basis’s joint penalty Σ_k S_k has a non-trivial null space.

KroneckerFactoredBasis

Factored tensor-product basis metadata for operator-backed downstream use.

LIndex

A single requested derivative direction in L-space: the lower-triangular entry (i, j) with i >= j. The zeroth-order “direction” (the value itself) is handled separately; this names the active first-order channels.

LatentCoordDesignDerivative

Streaming design derivative for one per-row latent coordinate t[n, a].

MaternBasisSpec

Matérn basis configuration.

MaternSplineBasis

Matérn radial basis and penalties.

MeasureJetAnisotropyJets

The anisotropic energy together with its exact first and second jets with respect to the lower-triangular Cholesky factor entries of L.

MeasureJetBand

Realized geometric scale band: eps ascending, log_step the constant log-spacing ln(eps[ℓ+1]/eps[ℓ]) used as the Mellin quadrature weight.

MeasureJetBasisSpec

Measure-jet smooth configuration (mjs(x0, …, xd)).

MeasureJetEnergyJets

The energy and its exact hyperparameter jets in the live dials. s and α enter only through per-block log-weights. The retained ln τ slots are zero because the local fit is the exact weighted affine projection and no longer depends on τ. All forms are scattered from the SAME local residual blocks, and the ψ-channel consumes them with zero design drift.

MeasureJetFrozenQuadrature

Fit-time quadrature of the empirical measure (center masses + realized scale band), frozen onto the spec so predict-time rebuilds replay the exact fit-time penalty. Recomputing either from predict rows would silently change the penalty the coefficients were estimated under.

MeasureJetJetStats

The local jet-fit sufficient statistics read off one table — exactly the per-block quantities assemble_weighted_forms (measure_jet_smooth.rs) computes from raw points when the table weights are frozen at the same center and scale, reproduced in closed form from stored moments.

MeasureJetMomentTable

Per-cell moment table: Gaussian-weighted coordinate moments of orders 0..=2 crossed with response channels, all centered at the cell’s reference point c.

MeasureJetRangeBracket

The deterministic bracket the representer range ℓ is SCREENED over before the outer ψ search refines it, in the STANDARDIZED frame the basis is realized in (gam#2750).

ParametricResidualization

The span-preserving orthogonalization of a smooth design against a constraint block: the realized block becomes X·T − C·R.

PenaltyCandidate

PeriodicBSplineBasisSpec

Configuration for a dense one-dimensional periodic B-spline basis.

PeriodicSplineCurve

Fitted vector-valued periodic spline curve.

ResolvedDuchonChart

A DuchonBasisSpec with every ψ-invariant chart decision resolved against the data, plus the artifacts those decisions produced.

Sparse

Marker type for sparse basis matrix output.

SpatialBasisPlan

Resource-aware plan for a spatial smooth (Duchon / Matérn / TPS).

SphericalSplineBasisSpec

Intrinsic S² (sphere) smooth configuration.

SplineScratch

Scratch memory for B-spline evaluation to avoid allocations in tight loops.

ThinPlateBasisSpec

Thin-plate basis configuration.

ThinPlatePenaltyMatrix

ThinPlateSplineBasis

Thin-plate regression spline basis and penalty (order m=2).

Enums

AnisoSeedMode

How the Matérn forward design build interprets an exactly all-zero aniso_log_scales vector.

BSplineEndpointBoundaryCondition

Per-endpoint boundary constraint policy for B-spline 1D bases.

BSplineIdentifiability

Per-smooth identifiability policy for 1D B-spline bases.

BSplineKnotPlacement

Internal-knot placement strategy when knots are automatically inferred.

BSplineKnotSpec

Which knot strategy to use for 1D B-spline bases.

BasisError

Re-export of the neutral basis-error contract. #1521: BasisError lives in gam-problem so EstimationError can wrap it (#[from]) without a back-edge; gam-terms re-exports it to preserve gam_terms::basis::BasisError. A comprehensive error type for all operations within the basis module.

BasisEvalKind

BasisFamily

Basis-family selector for 1D spline evaluation.

BasisMetadata

Metadata returned by generic basis builders.

BasisStorageLayout

Storage layout discriminant for BasisOutputFormat impls. Encoded as an enum rather than a bool so the type-level distinction reads as “Dense vs Sparse” at call sites instead of a polarity-sensitive flag.

CenterCountRequest

How plan_spatial_basis should pick the spatial center count.

CenterStrategy

Spatial center selection strategy.

CenterStrategyKind

ConstantCurvatureIdentifiability

Realized-design identifiability policy for the constant-curvature smooth. Mirrors super::SphericalSplineIdentifiability (#532): the fit-time center-space sum-to-zero z gets the parametric orthogonalization composed onto it by the global identifiability pipeline, and the composed transform is frozen here so predict-time (and future per-ψ-trial) rebuilds replay it verbatim instead of recomputing z from the centers.

DuchonNullspaceOrder

Duchon null-space polynomial degree.

DuchonPsiDirection

The outer coordinate a Duchon ψ-derivative differentiates (gam#2735).

DuchonSpectralBasis

Explicit low-rank spectral construction for a Duchon kernel.

KnotSource

Specifies the source of knots for basis generation.

MaternIdentifiability

Per-smooth identifiability policy for Matérn kernel coefficients.

MaternLengthScale

User intent and resolved numeric state for a Matérn kernel length scale.

MaternNu

Matérn smoothness parameter nu (half-integer variants with closed forms).

MeasureJetExtrapolationSpectrum

MeasureJetIdentifiability

Realized-design identifiability policy for the measure-jet smooth. Mirrors super::ConstantCurvatureIdentifiability (#532): the fit-time section gets the parametric orthogonalization composed onto it by the global identifiability pipeline, and the composed transform is frozen so predict-time (and per-ψ-trial) rebuilds replay it verbatim.

OneDimensionalBoundary

Boundary-condition policy for one-dimensional smooth bases.

OperatorPenaltySpec

PenaltyDropReason

PenaltySource

RadialScalarKind

Which radial kernel family is being used. Stored in the streaming operator so that (q, t) scalars can be recomputed on the fly without a closure.

SpatialIdentifiability

Per-smooth identifiability policy for spatial (TPS / Duchon) bases.

SpatialStorageMode

Storage mode recommended by plan_spatial_basis.

SphereMethod

Which intrinsic S² smooth construction to use.

SphereWahbaKernel

Which reproducing kernel to use for SphereMethod::Wahba.

SphericalSplineIdentifiability

Realized-design identifiability policy for the Wahba spherical spline (#532).

Traits

BasisOutput

Trait for selecting basis storage format at compile time.

BasisOutputFormat

Trait for building basis matrices with different storage formats. This is an implementation detail for the unified create_basis function.

LocalDesignJacobianProvider

The complete contract a per-row latent / novel-manifold coordinate type must supply to participate in the REML design-derivative operator surface.

Functions

accumulate_moment_table

Accumulate one cell’s moment table from raw rows. The single point where data rows are read; everything downstream is closed-form algebra on the result.

analyze_penalty_block

analyze_penalty_block_with_op

apply_linear_extension_from_first_derivative

Applies first-order linear extension outside a knot-domain interval to a basis matrix that was evaluated at clamped coordinates.

apply_sum_to_zero_constraint

Applies a sum-to-zero constraint to a basis matrix for model identifiability.

apply_sum_to_zero_constraint_sparse

Build a sum-to-zero reparametrization for a sparse basis.

applyweighted_orthogonality_constraint

Reparameterizes a basis matrix so its columns are orthogonal (with optional weights) to a supplied constraint matrix.

assert_no_dense_derivative_materialization

assert_spatial_centers_below_large_scale_cap

auto_centers_1d_equal_mass

Place num_centers Duchon centers on 1-D data via the equal-mass strategy.

auto_knot_vector_1d_quantile

Build a clamped B-spline full knot vector from 1-D data.

auto_spatial_center_strategy

auto_streaming_chunk_size_for_dense

Auto-derive a streaming row chunk size for dense basis evaluation.

basis_is_saturated

Is a fitted spatial smooth’s basis SATURATED — i.e. does its own evidence say the data wants more resolution than its realized coefficient span provides (#1689)?

bspline_derivative_penalty_factor

Constructive energy factor for the exact open B-spline roughness.

bspline_derivative_penalty_matrix

Exact open/clamped B-spline roughness penalty S_ij = ∫ B_i^{(order)} B_j^{(order)} dx over the modeling interval [t_degree, t_{num_basis}].

bspline_tensor_first_derivative

Tensor-product 1-D-B-spline first-derivative jet ∂Φ/∂t per row.

build_bspline_basis_1d

Generic 1D B-spline builder returning design + penalty list.

build_constant_curvature_basis

Build the constant-curvature reproducing-kernel smooth: realized design K_κ(data, centers)·z, RKHS penalty zᵀ K_κ(centers, centers) z, and the replayable BasisMetadata::ConstantCurvature. Structure mirrors the Wahba S² builder (build_spherical_spline_basis); geometry comes from ConstantCurvature at the spec’s fixed κ.

build_constant_curvature_basis_kappa_derivatives

The κ slice of build_constant_curvature_basis_psi_derivatives, in the generic BasisPsiDerivativeBundle shape the isotropic spatial ψ-channel consumes for callers that hold the range fixed.

build_constant_curvature_basis_psi_derivatives

Full (κ, η) derivative bundle for the constant-curvature smooth — the outer-channel hook that lets the signed curvature AND the kernel range join the REML optimization as two design-moving coordinates.

build_cubic_regression_basis_1d

Build a natural cubic regression spline (mgcv bs="cr"/"cs", #1074) basis from a fixed Lancaster–Salkauskas knot set.

build_duchon_basis

Generic Duchon builder returning design + penalty list.

build_duchon_basis_design_and_jets

Forward design, input-location first jet, and input-location second jet (Hessian) of the general Duchon basis — the same matrix build_duchon_basis / build_duchon_basis_mixed_periodicity_auto produce for the resolved spec, differentiated exactly.

build_duchon_basis_log_kappa_aniso_derivativeswith_collocationwithworkspace

Per-axis ψ derivatives of a hybrid Duchon basis — the anisotropic sibling of build_duchon_basis_log_kappa_derivativeswith_collocationwithworkspace (gam#2735).

build_duchon_basis_log_kappa_derivative

build_duchon_basis_log_kappa_derivatives

build_duchon_basis_log_kappa_derivativeswith_collocationwithworkspace

build_duchon_basis_log_kappa_derivativeswithworkspace

build_duchon_basis_log_kappa_derivativewithworkspace

build_duchon_basis_log_kappasecond_derivative

build_duchon_basis_log_kappasecond_derivativewithworkspace

build_duchon_basis_mixed_periodicity_auto

Public driver for the mixed-periodicity Duchon basis: derives per-axis (left_j, period_j) from the supplied centers (mirroring how the 1D periodic path infers the period from min/max), then dispatches into build_duchon_basis_mixed_periodicity.

build_duchon_basis_spec_chart

Build a Duchon design whose COLUMN SPACE is a property of the spec alone (gam#237).

build_duchon_basiswithworkspace

build_duchon_collocation_operator_matrices

build_duchon_collocation_operator_matriceswithworkspace

build_duchon_native_penalty_psi_derivatives

build_duchon_native_penalty_psi_derivatives_in_directions

The native (kernel-Gram + trend-ridge) penalty ψ-derivatives, one bundle per requested DuchonPsiDirection.

build_duchon_operator_penalty_matrices

build_duchon_operator_penalty_psi_derivatives

build_duchon_operator_penalty_psi_derivatives_in_directions

The operator-collocation penalty ψ-derivatives, one bundle per requested DuchonPsiDirection — and the per-axis bundles are the isotropic one scaled, because the operator penalties DO NOT DEPEND ON η (gam#2735).

build_matern_basis

build_matern_basis_literal_aniso

Public forward Matérn design that honors an explicit all-zero aniso_log_scales literally as the isotropic metric, rather than the κ-optimizer’s geometry-seeding sentinel. This is what the public matern_basis FFI evaluates, so a caller’s explicit isotropic request is not silently hijacked into a data-driven anisotropic kernel (#1042). For every internal/fit build, use build_matern_basis (auto-seed).

build_matern_basis_log_kappa_aniso_derivatives

Build per-axis ψ_a derivatives for anisotropic Matérn terms, including both design-matrix and penalty derivatives.

build_matern_basis_log_kappa_derivative

build_matern_basis_log_kappa_derivatives

build_matern_basis_log_kappa_derivativeswithworkspace

build_matern_basis_log_kappa_derivativewithworkspace

build_matern_basis_log_kappasecond_derivative

build_matern_basis_log_kappasecond_derivativewithworkspace

build_matern_basiswithworkspace

build_matern_collocation_operator_matrices

build_matern_operator_penalty_psi_derivatives

build_measure_jet_basis

Build the measure-jet smooth: Gaussian representer design K(data, centers)·z, multiscale jet-residual penalty (one candidate per scale in spectral mode, one Primary in pinned-order mode), an optional separate function-space null-component candidate, and the replayable BasisMetadata::MeasureJet. The geometry comes from the empirical measure (centers + masses + band) through the shared realization helper — the same source the ψ-derivative producer uses.

build_measure_jet_basis_psi_derivatives

Exact ψ-jets of the REALIZED measure-jet penalty candidates, adapted to the anisotropic group-ψ carrier the spatial optimizer consumes.

build_periodic_bspline_basis_1d

Build a dense periodic cardinal B-spline design for one circular parameter.

build_spherical_spline_basis

build_thin_plate_basis

Generic thin-plate builder returning design + penalty list.

build_thin_plate_basis_log_kappa_derivative

build_thin_plate_basis_log_kappa_derivatives

build_thin_plate_basis_log_kappa_derivativeswithworkspace

build_thin_plate_basis_log_kappa_derivativewithworkspace

build_thin_plate_basis_log_kappasecond_derivative

build_thin_plate_basis_log_kappasecond_derivativewithworkspace

build_thin_plate_basiswithworkspace

build_thin_plate_penalty_matrix

build_thin_plate_penalty_psi_derivativeswithworkspace

center_strategy_is_auto

center_strategy_kind

center_strategy_num_centers

center_strategy_with_num_centers

clamped_knot_vector_from_internal_positions

Build a clamped full B-spline knot vector from explicit internal knot positions (mgcv knots= semantics).

closed_form_aniso_psi_derivatives_in_total_basis

Closed-form anisotropic penalty S_q and its raw-η derivatives — full d×d Hessian materialized — in the final (post-transform) basis space. Returns (S_q, S_q_eta_a per axis, S_q_eta_a_a per axis, S_q_eta_a_b for (a, b) with a < b). All derivatives are with respect to raw η components directly per math team Letter A §9 — no centering, no apply_raw_psi_scaling.

closed_form_anisotropic_pair_block

closed_form_anisotropic_pair_block_pure

Pure-Duchon (κ=0) variant of closed_form_anisotropic_pair_block.

closed_form_matern_pair_block

Closed-form pair-block penalty for the pure Matérn basis at operator order q ∈ {0, 1, 2}.

closed_form_operator_penalty_in_total_basis

closed_form_operator_penalty_in_total_basis_pure

Pure-Duchon (κ=0 / length_scale = None) counterpart of closed_form_operator_penalty_in_total_basis. Uses closed_form_anisotropic_pair_block_pure to evaluate the closed-form penalty via analytic radial derivatives of the pure-Riesz kernel, which is finite for R > 0 in any (m, s, d, q) regime where radial_derivatives_of_isotropic_duchon is defined. Self-pair (R=0) regularization is handled inside the pair-block routine.

closed_form_psi_derivatives_in_total_basis

Closed-form penalty value S_q and its log-κ derivatives S_q_psi, S_q_psi_psi in the final (post-transform) basis space, computed via pair_block_radial_with_j_second_derivatives from the closed_form_penalty module. Bundle’s d_kappa and d2_kappa are κ-derivatives; chain rule converts to log-κ: ∂/∂ψ = κ·∂/∂κ, ∂²/∂ψ² = κ²·∂²/∂κ² + κ·∂/∂κ.

compute_geometric_constraint_transform

Compute the constraint transform Z using Greville abscissae (geometric constraints).

compute_greville_abscissae

Compute Greville abscissae for a B-spline basis.

compute_joint_null_rotation

Compute the joint-null absorption rotation for a smooth with one or more active penalty blocks.

conservative_secondary_centers

Conservative center count for a secondary (distributional) predictor’s spatial smooth — e.g. the log-σ scale model in a Gaussian location-scale fit.

constant_curvature_center_chart_radius2

Select constant-curvature centers.

constant_curvature_data_chart_radius2

max‖x‖² over the term’s feature columns of data, the other half of the evaluated pair set. Non-finite coordinates are skipped rather than poisoning the maximum (the basis build refuses them separately, by row and name).

constant_curvature_evaluated_scale_span

The scales the kernel actually evaluates: (d_min⁺, d_max) over the data→center and center→center pairs, in the κ = 0 doubled chart gauge, excluding the exact zeros that self-pairs contribute.

constant_curvature_kernel_kappa_jets

(k, ∂k/∂κ, ∂²k/∂κ²) — the κ slice of constant_curvature_kernel_psi_jets, kept as its own entry point for callers that hold ℓ fixed.

constant_curvature_kernel_matrix

k_κ(data, centers) — the realized constant-curvature model kernel matrix ℓ·(e^{−d_κ(x_i,c_j)/ℓ} − 1), evaluated as ℓ·expm1(−d_κ/ℓ).

constant_curvature_kernel_psi_jets

Build ConstantCurvatureKernelPsiJets for one (data, centers) block.

constant_curvature_length_scale_bounds

DERIVED box [ℓ_lo, ℓ_hi] for the kernel range — the interval on which the realized design’s GRAM is still resolvable in double precision, which is the only thing a box on this coordinate is entitled to enforce.

constant_curvature_realized_centers

The REALIZED center set the builder will use for spec on data — the pole-aware selection, not the raw strategy output.

contained_constraint_directions

The part of constraint_matrix that design’s realized column span actually CONTAINS, as vectors in row space (an n × r block, r ≤ q).

create_basis

Unified B-spline basis generation with configurable storage, knot source, and options.

create_difference_penalty_matrix

Creates the discrete coefficient-sequence operator S = D' * D, penalizing squared order-th differences of the supplied coordinates.

create_duchon_basis_1d_derivative_dense

create_duchon_basis_1d_derivative_dense_with_radial_reparam

Evaluate a 1-D Duchon design derivative in an already-frozen radial chart. Position-batched consumers compute the data-metric chart once from the complete ragged batch and reuse it for every segment; without this argument each segment differentiates a different coefficient basis.

create_ispline_derivative_dense

Compute the k-th derivative of an I-spline basis as a dense matrix.

create_matern_spline_basiswithworkspace

Creates a Matérn spline basis from data and centers.

create_thin_plate_spline_basis

Creates a thin-plate regression spline basis from data and knot locations.

create_thin_plate_spline_basis_in_chart

Evaluates a thin-plate basis at data in a radial chart supplied by the caller, rather than one chosen from data itself.

create_thin_plate_spline_basis_with_knot_count

High-level TPS constructor: selects knots from data, then builds basis+penalty.

create_thin_plate_spline_basis_with_knot_count_andworkspace

create_thin_plate_spline_basiswithworkspace

cyclic_bspline_derivative_penalty_factor

Constructive energy factor for the exact cyclic B-spline roughness.

cyclic_bspline_derivative_penalty_matrix

Exact cyclic (periodic) B-spline roughness penalty over one full period: S_ab = ∮ B_a^{(order)}(θ) B_b^{(order)}(θ) dθ for the wrapped uniform basis of num_basis cardinal translates with spacing h = period / num_basis.

default_num_centers

Adaptive default center count for spatial smooths (TPS, Duchon, Matérn).

default_spatial_center_strategy

default_spherical_harmonic_degree

Default L for the harmonic basis when the user does not set max_degree. Targets ~k = 50 columns (mgcv sos default) for sample sizes large enough to support that many parameters, scaling down toward L=2 for small n (target ≈ n/4 columns), and capped at L=12 (168 cols) at the upper end.

duchon_axis_log_kappa_derivatives

Per-axis ψ derivatives of a radial scalar F(r; κ) = κ^E G(κ r).

duchon_axis_shares

Normalized per-axis shares σ_a = s_a / r² of the anisotropic squared distance, with the symmetric convention σ_a = 1/d at collision.

duchon_cubic_default

The magic request-layer default (nullspace_order, power) for a non-periodic Euclidean Duchon basis of dimension d: the cubic polyharmonic kernel in every dimension.

duchon_design_build_count

Current value of the Duchon design-build counter (test-support).

duchon_direction_derivatives

First and second ψ derivatives of a radial scalar along direction.

duchon_effective_nullspace_order

Returns the effective Duchon null-space order, auto-degrading when the requested order leaves no radial kernel degrees of freedom.

duchon_kernel_constraint_nullspace

Cache-free canonical Duchon kernel-constraint null space: the SAME degrade → mean-center → RRQR construction the cached design path uses. Every consumer of a Duchon Z outside the workspace-cached design builder (e.g. the FFI derivative jets, which must be the exact column-for-column derivative of the forward design) must route through this one construction; re-deriving Z without the centering lands on a different orthonormal basis of the same null space and silently desyncs the jet’s frame from the design’s.

duchon_max_active_operator_derivative_order

Returns the maximum derivative order required by the active operator penalties: 2 if stiffness is Active, else 1 if tension is Active, else 0. Mass-only (or no active operator) penalties only require kernel validity (2(p+s) > d), tension requires D1 collocation (2(p+s) > d+1), and stiffness requires D2 collocation (2(p+s) > d+2).

duchon_nullspace_dimension

duchon_nullspace_order_from_m

The one m→order mapping: m is the spline ORDER knob (mgcv’s m), and it selects the polynomial null space the smoother leaves unpenalized (1 → mean only, 2 → mean + linear, k → total degree ≤ k−1). It is NOT the spectral power. Inverse of duchon_p_from_nullspace_order.

duchon_penalties_at_length_scale

Rebuild the Duchon penalty list at a NEW length_scale purely from FROZEN basis geometry — no data rows touched (#1033, n-free per-ψ penalty re-key).

duchon_polynomial_first_derivative_nd

N-D Duchon polynomial-nullspace first derivative ∂P/∂t per row.

duchon_power_to_usize

Convert a Duchon spectral-power f64 into the integer view used by the closed-form code paths. Non-finite, negative, or fractional values clamp to 0 so the validator downstream emits the canonical error.

duchon_pure_kernel_amplification

Scalar kernel amplification α that build_duchon_basis applies to the pure scale-free polyharmonic Duchon kernel block (length_scale = None, power = 0, no anisotropy) for the given requested null-space order.

duchon_radial_first_derivative_nd

N-D Duchon radial first-derivative φ'(r) evaluated for every (row, center) pair.

duchon_radial_second_derivative_nd

N-D Duchon radial second derivative φ''(r) evaluated for every (row, center) pair.

duchon_radial_third_derivative_nd

N-D Duchon radial third derivative φ'''(r) evaluated for every (row, center) pair.

duchon_resolve_chart

Resolve every ψ-invariant chart decision a Duchon build makes, so a caller can hand the SAME chart to the forward and to its ψ-derivative.

duchon_sae_atom_basis_with_jet

Forward design and input-location first jet of the scale-free Duchon atom used by the SAE-manifold path, recomputed self-consistently at arbitrary latent coordinates t.

duchon_sae_atom_penalty

Reproducing-norm smoothness penalty for the scale-free Duchon SAE atom, consistent column-for-column with duchon_sae_atom_basis_with_jet.

duchon_sae_atom_second_jet

Second input-location jet of the scale-free Duchon SAE atom (the analytic Hessian ∂²Φ / ∂t_a ∂t_c), consistent with duchon_sae_atom_basis_with_jet column-for-column and α-for-α.

duchon_sae_atom_third_jet

Third input-location jet of the scale-free Duchon SAE atom (the analytic ∂³Φ / ∂t_a ∂t_c ∂t_e), consistent with duchon_sae_atom_basis_with_jet and duchon_sae_atom_second_jet column-for-column and α-for-α.

duchon_spec_supports_axis_psi

Whether a Duchon spec’s per-axis ψ derivative surface is complete, so its aniso_log_scales may be enrolled as outer REML coordinates (gam#2735).

estimate_penalty_nullity

evaluate_bspline_basis_scalar

Evaluates B-spline basis functions at a single scalar point x into a provided buffer.

evaluate_bspline_derivative_scalar

Evaluates B-spline basis derivatives at a single scalar point x into a provided buffer.

evaluate_bspline_derivative_scalar_into

Zero-allocation version: pass pre-allocated buffers for lower_basis and scratch.

evaluate_bspline_fourth_derivative_scalar

Evaluates B-spline fourth derivatives at a single scalar point x into out.

evaluate_bsplinesecond_derivative_scalar

Evaluates B-spline second derivatives at a single scalar point x into out.

evaluate_bsplinethird_derivative_scalar

Evaluates B-spline third derivatives at a single scalar point x into out.

evaluate_ispline_scalar

evaluate_ispline_scalarwith_scratch

Evaluates I-spline basis functions at a scalar point x into a provided buffer.

evaluate_mspline_scalar

Evaluates M-spline basis functions at a scalar point x into a provided buffer.

expand_periodic_centers

expanded_num_centers

Next evidence-backed center count for a saturated spatial basis, bounded by the already validated production-default resolution.

filter_penalty_candidates

Canonicalize candidate matrices and partition them into active penalty identities and separately typed dropped diagnostics.

fit_periodic_bspline_curve

Fit a vector-valued 1D periodic spline curve by penalized least squares.

function_space_nullspace_shrinkage

Function-space double-penalty ridge: shrink the function component that the primary penalty cannot see, not the raw coefficients (SPEC rule 5).

initial_aniso_contrasts

Compute initial anisotropy contrasts η_a from knot center geometry.

initializewiggle_knots_from_seed

Generate a B-spline knot vector spanning a 1-D seed sample.

ispline_function_gram

Exact L² Gram G_ij = ∫ I_i(x) I_j(x) dx for an anchored I-spline basis.

ispline_function_penalties

Exact I-spline roughness and optional function-space null shrinkage.

jet_sufficient_stats

Read the local jet-fit sufficient statistics off a moment table at scale eps, for value channel channel.

knot_cloud_axis_scales

Compute per-axis standard deviations of knot center coordinates.

lower_triangular_indices

Enumerate the active lower-triangular entries of a d×d factor in column-major order (column j, rows j..d). This is the canonical order every output of this module uses for its L-derivative channels.

matern_input_location_hessian_nd

N-D Matérn input-location Hessian ∂²Φ/∂t∂tᵀ under the anisotropic metric.

matern_input_location_jet_nd

N-D Matérn input-location jet ∂Φ/∂t under the anisotropic metric.

matern_radial_first_derivative_nd

N-D Matérn radial first-derivative φ'(r) evaluated for every (row, center) pair.

matern_radial_second_derivative_nd

N-D Matérn radial second derivative φ''(r) evaluated for every (row, center) pair.

measure_jet_affine_head_block

Realize the affine head block [1 | points] · T_aff for the lift returned by measure_jet_affine_head_lift. A zero-column lift (multiscale mode, which carries no head) yields a zero-column block.

measure_jet_affine_head_lift

Affine head lift T_aff ((d+1) × (1 + head_rank)) acting on the augmented point rows [1 | x]: column 0 is the constant, the rest are the supported ambient-linear directions of measure_jet_affine_head_transform.

measure_jet_affine_head_transform

Rank-revealing ambient-linear head lift T (d × head_rank) for the extrapolation null space (#1845).

measure_jet_ambient_gradient

Analytic ambient gradient ∇f̂(x★) of a frozen measure-jet term’s fitted contribution to the linear predictor, in the (standardized) ambient coordinates the frozen geometry lives in.

measure_jet_anisotropy_energy_form

The det-normalized anisotropic measure-jet energy form Q for the metric A = L Lᵀ. With L = I this returns the isotropic super::measure_jet_energy_form bit-for-bit.

measure_jet_anisotropy_energy_form_with_jets

The det-normalized anisotropic energy together with its EXACT first and second derivatives with respect to the lower-triangular Cholesky factor entries of L. Value and jets come from one block walk so they cannot drift apart.

measure_jet_band

Build the realized geometric scale band from the center set: floor at the median nearest-center spacing (below it the quadrature resolves nothing), ceiling at half the bounding-box diagonal (a deterministic diameter-scale cap; local fits remain center-weighted and distinct there). num_scales == 0 requests the auto count clamp(⌈log2(ε_max/ε_min)⌉ + 1, 3, 8); a degenerate band (ceiling ≤ floor) collapses to the single floor scale with log_step = ln 2.

measure_jet_center_masses

Per-center masses of the empirical measure (the zeroth-moment half of measure_jet_quadrature_nodes; single assignment source).

measure_jet_design_matrix

Gaussian representer features exp(−‖x − c‖²/(2ℓ²)) (n × m).

measure_jet_energy_form

The multiscale jet-residual energy Q (m × m, symmetric PSD) on the center set. See the module docs for the formula and contracts; the local residual form is assembled through the closed-form identities

measure_jet_energy_form_with_jets

The energy together with its exact first and second jets in the live dials, plus zero slots for the retained ψ_τ = ln τ coordinate. With g_s = −2 ln ε, g_α = −2 ln q:

measure_jet_energy_forms_per_scale

The per-scale energy forms Q_ℓ (each m × m, symmetric PSD), with Σ_ℓ Q_ℓ = Q to the PSD-projection floor (same blocks, one-hot weights). These are the spectral-split carriers: emitted as separate penalty candidates they let the multi-penalty REML engine learn per-level amplitudes λ_ℓ directly — scale adaptivity at ρ-speed with no rebuild and no new optimizer code.

measure_jet_extrapolation_variance

Frame-note §5: closed-form extrapolation variance at a query — the price of ignorance off the web, read from the fitted spectrum. ε★ = the first covering scale (smallest band scale at which the query’s kernel mass clears coverage_floor × q̄_ℓ); levels finer than ε★ contribute their full prior variance λ̂_ℓ⁻¹, levels from ε★ up contribute the uncovered fraction (1 − a_ℓ(x★)) · λ̂_ℓ⁻¹ with a_ℓ(x★) = min(q_ℓ(x★)/q̄_ℓ, 1) the smooth on-web-ness weight. Equivalently (see the module docs) the total prior ignorance Σ_ℓ λ̂_ℓ⁻¹ minus the §5 coverage-recovered sum Σ_{ℓ: ε_ℓ ≥ ε★} a_ℓ(x★)/λ̂_ℓ. On-web queries (ε★ = ε_0, a ≈ 1) pay ≈ 0 extra; queries never covered by the band pay Σ_ℓ λ̂_ℓ⁻¹ exactly — intervals widen monotonically with distance (theorem in the module docs).

measure_jet_input_noise_scale

Estimate the ambient input-measurement-error scale σ_coord — the perpendicular off-manifold residual spread of the empirical measure — for the errors-in-variables predictive-variance term Var_input = ∇f̂ᵀΣ_x∇f̂, Σ_x = σ_coord²·I (issue #2225).

measure_jet_ln_range_window

The ln ℓ SEARCH WINDOW for the design-moving representer range, in the frame spec.length_scale is expressed in (gam#2750).

measure_jet_multiscale_mode

Whether a measure-jet spec runs in multiscale mode (per-scale spectral energies + (α, ln τ) ψ dials). The separate double_penalty affine/null-component candidate is available in both modes. This is the single source of truth shared by the builder and outer enrollment predicates, so the energy layout and ψ dimension cannot disagree. Multiscale is an explicit opt-in (spec.multiscale); there is no center-count auto-gate (#1116).

measure_jet_quadrature_nodes

First-moment-exact quadrature of the empirical measure on the cell partition induced by the seed centers: nearest-center assignment (deterministic tie-break: lowest center index) yields per-cell masses, and each non-empty cell’s quadrature node is its mass-weighted barycenter. Empty cells keep their seed coordinates with zero mass (the assembly skips them; their representer columns remain valid).

measure_jet_range_bracket

Realize MeasureJetRangeBracket for a fresh (unfrozen) measure-jet spec.

measure_jet_range_feasibility_ceiling

The range at which a node pair separated by spacing stops being DISTINGUISHABLE from a coincident one in f64.

measure_jet_scale_spectrum

Per-scale energy decomposition of center values v: element ℓ is vᵀ Q_ℓ v, the detail energy charged at scale ε_ℓ. Sums exactly to vᵀQv (same blocks, one-hot weights) and doubles as the scale spectrum diagnostic of the fitted intensity field — where along the band the signal lives, and the analytic carrier of ∂/∂s reweightings.

measure_jet_support_curve

The support diagnostic ε ↦ q_ε(x★): kernel mass of the (frozen) center quadrature seen from each query point at every band scale (n_query × L). A query ON the web sees its strand’s mass already at fine scales; a query OFF the web accumulates mass only once ε reaches its distance to the support. This is the on-web-ness statistic shipped alongside predictions — smooth, multiresolution, derived from the measure with no neighbor sets.

merge_moment_tables

Monoid merge: recenter compatible frozen-weight tables onto a common reference, then add componentwise. Exact for those polynomial moments (pure binomial shift, no kernel re-evaluation) and deterministic.

minimum_duchon_power_for_operator_penalties

monomial_exponents

operator_penalty_candidates_closed_form

operator_penalty_candidates_closed_form_pure

Pure-Duchon (κ=0 / length_scale = None) counterpart of operator_penalty_candidates_closed_form.

orthogonality_transform_for_design

parametric_residualization_for_design

Orthogonalize design against constraint_matrix without deleting a model dimension, by projecting in row space rather than restricting in coefficient space.

periodic_bspline_first_derivative_nd

N-D periodic-cyclic-B-spline first-derivative jet ∂Φ̃/∂t per row.

plan_spatial_basis

Build a resource-aware plan for a spatial smooth basis.

pseudo_s2_truncated_coefficients

Build the truncated pseudo-spline coefficient array c_0 = 0, c_ℓ = 2 / (4π · Π_{k=1..m+1}(ℓ + k)) for ℓ = 1..=lmax.

radial_input_location_jet_nd

Per-(row, center) input-location jet of a radial kernel from its scalar first derivative φ'(r).

realized_constant_curvature_length_scale

Resolve the realized kernel range ℓ. An explicit positive spec_length_scale is used verbatim; the 0.0 sentinel auto-initializes from the median pairwise CHART distance among the centers, doubled to match the κ = 0 chart gauge (d_0 = 2‖Δ‖).

realized_measure_jet_length_scale

Resolve the realized representer range ℓ. An explicit positive spec_length_scale is used verbatim; the 0.0 sentinel auto-initializes from the median nearest-center spacing (one spacing width: neighbors overlap at exp(−1/2) ≈ 0.61, smooth blend without collinearity).

recenter_moment_table

Exact recentering via the binomial shift: the same frozen-weight polynomial table re-expressed about new_center, with no kernel re-evaluation. This is not a moving-kernel identity; if the Gaussian center changes, the caller must recompute or approximate the weights.

resolve_duchon_orders

Resolve a fully admissible Duchon (nullspace_order, power) pair.

select_centers_by_strategy

select_cr_knots

Place k cr knots at evenly-spaced quantiles of the unique sorted data, exactly as mgcv’s default cr knot placement: the first and last knots are the min/max, and the interior knots are at the 1/(k-1) … (k-2)/(k-1) quantiles of the unique observed values. Returns a strictly increasing length-k knot vector.

select_spherical_farthest_point_centers

Select spherical-spline basis centers by geodesic farthest-point sampling of the data cloud, returning a well-spread subset of the actual data rows.

select_thin_plate_knots

Deterministically selects thin-plate knots via farthest-point sampling.

should_use_implicit_operators_with_policy

Determine whether implicit operators should be used based on problem size and the supplied ResourcePolicy.

should_use_sparse_basis

Returns true if the B-spline basis should be built in sparse form based on density.

sobolev_s2_truncated_coefficients

Build the truncated Sobolev coefficient array c_0 = 0, c_ℓ = (2ℓ+1) / (4π · [ℓ(ℓ+1)]^m) for ℓ = 1..=lmax. Returned vector has length lmax + 1 with result[ℓ] = c_ℓ. The GPU s2_wahba_legendre_colmajor kernel uploads exactly this array.

sphere_first_derivative_nd

N-D Sobolev-sphere first-derivative jet ∂Φ/∂t per row, on the unit sphere S^{dim−1}.

sphere_truncated_spectral_eval

Evaluate Σ_{ℓ=0..=lmax} c_ℓ · P_ℓ(cos γ) via the same Legendre 3-term recurrence the GPU kernel runs. coeffs[ℓ] = c_ℓ with coeffs.len() = lmax + 1. The recurrence is p_{ℓ+1} = ((2ℓ+1)·t·p_ℓ − ℓ·p_{ℓ−1}) / (ℓ + 1).

spherical_spline_design_jet

Realized-design DESIGN jet ∂Φ/∂(lat, lon) for the spherical-spline basis, matching the column layout of build_spherical_spline_basis with the given spec. Returns (N, K, 2) where K equals the forward design’s column count and the last axis is (∂col/∂lat, ∂col/∂lon) in the same angular units as the raw input.

spherical_wahba_kernel_matrix

Build a Wahba S² kernel matrix with the untruncated Sobolev kernel.

spherical_wahba_kernel_matrix_cpu

CPU oracle for the Wahba S² kernel design matrix — the bit-defining reference the GPU truncated path is held to. Always evaluates on host, regardless of the GPU dispatch decision, so parity tests and any caller that needs the deterministic reference can bypass device routing entirely.

spherical_wahba_kernel_matrix_with_kind

Build a Wahba S² kernel matrix with an explicit kernel family.

starting_num_centers

Low-rank starting center count for saturation-driven spatial fitting.

thin_plate_penalties_at_length_scale

Rebuild the thin-plate (Matérn-blended) penalty list at a NEW length_scale from FROZEN basis geometry — no data rows touched (#1033, n-free per-ψ penalty re-key). Mirrors the cold penalty assembly in build_thin_plate_basiswithworkspace (the bending + optional ridge built by build_thin_plate_penalty_matrices, normalized, gauge-restricted through the frozen identifiability transform, then filtered), but every input is the already-frozen BasisMetadata::ThinPlate (centers, identifiability transform); only length_scale moves.

thin_plate_polynomial_basis_dimension