mod atomistic_hybrid

module atomistic_hybrid

Same-PES atomistic basin and ridge exploration by joint-optimum information. Same-PES atomistic global-minimum exploration by finite-action information.

Each invocation owns its descriptor geometry, chemical context, exact witness, action posterior, and stationary network. Basin actions are isotropic Gaussian perturbations followed by rgmin quenches. Ridge actions are physically projected local modes executed by rgsaddle minimum-mode, P-RFO, and IRC sessions. A GP for each action family is coupled only through the identity and value of the lowest reachable minimum. The selected action maximizes joint-optimum information divided by posterior mean PES cost.

Functions

fn explore_atomistic_with_policy<S, W>(surface: &S, descriptor_space: &DescriptorSpace, initial: ArrayView1<'_, f64>, system: &AtomisticSystem, config: &AtomisticHybridConfig, witness: &W, seed: u64, policy: AtomisticHybridPolicy) -> Result<AtomisticHybridReport, AtomisticHybridError>
where
    S: PesSurface + ?Sized,
    W: ExactStructureWitness + ?Sized

Explore one atomistic PES under an adaptive or fixed matched-cost policy.

Enums

enum AtomisticHybridError

Invalid system, action model, or initial-source failure.

InvalidConfig(&'static str)

A system or campaign control lies outside its domain.

InitialSource

The initial source did not reach a force-certified minimum.

error: String

Stable rgmin or surface failure.

charged_evaluations: u64

PES calls consumed before the failure.

Descriptor(DescriptorError)

Descriptor construction or exact-network comparison failed.

ActionFeature(ActionFeatureError)

An invariant action representation rejected a point.

MinimumInformation(MinimumInformationError)

A minimum-information model rejected its inputs.

Exploration(PesExplorationError)

A projected mode could not be constructed.

enum AtomisticHybridMechanism

Mechanism responsible for one charged atomistic action.

Ridge

Projected minimum-mode ride and IRC endpoint quenches.

BasinEscape

Isotropic perturbation followed by an rgmin quench.

enum AtomisticHybridPolicy

Mechanism restriction used by matched-PES-call comparisons.

Adaptive

Select across both action families by joint-optimum information per cost.

RidgeOnly

Evaluate only the finite projected ridge portfolio.

BasinEscapeOnly

Evaluate only perturb-and-quench actions.

enum AtomisticHybridTermination

Terminal condition of one atomistic campaign.

BudgetConsumed

The matched PES-call budget was consumed.

NoPesProgress

A numerical action returned without issuing a PES call.

RidePortfolioExhausted

Every finite ridge action was attempted.

Structs and Unions

struct AtomisticHybridConfig

Controls for one system-local atomistic exploration campaign.

evaluation_budget: u64

Hard PES-call budget including the initial source quench.

ride_evaluation_cap: u64

Largest PES-call slice assigned to one ridge action.

escape_evaluation_cap: u64

Largest PES-call slice assigned to one perturb-and-quench action.

ride_modes_per_atom: u16

Deterministic localized mode ranks exposed per mobile atom and source.

localization_radius: f64

Gaussian locality radius for rgsaddle launch modes.

escape_scales: Vec<f64>

Physical standard deviations in the finite basin-action portfolio.

minimum_information_samples: usize

Monte Carlo draws used by joint entropy search.

information_length_scale: f64

Descriptor-space GP length scale.

information_amplitude: f64

Terminal-energy-change GP amplitude.

information_noise: f64

Terminal-energy-change GP observation noise.

expected_ride_cost: f64

Prior mean PES calls for a ridge action.

expected_escape_cost: f64

Prior mean PES calls for a basin action.

cost_prior_strength: f64

Pseudo-observation weight of each cost prior.

exploration: PesExplorationConfig

rgmin, rgsaddle, P-RFO, IRC, and certification controls.

struct AtomisticHybridEvent

One observable action and its exact stationary-structure yield.

attempt: u64

Monotonic charged-action index.

mechanism: AtomisticHybridMechanism

Selected action family.

source_basin: usize

Exact source minimum in this report’s network.

source_energy: f64

Source energy used by the action model.

terminal_energy: f64

Lowest terminal energy returned by the action.

selected_information: f64

Joint optimum identity-and-value information.

selected_information_rate: f64

Selected information divided by posterior mean PES cost.

representative_atom: Option<usize>

Mobile atom localizing a ridge launch.

mode_rank: Option<u16>

Deterministic localized mode rank.

direction: Option<RideModeDirection>

Signed ridge direction.

escape_scale: Option<f64>

Gaussian basin displacement scale.

new_minimum_ids: Vec<usize>

Exact minimum identities introduced by this action.

new_saddle_ids: Vec<usize>

Certified index-one saddle identities introduced by this action.

new_unresolved_saddle_ids: Vec<usize>

Unresolved index-one saddle observations introduced by this action.

charged_evaluations: u64

PES calls charged to this action.

converged: bool

Whether the action returned its certified object.

budget_exhausted: bool

Whether the action attempted to exceed its assigned PES-call slice.

error: Option<String>

Stable numerical failure text.

struct AtomisticHybridReport

System-local stationary network and action-allocation evidence.

identity_domain: String

Caller namespace for the single PES represented by this report.

network: PesNetwork

Exact minima and certified or unresolved saddle observations.

policy: AtomisticHybridPolicy

Adaptive or fixed mechanism policy.

charged_evaluations: u64

Total PES calls, including the initial source quench.

events: Vec<AtomisticHybridEvent>

Ordered charged-action evidence.

mechanism_pulls: [usize; 2]

Ridge then basin-action exposure counts.

expected_mechanism_costs: [f64; 2]

Posterior mean cost for ridge then pooled basin actions.

termination: AtomisticHybridTermination

Terminal budget condition.

Implementations

impl AtomisticHybridReport

Functions

fn best_energy(&self) -> Option<f64>

Lowest force-certified minimum retained by this same-PES invocation.

fn first_encounter(&self, target: f64, tolerance: f64) -> Encounter

Charged work at the first encounter with a target energy.

A missing encounter remains censored at the campaign’s actual charged count, so fixed-budget failures participate in Kaplan–Meier summaries.

struct AtomisticSystem

Chemical and mechanical identity of one atomistic PES invocation.

species: Vec<u32>

Atomic numbers in coordinate order.

masses: Vec<f64>

Native masses, one per atom.

frozen_atoms: Vec<bool>

Coordinates constrained by the caller’s PES adapter.

identity_domain: String

Stable caller namespace retained with the report.