mod molecular

module molecular

GFN2-xTB water-cluster catalog identity.

The catalog uses the same fixed-dimensional multiscale invariant schema as clusters and surfaces through descriptor_space. The GFN2 engine, atomic species, flexible Cartesian degrees of freedom, and coordinate dimension remain in the system signature, so sharing a descriptor schema never merges PES state. Water groups remain proposal metadata and do not impose rigid distances on GFN2 minima. leftover_space remains the molecular proposal feature: its stacked species-conditioned residual p_i - mu_z(i) is not basin identity.

A complete visit still needs a loaded rgpot engine. Required engine fields: - kind: ENGINE_KIND - config_digest: SHA-256 of the declared GFN2 handle

(method=3, accuracy=0.01, etemp=300, maxiter=500, net_electron_count=0, uhf=0, vacuum_box=60)

• external_inputs["libxtb_engine"]: SHA-256 of the loaded libxtb_engine.so

fresh_evaluation is a compile-time stub under both rgpot-ex and the default feature set. anneal-core does not vendor the GFN2 Hamiltonian, so this module does not invent an energy.

Variables

const DESCRIPTOR_SCHEMA: &str

Catalog descriptor schema selected by this build.

const DESCRIPTOR_SCHEMA: &str

Featomic-backed catalog descriptor schema used by production builds.

const DESCRIPTOR_VERSION: u32

Schema version of DESCRIPTOR_SCHEMA.

const DESCRIPTOR_VERSION: u32

Schema version of DESCRIPTOR_SCHEMA.

const ENGINE_BINARY_INPUT: &str

External-input name for the loaded GFN2 engine shared object.

const ENGINE_KIND: &str

Stable engine family for the in-process rgpot GFN2-xTB handle.

const GFN2_ACCURACY: f64

SCF accuracy resolving cold-start force noise below the catalog threshold.

const GFN2_MAX_ITERATIONS: i32

SCF iteration ceiling paired with GFN2_ACCURACY.

const GFN2_METHOD: i32

xtb method code for GFN2 in the rgpot handle (XtbConfig::method).

const GROUP_SCHEMA: &str

Flexible atomic degrees of freedom of the GFN2 water PES.

const LEFTOVER_DESCRIPTOR_SCHEMA: &str

Molecular proposal-only leftover SOAP schema.

const LEFTOVER_DESCRIPTOR_VERSION: u32

Schema version of LEFTOVER_DESCRIPTOR_SCHEMA.

const MAX_GRADIENT_NORM: f64

Receiving-side Euclidean gradient-norm gate for GFN2 stationary points.

const VACUUM_BOX: f64

Vacuum box edge used by molecular_cluster (A).

const WATER_HEXAMER_MOLECULES: usize

Paper water-hexamer molecule count.

Functions

fn component_gradient_tolerance(coordinate_dim: usize) -> Result<f64, MolecularCatalogPresetError>

Componentwise solver tolerance that guarantees MAX_GRADIENT_NORM.

fn descriptor_space(species: &[u32]) -> Result<DescriptorSpace, MolecularCatalogPresetError>

Fixed-dimensional universal invariant space for a water catalog.

fn engine_binary_digest(bytes: &[u8]) -> [u8; 32]

SHA-256 of a loaded libxtb_engine.so. Callers pass the file bytes.

fn engine_config_digest() -> [u8; 32]

SHA-256 of the declared GFN2 handle. This is not the engine binary.

fn fresh_evaluation(n_molecules: usize, coordinates: &[f64]) -> Result<FreshEvaluation, String>

Fresh GFN2-xTB energy and forces for receiving-side validation.

The Hamiltonian is not in this crate. Both feature configurations refuse so a coordinator cannot mint an energy without the engine.

fn leftover_descriptor_dim(species: &[u32]) -> Result<usize, MolecularCatalogPresetError>

Stacked leftover dimension n_atoms * feat_dim(species).

fn leftover_space(species: &[u32]) -> Result<DescriptorSpace, MolecularCatalogPresetError>

Leftover SOAP used by the molecular proposal mechanism.

fn leftover_spec(species: &[u32]) -> Result<SoapSpec, MolecularCatalogPresetError>

Leftover SOAP spec used by the molecular hop on this species set.

fn leftover_values(coordinates: &[f64], species: &[u32]) -> Result<Vec<f64>, MolecularCatalogPresetError>

Species-conditioned leftover p_i - mu_z(i) stacked over atoms.

fn length_scale(species: &[u32]) -> Result<f64, MolecularCatalogPresetError>

Length scale of Config::for_molecular on the given species.

fn reference_coordinates(n_molecules: usize) -> Result<Vec<f64>, MolecularCatalogPresetError>

Nonoverlapping development reference from the isolated-water template.

fn system_signature(n_molecules: usize, engine_binary_digest: [u8; 32]) -> Result<SystemSignature, MolecularCatalogPresetError>

Canonical system signature for one (H2O)m GFN2-xTB cluster.

engine_binary_digest is the SHA-256 of the loaded libxtb_engine.so. This function does not invent that digest.

fn validator_config(reference_coordinates: &[f64], descriptor_dim: usize) -> Result<ValidatorConfig, MolecularCatalogPresetError>

Receiving-side validation settings for one water coordinate reference.

The numeric floors are the catalog validator contract, not a measured GFN2 gradient or energy tolerance.

fn water_groups(n_molecules: usize) -> Result<Vec<Vec<usize>>, MolecularCatalogPresetError>

Molecular proposal groups of (H2O)m: one water per three consecutive atoms.

fn water_species(n_molecules: usize) -> Result<Vec<u32>, MolecularCatalogPresetError>

Atomic numbers of (H2O)m in coordinate order.

Enums

enum MolecularCatalogPresetError

Invalid GFN2-xTB water catalog preset input.

InvalidMoleculeCount

At least one water molecule is required.

CoordinateDimension

Cartesian length must be exactly nine times the molecule count.

DescriptorDimension

Descriptor dimension must be positive.

SpeciesMismatch

Species vector must be [8, 1, 1] repeated once per molecule.