`mod pes_exploration`¶

module pes_exploration¶

rgmin quenches and rgsaddle minimum–saddle–minimum connections. Minimum–saddle–minimum exploration with rgmin and rgsaddle.

The descriptor orders structural comparisons but never certifies identity. A caller-supplied exact witness makes the final equivalence decision. This keeps catalog admission independent of a fixed descriptor radius while the same universal descriptor remains available for novelty and acquisition.

Re-exports

:rust:any:rgsaddle::IrcKind

Functions

fn deflate_cartesian_mode(coordinates: ArrayView1<f64>, mode: ArrayView1<f64>, avoided_saddles: &[Vec<f64>], frozen_atoms: &[bool], geometry: DescriptorGeometry) -> Result<Array1<f64>, PesExplorationError>¶

Remove escape directions leading to already certified saddles.

Every avoided saddle is expressed in the same labelled Cartesian frame as coordinates. Minimum-image displacements are projected onto the live free-coordinate tangent space and orthonormalized before they are removed from mode. If the supplied mode lies entirely in the known subspace, the largest remaining canonical tangent direction provides a deterministic replacement.

fn discover_cartesian_mode_connection<S, W>(surface: &S, descriptor_space: &DescriptorSpace, network: &mut PesNetwork, start: ArrayView1<f64>, masses: ArrayView1<f64>, frozen_atoms: &[bool], mode: ArrayView1<f64>, species: Option<&[u32]>, config: &PesExplorationConfig, witness: &W) -> Result<SaddleConnection, PesExplorationError>¶ where S: PesSurface, W: ExactStructureWitness + ?Sized ¶

Discover an atomistic connection and certify its index only on free modes.

The descriptor geometry determines whether rotations are rigid symmetries; frozen_atoms removes externally fixed coordinates. This is the production path for finite clusters, molecules, and periodic surfaces. The native discover_mode_connection path remains available for Cartesian-shaped mathematical surfaces whose coordinates do not obey atomistic symmetries.

fn discover_cartesian_mode_connection_in_context_with_budget<S, W>(surface: &S, descriptor_space: &DescriptorSpace, network: &mut PesNetwork, start: ArrayView1<f64>, frozen_atoms: &[bool], mode: ArrayView1<f64>, context: &StructureContext, config: &PesExplorationConfig, witness: &W, maximum_evaluations: u64) -> CartesianConnectionAttempt¶ where S: PesSurface + ?Sized, W: ExactStructureWitness + ?Sized ¶

Run one budgeted atomistic ridge ride in a caller-owned identity domain.

The context supplies the species, masses, descriptor geometry, and system namespace stored on every admitted minimum and saddle. This keeps records from distinct PES invocations non-interchangeable even when their Cartesian shapes happen to be equivalent.

fn discover_cartesian_mode_connection_with_budget<S, W>(surface: &S, descriptor_space: &DescriptorSpace, network: &mut PesNetwork, start: ArrayView1<f64>, masses: ArrayView1<f64>, frozen_atoms: &[bool], mode: ArrayView1<f64>, species: Option<&[u32]>, config: &PesExplorationConfig, witness: &W, maximum_evaluations: u64) -> CartesianConnectionAttempt¶ where S: PesSurface + ?Sized, W: ExactStructureWitness + ?Sized ¶

Run one atomistic ridge ride under a hard PES-evaluation boundary.

This preserves the Cartesian free-mode projection, receiving-side index certification, mass-weighted IRC, invariant descriptors, and exact identity witness of discover_cartesian_mode_connection. Calls refused at the boundary are not charged.

fn discover_mode_connection<S, W>(surface: &S, descriptor_space: &DescriptorSpace, network: &mut PesNetwork, start: ArrayView1<f64>, masses: ArrayView1<f64>, mode: ArrayView1<f64>, species: Option<&[u32]>, config: &PesExplorationConfig, witness: &W) -> Result<SaddleConnection, PesExplorationError>¶ where S: PesSurface, W: ExactStructureWitness + ?Sized ¶: Quench a basin, ride one supplied mode, roll both IRC branches, and admit the resulting exact minimum and saddle identities.

fn discover_nd_connection<S, W>(surface: &S, network: &mut NdPesNetwork, start: ArrayView1<f64>, mode: ArrayView1<f64>, config: &PesExplorationConfig, witness: &W) -> Result<NdSaddleConnection, PesExplorationError>¶ where S: PesSurface, W: ExactStructureWitness + ?Sized ¶

Quench a point, ride one supplied mode to an index-one saddle, and quench both downhill branches on an arbitrary-dimensional surface.

This path has no atomistic descriptor, mass, species, or 3N requirement. Both branches use the established rgsaddle IRC session with a Euclidean coordinate metric, then rgmin certifies their endpoint minima. An atomistic caller uses discover_mode_connection to select the mass-weighted rigid quotient instead.

fn discover_nd_connection_with_budget<S, W>(surface: &S, network: &mut NdPesNetwork, start: ArrayView1<f64>, mode: ArrayView1<f64>, config: &PesExplorationConfig, witness: &W, maximum_evaluations: u64) -> NdConnectionAttempt¶ where S: PesSurface + ?Sized, W: ExactStructureWitness + ?Sized ¶

Run one N-dimensional ridge ride under a hard PES-evaluation boundary.

Calls refused at the boundary are not charged. The supplied network keeps any certified minima or unresolved saddle evidence accumulated before a scientific failure, so a hybrid explorer can reuse the evidence.

fn gaussian_nd_mode(dimension: usize, seed: u64, rank: u16, direction: RideModeDirection) -> Result<Array1<f64>, PesExplorationError>¶: Generate a deterministic normalized Gaussian mode for an arbitrary-N surface.

fn localized_cartesian_mode(coordinates: ArrayView1<f64>, representative_atom: usize, frozen_atoms: &[bool], geometry: DescriptorGeometry, localization_radius: f64, seed: u64, rank: u16, direction: RideModeDirection) -> Result<Array1<f64>, PesExplorationError>¶

Generate an atom-local Gaussian mode with physical constraints applied.

Gaussian components are attenuated by scaled minimum-image distance from representative_atom. Fully mobile finite clusters lose translations and rotations; periodic structures lose translations only. Frozen atoms remain exactly stationary and make the external constraints authoritative instead of applying whole-structure rigid-motion projection.

fn orthonormal_nd_mode(dimension: usize, seed: u64, rank: u16, direction: RideModeDirection) -> Result<Array1<f64>, PesExplorationError>¶

Generate one direction from a seeded orthonormal basis block in arbitrary N.

Ranks 0..dimension cover one Gaussian-distributed orthonormal basis before the next independently seeded block begins. This preserves isotropy while preventing a finite ride portfolio from repeatedly sampling nearly parallel directions. The direction sign is applied after orthogonalization.

fn quench_minimum<S: PesSurface + ?Sized>(surface: &S, start: ArrayView1<f64>, steps: usize, gradient_tolerance: f64) -> Result<QuenchedMinimum, PesExplorationError>¶

Quench an arbitrary-dimensional PES point with rgmin L-BFGS.

The returned point must satisfy the requested Cartesian infinity-norm gradient condition; exhausting the iteration limit is an explicit error.

fn quench_minimum_with_norm<S: PesSurface + ?Sized>(surface: &S, start: ArrayView1<f64>, steps: usize, gradient_tolerance: f64, gradient_norm_tolerance: f64) -> Result<QuenchedMinimum, PesExplorationError>¶

Quench an arbitrary-dimensional PES point with a strict rgmin target and an independent Euclidean force-norm certification gate.

The component tolerance controls rgmin. The returned point is accepted if its measured gradient satisfies either that infinity-norm target or the supplied Euclidean norm contract.

fn stationary_index<S: PesSurface + ?Sized>(surface: &S, coordinates: ArrayView1<f64>, step: f64, negative_tolerance: f64) -> Result<StationaryIndex, PesExplorationError>¶

Certify a stationary-point index from central differences of PES gradients.

This arbitrary-dimensional form counts every native coordinate. Atomistic callers with rigid or frozen directions use stationary_index_cartesian.

fn stationary_index_cartesian<S: PesSurface + ?Sized>(surface: &S, coordinates: ArrayView1<f64>, frozen_atoms: &[bool], periodic: [bool; 3], step: f64, negative_tolerance: f64) -> Result<StationaryIndex, PesExplorationError>¶

Certify the index on the free Cartesian tangent space of one atomic system.

Frozen coordinates are removed exactly. An unconstrained finite system also removes translation and rotation, while an unconstrained periodic system removes translation. The projected directions remain as numerical zero eigenvalues and therefore cannot masquerade as unstable physical modes.

Traits

trait ExactStructureWitness¶

Symmetry-aware final witness for structural identity.

Functions

fn equivalent(&self, left: ArrayView1<f64>, right: ArrayView1<f64>) -> bool¶: Whether two Cartesian structures represent the same stationary point.

fn equivalent_structures(&self, left: StructureView<'_>, right: StructureView<'_>) -> bool¶

Whether two fully contextualized structures represent one identity.

The default rejects species, cell/PBC, or identity-domain mismatches before applying the coordinate witness. Implementations may override this method to canonicalize symmetry-equivalent cells or domains.

fn relation(&self, left: ArrayView1<f64>, right: ArrayView1<f64>) -> ExactStructureRelation¶

Exact relation between two Cartesian representatives.

The default distinguishes identity from non-identity but does not claim a symmetry operation. Implementations backed by an exact matcher can return the atom permutation that certifies a quotient-space self-loop.

fn relation_structures(&self, left: StructureView<'_>, right: StructureView<'_>) -> ExactStructureRelation¶: Exact relation between two fully contextualized representatives.

Implemented for

impl<F> ExactStructureWitness for F¶ where F: for<'a, 'b> Fn(ArrayView1<'a, f64>, ArrayView1<'b, f64>) -> bool ¶

impl crate::pes_exploration::ExactStructureWitness for IraStructureWitness¶

trait PesSurface¶

Energy and Cartesian-gradient evaluator used by all exploration stages.

Types

type Error¶: Surface-specific evaluation failure.

Functions

fn evaluate(&self, coordinates: ArrayView1<f64>) -> Result<(f64, Array1<f64>), Self::Error>¶: Return energy and a gradient matching the Cartesian input dimension.

Implemented for

impl crate::pes_exploration::PesSurface for PairPotential¶

impl<S> PesSurface for BudgetedSurface<'_, S>¶ where S: PesSurface + ?Sized ¶

impl<S> PesSurface for LimitedSurface<'_, S>¶ where S: PesSurface + ?Sized ¶

Enums

enum ExactStructureRelation¶

Exact relation between two stationary-structure representatives.

Distinct¶: The structures are different stationary points.

Equivalent¶: The structures are the same representative within the witness tolerance.

NontrivialPermutation(Vec<usize>)¶: A non-identity atom permutation is required to establish equivalence.

Implementations

impl ExactStructureRelation¶

Functions

fn is_equivalent(&self) -> bool¶: Whether the relation belongs to one exact stationary-point identity.

fn is_nontrivial_permutation(&self) -> bool¶: Whether the relation certifies a quotient-space rearrangement.

enum PesExplorationError¶

Failure that prevents one connection from becoming catalog evidence.

InvalidShape(&'static str)¶: Coordinates, masses, species, or a mode have incompatible dimensions.

InvalidConfig(&'static str)¶: A configuration field violates its numerical domain.

Surface(String)¶: The user surface rejected an evaluation.

InvalidEvaluation(&'static str)¶: A surface returned a malformed or nonfinite value/gradient pair.

QuenchNotConverged¶

rgmin stopped without satisfying the minimum force condition.

max_gradient: f64¶: Final infinity norm.

SaddleNotConverged¶

A saddle-search or certification stage stopped before its force condition.

stage: SaddleConvergenceStage¶: Saddle stage that stopped.

ActivationNotEscaped¶

The activation ray did not reach negative directional curvature.

lowest_curvature: f64¶: Lowest directional curvature observed across all activation radii.

MinimumModeLostCurvature¶

Minimum-mode following ended without retaining an unstable mode.

curvature: f64¶: Curvature reported at the force-converged minimum-mode candidate.

NotFirstOrder¶

The stationary candidate is not an index-one saddle.

negative_modes: usize¶: Number of eigenvalues below the negative-curvature tolerance.

lowest_curvature: f64¶: Lowest certified Hessian eigenvalue.

CollapsedConnection¶: Both IRC branches resolved to one exact minimum.

DisconnectedConnection¶: A one-sided minimum-mode ride did not reconnect to its source basin.

Descriptor(DescriptorError)¶: Universal descriptor evaluation or comparison failed.

Saddle(String)¶: rgsaddle session failure.

enum RideMethod¶

Lowest-mode ride used to approach a saddle.

Dimer¶: Jónsson dimer rotation with finite-difference Hessian actions.

Lanczos¶: Matrix-free Lanczos estimate of the lowest Hessian mode.

Implementations

impl RideMethod¶

impl RideMethod¶

Traits implemented

impl From<WireRideMethod> for RideMethod¶

enum RideModeDirection¶

Sign of a deterministic transition-search initialization.

Negative¶: Reverse the generated mode.

Positive¶: Use the generated mode as sampled.

Implementations

impl RideModeDirection¶

enum SaddleConvergenceStage¶

Numerical stage that must converge before a saddle can be certified.

MinimumMode¶: Minimum-mode following along the activated unstable direction.

Prfo¶: Sella partitioned rational-function refinement.

ForceCertification¶: Independent force check at the proposed saddle coordinates.

Traits implemented

impl Display for SaddleConvergenceStage¶

Structs and Unions

struct CartesianConnectionAttempt¶

Result and exact potential charge of one budgeted atomistic ridge ride.

connection: Result<SaddleConnection, PesExplorationError>¶: Certified connection or the scientific failure returned by the ride.

charged_evaluations: u64¶: PES evaluations accepted by the hard counter.

budget_exhausted: bool¶: Whether the ride attempted an evaluation beyond its assigned slice.

struct MinimumAdmission¶

Result of exact-witness minimum admission.

id: usize¶: Stable minimum index.

is_new: bool¶: Whether a new exact structural identity entered the network.

nearest_descriptor_distance: Option<f64>¶: Nearest descriptor distance before the exact witness decision.

struct MinimumRecord¶

One rgmin-certified local minimum.

id: usize¶: Stable index in the owning PesNetwork.

energy: f64¶: Receiving-side energy evaluated at the stored coordinates.

coordinates: Array1<f64>¶: Cartesian stationary point.

context: StructureContext¶: Species, cell/PBC, and system namespace used for exact identity.

max_gradient: f64¶: Final gradient infinity norm.

descriptor: DescriptorVector¶: Universal descriptor used for retrieval and novelty.

struct NdConnectionAttempt¶

Result and exact potential charge of one budgeted N-dimensional ridge ride.

connection: Result<NdSaddleConnection, PesExplorationError>¶: Certified connection or the scientific failure returned by the ride.

charged_evaluations: u64¶: PES evaluations accepted by the hard counter.

budget_exhausted: bool¶: Whether the ride attempted an evaluation beyond its assigned slice.

struct NdMinimumAdmission¶

Result of exact-witness minimum admission on one N-dimensional surface.

id: usize¶: Stable minimum index.

is_new: bool¶: Whether a new exact point identity entered the network.

nearest_coordinate_distance: Option<f64>¶: Nearest coordinate distance before the exact witness decision.

struct NdMinimumRecord¶

One rgmin-certified minimum on an arbitrary-dimensional point surface.

id: usize¶: Stable index in the owning NdPesNetwork.

energy: f64¶: Receiving-side energy evaluated at the stored point.

coordinates: Array1<f64>¶: Point in the native coordinates of the optimization problem.

max_gradient: f64¶: Final gradient infinity norm.

struct NdPesNetwork¶

Exact stationary-point graph for a single arbitrary-dimensional surface.

Point coordinates are used only to order exact-witness checks. The graph has no atom, species, Cartesian-geometry, or universal-descriptor contract, and it is never comparable with a graph belonging to another surface.

Implementations

impl NdPesNetwork¶

Functions

fn admit_minimum<W: ExactStructureWitness + ?Sized>(&mut self, minimum: QuenchedMinimum, witness: &W) -> NdMinimumAdmission¶: Admit a force-certified source minimum using the network’s exact witness.

fn minima(&self) -> &[NdMinimumRecord]¶: Stored minima in stable admission order.

fn minimum_count(&self) -> usize¶: Number of exact-witness minimum identities.

fn new() -> Self¶: Empty stationary-point graph for one point surface.

fn saddle_count(&self) -> usize¶: Number of exact-witness saddle identities.

fn saddle_observations(&self) -> u64¶: Exact connected and unresolved saddle observations, including repeats.

fn saddle_singletons(&self) -> u64¶: Exact saddle identities occurring once in the combined saddle sample.

fn saddles(&self) -> &[NdSaddleConnection]¶: Stored saddle connections in stable admission order.

fn unresolved_saddles(&self) -> &[NdSaddleConnection]¶: Index-one saddles whose downhill branches collapsed to one minimum.

struct NdSaddleConnection¶

One certified index-one connection on an arbitrary-dimensional surface.

id: usize¶: Stable index in the owning NdPesNetwork.

origin: usize¶: Minimum from which the mode ride started.

endpoints: [usize; 2]¶: Exact-witness endpoint minimum indices, positive then negative branch.

saddle_energy: f64¶: Receiving-side saddle energy.

saddle_coordinates: Array1<f64>¶: Saddle point in the native coordinates of the optimization problem.

curvature: f64¶: Lowest certified Hessian eigenvalue.

lowest_mode: Array1<f64>¶: Receiving-side lowest Hessian eigenvector.

negative_modes: usize¶: Number of certified negative Hessian eigenvalues.

saddle_max_gradient: f64¶: Saddle gradient infinity norm.

ride_method: RideMethod¶: Lowest-mode solver used for this connection.

struct PesExplorationConfig¶

Controls for one minimum–saddle–minimum connection attempt.

ride_method: RideMethod¶: Lowest-mode algorithm.

quench_steps: usize¶: Maximum rgmin L-BFGS iterations for each minimum certification.

saddle_steps: usize¶: Maximum rgsaddle lowest-mode steps.

minimum_mode_force_tolerance: f64¶: Force threshold for handing minimum-mode following to P-RFO.

irc_steps: usize¶: Maximum rgsaddle IRC outer points per direction.

prfo_steps: usize¶: Maximum Sella P-RFO refinement steps.

activation_attempts: usize¶: Number of expanding activation shells probed before minimum-mode following.

activation_growth: f64¶: Multiplicative radius increase while leaving the convex basin.

activation_relaxation_steps: usize¶: rgmin FIRE steps in the perpendicular hyperplane at each shell.

quench_gradient_tolerance: f64¶: Infinity-norm gradient threshold for a certified minimum.

quench_gradient_norm_tolerance: Option<f64>¶

Optional Euclidean gradient-norm certification threshold.

The infinity-norm threshold remains the rgmin stopping target. This second gate lets a receiving-side force contract certify the measured endpoint when numerical force noise prevents the optimizer from reaching its stricter component target.

saddle_force_tolerance: f64¶: Force threshold for the saddle sessions.

saddle_displacement: f64¶: Displacement from the quenched minimum along the supplied mode.

negative_curvature_tolerance: f64¶: Curvature must be below the negative of this value.

hessian_step: f64¶: Cartesian finite-difference step used to certify stationary index.

maximum_move: f64¶: Maximum Cartesian move used by minimum-mode and IRC steppers.

irc_step: f64¶: IRC outer radius in the selected coordinate metric.

irc_kind: IrcKind¶: Established rgsaddle IRC integration backend.

branch_attempts: usize¶: Resolution levels used to choose the molecular IRC launch radius.

branch_growth: f64¶: Reciprocal molecular IRC refinement factor.

irc_force_tolerance: f64¶: IRC force threshold before endpoint quenching.

refine_with_prfo: bool¶: Refine the lowest-mode candidate with Sella order-1 P-RFO.

Implementations

impl PesExplorationConfig¶

Traits implemented

impl Default for PesExplorationConfig¶

struct PesNetwork¶

Exact stationary-point graph accumulated across ride attempts.

Implementations

impl PesNetwork¶

Functions

fn admit_minimum<W: ExactStructureWitness + ?Sized>(&mut self, energy: f64, coordinates: Array1<f64>, max_gradient: f64, descriptor: DescriptorVector, witness: &W) -> Result<MinimumAdmission, DescriptorError>¶: Admit a certified minimum without applying a descriptor cutoff.

fn admit_minimum_with_context<W: ExactStructureWitness + ?Sized>(&mut self, energy: f64, coordinates: Array1<f64>, max_gradient: f64, descriptor: DescriptorVector, context: StructureContext, witness: &W) -> Result<MinimumAdmission, DescriptorError>¶: Admit a certified minimum with its complete exact-identity context.

fn minima(&self) -> &[MinimumRecord]¶: Stored minima in stable admission order.

fn minimum_count(&self) -> usize¶: Number of exact-witness minimum identities.

fn new() -> Self¶: Empty stationary-point graph.

fn saddle_count(&self) -> usize¶: Number of exact-witness saddle identities.

fn saddles(&self) -> &[SaddleConnection]¶: Stored saddle connections in stable admission order.

fn unresolved_saddles(&self) -> &[SaddleConnection]¶: Index-one saddles whose downhill branches did not define a new edge.

struct QuenchedMinimum¶

A force-converged local minimum produced by the rgmin quench contract.

energy: f64¶: Potential energy at the converged coordinates.

coordinates: Array1<f64>¶: Coordinates satisfying the requested force condition.

gradient: Array1<f64>¶: Fresh Cartesian gradient used to certify the returned coordinates.

max_gradient: f64¶: Infinity norm of the final Cartesian gradient.

struct SaddleConnection¶

One index-one saddle and its two quenched IRC endpoints.

id: usize¶: Stable index in the owning PesNetwork.

origin: usize¶: Minimum from which the mode ride started.

endpoints: [usize; 2]¶: Exact-witness endpoint minimum indices, forward then reverse.

saddle_energy: f64¶: Saddle energy.

saddle_coordinates: Array1<f64>¶: Cartesian saddle coordinates.

context: StructureContext¶: Species, cell/PBC, and system namespace used for exact identity.

curvature: f64¶: Lowest curvature reported at the force-converged candidate.

lowest_mode: Array1<f64>¶: Receiving-side lowest Hessian eigenvector at the certified saddle.

negative_modes: usize¶: Number of certified negative Hessian eigenvalues.

saddle_max_gradient: f64¶: Saddle gradient infinity norm.

descriptor: DescriptorVector¶: Descriptor retained for saddle deduplication and novelty.

ride_method: RideMethod¶: Lowest-mode ride used for this connection.

irc_at_minimum: [bool; 2]¶: Whether each IRC session met its own endpoint force condition.

struct StationaryIndex¶

Dense receiving-side Hessian eigensystem and stationary-point index.

eigenvalues: Array1<f64>¶: Hessian eigenvalues in ascending order.

lowest_mode: Array1<f64>¶: Normalized eigenvector belonging to the lowest eigenvalue.

negative_modes: usize¶: Number of eigenvalues below -negative_tolerance.

struct StructureContext¶

Species, boundary geometry, and caller domain carried by exact identity.

Implementations

impl StructureContext¶

Functions

fn geometry(&self) -> Option<DescriptorGeometry>¶: Descriptor geometry, including cell and periodic axes.

fn identity_domain(&self) -> Option<&str>¶: Caller-defined namespace preventing cross-system identity merges.

fn masses(&self) -> Option<&[f64]>¶: Per-atom masses in the native PES unit system, when known.

fn new(species: Option<Vec<u32>>, geometry: Option<DescriptorGeometry>, identity_domain: Option<String>) -> Self¶: Construct an owned identity context for a stationary structure.

fn species(&self) -> Option<&[u32]>¶: Ordered atomic numbers, when chemical identities are known.

fn with_masses(mut self, masses: Option<Vec<f64>>) -> Self¶: Attach per-atom native masses to the identity and persistence context.

struct StructureView<'a>¶

Borrowed structure and identity metadata presented to an exact witness.

coordinates: ArrayView1<'a, f64>¶: Cartesian coordinates.

context: &'a StructureContext¶: Species, boundary geometry, and caller identity namespace.

mod pes_exploration¶

`mod pes_exploration`¶