Crate gam_problem 

Shared REML/LAML contract types.

These are the family-facing interfaces for REML outer assembly. They live below solver so families can construct operator-backed derivative payloads without importing solver::estimate::reml::reml_outer_engine.

Re-exports

pub use riemannian_retraction::LatentRetractionRegistry;

pub use row_measure::RowSubsampleMask;

pub use basis_error::BasisError;

pub use block_count_error::BlockCountMismatch;

pub use block_role::BlockRole;

pub use block_spec::AdditiveBlockJacobian;

pub use block_spec::BlockEffectiveJacobian;

pub use block_spec::BlockGeometryDirectionalDerivative;

pub use block_spec::BlockWorkingSet;

pub use block_spec::CoefficientCoordinate;

pub use block_spec::FamilyChannelHessian;

pub use block_spec::FamilyLinearizationState;

pub use block_spec::GaugeComposedJacobian;

pub use block_spec::ParameterBlockSpec;

pub use block_spec::ParameterBlockState;

pub use block_spec::RowScaledJacobian;

pub use coefficient_prior_mean::CoefficientPriorMean;

pub use coefficient_prior_mean::PriorMeanError;

pub use custom_family_blockwise::CUSTOM_FAMILY_RIDGE_FLOOR;

pub use custom_family_blockwise::ExactNewtonOuterCurvature;

pub use custom_family_blockwise::validate_blockspec_consistency;

pub use custom_family_error::CustomFamilyError;

pub use custom_family_error::InnerConvergenceTerminalState;

pub use custom_family_error::JointNewtonTerminalReason;

pub use custom_family_error::relative_stationarity;

pub use dispersion::Dispersion;

pub use dispersion::DispersionError;

pub use dispersion_cov::CovarianceStandardErrorError;

pub use dispersion_cov::PhiScaledCovariance;

pub use dispersion_cov::UnscaledPrecision;

pub use dispersion_cov::se_from_covariance;

pub use estimation_error::EstimationError;

pub use estimation_error::FixedLambdaCheckpoint;

pub use estimation_error::FixedLambdaResidualKind;

pub use estimation_error::FixedLambdaSolverStage;

pub use estimation_error::FixedLambdaStallReason;

pub use estimation_error::FixedLambdaStationarityEvidence;

pub use estimation_error::StationarityRung;

pub use estimation_error::StationarityStandard;

pub use estimation_error::FitStationarityEvidence;

pub use execution_path::ExecutionPath;

pub use family_options::ExactNewtonOuterObjective;

pub use family_options::ExactOuterDerivativeOrder;

pub use finite_validation::bail_if_cached_beta_non_finite;

pub use finite_validation::ensure_finite_scalar;

pub use finite_validation::ensure_finite_scalar_estimation;

pub use finite_validation::validate_all_finite;

pub use finite_validation::validate_all_finite_estimation;

pub use finite_validation::validate_all_finite_trial_point;

pub use serde_finite::NonFiniteFloat;

pub use serde_finite::ensure_serialized_floats_are_finite;

pub use fisher_rao::FisherRaoDefiniteness;

pub use fisher_rao::normalize_fisher_rao_blocks;

pub use fisher_rao::normalize_fisher_rao_blocks_pd;

pub use roundoff::roundoff_growth_factor;

pub use roundoff::weighted_residual_is_at_roundoff_floor;

pub use gauge::Gauge;

pub use identifiability_audit::AliasedPair;

pub use identifiability_audit::BlockIdentity;

pub use identifiability_audit::DroppedColumn;

pub use identifiability_audit::IdentifiabilityAudit;

pub use identifiability_audit::JointRankCertificate;

pub use identifiability_audit::MapUniquenessError;

pub use joint_penalty::JointPenaltyBundle;

pub use joint_penalty::JointPenaltyError;

pub use joint_penalty::JointPenaltySpec;

pub use log_strength::IndexedLogStrengthDomainError;

pub use log_strength::LOG_STRENGTH_MAX;

pub use log_strength::LOG_STRENGTH_MIN;

pub use log_strength::LogStrengthDomainError;

pub use log_strength::PhysicalStrengthDomainError;

pub use log_strength::checked_exp_log_strength;

pub use log_strength::checked_exp_log_strengths;

pub use log_strength::checked_log_strength;

pub use log_strength::validate_log_strength;

pub use log_strength::validate_log_strengths;

pub use monotone_root_error::MonotoneRootError;

pub use penalty_coordinate::PenaltyCoordinate;

pub use penalty_coordinate::project_block_root_out_of_null_directions;

pub use penalty_matrix::PenaltyMatrix;

pub use psi_design_contract::CustomFamilyBlockPsiDerivative;

pub use psi_design_contract::CustomFamilyHyperAxis;

pub use psi_design_contract::CustomFamilyHyperLayout;

pub use psi_design_contract::CustomFamilyPsiDerivativeOperator;

pub use psi_design_contract::JointHessianSourcePreference;

pub use psi_design_contract::MaterializablePsiDerivativeOperator;

pub use psi_design_contract::MaterializationIntent;

pub use psi_design_contract::SharedCustomFamilyHyperLayout;

pub use psi_terms::ExactNewtonJointPsiSecondOrderContracted;

pub use psi_terms::ExactNewtonJointPsiSecondOrderTerms;

pub use psi_terms::ExactNewtonJointPsiTerms;

pub use psi_terms::ExactNewtonJointPsiWorkspace;

pub use row_metric::FisherFactorKind;

pub use row_metric::MetricProvenance;

pub use row_metric::RowMetric;

pub use row_metric::WeightField;

pub use row_metric::pack_probe_factors;

pub use schedule::GumbelTemperatureSchedule;

pub use schedule::ScheduleKind;

pub use solver_contract::DeclaredHessianForm;

pub use solver_contract::Derivative;

pub use solver_contract::EfsEval;

pub use solver_contract::FixedPointCertificateEval;

pub use solver_contract::FixedPointCoordinateCertificate;

pub use solver_contract::OuterEval;

pub use solver_contract::OuterStrategyError;

pub use types::*;

Modules

basis_error

Leaf error type for basis construction.

block_count_error

Neutral block-count arity mismatch carrier.

block_role

block_spec

Data model for the blockwise carrier (subset moved down to gam-problem): parameter-block specs, the effective-Jacobian and channel-Hessian abstractions, per-block working sets and states, and the block geometry directional derivative.

coefficient_prior_mean

Neutral programmatic prior-mean type for a coefficient penalty block.

custom_family_blockwise

Neutral blockwise custom-family contract primitives shared by the CustomFamily trait layer (gam-model-api) and the solver (gam-solve): the ridge floor, the block-spec consistency validator, and the exact-Newton outer-curvature payload.

custom_family_error

Custom-family error type and its String conversions.

diagnostics

Analytic diagnostic helpers for LAML/REML optimization.

dispersion

Validated dispersion/scale contract used by covariance and sampling code.

dispersion_cov

Newtype wrappers that disambiguate the two coefficient-space second-order quantities used throughout inference.

estimation_error

execution_path

Execution-path telemetry for hot solver/GPU paths.

family_options

Fit-time outer-objective and exact-derivative-order declarations shared by the custom-family solver entry points.

finite_validation

Shared finite-value validation helpers for estimation/result contracts.

fisher_rao

Fisher–Rao precision-weight normalization for response-geometry REML.

gauge

identifiability_audit

Pure-data identifiability-audit result types.

joint_penalty

Joint (cross-block) penalty specifications.

laplace_sampler_contract

Laplace-correction / mode-posterior sampler contract (trait-inversion #1521).

log_strength

Exact supported domain for logarithmic penalty strengths.

monotone_root_error

outer_subsample

Outer-loop row subsampling primitive shared across the solver and the family-specific outer-score evaluators.

penalty_coordinate

Neutral penalty-coordinate contract (moved from solver::reml::reml_outer_engine under #1521). The enum is pure data; its operators use only gam-problem’s own dense linalg helpers, so hosting it here lets the criterion/solver layers share one definition without an upward edge into the engine.

penalty_matrix

The PenaltyMatrix carrier (dense / Kronecker / scaled) used by every custom-family block, plus its constructors and the Array2 conversion.

psi_design_contract

The neutral ψ (hyperparameter) design-derivative contract carriers and operator traits shared by the CustomFamily trait layer (gam-model-api) and the solver: the per-block ψ-derivative carrier, the matrix-free CustomFamilyPsiDerivativeOperator trait (+ its dense-materialization extension), and the joint-Hessian source-preference / materialization-intent enums.

psi_terms

Exact-Newton joint-ψ term carriers and the joint-ψ workspace trait.

rho_posterior

ρ-posterior certificate / escalation DATA types (contract-down #1521).

riemannian_retraction

roundoff

One definition of “this residual is indistinguishable from zero”.

row_measure

Row-subsample mask handle for trust-region invariant enforcement.

row_metric

RowMetric — the single provenance-carrying per-row inner product shared by the SAE-manifold likelihood (residual whitening) and the gauge (isometry pullback weight).

schedule

serde_extended_real

JSON encoding for quantities whose mathematical domain includes +∞.

serde_finite

Structural non-finite-float guard for anything that implements Serialize.

solver_contract

Outer-objective contract (lower shared layer)

test_support

Parameter-block test fixtures shared across the workspace.

topology_certificates

The unified certificate contract (task #16).

types

Macros

bail_dim_basis

bail_dim_custom

bail_invalid_basis

bail_invalid_estim

Structs

BlockLocalDrift

ConstraintRowId

A row index in a ConstraintSet’s OWN constraint-row space — the space addressed by ConstraintSet::values, ConstraintSet::bound and ConstraintSet::row_norm, i.e. 0..nrows().

ContractFeasibleStep

Result of the contract-feasible ratio test (ConstraintSet::max_contract_feasible_step).

ContractedPsiSecondOrder

DenseMatrixHyperOperator

HyperCoord

HyperCoordDrift

HyperCoordPair

KhatriRaoConeConstraints

Nonnegativity cone (e_k ⊗ ψ_i)ᵀ β ≥ 0 for a row-major Khatri-Rao block.

LinearInequalityConstraints

ObjectiveEvalError

A failed objective evaluation, classified by the producer.

OrderedRhoBounds

A validated, finite, ordered ρ (log-λ) seed interval [lo, hi].

PlacedConstraintBlock

One block of a ConstraintSet::BlockDiagonal composition: an inner set acting on the coefficient columns [col_start, col_start + set.ncols()) of the joint vector.

ProjectedFactorCache

Memoizer for projected factor products keyed on a (design, factor) fingerprint.

ProjectedFactorKey

SeedConfig

Enums

ConstraintSet

Closed union of the constraint carriers the blockwise solvers accept.

ContractFeasibleStepError

Why the contract-feasible ratio test could not answer.

DriftDerivResult

EvalMode

Evaluation mode for the unified evaluator.

HessianMaterialization

How (and whether) a HessianOperator can produce a dense materialized Hessian. Reported by HessianOperator::materialization() so a trust-region or ARC solver can decide between calling materialize_dense once and falling back to repeated Hessian-vector products through apply_into.

HessianValue

Exact Hessian payload used by operator-aware optimizers and objective contracts.

PseudoLogdetMode

How the penalized Hessian’s log-determinant and derivatives treat the spectrum below the stability floor.

SeedRiskProfile

Constants

PRIMAL_FEASIBILITY_TOL

Primal-feasibility tolerance of the inequality-constrained active-set Newton solver, measured in the unit-normalized row metric this module defines: a point β is feasible for a ConstraintSet exactly when

Traits

HessianOperator

An exact analytic Hessian-vector product (and optional materialization).

HyperOperator

Functions

feasibility_quantities_are_finite

Can this row’s feasibility be DECIDED by comparison at all?

in_nested_parallel_region

true when the current thread is inside at least one NestedParallelGuard scope, i.e. a parallel row reduction is already in flight on this thread.

with_nested_parallel

Run body with the current thread marked as inside a data-parallel row region, so any faer GEMM it issues (directly or transitively) pins to Par::Seq via effective_global_parallelism instead of re-fanning the global Rayon pool. The guard is held for exactly the duration of body and dropped on return — including early ? returns from inside body, since the guard lives in this function’s frame.

Type Aliases

ContractedPsiSecondOrderFn

FixedDriftDerivFn

HyperCoordPairFn

Shared-ownership callback computing a second-order fixed-β HyperCoordPairResult for a coordinate pair (i, j).

HyperCoordPairResult

Fallible result of computing one second-order fixed-β coordinate pair.

SharedFixedDriftDerivFn

Shared-ownership form of FixedDriftDerivFn used for InnerSolution storage, so the same M_i[u] = D_β B_i[u] callback can be cloned into a derived (tangent-projected) solution. Construction sites still hand back a Box (FixedDriftDerivFn); storage re-tags it via Arc::from (free). The drift M is a p-space matrix that every consumer contracts through the (tangent-wrapped) Hessian operator’s trace_logdet_*, so the clone-through is exact under projection.