v1.21.2

Full Changelog: v1.21.1...v1.21.2

MultiOptPy v1.21.2 Release Notes

🚀 New Features

RCMC (Rate Constant Matrix Contraction) Priority Queue

A new kinetics-driven exploration strategy is now available as an alternative to the default Boltzmann-weighted queue. The RCMC algorithm dynamically prioritizes frontier EQ nodes based on transient population dynamics over the growing reaction network.

• New module: multioptpy/Utils/rcmc.py — implements RCMCQueue, a drop-in replacement for BoltzmannQueue.
• Constructs the full rate constant matrix K from TST (Transition State Theory) rate constants at each iteration.
• Iteratively contracts the rate matrix to separate fast and slow timescales, identifying kinetically relevant super-states.
• Outputs the contracted super-state rate matrix to rcmc_K_contracted.csv for inspection.
• Configurable via CLI (--use_rcmc, --rcmc_temperature, --rcmc_time, --rcmc_start_node) or mapper_settings JSON block (use_rcmc, rcmc_temperature_K, rcmc_reaction_time_s, rcmc_start_node_id).

EQ Node Exclusion

Users can now control which equilibrium structures are used as starting points for AFIR exploration:

• --exclude_nodes NODE_ID [...] — manually specify EQ node IDs to exclude from exploration. Excluded nodes are still registered in the graph but are never selected as AFIR starting points (after an initial one-time exploration).
• --exclude_bond_rearrangement — automatically exclude any newly discovered EQ node whose covalent bond topology differs from the seed structure (EQ0). Useful for restricting the network search to conformational isomers without crossing into reactive products.

BondTopologyChecker

A new BondTopologyChecker class detects covalent bond rearrangements by comparing atom-index-permutation-invariant bond-type fingerprints. It uses covalent radii with a configurable margin (default 120%) to determine bonding and produces element-pair-keyed bond count dictionaries for comparison.

🔧 Improvements

StructureChecker Overhaul

The StructureChecker has been significantly improved for robustness on symmetric and near-symmetric molecules:

• Proper rotation enforcement: PCA alignment now guarantees det(R) = +1 by negating the last eigenvector when necessary, preventing enantiomers from being incorrectly declared identical.
• Degeneracy-aware rotation sampling: A multi-stage comparison strategy is now used:
  • Stage 1: 4 sign-flip candidates (sufficient for non-degenerate cases).
  • Stage 2: Degeneracy detection via relative eigenvalue tolerance.
  • Stage 3: Coarse planar rotation grid for partially degenerate axes (Rz or Rx rotations).
  • Stage 4: Fine SO(3) Euler-angle grid for fully degenerate (spherical-top) molecules.
• PCA eigenvalues are now returned alongside aligned coordinates to enable degeneracy analysis.

Queue-Agnostic Temperature Retrieval

• Temperature for Boltzmann sampling in the fallback path now uses getattr(self.queue, "temperature_K", 300.0) instead of isinstance checks, making it compatible with both BoltzmannQueue and RCMCQueue.

v1.21.1

Full Changelog: v1.21.0...v1.21.1

Added

• Added --no_symmetry_analyzer (-nosymm) option: Skips symmetry analysis after geometry optimization (treats the structure as C1 symmetry).
• Fix critical bugs related to the calculation wrappers of ASE and PySCF.

---

Thank you for your understanding and patience.

v1.20.9

Full Changelog: v1.20.8...v1.20.9

MultiOptPy v1.20.9

This release introduces a new semi-numerical Hessian generation method (O1NumHess) and a vectorized implementation of Swart's approximate Hessian model. These additions are integrated into the main optimization workflow to improve Hessian estimation stability and performance.

---

🚀 New Features

O1NumHess Implementation

• New Module: Added multioptpy/ModelHessian/o1numhess.py.
• Functionality: Implemented O1NumHessCalculator, a class for generating semi-numerical Hessians using Optimal 1-sided differentiation.
• Key Algorithms:
  • Adaptive Cutoff: Implemented a cutoff strategy based on the sum of covalent radii scaled by rcov_scale.
  • Strict LR Loop: Added a strict low-rank correction loop (_lr_loop_strict) with adaptive damping to handle convergence and divergence detection.

How to use

python optmain.py aldol_rxn_PT.xyz -xtb GFN1-xTB -opt rsirfo_block_fsb -modelhess o1numhess

python nebmain.py aldol_rxn -xtb GFN1-xTB -ns 20 -adpred 1 -nd 0.4 -modelhess o1numhess -spng

Swart Approximate Hessian

• New Module: Added multioptpy/ModelHessian/swart.py.
• Functionality: Implemented SwartApproxHessian and its D2/D3/D4 variants for empirical force constant estimation based on bond lengths and angles.
• Improvements:
  • Vectorization: The calculation of bond and angle terms is fully vectorized for performance.
  • Singularity Handling: Added safety mechanisms for linear angles and overlapping atoms to prevent division by zero errors.
  • Fallback Mechanism: Implemented logic to automatically fall back to a Distance-Only (Bond) Hessian if NaN or Inf values are detected in the computed Cartesian Hessian.

How to use

python optmain.py aldol_rxn_PT.xyz -xtb GFN1-xTB -opt rsirfo_block_fsb -modelhess swart

---

🛠 Integration & Updates

Optimization Workflow (optimization.py)

• O1NumHess Integration:
  • Updated Optimize.run loop to explicitly handle the o1numhess option.
  • When selected via --use_model_hessian o1numhess, the optimization loop now bypasses the standard ApproxHessian dispatch and directly instantiates O1NumHessCalculator to compute the Hessian matrix at specified intervals (mFC_COUNT).

Interface (interface.py)

• Updated the argument parser to accept o1numhess and swart (along with variants swartd2, swartd3, swartd4) as valid options for the -modelhess / --use_model_hessian argument.

Approximate Hessian Dispatch (approx_hessian.py)

• Updated the ApproxHessian.main method to route Swart family keywords to the newly added SwartApproxHessian classes.

---

⚠️ Note

The O1NumHess implementation is experimental. It has not been formally validated against the original performance benchmarks.

Reference

• J. Chem. Theory Comput. 2025, 21, 21, 10893–10909.

v1.20.8

Full Changelog: v1.20.7...v1.20.8

Release Notes: v1.20.8

Summary

Numerical robustness improvements for all potential energy classes to prevent NaN/Inf gradients at geometric singularities.

---

Changes

Angle Potential (keep_angle_potential.py)

• 5th-order Taylor expansion (Horner's method) near θ = 0° and 180°
• Quadratic extrapolation with Gauss-Newton Hessian for non-equilibrium singularities
• Configurable thresholds: THETA_CUT (1e-3 rad), EPSILON_PARAM (1e-8 rad)

Dihedral Angle Potential (keep_dihedral_angle_potential.py)

• Collinearity Guard: Clamps energy to 0 when plane is undefined
• Replaced acos with atan2 for stable [-π, π] calculation
• Added periodicity wrapping for angle differences

Out-of-Plane Angle Potential (keep_outofplain_angle_potential.py)

• Plane Undefined Guard for collinear base vectors
• Replaced asin with atan2(h, r_proj) for ±90° stability

Distance Potential (keep_potential.py)

• Robust norm: torch.clamp(sqrt(sum²), min=1e-12)
• Vectorized centroid calculation
• Automatic device/dtype propagation

---

Known Mathematical Limitations

Potential	Condition	Issue
Dihedral	φ₀ = 180°, φ → ±180°	Periodicity wrapping discontinuity at ±π boundary
Angle	θ₀ ≠ 0,π and θ → 0 or π	Negative Hessian (Gauss-Newton approximation artifact)

Warning on Numerical Stability (Angle): Numerical stability and gradient convergence are not guaranteed when the equilibrium angle (sinθ₀) is specified within the following ranges: about [0.5, 20.0] degrees and [160.0, 179.5] degrees In these "near-singular" regions, the geometric derivative 1/sinθ increases significantly while the restorative force (θ - θ₀) remains non-zero, potentially leading to gradient divergence. For targets near 0 or 180 degrees, it is recommended to use exactly 0.0 or 180.0 degrees to activate the Taylor expansion branches.

Note: First derivatives (C1) remain accurate. These limitations primarily affect Newton-type optimizers in rare extreme configurations.

---

Files Modified

• multioptpy/Potential/keep_angle_potential.py
• multioptpy/Potential/keep_dihedral_angle_potential.py
• multioptpy/Potential/keep_outofplain_angle_potential.py
• multioptpy/Potential/keep_potential.py

v1.20.7

Full Changelog: v1.20.6...v1.20.7

Summary of Changes

Dependency Resolution

• Resolved dependency conflicts and updated package requirements for improved compatibility.

---

Note: For the complete commit history, see: ss0832/MultiOptPy commits on stable-v1.20

v1.20.6

Full Changelog: v1.20.5...v1.20.6

Summary of Changes from v1.20.5 to v1.20.6

1. Version Update

• Version number updated from 1.20.5 to 1.20.6 in pyproject.toml and documentation.

---

2. Conformation Search (conformation_search.py) - Major Enhancements

New Features:

• Bond Connectivity Preservation (-pbc / --preserve_bond_connectivity):

  • Excludes conformers whose bond connectivity differs from the initial optimized structure (EQ0).
  • Rejected conformers are saved to a separate REJECTED_CONFORMERS/ folder with detailed bond change information.

• Tabu Search / Metadynamics-like Frequency Penalty (-tabu / --tabu_search):

  • Implements a penalized Boltzmann distribution to avoid revisiting the same conformers repeatedly.
  • Formula: P_i^{select} ∝ P_i^{Boltzmann} × exp(-α × N_i) where N_i is the visit count.
  • Configurable penalty coefficient via --tabu_alpha (default: 0.5).
  • Selection history and logs are saved for analysis.

Code Quality:

• Added functions for calculating, loading, and saving bond connectivity tables.
• Added restart capability: reference bond table and visit counts are stored and reloaded on restart.
• Improved folder naming with timestamp for unique run identification.

---

3. Thermostat Module (multioptpy/MD/thermostat.py) - Performance Optimization

Changes:

• Vectorized Operations: Pre-computation of masses and inverse masses for vectorized kinetic energy and momentum calculations.
• New Langevin Thermostat (BAOAB Integrator): Added a new Langevin_thermostat() method implementing the BAOAB integrator from Leimkuhler and Matthews (J. Chem. Phys. 138, 174102, 2013).
• Internal helpers added: _update_momentum(), _update_position(), _propagate_nhc_zeta() for logical separation and reuse.
• Mutable default argument fix: Corrected the default argument for element_list.

---

4. Model Hessian (multioptpy/ModelHessian/fischerd3.py) - Robustness Improvements

Changes:

• Dynamic D3 Dispersion Correction:

  • Implemented fractional coordination numbers (CN) calculation.
  • Dynamic C6 scaling based on coordination numbers (Grimme D3-style).
  • Expanded reference coordination number map covering elements H through Xe.

• Robustness for Linear Molecules:

  • Added strict linearity checks (sin²(θ) damping) for angles and dihedrals.
  • Exception handling in angle/dihedral calculations to avoid NaN propagation.

• Vectorization:

  • Distance matrix and D3 dispersion calculations are fully vectorized using NumPy/SciPy.

• NaN Safety:

  • Added checks to reset Hessian to identity if NaNs are detected after projection.

---

5. Optimizer (multioptpy/Optimizer/rsirfo.py & rsprfo.py) - Stability Improvements

RS-I-RFO (rsirfo.py):

• TR/ROT Gradient Projection: Added _project_grad_tr_rot() method to remove translation/rotation components from gradients using QR decomposition.
• NaN Handling:
  • Added checks for NaN/Inf in Hessian eigendecomposition; falls back to identity Hessian.
  • Final step NaN check with steepest descent fallback.
• Improved Logging: Reports gradient norm changes after projection.

Enhanced RS-PRFO (rsprfo.py):

• Expanded Docstrings: Comprehensive documentation of parameters and algorithm.
• Improved Trust Region:
  • New thresholds (eta_1, eta_2, eta_3, gamma_1, gamma_2) based on Nocedal & Wright.
  • Asymmetric expansion/contraction, step rejection mechanism.
• Hessian Eigenvalue Shifting: Smaller minimum eigenvalues to avoid over-shifting.
• Gradient-Based Step Scaling: Near convergence, step scaling based on gradient magnitude.
• Step Rejection Mechanism: Tracks consecutive rejections; rejects very poor steps.
• TR/ROT Gradient Projection: Same as RS-I-RFO.

---

6. Documentation Updates

OPTION_README.md:

• Version updated to 1.20.6.
• Formatting fixes for markdown arrays (removed escaping issues).

README.md:

• Updated download links and examples to point to v1.20.5.
• Fixed example command: corrected -elec 0 to -elec -1 for SN2 reaction.

docs/source/index.rst:

• Complete rewrite and modernization of documentation.
• Added structured sections: Installation, Quick Start, CLI, AutoTS Workflow, Configuration Reference, Bias Potentials, Examples, References.
• Version updated to 1.20.5 / 1.20.6.
• Added maintenance mode / frozen status notice.
• Added Zenodo citation information.

---

Summary Table

Area	Changes
Version	1.20.5 → 1.20.6
Conformation Search	Bond connectivity preservation, Tabu search penalty
MD/Thermostat	Vectorization, Langevin (BAOAB) thermostat
Model Hessian	Dynamic D3, linear molecule robustness, NaN safety
Optimizers	TR/ROT projection, NaN handling, trust region improvements
Documentation	Major rewrite, new sections, citation info

---

Note: The commit history may contain additional commits not shown here. For the complete commit history, see: ss0832/MultiOptPy commits on stable-v1.20

v1.20.5

Full Changelog: v1.20.4...v1.20.5

---

v1.20.5 Update: ORCA 6.1.0 Interface Implementation

New Features:

• ORCA 6.1.0 Support: Implemented a new interface for ORCA 6.1.0 using ASE (Atomic Simulation Environment).
• Usage: To use this interface, run the script with the option -os orca.

Configuration Instructions:
To enable ORCA support, you must update your configuration file.

Please specify the absolute path to the ORCA executable in software_path.conf using the format orca::<path>. For Linux, provide the path to the binary (e.g., /absolute/path/to/orca), and for Windows, provide the path to the executable file (e.g., C:\absolute\path\to\orca.exe).

Configuration Example (software_path.conf):

# Linux example
orca::/home/user/orca_6_1_0/orca

# Windows example
orca::C:\Orca\orca.exe

Command Example:

python optmain.py aldol_rxn_PT.xyz -os orca -opt rsirfo_block_bofill -order 1 -tcc -freq -bs sto-3g -func hf -fc 5

v1.20.4

Full Changelog: v1.20.3...v1.20.4

• fix a critical bug (optimization.py)

v1.20.3

Full Changelog: v1.20.2...v1.20.3

v1.20.3 Release Note

1. Mode-Following RS-I-RFO (MF-RS-I-RFO)

Overview

This is an algorithm for Saddle Point Optimization that proceeds by tracking a specific Hessian mode. Based on the conventional RS-I-RFO method, it incorporates tracking logic to prevent mode swapping between steps.

Implementation Details

• Mode Tracking Strategy: Uses the ModeFollowing class to calculate the overlap with the Hessian eigenvectors of the previous step.
• Mass-Weighted Overlap (MWO): If an atom list is provided, the projection is performed in the mass-weighted coordinate system rather than Cartesian coordinates, achieving physically valid tracking.
• Adaptive Update (EMA): Uses Exponential Moving Average (EMA) to dynamically update the reference vector, allowing the method to follow mode rotation.
• Gradient Bias: Adds the overlap in the direction of the current force (gradient) to the score, prioritizing the selection of energetically significant modes.

Command Line Arguments (-opt)

Detailed parameters are specified using colons : within the -opt argument string.

• Basic Format: -opt mf_rsirfo:<target_index>:<ema_val>:<grad_val>
• Parameters:
  • target_index: The index of the eigenvalue to track (starting from 0).
  • ema<val>: Update rate (0.0 to 1.0). 1.0 for full replacement (adaptive), 0.0 for fixed.
  • grad<val>: Weighting for the gradient direction.

Usage Example:

# Execute transition state geometry optimization tracking mass-weighted mode 1, 
# with an adaptive update rate of 0.5 and a gradient bias of 0.3.
python optmain.py  input.xyz -opt mwmf_rsirfo_fsb:1:ema0.5:grad0.3 -fc 5 -order 1 -freq -tcc

2. Constrained RS-I-RFO (C-RS-I-RFO)

Overview

A method for performing saddle point searches using RS-I-RFO while imposing geometric constraints (bond distances, angles, etc.).

Implementation Details

• Subspace Projection: Uses Singular Value Decomposition (SVD) to construct a "null space basis" orthogonal to the imposed constraints.
• Constrained Optimization: Projects the full-space gradient and Hessian onto this subspace and calculates the RFO step within it. This calculates the movement vector to the saddle point while maintaining the constraints.
• SHAKE-like Correction: Includes geometric adjustment logic to correct deviations in constraints due to numerical errors.

Command Line Arguments (-opt, -pc)

Specify crsirfo family methods with -opt and define constraints with -pc.

Usage Example:

# Geometry optimization while fixing the distance between atoms 1 and 2, and the angle of atoms 2-3-4.
python optmain.py input.xyz -opt crsirfo_block_fsb -pc bond 1,2 bend 2,3,4

3. Integration of Multiple PES Information and Model Function Optimization (BITSS, etc.)

Overview

A feature to perform geometry optimization on an "effective potential" constructed by combining energies or gradients from multiple electronic states (PES).
Specifically, version 1.20.3 implements the Binary-Image Transition State Search (BITSS) method.

Implementation Details

• Independent Calculator Instances: ModelFunctionHandler creates independent directories and calculators for State1 and State2 to prevent interference between states.
• BITSS Implementation:
  • 6N-Dimensional Expansion: Concatenates two structures (Image 1 & 2) and treats them as a $6N \times 6N$ Hessian and a $2N$ atom system.
  • Second Derivative (Hessian): Mathematically derives the second derivatives for distance and energy equality constraint terms and implements them as the calc_hess method.

Command Line Arguments (-mf)

Use the -mf argument to specify the type of model function and accompanying parameters (the file path of the reference structure in the case of BITSS).

Usage Example:

# Search for a pathway connecting two points using the BITSS method, with target.xyz as the target structure.
python optmain.py  start.xyz -mf bitss target.xyz

# Minimum energy seam of crossing (MESX) using Seam Model Function (between charge 0, multiplicity 1 and 3 states)
python optmain.py  input.xyz -mf opt_meci 0 3 -elec 0 -spin 3

Note: Internal Data Structure Changes

• OptimizationState: In BITSS mode, element_list and geometry are automatically expanded to double size (2N).
• Hessian Integration: Model_hess (derived from PES) and bias_hessian (derived from constraint/penalty terms) are managed separately and summed just before being passed to the optimizer.

References

• J. Chem. Phys. 157, 124107 (2022)
• J. Am. Chem. Soc. 2015, 137, 10, 3433–3445

v1.20.2

Full Changelog: v1.20.1...v1.20.2

• Add Command Line Interface (CLI) Functionality (only Linux, pip install)

conda create -n <env-name> python=3.12 pip
conda activate <env-name>
pip install git+https://github.com/ss0832/MultiOptPy.git@v1.20.2
# or pip install MultiOptPy