Struct SparseEmpiricalCubaturePlan 

pub struct SparseEmpiricalCubaturePlan { /* private fields */ }

Row-wise Tchakaloff cubature of the joint σ-pushforward measure on a fixed target grid.

Laid out in flat Struct-of-Arrays (SoA) form for cache-friendly online evaluation:

• row_starts[i]..row_starts[i+1] indexes into weights/atoms for row i.
• weights[q] is the per-atom nonneg weight (sums to 1.0 within each row since the source measure is row-stochastic).
• atoms[q] is a flat row-major block of length k storing the atom’s joint σ coordinates.

Built once per (grid, isotope_set, training_densities, anchor) tuple and applied repeatedly during LM / KL iterations via Self::forward and Self::forward_and_jacobian.

Implementations

impl SparseEmpiricalCubaturePlan

pub fn default_training_points(train_max: &[f64]) -> Vec<Vec<f64>>

Canonical default training-density rule from the codex04 round-2 reference: for an upper-bound density vector train_max ∈ ℝ^k, return S = 2 + k training points consisting of 0.25 * train_max, 0.75 * train_max, and the k axis-aligned “unit” points train_max[i] · e_i (all other components zero). Exposed as a helper so callers — including the wiring in PR #474b — don’t have to hand-roll the rule.

Duplicates are NOT removed. In practice the rule produces S = k + 2 distinct points for any k ≥ 1 with all train_max[i] > 0.

pub fn default_jacobian_anchor(train_max: &[f64]) -> Vec<f64>

Canonical default Jacobian anchor from the codex04 round-2 reference: 0.5 * train_max, the midpoint of the density box.

pub fn build( matrix: &ResolutionMatrix, sigmas: &[f64], k: usize, training_densities: &[Vec<f64>], jacobian_anchor: &[f64], ) -> Result<Self, CubatureBuildError>

Build a Tchakaloff sparse-cubature plan row-by-row from an exact ResolutionMatrix + isotope cross-section stack.

Arguments

• matrix — exact sparse R (built via crate::resolution::ResolutionPlan::compile_to_matrix).
• sigmas — per-isotope cross-sections on the matrix’s target grid, flat row-major: sigmas[j * n_rows + ℓ] = σ_j(E’_ℓ).
• k — number of isotopes (must match sigmas.len() / n_rows).
• training_densities — a slice of density vectors n^(s) ∈ ℝ^k covering the density box the fit is expected to explore. Codex04’s default rule is [0.25 * train_max, 0.75 * train_max] ∪ {train_max_e_i : i=1..k} which gives S = 2 + k distinct training points.
• jacobian_anchor — a single density n* ∈ ℝ^k at which the Jacobian features are evaluated. Codex04 uses 0.5 * train_max.

Per-row LP:

find   x ≥ 0 in ℝ^{|support|}
s.t.   Σ_q x_q = 1
       phi[s, q]  = exp(-n^(s) · σ_support[q])      for s = 1..S
       phi[ℓ, q]  = σ_{ℓ, support[q]} · exp(-n* · σ_support[q])
                                                    for ℓ = 1..k
       phi @ x    = phi @ w_exact_support

where w_exact_support = R[i, support] / Σ_q R[i, support[q]] is the exact full-support row measure (the existing non-sparse weight distribution — NOT uniform; the entries carry the kernel shape). It serves as the feasibility fallback for the LP: the identity x = w_exact_support always satisfies the equality constraints, so a feasible solution exists. The returned basic feasible solution has at most S + k + 1 nonzero entries (Carathéodory).

pub fn len(&self) -> usize

Number of rows (target-grid size) covered by this plan.

pub fn is_empty(&self) -> bool

True when the plan covers no target energies.

pub fn k(&self) -> usize

Number of isotopes (per-atom dimensionality).

pub fn n_atoms(&self) -> usize

Total number of stored atoms across all rows.

pub fn target_energies(&self) -> &[f64]

Target energy grid the plan was built for.

Mirrors crate::resolution::ResolutionPlan::target_energies / crate::resolution::ResolutionMatrix::target_energies — callers implementing plan caches compare this against their current grid to decide whether the plan is still valid.

pub fn row_starts(&self) -> &[u32]

CSR row-start offsets. row_starts()[i]..row_starts()[i+1] names the atom range for row i. Length len() + 1.

pub fn weights(&self) -> &[f64]

Per-atom weights.

pub fn atoms(&self) -> &[f64]

Per-atom σ coordinates, flat row-major. Atom q at atoms()[k * q .. k * (q + 1)].

pub fn density_box(&self) -> Option<&[f64]>

Training-density upper bound recorded at build time, if any. Dispatch layers use this to detect when the fit iterate escapes the training region and safely fall back to the exact path (cubature accuracy degrades quickly outside the trained box). None when the caller chose not to record one — in that case dispatch cannot safety-check.

pub fn with_density_box(self, train_max: Vec<f64>) -> Self

Attach the training-density upper bound (train_max) used during build, so dispatch can refuse to fire on iterates that escape the trained region. Builder-style; returns self for chaining. Callers in spatial_map_typed populate this with the same train_max vector fed into Self::default_training_points / Self::default_jacobian_anchor.

Panics

Panics if train_max.len() != self.k().

pub fn forward(&self, n: &[f64]) -> Vec<f64>

Evaluate the surrogate forward model T_i(n) at density vector n ∈ ℝ^k.

Panics

Panics if n.len() != self.k().

pub fn forward_and_jacobian(&self, n: &[f64]) -> (Vec<f64>, Vec<f64>)

Evaluate forward + per-density Jacobian at density vector n. Returns (T, J) where T[i] = T_i(n) and J[i * k + ℓ] = ∂T_i/∂n_ℓ, both computed from the same atom scan so the online cost is (k + 1) FLOPs per atom rather than k + 1 separate passes.

Panics

Panics if n.len() != self.k().

Trait Implementations

impl Clone for SparseEmpiricalCubaturePlan

fn clone(&self) -> SparseEmpiricalCubaturePlan

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SparseEmpiricalCubaturePlan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.