mod universal_coverage

module universal_coverage

Uncertainty-aware coverage over universal stationary-point descriptors. Uncertainty-aware coverage over the universal stationary-point descriptor.

Coverage is evidence for choosing the next exploration target, not a basin identity rule. Exact structural witnesses assign class identifiers. This module combines continuous per-block novelty, Euclidean Gaussian-process uncertainty, disagreement between full and block models, and the graph residual field without applying a descriptor merge radius.

Enums

enum CoverageError

Invalid coverage model input or evidence request.

InvalidConfig(&'static str)

A configuration value violates its numerical domain.

InvalidDeepKernel(&'static str)

A neural feature-map shape or value is invalid.

NonFiniteEnergy

Only finite stationary energies can train the evidence models.

DescriptorDimension

Schema-bound values have the wrong descriptor dimension.

expected: usize

Descriptor dimension fixed at model construction.

actual: usize

Descriptor dimension supplied by the caller.

NonFiniteDescriptor

Schema-bound values contain NaN or infinity.

index: usize

Index of the first invalid coordinate.

UnknownClass

A graph edge or assigned query names a class without observations.

class: usize

Unobserved class identifier.

Descriptor(DescriptorError)

Descriptor schema or value compatibility failure.

Structs and Unions

struct CoverageCompression

Auditable size and covariance loss of the invariant kernel coresets.

exact_classes: usize

Exact structural classes retained outside the continuous surrogates.

maximum_rank: usize

Hard rank ceiling applied independently to every descriptor view.

full_rank: usize

Inducing rank of the full universal descriptor GP.

block_ranks: Vec<usize>

Inducing rank of every ordered descriptor-block GP.

deep_rank: Option<usize>

Inducing rank of the optional residual-neural GP.

maximum_residual_fraction: f64

Largest remaining conditional-covariance trace fraction across views.

rank_limited: bool

Whether any view reached the hard ceiling above its covariance floor.

struct CoverageConfig

Gaussian-process scales for the universal exploration acquisition.

energy_length_scale: f64

Full-descriptor GP length scale.

component_length_scale: f64

Per-block and optional deep-kernel GP length scale.

amplitude: f64

GP prior standard deviation in energy units.

noise: f64

GP observation noise in energy units.

maximum_model_rank: usize

Hard rank ceiling for every kernel coreset.

Implementations

impl CoverageConfig

Traits implemented

impl Default for CoverageConfig

struct CoverageEvidence

Evidence used to rank one stationary-structure exploration target.

nearest_block_distances: Vec<Option<f64>>

Nearest observed distance for every ordered descriptor block.

block_novelty: f64

RMS of smoothly squashed nearest-block distances.

energy_mean: f64

Full-descriptor GP posterior mean energy.

energy_standard_deviation: f64

Full-descriptor GP posterior standard deviation.

block_means: Vec<f64>

Per-block GP posterior mean energies.

block_standard_deviations: Vec<f64>

Per-block GP posterior standard deviations.

deep_kernel_mean: Option<f64>

Optional residual-neural deep-kernel GP posterior mean.

deep_kernel_standard_deviation: Option<f64>

Optional residual-neural deep-kernel GP posterior standard deviation.

ensemble_mean: f64

Uniform model-average posterior mean across invariant descriptor views.

ensemble_standard_deviation: f64

Moment-matched posterior standard deviation, including disagreement.

model_disagreement: f64

Standard deviation of the posterior means, scaled by the GP amplitude.

residual_variance: f64

Effort-adjusted graph-GMRF variance, or the unassigned residual variance.

expected_improvement: f64

Moment-matched model-average expected improvement for minimization.

acquisition: f64

Expected improvement divided by the declared system energy scale.

struct StableDeepKernel

Deterministic residual neural feature map for a deep-kernel GP.

The output concatenates the invariant input descriptor with bounded neural features. Consequently its Euclidean distance is never smaller than the raw descriptor distance, so the neural map cannot hide a raw separation. The input is already rotation/permutation invariant, making any deterministic map of it invariant as well. This is a deep-kernel feature map, not a deep Gaussian process: its layer functions are not marginalized as random GPs.

Implementations

impl StableDeepKernel

Functions

fn distance(&self, left: &[f64], right: &[f64]) -> Result<f64, CoverageError>

Stable Euclidean distance in the residual neural feature space.

fn embed(&self, input: &[f64]) -> Result<Vec<f64>, CoverageError>

Raw skip coordinates followed by the final bounded neural features.

fn input_dim(&self) -> usize

Required raw descriptor dimension.

fn seeded(input_dim: usize, widths: &[usize], seed: u64) -> Result<Self, CoverageError>

Construct normalized tanh layers from a reproducible seed.

struct UniversalCoverage

GP/GMRF evidence model over exact stationary-point classes.

Implementations

impl UniversalCoverage

Functions

fn assign_minimum_information_values(&mut self, candidates: &[(usize, Vec<f64>)], batch_size: usize, max_family_size: usize, minimum_samples: usize) -> Result<Vec<usize>, CoverageError>

Select a same-system launch batch by GIBBON minimum-value information.

Candidate descriptors must match this coverage model’s immutable schema. The full invariant descriptor GP supplies both the singleton information and posterior correlations, while max_family_size remains a hard feasibility constraint rather than an acquisition term.

fn compression(&mut self) -> CoverageCompression

Kernel ranks and residual covariance retained by the cached coresets.

fn connect(&mut self, left: usize, right: usize) -> Result<(), CoverageError>

Add an observed transition edge between exact classes.

fn evidence(&mut self, descriptor: &DescriptorVector, assigned_class: Option<usize>) -> Result<CoverageEvidence, CoverageError>

Assemble novelty, posterior uncertainty, disagreement, and graph evidence.

fn evidence_values(&mut self, descriptor: &[f64], assigned_class: Option<usize>) -> Result<CoverageEvidence, CoverageError>

Assemble evidence from values already validated against this schema.

fn exact_class_count(&self) -> usize

Number of class identifiers admitted by exact witnesses.

fn new(reference: &DescriptorVector, config: CoverageConfig) -> Result<Self, CoverageError>

Construct full-descriptor, per-block, and graph residual models.

fn observation_count(&self) -> usize

Number of energy/descriptor observations, including repeat effort.

fn observe(&mut self, class: usize, descriptor: &DescriptorVector, energy: f64) -> Result<(), CoverageError>

Record an energy observation assigned by an exact structural witness.

fn observe_values(&mut self, class: usize, descriptor: &[f64], energy: f64) -> Result<(), CoverageError>

Record schema-bound descriptor values assigned by an exact witness.

fn with_deep_kernel(reference: &DescriptorVector, config: CoverageConfig, deep_kernel: StableDeepKernel) -> Result<Self, CoverageError>

Construct coverage with an additional residual-neural deep-kernel GP.