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)

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

v1.20.1

Full Changelog: v1.20.0...v1.20.1

• Fixed an issue in Fischer's model Hessian generation where numerical instability occurred when four atoms were aligned linearly.

With this update, I am stepping away from this project for the time being.

v1.20.0-pre-release-6

Full Changelog: v1.20.0-rc.5...v1.20.0-rc.6

• Fix a bug

v1.20.0

• Fix a bug.
• Delete an unused file.
• Add an experimental method.