Struct State 

pub struct State {
    pub energy: f64,
    pub forces: DVector<f64>,
    pub geometry: Geometry,
}

Represents an electronic state of a molecule with energy, forces, and geometry.

The State struct encapsulates all information about a single electronic state needed for MECP optimization: the potential energy, the gradient (forces), and the molecular geometry at which these were evaluated.

In the MECP algorithm, we track two states simultaneously (typically called “state A” and “state B”) and seek the geometry where their energies are equal while minimizing the perpendicular gradient component.

Unit Conventions

• Energy: Hartree (Ha) - atomic unit of energy
• Forces/Gradients: Hartree/Angstrom (Ha/Å) - converted from native QM output
• Geometry coordinates: Angstrom (Å) - see Geometry documentation

Force Convention

Forces are the negative gradient of the energy with respect to nuclear positions:

F = -∇E

This is the standard convention in quantum chemistry, where positive forces point in the direction of decreasing energy. Forces are converted from the native QM program output (Ha/Bohr) to Ha/Å for consistency with coordinates.

Fields

energy: f64

Potential energy of the state in Hartree (Ha)

forces: DVector<f64>

Forces (negative gradient) in Hartree/Angstrom (Ha/Å) Stored as a flat vector matching Geometry::coords format

geometry: Geometry

Molecular geometry at which energy and forces were evaluated (coordinates in Angstrom)

Implementations

impl State

pub fn validate(&self) -> Result<(), String>

Validates that the State contains meaningful data and is not a zero-energy failure.

This method checks for common failure modes where QM calculations appear to succeed but actually return invalid or default values. It prevents silent failures that could lead to incorrect MECP optimization results.

Validation Criteria

The State is considered invalid if:

• Energy is exactly zero (indicates parsing failure or uninitialized state)
• All force components are zero (indicates gradient calculation failure)
• Forces vector is empty (indicates missing gradient data)

Returns

• Ok(()) if the State contains valid, meaningful data
• Err(String) with a descriptive error message if validation fails

Examples

use omecp::geometry::{Geometry, State};
use nalgebra::DVector;

// Valid state with non-zero energy and forces
let geometry = Geometry::new(vec!["H".to_string()], vec![0.0, 0.0, 0.0]);
let valid_state = State {
    energy: -0.5,
    forces: DVector::from_vec(vec![0.1, -0.2, 0.0]),
    geometry,
};
assert!(valid_state.validate().is_ok());

// Invalid state with zero energy
let geometry = Geometry::new(vec!["H".to_string()], vec![0.0, 0.0, 0.0]);
let invalid_state = State {
    energy: 0.0,
    forces: DVector::from_vec(vec![0.1, -0.2, 0.0]),
    geometry,
};
assert!(invalid_state.validate().is_err());

Trait Implementations

impl Clone for State

fn clone(&self) -> State

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for State

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.