Struct DriveCoordinate 

pub struct DriveCoordinate {
    pub coord_type: CoordinateType,
    pub atoms: Vec<usize>,
    pub target_value: f64,
}

Represents a specific geometric coordinate to drive during reaction path exploration.

This struct encapsulates all information needed to define and manipulate a reaction coordinate during path optimization or coordinate driving procedures. It serves as the fundamental building block for reaction path methods.

Coordinate Specification

The coordinate is fully specified by:

1. Type: Bond, angle, or dihedral (determines the mathematical formula)
2. Atoms: The specific atoms involved (defines which atoms to measure)
3. Target: The desired value to drive the coordinate toward

Atom Indexing Convention

All atom indices are 0-based (first atom is index 0). The number of atoms required depends on the coordinate type:

• Bond: 2 atoms [i, j] - distance between atoms i and j
• Angle: 3 atoms [i, j, k] - angle i-j-k with j as vertex
• Dihedral: 4 atoms [i, j, k, l] - torsion around j-k bond

Units and Conventions

• Bond lengths: Angstroms (Angstrom) - typical range 0.5-5.0 Angstrom
• Angles: Radians internally - typical range 0 to π (0° to 180°)
• Dihedrals: Radians internally - range -π to π (-180° to 180°)

Examples

use omecp::reaction_path::{DriveCoordinate, CoordinateType};

// C-H bond dissociation: drive from 1.1 Angstrom to 3.0 Angstrom
let bond_breaking = DriveCoordinate::new(
    CoordinateType::Bond,
    vec![0, 1],  // Carbon (0) to Hydrogen (1)
    3.0          // Target distance in Angstroms
);

// Ring opening: drive C-C-C angle from 60° to 120°
let ring_opening = DriveCoordinate::new(
    CoordinateType::Angle,
    vec![0, 1, 2],           // Atoms forming the angle
    120.0_f64.to_radians()   // Target angle in radians
);

// Conformational change: rotate around C-C bond
let rotation = DriveCoordinate::new(
    CoordinateType::Dihedral,
    vec![0, 1, 2, 3],        // Four atoms defining dihedral
    180.0_f64.to_radians()   // Target dihedral in radians
);

Fields

coord_type: CoordinateType

The type of geometric coordinate being driven.

Determines the mathematical formula used to calculate the coordinate value and its derivatives. This affects how the constraint forces are computed during optimization.

atoms: Vec<usize>

Vector of atom indices (0-based) defining the coordinate.

The length and interpretation depend on the coordinate type:

• Bond: [atom1, atom2] - 2 atoms
• Angle: [atom1, atom2, atom3] - 3 atoms (atom2 is vertex)
• Dihedral: [atom1, atom2, atom3, atom4] - 4 atoms (rotation around bond 2-3)

target_value: f64

The target value for the coordinate.

Units depend on coordinate type:

• Bond: Angstroms (Angstrom)
• Angle: Radians (use .to_radians() to convert from degrees)
• Dihedral: Radians (range -π to π)

Implementations

impl DriveCoordinate

pub fn new( coord_type: CoordinateType, atoms: Vec<usize>, target_value: f64, ) -> Self

Creates a new DriveCoordinate instance.

Arguments

• coord_type - The type of geometric coordinate (Bond, Angle, Dihedral).
• atoms - A vector of atom indices (0-based) defining the coordinate.
• target_value - The target value for the coordinate.

Returns

A new DriveCoordinate instance.

pub fn current_value(&self, geometry: &Geometry) -> f64

Calculates the current value of this coordinate in the given geometry.

This method evaluates the coordinate using the current atomic positions and returns the actual measured value. It’s essential for monitoring the progress of coordinate driving and checking convergence.

Arguments

• geometry - The molecular geometry to evaluate the coordinate in

Returns

The current value of the coordinate in appropriate units:

• Bond: distance in Angstroms
• Angle: angle in radians
• Dihedral: torsion angle in radians (-π to π)

Algorithm

1. Convert the coordinate specification to a constraint
2. Use the constraint evaluation system to calculate the current value
3. Return the measured value (constraint violation represents deviation from target)

Examples

use omecp::reaction_path::{DriveCoordinate, CoordinateType};

let bond_coord = DriveCoordinate::new(
    CoordinateType::Bond,
    vec![0, 1],
    1.5  // Target value (not used in current_value)
);

// let current_distance = bond_coord.current_value(&geometry);
// println!("Current C-H distance: {:.3} Angstrom", current_distance);

pub fn to_constraint(&self) -> Constraint

Creates a constraint object for this coordinate using the stored target value.

This method converts the coordinate specification into a constraint that can be used by the optimization system. The constraint represents the mathematical relationship that should be satisfied.

Returns

A Constraint enum variant appropriate for the coordinate type, with the target value set to self.target_value.

Implementation Details

The method maps coordinate types to constraint types:

• CoordinateType::Bond → Constraint::Bond
• CoordinateType::Angle → Constraint::Angle
• CoordinateType::Dihedral → Constraint::Dihedral

Each constraint contains the atom indices and target value needed for constraint evaluation and gradient calculation.

Examples

let coord = DriveCoordinate::new(
    CoordinateType::Bond,
    vec![0, 1],
    1.8
);

let constraint = coord.to_constraint();
// This constraint can now be used in optimization

pub fn to_constraint_with_value(&self, target_value: f64) -> Constraint

Creates a constraint object for this coordinate with a custom target value.

This method is similar to to_constraint() but allows specifying a different target value than the one stored in the coordinate. This is particularly useful during coordinate driving where the target value changes at each step.

Arguments

• target_value - The desired target value for the constraint

Returns

A Constraint enum variant with the specified target value.

Use Cases

• Coordinate Driving: Generate constraints for intermediate target values
• Path Optimization: Create constraints for specific path points
• Scanning: Systematically vary the target value for PES exploration

Examples

let coord = DriveCoordinate::new(
    CoordinateType::Bond,
    vec![0, 1],
    2.0  // Original target
);

// Create constraint for intermediate value during driving
let intermediate_constraint = coord.to_constraint_with_value(1.5);

Trait Implementations

impl Clone for DriveCoordinate

fn clone(&self) -> DriveCoordinate

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DriveCoordinate

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

Formats the value using the given formatter.