`mod nd_hybrid`¶

module nd_hybrid¶

Cooperative basin and ridge exploration on one arbitrary-dimensional PES. Same-surface hybrid exploration for arbitrary-dimensional energy landscapes.

Basin escapes generate force-certified sources and minimum-mode rides turn those sources into index-one connections. Separate action-outcome GPs rank the next finite experiment by joint information about the identity and energy of the lowest reachable minimum per charged PES evaluation. Catalog admission is a producer–consumer barrier: an escape-discovered source is acknowledged by the ridge segment before escapes resume. The returned network belongs to one caller-supplied surface and witness; no identity, energy model, or evidence crosses between systems.

Functions

fn explore_nd_hybrid<S, W>(surface: &S, initial: ArrayView1<'_, f64>, config: &NdHybridConfig, witness: &W, seed: u64) -> Result<NdHybridReport, NdHybridError>¶ where S: PesSurface + ?Sized, W: ExactStructureWitness + ?Sized ¶

Explore one arbitrary-dimensional PES with cooperative basin and ridge arms.

Every discovered minimum enters one exact-witness network immediately. The ridge action domain dovetails over source-minimum segments and uses joint minimum information to order the signed modes inside each segment. This makes every admitted source reachable without assigning graph novelty or a stationary-point reward. A new invocation creates new action models and a new network, so two surfaces cannot share evidence.

fn explore_nd_with_policy<S, W>(surface: &S, initial: ArrayView1<'_, f64>, config: &NdHybridConfig, witness: &W, seed: u64, policy: NdHybridPolicy) -> Result<NdHybridReport, NdHybridError>¶ where S: PesSurface + ?Sized, W: ExactStructureWitness + ?Sized ¶

Explore one PES under an adaptive or fixed matched-budget mechanism policy.

Fixed policies use the same quench, ridge, witness, and accounting paths as the adaptive campaign, isolating the contribution of mechanism allocation.

fn explore_nd_with_policy_and_features<S, W, F>(surface: &S, initial: ArrayView1<'_, f64>, config: &NdHybridConfig, witness: &W, seed: u64, policy: NdHybridPolicy, action_features: &F) -> Result<NdHybridReport, NdHybridError>¶ where S: PesSurface + ?Sized, W: ExactStructureWitness + ?Sized, F: ActionFeatureMap + ?Sized ¶

Explore one PES with an explicit action representation.

Generic objectives use CoordinateActionFeatures. Atomistic callers use DescriptorActionFeatures so the outcome posterior compares physical structures independently of rigid coordinates and like-species labels.

Traits

trait ActionFeatureMap¶

Maps a concrete search point to the stable coordinates of an action GP.

Functions

fn encode(&self, point: ArrayView1<'_, f64>) -> Result<Vec<f64>, ActionFeatureError>¶: Encode one proposed or ridge-displaced point.

Enums

enum ActionFeatureError¶

Failure to construct a stable action coordinate for the outcome model.

EmptyPoint¶: Generic action points must contain at least one coordinate.

NonFiniteCoordinate¶

Generic action points cannot contain NaN or infinity.

index: usize¶: Index of the first invalid coordinate.

Descriptor(DescriptorError)¶: An invariant atomistic descriptor rejected the point or species.

enum NdEscapeKernel¶

Proposal kernel drawn for a generic basin-escape event.

Gaussian¶: Finite-variance local displacement.

Tsallis¶: Heavy-tailed generalized-simulated-annealing displacement.

enum NdHybridError¶

Configuration or initial-source failure that prevents a campaign.

InvalidConfig(&'static str)¶: A hybrid control lies outside its numerical domain.

InitialSource¶

The initial point did not produce a force-certified source minimum.

error: String¶: Stable quench failure text.

charged_evaluations: u64¶: PES calls consumed before the failure.

Mode(PesExplorationError)¶: A deterministic mode could not be constructed.

MinimumInformation(MinimumInformationError)¶: The action-outcome model rejected an invalid feature or score.

ActionFeature(ActionFeatureError)¶: The action representation rejected a concrete point.

enum NdHybridMechanism¶

Discovery mechanism responsible for one charged exploration event.

Ridge¶: Minimum-mode ridge following from a shared exact minimum.

BasinEscape¶: Gaussian or heavy-tailed proposal followed by an rgmin quench.

enum NdHybridPolicy¶

Mechanism policy used for matched-budget comparisons.

Adaptive¶: Allocate every concrete action by minimum-energy information per cost.

RidgeOnly¶: Explore only the finite signed mode portfolio of discovered sources.

BasinEscapeOnly¶: Generate exact minima by perturb–quench escapes without riding them.

enum NdHybridTermination¶

Why a hybrid campaign stopped issuing PES evaluations.

BudgetConsumed¶: The matched potential-call budget was consumed.

NoPesProgress¶: A numerical path returned without issuing a PES evaluation.

RidePortfolioExhausted¶: Every configured signed ridge mode has been attempted.

Structs and Unions

struct CoordinateActionFeatures¶

Identity feature map for generic N-dimensional objective functions.

Traits implemented

impl ActionFeatureMap for CoordinateActionFeatures¶

struct DescriptorActionFeatures¶

Rotation-, translation-, and like-species-permutation-invariant atomistic map.

Implementations

impl DescriptorActionFeatures¶

Functions

fn new(descriptor_space: DescriptorSpace, species: Vec<u32>) -> Self¶: Bind one immutable descriptor geometry and ordered species vector.

Traits implemented

impl ActionFeatureMap for DescriptorActionFeatures¶

struct NdHybridConfig¶

Controls for one system-local generic PES exploration campaign.

evaluation_budget: u64¶: Hard PES-evaluation budget, including the initial source quench.

ride_evaluation_cap: u64¶: Largest call slice assigned to one ridge ride.

escape_evaluation_cap: u64¶: Largest call slice assigned to one perturb–quench escape.

ride_mode_blocks: u16¶: Seeded orthonormal mode blocks explored per source.

initial_escape_scale: f64¶: Initial scale of Gaussian and Tsallis source proposals.

initial_acceptance_threshold: f64¶: Initial Goedecker acceptance threshold on quenched energy rises.

visiting_q: f64¶: Tsallis visiting index in (1, 3) for the heavy-tailed escape arm.

exploration: PesExplorationConfig¶: rgmin, rgsaddle, P-RFO, and branch-certification controls.

struct NdHybridEvent¶

One observable mechanism decision and its stationary-point yield.

attempt: u64¶: Monotonic event index after the initial source quench.

mechanism: NdHybridMechanism¶: Mechanism selected by the declared discovery policy.

ridge_information_rate: Option<f64>¶: Best ridge-action minimum-information rate at this decision.

escape_information_rate: Option<f64>¶: Best basin-action minimum-information rate at this decision.

selected_information: f64¶: GIBBON information of the concrete action that was evaluated.

selected_information_rate: f64¶: Selected information divided by its expected charged PES cost.

source_basin: Option<usize>¶: Exact source basin for the proposal or ridge.

source_energy: f64¶: Exact energy of the source minimum used by the action model.

terminal_energy: f64¶: Lowest terminal minimum energy returned by this action.

mode_rank: Option<u16>¶: Mode rank for ridge events.

direction: Option<RideModeDirection>¶: Signed initialization for ridge events.

escape_kernel: Option<NdEscapeKernel>¶: Proposal kernel for basin-escape events.

new_minimum_ids: Vec<usize>¶: Exact minimum identities introduced by this event.

new_saddle_ids: Vec<usize>¶: Certified saddle identities introduced by this event.

new_unresolved_saddle_ids: Vec<usize>¶: Unresolved index-one saddle identities introduced by this event.

escape_observations: u64¶: Successful source quenches included in the exact-basin census.

escape_unseen_mass_upper: Option<f64>¶: Esty one-sided upper bound on unseen exact-basin mass.

escape_coverage_saturated: bool¶: Whether the source census meets its visit and unseen-mass criteria.

charged_evaluations: u64¶: PES evaluations charged to this event.

converged: bool¶: Whether the selected numerical path returned its certified object.

budget_exhausted: bool¶: Whether the event attempted to step beyond its assigned slice.

error: Option<String>¶: Stable numerical failure text, when no certified object was returned.

struct NdHybridReport¶

Exact stationary network and allocation evidence from one surface.

network: NdPesNetwork¶: System-local exact minimum–saddle graph.

policy: NdHybridPolicy¶: Adaptive or fixed mechanism policy used by the campaign.

charged_evaluations: u64¶: Total PES evaluations, including the initial source quench.

events: Vec<NdHybridEvent>¶: Ordered mechanism evidence.

mechanism_pulls: Vec<usize>¶: Ridge then basin-escape exposure counts.

mechanism_discovery_rates: Vec<f64>¶: Empirical distinct-stationary-object discoveries per PES evaluation.

move_pulls: Vec<usize>¶: Gaussian then Tsallis proposal exposure counts.

move_success_rates: Vec<f64>¶: Empirical probability that each escape proposal lowers source energy.

escape_observations: u64¶: Successful source quenches included in the exact-basin census.

escape_singletons: u64¶: Exact basins represented by one source-quench observation.

escape_unseen_mass_upper: Option<f64>¶: Esty one-sided upper bound on unseen exact-basin mass.

escape_coverage_saturated: bool¶: Whether the source census meets its visit and unseen-mass criteria.

termination: NdHybridTermination¶: Terminal budget condition.

mod nd_hybrid¶

`mod nd_hybrid`¶