`mod descriptor_space`¶

module descriptor_space¶

Versioned multiscale invariant coordinates for basin catalogs. Versioned multiscale invariant descriptor spaces for catalog geometry.

Modules

mod pullback

Variables

const FEATOMIC_SOAP_NORMALIZATION: &str¶: Metric preprocessing applied to each featomic SOAP scale.

const FEATOMIC_SOAP_SCHEMA: &str¶: Stable schema name for featomic-backed multiscale SOAP features.

const FEATOMIC_SOAP_VERSION: u32¶: Schema version of FEATOMIC_SOAP_SCHEMA.

const UNIVERSAL_DESCRIPTOR_SCHEMA: &str¶: Stable schema name for the cross-system descriptor.

const UNIVERSAL_DESCRIPTOR_VERSION: u32¶: Stable schema version for the cross-system descriptor.

const UNIVERSAL_LOCAL_ENVIRONMENT_RADIUS: f64¶: Euclidean radius for block-balanced universal local environments.

Functions

fn universal_descriptor_space(geometry: DescriptorGeometry) -> DescriptorSpace¶: Construct the immutable descriptor shared by clusters, molecules, and surfaces.

Traits

trait InvariantDescriptorProvider¶

External source of fixed-dimensional invariant atomistic features.

Implementations typically wrap a metatomic feature or mtt::feature::<layer> output, or a featomic invariant calculator. Anneal owns neither the feature construction nor its fitted parameters.

Functions

fn contract(&self) -> &DescriptorProviderContract¶: Immutable identity and shape contract.

fn describe_atoms(&self, _input: DescriptorProviderInput<'_>) -> Result<Option<Array2<f64>>, DescriptorProviderError>¶: Evaluate the optional one-row-per-atom invariant feature.

fn describe_system(&self, input: DescriptorProviderInput<'_>) -> Result<Vec<f64>, DescriptorProviderError>¶: Evaluate the one-row-per-system invariant feature.

Enums

enum DescriptorBlockKind¶

Invariant aggregation used by one descriptor block.

SoapMean¶: Mean of species-aware local SOAP power spectra.

SoapVariance¶: Diagonal second central moment of local SOAP spectra.

AceNu3Mean¶: Mean ACE nu=3 contraction of local spherical expansions.

SoapLeftover¶: Stacked species-conditioned leftover (p_i-mu_{z(i)}).

PairRadial¶: Fixed-channel radial spectrum of minimum-image pair distances.

ThreeBodyAngular¶: Fixed-channel radial and angular spectrum of centred triples.

GraphTopology¶: Multiscale graph moments and connectivity statistics.

InvariantSoapMean¶: Fixed-channel rotation-invariant SOAP mean.

InvariantAceNu3Mean¶: Fixed-channel rotation-invariant ACE nu=3 mean.

ChiralMoment¶: Permutation-invariant pseudoscalar moments that distinguish mirror minima.

ProviderFeature¶: Fixed-dimensional invariant output supplied by an external provider.

Implementations

impl DescriptorBlockKind¶

enum DescriptorError¶

Input or schema failure that prevents descriptor evaluation.

EmptySchemaName¶: Schema name must identify its semantics.

ZeroSchemaVersion¶: Schema version zero is reserved.

EmptySchema¶: A descriptor requires at least one block.

ZeroRadialFunctions¶: SOAP requires at least one radial function.

InvalidCutoff¶: SOAP cutoff must be finite and positive.

InvalidLengthScale¶: Universal coordinates require a finite positive reference length.

PeriodicCellRequired¶: Periodic axes require an explicit simulation cell.

InvalidCell¶: A simulation cell must be finite and nonsingular.

CoordinateDimension¶

Cartesian coordinates must have exactly three components per atom.

actual: usize¶: Supplied coordinate length.

SpeciesDimension¶

Species count must equal atom count.

expected: usize¶: Number of Cartesian atoms.

actual: usize¶: Supplied species count.

NonFiniteCoordinate¶

Cartesian input contains NaN or infinity.

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

NonFiniteDescriptor¶

A SOAP or ACE primitive produced NaN or infinity.

block: usize¶: Ordered block index.

index: usize¶: Index within that block.

InvalidFiniteDifferenceStep¶: Central differences require a finite, strictly positive Cartesian step.

IncompatibleDescriptorVectors¶: Distances require vectors from one exact descriptor schema.

UniversalGeometryRequired¶: Universal blocks need the length scale and boundary conditions they encode.

NeighborSearch¶: Periodic linked-cell construction or search rejected the geometry.

EmptyProviderOutput¶: A provider output needs a stable name.

ZeroProviderDimension¶: A provider output must have at least one scalar channel.

MissingProviderDigest¶: Provider identity must pin a model or complete calculator configuration.

InvalidProviderInteractionRange¶: Provider interaction range must be finite and positive.

EmptyProviderNormalization¶: Provider normalization must identify its fixed metric semantics.

ProviderEvaluation¶

The external provider could not evaluate its declared output.

provider: String¶: Stable provider schema name.

message: String¶: Provider-supplied diagnostic.

ProviderDimension¶

A provider returned a vector that violates its fixed shape contract.

output: String¶: Declared output name.

expected: usize¶: Declared fixed dimension.

actual: usize¶: Returned dimension.

ProviderAtomicOutputRequired¶: Local descriptor rows are required for atom-targeted exploration.

ProviderAtomicShape¶

A provider returned an atomic matrix that violates its fixed shape contract.

output: String¶: Declared output name.

expected_rows: usize¶: Expected atom rows.

expected_columns: usize¶: Expected feature columns.

actual_rows: usize¶: Returned rows.

actual_columns: usize¶: Returned columns.

enum FeatomicSoapProviderError¶

Construction failure for a featomic SOAP provider.

EmptySpecies¶: At least one chemical species channel is required.

InvalidAtomicNumber(u32)¶: Atomic numbers must be positive and fit featomic’s signed label type.

EmptyScales¶: At least one radial scale is required.

InvalidScale¶: Cutoff and density widths must define a finite positive smooth cutoff.

DimensionOverflow¶: The selected basis and species channels exceed addressable memory.

Contract(DescriptorError)¶: Generic invariant-provider contract rejected the derived configuration.

Structs and Unions

struct DescriptorBlockMetadata¶

Metadata locating one normalized block in a descriptor vector.

Implementations

impl DescriptorBlockMetadata¶

Functions

fn cutoff(&self) -> f64¶: Fixed radial cutoff in coordinate units.

fn is_empty(&self) -> bool¶: Whether this block contains no values.

fn kind(&self) -> DescriptorBlockKind¶: Aggregation represented by this block.

fn l_max(&self) -> usize¶: Largest angular momentum channel.

fn len(&self) -> usize¶: Number of values in this block.

fn n_max(&self) -> usize¶: Number of radial basis functions.

fn normalization(&self) -> &str¶: Versioned normalization convention.

fn offset(&self) -> usize¶: First value belonging to this block.

fn raw_norm(&self) -> f64¶: Norm measured before block normalization.

struct DescriptorBlockSpec¶

Resolution and aggregation contract for one normalized block.

Implementations

impl DescriptorBlockSpec¶

Functions

fn cutoff(self) -> f64¶: Fixed radial cutoff in coordinate units.

fn kind(self) -> DescriptorBlockKind¶: Aggregation used by this block.

fn l_max(self) -> usize¶: Largest angular momentum channel.

fn n_max(self) -> usize¶: Number of radial basis functions.

fn new(kind: DescriptorBlockKind, n_max: usize, l_max: usize, cutoff: f64) -> Result<Self, DescriptorError>¶: Construct a validated block specification.

struct DescriptorGeometry¶

Length scale, simulation cell, and periodic axes used by one descriptor space.

Implementations

impl DescriptorGeometry¶

Functions

fn cell(self) -> Option<[f64; 9]>¶: Row-major cell vectors, when supplied.

fn finite(length_scale: f64) -> Result<Self, DescriptorError>¶: Construct nonperiodic geometry in units of length_scale.

fn length_scale(self) -> f64¶: Coordinate unit represented by one descriptor length.

fn new(length_scale: f64, cell: Option<[f64; 9]>, periodic: [bool; 3]) -> Result<Self, DescriptorError>¶: Construct geometry with row-major cell vectors and selected periodic axes.

fn periodic(self) -> [bool; 3]¶: Periodic lattice-vector flags.

struct DescriptorOutputSpec¶

One fixed-dimensional output exposed by a descriptor provider.

Implementations

impl DescriptorOutputSpec¶

Functions

fn dimension(&self) -> usize¶: Fixed number of scalar channels in the output.

fn name(&self) -> &str¶: Metatomic or provider-specific output name.

fn new(name: impl Into<String>, dimension: usize) -> Result<Self, DescriptorError>¶: Define a named output with a fixed number of scalar channels.

struct DescriptorProviderContract¶

Versioned identity and metric semantics of an invariant descriptor provider.

Implementations

impl DescriptorProviderContract¶

Functions

fn atomic_output(&self) -> Option<&DescriptorOutputSpec>¶: Optional one-row-per-atom output used for local ride targets.

fn interaction_range(&self) -> f64¶: Largest physical interaction range needed by the provider.

fn model_digest(&self) -> [u8; 32]¶: SHA-256 digest of the complete model or calculator configuration.

fn model_digest_hex(&self) -> String¶: Lowercase hexadecimal SHA-256 digest for catalog signatures and manifests.

fn new(schema_name: impl Into<String>, schema_version: u32, model_digest: [u8; 32], system_output: DescriptorOutputSpec, atomic_output: Option<DescriptorOutputSpec>, interaction_range: f64, normalization: impl Into<String>) -> Result<Self, DescriptorError>¶

Define an invariant provider whose scalar outputs use Euclidean distance.

system_output represents one row per system. atomic_output, when present, represents one row per atom. The provider implementation guarantees translation, rotation, and like-species permutation invariance for the system output and the corresponding equivariance of atomic rows. model_digest pins the complete model or analytic calculator configuration that gives these outputs their meaning.

fn normalization(&self) -> &str¶: Versioned preprocessing and normalization convention.

fn schema_name(&self) -> &str¶: Stable descriptor-family name.

fn schema_version(&self) -> u32¶: Positive descriptor-family version.

fn system_output(&self) -> &DescriptorOutputSpec¶: Required one-row-per-system output.

struct DescriptorProviderError¶

Evaluation failure reported by an external descriptor implementation.

Implementations

impl DescriptorProviderError¶

Functions

fn message(&self) -> &str¶: Provider-supplied diagnostic.

fn new(message: impl Into<String>) -> Self¶: Construct an evaluation error without exposing provider internals.

struct DescriptorProviderInput<'a>¶

Validated geometry and species passed to an external descriptor provider.

Implementations

impl<'a> DescriptorProviderInput<'a>¶

Functions

fn coordinates(&self) -> &ArrayView1<'a, f64>¶: Flat Cartesian coordinates with three entries per atom.

fn geometry(&self) -> DescriptorGeometry¶: Length scale, cell, and periodic axes for this evaluation.

fn species(&self) -> Option<&'a [u32]>¶: Atomic numbers in coordinate order, when supplied.

struct DescriptorSchema¶

Stable name, version, and ordered normalized-block definition.

Implementations

impl DescriptorSchema¶

Functions

fn blocks(&self) -> &[DescriptorBlockSpec]¶: Ordered block definitions.

fn name(&self) -> &str¶: Stable schema name.

fn new(name: impl Into<String>, version: u32, blocks: Vec<DescriptorBlockSpec>) -> Result<Self, DescriptorError>¶: Construct a versioned descriptor schema.

fn version(&self) -> u32¶: Schema version.

struct DescriptorSpace¶

Evaluator bound to one immutable descriptor schema.

Implementations

impl DescriptorSpace¶

Functions

fn describe(&self, coordinates: ArrayView1<f64>, species: Option<&[u32]>) -> Result<DescriptorVector, DescriptorError>¶: Evaluate all invariant blocks and concatenate their normalized values.

fn describe_local(&self, coordinates: ArrayView1<f64>, species: Option<&[u32]>) -> Result<Array2<f64>, DescriptorError>¶

Evaluate one fixed-dimensional invariant row for every atomic centre.

Universal local rows use the same geometry, species sketch, ordered blocks and contractive normalization as the global descriptor. Their final norm is below one, so one schema-bound Euclidean radius has stable meaning for clusters, molecules, and surfaces.

fn from_provider<P>(geometry: DescriptorGeometry, provider: P) -> Result<Self, DescriptorError>¶ where P: InvariantDescriptorProvider + 'static ¶: Bind an externally implemented invariant descriptor to this evaluator.

fn geometry(&self) -> Option<DescriptorGeometry>¶: Geometry contract carried by universal descriptor spaces.

fn jacobian_analytic(&self, coordinates: ArrayView1<f64>, species: Option<&[u32]>) -> Result<Array2<f64>, DescriptorError>¶: Evaluate the analytic Cartesian Jacobian of every normalized block.

fn jacobian_fd(&self, coordinates: ArrayView1<f64>, species: Option<&[u32]>, step: f64) -> Result<Array2<f64>, DescriptorError>¶: Evaluate the Cartesian Jacobian of the normalized descriptor by central differences.

fn new(schema: DescriptorSchema) -> Self¶: Bind an evaluator to a validated schema.

fn provider_contract(&self) -> Option<&DescriptorProviderContract>¶: External descriptor contract, or None for an in-tree legacy evaluator.

fn schema(&self) -> &DescriptorSchema¶: Immutable schema interpreted by this evaluator.

struct DescriptorVector¶

One descriptor vector and the metadata needed to interpret every value.

Implementations

impl DescriptorVector¶

Functions

fn blocks(&self) -> &[DescriptorBlockMetadata]¶: Ordered block metadata.

fn distance(&self, other: &Self) -> Result<f64, DescriptorError>¶: Euclidean pseudometric between vectors from the same descriptor schema.

fn schema_name(&self) -> &str¶: Stable schema name.

fn schema_version(&self) -> u32¶: Schema version.

fn values(&self) -> &[f64]¶: Concatenated normalized block values.

struct FeatomicSoapProvider¶

Fixed-channel multiscale SOAP features computed by featomic.

Species channels and all calculator hyperparameters are fixed at construction. Missing (center, neighbor_1, neighbor_2) blocks are zero, so the feature dimension does not depend on which species or coordination shells happen to be present in one structure.

Implementations

impl FeatomicSoapProvider¶

Functions

fn new(mut species_channels: Vec<u32>, scales: Vec<FeatomicSoapScale>) -> Result<Self, FeatomicSoapProviderError>¶: Bind fixed species channels and ordered SOAP resolutions.

fn scales(&self) -> &[FeatomicSoapScale]¶: Ordered short- and medium-range SOAP resolutions.

fn species_channels(&self) -> &[u32]¶: Ordered chemical species channels encoded by every output row.

Traits implemented

impl InvariantDescriptorProvider for FeatomicSoapProvider¶

struct FeatomicSoapScale¶

One radial and angular resolution in a multiscale SOAP provider.

Implementations

impl FeatomicSoapScale¶

Functions

fn cutoff(self) -> f64¶: Spherical cutoff in reduced descriptor coordinates.

fn density_width(self) -> f64¶: Gaussian atomic-density width in reduced descriptor coordinates.

fn max_angular(self) -> usize¶: Largest angular channel.

fn max_radial(self) -> usize¶: Largest radial basis index; the basis contains max_radial + 1 rows.

fn new(cutoff: f64, max_radial: usize, max_angular: usize) -> Result<Self, FeatomicSoapProviderError>¶: Construct a scale with widths tied to its cutoff.

fn smoothing_width(self) -> f64¶: Shifted-cosine smoothing width in reduced descriptor coordinates.

fn with_widths(cutoff: f64, max_radial: usize, max_angular: usize, density_width: f64, smoothing_width: f64) -> Result<Self, FeatomicSoapProviderError>¶: Construct a scale with explicit Gaussian-density and cutoff widths.

mod descriptor_space¶

`mod descriptor_space`¶