Skip to main content
← OpenMECP Documentation

omecp/
lib.rs

1#![deny(missing_docs)]
2
3//! OpenMECP - High-Performance Minimum Energy Crossing Point Optimizer
4//!
5//! OpenMECP is a Rust implementation of the Harvey et al. algorithm for locating
6//! Minimum Energy Crossing Points (MECP) between two potential energy surfaces
7//! in quantum chemistry calculations.
8//!
9//! # Overview
10//!
11//! The MECP is the geometry where two electronic states have the same energy but
12//! different wavefunctions. This is crucial for understanding:
13//! - Photochemical reactions
14//! - Spin-forbidden processes
15//! - Intersystem crossing
16//! - Conical intersections
17//! - Non-adiabatic dynamics
18//!
19//! # Algorithm
20//!
21//! OpenMECP implements the Harvey et al. algorithm (Chem. Phys. Lett. 1994) with
22//! modern optimization strategies. The MECP gradient combines two components:
23//!
24//! 1. **f-vector**: Drives energy difference to zero
25//!    ```text
26//!    f = (E1 - E2) * x_norm
27//!    ```
28//!
29//! 2. **g-vector**: Minimizes energy perpendicular to gradient difference
30//!    ```text
31//!    g = f1 - (x_norm ยท f1) * x_norm
32//!    ```
33//!
34//! Where `x_norm = (f1 - f2) / |f1 - f2|` is the normalized gradient difference.
35//!
36//! # Features
37//!
38//! - **Multiple Optimizers**: BFGS, GDIIS, GEDIIS with automatic switching
39//! - **QM Program Support**: Gaussian, ORCA, Bagel, XTB, Custom interfaces
40//! - **Constraint System**: Bond, angle, and fixed atom constraints with Lagrange multipliers
41//! - **Advanced Methods**: LST interpolation, NEB, PES scans, coordinate driving
42//! - **Run Modes**: Normal, Read, NoRead, Stable, InterRead modes for various scenarios
43//! - **Energy Scanning**: 1D and 2D potential energy surface scans
44//! - **Restart Capability**: Checkpoint system for restarting calculations
45//! - **Multi-layer QM/MM**: ONIOM support for hybrid calculations
46//!
47//! # Quick Start
48//!
49//! ```no_run
50//! use omecp::parser::parse_input;
51//! use std::path::Path;
52//!
53//! fn main() -> Result<(), Box<dyn std::error::Error>> {
54//!     // Create configuration from file
55//!     let input_data = parse_input(Path::new("input.inp"))?;
56//!     let config = input_data.config;
57//!
58//!     // Run MECP optimization
59//!     // let result = config.run()?;
60//!
61//!     // println!("MECP converged at step: {}", result.steps);
62//!     Ok(())
63//! }
64//! ```
65//!
66//! # Supported QM Programs
67//!
68//! | Program | Methods | Features |
69//! |---------|---------|----------|
70//! | Gaussian | DFT, TD-DFT, MP2, CASSCF | Full feature support, checkpoints |
71//! | ORCA | DFT, TD-DFT, CASSCF | Energy/gradient files, GBW checkpoints |
72//! | XTB | GFN2-xTB | Fast semi-empirical calculations |
73//! | Bagel | CASSCF, MRCI | Advanced quantum chemistry methods |
74//! | Custom | Any | JSON-configurable interface |
75//!
76//! # Optimizers
77//!
78//! ## BFGS (Broyden-Fletcher-Goldfarb-Shanno)
79//! - Quasi-Newton method with PSB Hessian updates
80//! - Default for first 3 steps
81//! - Good general-purpose optimizer
82//!
83//! ## GDIIS (Geometry-based Direct Inversion in Iterative Subspace)
84//! - Automatically activates after 3 BFGS steps
85//! - 2-3x faster convergence than BFGS
86//! - Stores last 4 geometries and gradients
87//! - Computes error vectors for optimal step direction
88//!
89//! ## GEDIIS (Energy-Informed DIIS)
90//! - Enhanced version of GDIIS using energy information
91//! - Set `use_gediis = true` to enable (or `"blend"` for new GDIIS_blend method)
92//! - 2-4x faster convergence than GDIIS for difficult cases
93//! - Better handling of energy-difference minimization
94//!
95//! # Modules
96//!
97//! - [`config`](config/index.html) - Configuration structures and parsing
98//! - [`geometry`](geometry/index.html) - Core geometry and state data structures
99//! - [`parser`](parser/index.html) - Input file parsing
100//! - [`qm_interface`](qm_interface/index.html) - QM program interfaces
101//! - [`optimizer`](optimizer/index.html) - MECP optimization algorithms
102//! - [`constraints`](constraints/index.html) - Geometric constraint system
103//! - [`io`](io/index.html) - File I/O utilities
104//! - [`lst`](lst/index.html) - Linear synchronous transit interpolation
105//! - [`checkpoint`](checkpoint/index.html) - Restart functionality
106//! - [`reaction_path`](reaction_path/index.html) - NEB and path optimization
107//! - [`template_generator`](template_generator/index.html) - Input file templates
108//! - [`help`](help/index.html) - Built-in help system
109//!
110//! # Input File Format
111//!
112//! OpenMECP uses a custom input format with section-based syntax:
113//!
114//! ```text
115//! *GEOM
116//! C  0.0  0.0  0.0
117//! H  1.0  0.0  0.0
118//! *
119//!
120//! *TAIL_a
121//! # Additional keywords for state A
122//! *
123//!
124//! *TAIL_b
125//! # Additional keywords for state B
126//! *
127//!
128//! program = gaussian
129//! method = B3LYP/6-31G*
130//! nprocs = 4
131//! mem = 4GB
132//! charge = 0
133//! mult_state_a = 1  # or mult_a = 1
134//! mult_state_b = 3  # or mult_b = 3
135//! ```
136//!
137//! # Examples
138//!
139//! See the [project repository](https://github.com/lenhanpham/OpenMECP) for
140//! complete examples including:
141//! - Basic singlet-triplet MECP
142//! - TD-DFT excited states
143//! - Open-shell singlet calculations
144//! - PES scans with constraints
145//! - LST interpolation
146//! - Coordinate driving
147//! - ONIOM calculations
148//!
149//! # References
150//!
151//! - Harvey, J. N.; Aschi, M.; Schwarz, H.; Koch, W.
152//!   *Theoret. Chim. Acta* **1994**, 90, 189-194.
153//!   [DOI: 10.1007/BF01120148](https://doi.org/10.1007/BF01120148)
154//!
155//! # License
156//!
157//! MIT License - see [LICENSE](../LICENSE) file for details
158//!
159//! # Version
160//!
161//! 0.0.1 (Alpha)
162
163/// Restart functionality
164pub mod checkpoint;
165/// Automated file cleanup for quantum chemistry calculations
166pub mod cleanup;
167pub mod config;
168pub mod constraints;
169/// GDIIS (Geometry Direct Inversion in Iterative Subspace) implementation
170pub mod gdiis;
171/// GEDIIS (Geometry Energy Direct Inversion in Iterative Subspace) implementation
172pub mod gediis;
173pub mod geometry;
174/// Built-in help system
175pub mod help;
176/// Hessian update methods (BFGS, Bofill, Powell)
177pub mod hessian_update;
178pub mod io;
179/// Linear synchronous transit interpolation
180pub mod lst;
181/// Dynamic file naming based on input file basename
182pub mod naming;
183pub mod optimizer;
184pub mod parser;
185/// PES scanning functionality
186pub mod pes_scan;
187pub mod qm_interface;
188/// NEB and path optimization
189pub mod reaction_path;
190/// Configuration management system
191pub mod settings;
192/// Input file templates
193pub mod template_generator;
194/// Run mode validation and compatibility checking
195pub mod validation;
196
197pub use config::Config;
198pub use geometry::Geometry;