MultiOptPy 1.20.2__py3-none-any.whl → 1.20.3__py3-none-any.whl

multioptpy/ModelFunction/binary_image_ts_search_model_function.py

@@ -1,47 +1,140 @@
 import numpy as np
 
-#J. Chem. Phys. 157, 124107 (2022)
-#https://doi.org/10.1063/5.0102145
+# J. Chem. Phys. 157, 124107 (2022)
+# https://doi.org/10.1063/5.0102145
 
 class BITSSModelFunction:
     def __init__(self, geom_num_list_1, geom_num_list_2):
         self.f = 0.5
         self.alpha = 10.0
-        self.beta = 0.1
-        self.d = np.linalg.norm(geom_num_list_1 - geom_num_list_2)
+        # self.beta controls the strength of the distance constraint.
+        # Smaller beta -> Larger kappa_d -> Stronger attractive force.
+        # Default: 0.1 -> Modified: 0.02 for stronger constraint.
+        self.beta = 0.02
         
-        return
+        # Initial distance
+        diff = geom_num_list_1 - geom_num_list_2
+        self.d = np.linalg.norm(diff)
         
+        # Initialize variables to avoid AttributeError if calc_hess/grad called before iter % 500 == 0
+        self.kappa_e = 0.0
+        self.kappa_d = 0.0
+        self.E_B = 0.0
+        
+        # Store vector info for Hessian calculation
+        self.diff_vec = diff.reshape(-1, 1) # (3N, 1)
+        self.current_dist = self.d
+
     def calc_energy(self, energy_1, energy_2, geom_num_list_1, geom_num_list_2, gradient_1, gradient_2, iter):
-        current_distance = np.linalg.norm(geom_num_list_1 - geom_num_list_2)
+        # Update distances
+        diff_vec = geom_num_list_1 - geom_num_list_2
+        current_distance = np.linalg.norm(diff_vec)
+        
+        # Update parameters periodically
         if iter % 500 == 0:
-
             self.E_B = abs(energy_1 - energy_2)
+            # Avoid division by zero
             self.kappa_e = self.alpha / (2.0 * self.E_B + 1e-10)
         
-            unit_vec = (geom_num_list_1 - geom_num_list_2) / current_distance
-            
-     
+            unit_vec = diff_vec / (current_distance + 1e-10)
             
-            proj_grad_1 = gradient_1 * unit_vec * (-1)
-            proj_grad_2 = gradient_2 * unit_vec
+            # Project gradients onto the distance vector direction
+            # grad_1 is (N, 3), unit_vec is (N, 3). Element-wise mult then sum gives dot product.
+            proj_grad_1 = np.sum(gradient_1 * (-1) * unit_vec)
+            proj_grad_2 = np.sum(gradient_2 * unit_vec)
 
-            a = np.sqrt(np.linalg.norm(proj_grad_1) + np.linalg.norm(proj_grad_2)) / (2 ** 1.5 * self.beta * self.d + 1e-10)
+            # Eq. (5) logic
+            grad_norm_term = np.sqrt(proj_grad_1**2 + proj_grad_2**2)
+            a = grad_norm_term / (2 ** 1.5 * self.beta * self.d + 1e-10)
             b = self.E_B / (self.beta * self.d ** 2 + 1e-10)
             self.kappa_d = max(a, b)
-            self.d = np.linalg.norm(geom_num_list_1 - geom_num_list_2)
+            
+            # Reset target distance d to current distance at update step
+            self.d = current_distance
         
+        # Reduce target distance
         self.d = max((1.0 - self.f) * self.d, 1e-10)
-        energy = energy_1 + energy_2 + self.kappa_e * (energy_1 + energy_2) ** 2 + self.kappa_d * (current_distance - self.d) ** 2
+        
+        # Calculate BITSS Energy
+        # Formula: E1 + E2 + ke * (E1 - E2)^2 + kd * (d - d0)^2
+        energy = energy_1 + energy_2 + self.kappa_e * (energy_1 - energy_2) ** 2 + self.kappa_d * (current_distance - self.d) ** 2
         
         return energy
         
     def calc_grad(self, energy_1, energy_2, geom_num_list_1, geom_num_list_2, gradient_1, gradient_2):
+        # Calculate vector r = x1 - x2 and distance d
         current_vec = geom_num_list_1 - geom_num_list_2
         current_dist = np.linalg.norm(current_vec) + 1e-10
 
-        bitss_grad_1 = gradient_1 + gradient_2 + 2.0 * self.kappa_e * (energy_1 - energy_2) * (gradient_1 - gradient_2) + current_vec * 2.0 * self.kappa_d * (current_dist - self.d) / current_dist
+        # Store for calc_hess (flattened for matrix ops)
+        self.diff_vec = current_vec.reshape(-1, 1)
+        self.current_dist = current_dist
+
+        # Common terms
+        delta_E = energy_1 - energy_2
+        dist_diff = current_dist - self.d
+        
+        # Gradient term for distance: 2 * kd * (d - d0) * (r / d)
+        grad_dist_term = current_vec * 2.0 * self.kappa_d * dist_diff / current_dist
+
+        # Gradient term for energy: 2 * ke * (E1 - E2) * (g1 - g2)
+        # Total Gradient 1: g1 + 2*ke*dE*g1 + dist_term
+        bitss_grad_1 = gradient_1 * (1.0 + 2.0 * self.kappa_e * delta_E) + grad_dist_term
+
+        # Total Gradient 2: g2 + 2*ke*dE*(-g2) - dist_term (since d(r)/dx2 = -r/d)
+        bitss_grad_2 = gradient_2 * (1.0 - 2.0 * self.kappa_e * delta_E) - grad_dist_term
+        
+        return bitss_grad_1, bitss_grad_2
 
-        bitss_grad_2 = gradient_1 + gradient_2 + 2.0 * self.kappa_e * (energy_1 - energy_2) * (gradient_1 - gradient_2) - current_vec * 2.0 * self.kappa_d * (current_dist - self.d) / current_dist
+    def calc_hess(self, energy_1, energy_2, grad_1, grad_2, hess_1, hess_2):
+        """
+        Calculate the 6N x 6N Hessian matrix for BITSS.
+        H = [ H11  H12 ]
+            [ H21  H22 ]
+        """
+        # Ensure inputs are flattened (3N, 1) or (3N, 3N)
+        N3 = self.diff_vec.shape[0]
+        g1 = grad_1.reshape(N3, 1)
+        g2 = grad_2.reshape(N3, 1)
+        
+        delta_E = energy_1 - energy_2
+        dist_diff = self.current_dist - self.d
+        
+        # --- Distance Constraint Hessian Terms ---
+        # Vd = kd * (d - d0)^2
+        # P = r * r.T / d^2 (Projection onto bond axis)
+        r = self.diff_vec
+        d = self.current_dist
+        P = np.dot(r, r.T) / (d**2)
+        I = np.eye(N3)
+        # H_dist_block = 2*kd * [ P + (d-d0)/d * (I - P) ]
+        term_d = P + (dist_diff / d) * (I - P)
+        H_dist = 2.0 * self.kappa_d * term_d
+        
+        # --- Total Hessian Blocks ---
+        
+        # Block 11: d^2 E / dx1^2
+        # = H1 * (1 + 2*ke*dE) + 2*ke * g1 * g1.T + H_dist
+        H11 = hess_1 * (1.0 + 2.0 * self.kappa_e * delta_E) + \
+              2.0 * self.kappa_e * np.dot(g1, g1.T) + \
+              H_dist
+              
+        # Block 22: d^2 E / dx2^2
+        # = H2 * (1 - 2*ke*dE) + 2*ke * g2 * g2.T + H_dist
+        H22 = hess_2 * (1.0 - 2.0 * self.kappa_e * delta_E) + \
+              2.0 * self.kappa_e * np.dot(g2, g2.T) + \
+              H_dist
+              
+        # Block 12: d^2 E / dx1 dx2
+        # = -2*ke * g1 * g2.T - H_dist
+        H12 = -2.0 * self.kappa_e * np.dot(g1, g2.T) - H_dist
+        
+        # Block 21: d^2 E / dx2 dx1
+        H21 = H12.T # Symmetric
+        
+        # Construct Full Matrix
+        H_top = np.hstack((H11, H12))
+        H_bot = np.hstack((H21, H22))
+        H_total = np.vstack((H_top, H_bot))
         
-        return bitss_grad_1, bitss_grad_2
+        return H_total

multioptpy/ModelFunction/opt_meci.py

@@ -2,49 +2,116 @@ import numpy as np
 
 class OptMECI:
     def __init__(self):
-        # ref.:https://doi.org/10.1021/ct1000268
+        # ref.: J. Am. Chem. Soc. 2015, 137, 3433-3445
+        # MECI optimization using GP method with Branching Plane Updating (BPU) 
        
-        self.switch_threshold = 5e-4
-        self.alpha = 1e-3
-        self.approx_cdv_vec = None
-        self.prev_dgv_vec = None
-        self.dgv_vec = None
-        
+        self.approx_cdv_vec = None # Represents 'y' vector (orthogonal to dgv inside BP)
+        self.prev_dgv_vec = None   # Represents 'x_{k-1}'
+        self.prev_y_vec = None     # Represents 'y_{k-1}'
         return
     
     def calc_energy(self, energy_1, energy_2):
         tot_energy = (energy_1 + energy_2) / 2.0 
         print("energy_1:", energy_1, "hartree")
         print("energy_2:", energy_2, "hartree")
-        print("energy_1 - energy_2:", abs(energy_1 - energy_2), "hartree")
+        print("|energy_1 - energy_2|:", abs(energy_1 - energy_2), "hartree")
         return tot_energy
         
     def calc_grad(self, energy_1, energy_2, grad_1, grad_2):
-        if self.approx_cdv_vec is None:
-            self.approx_cdv_vec = np.ones((len(grad_1)*3, 1))
-
-        delta_grad = grad_1 - grad_2
-        dgv_vec = delta_grad / np.linalg.norm(delta_grad)
-        dgv_vec = dgv_vec.reshape(-1, 1)
+        # Reshape inputs
+        grad_1_flat = grad_1.reshape(-1, 1)
+        grad_2_flat = grad_2.reshape(-1, 1)
         
-        if self.prev_dgv_vec is None:
-            self.prev_dgv_vec = dgv_vec
+        # 1. Calculate Difference Gradient Vector (x_k) 
+        delta_grad = grad_1_flat - grad_2_flat
+        norm_delta_grad = np.linalg.norm(delta_grad)
+        if norm_delta_grad < 1e-8:
+            dgv_vec = np.zeros_like(delta_grad) # Avoid division by zero
+        else:
+            dgv_vec = delta_grad / norm_delta_grad # x_k
         
-        self.approx_cdv_vec = (np.dot(self.approx_cdv_vec.T, dgv_vec) * self.prev_dgv_vec -1 * np.dot(self.prev_dgv_vec.T, dgv_vec) * self.approx_cdv_vec) / np.sqrt(np.dot(self.approx_cdv_vec.T, dgv_vec) ** 2 + np.dot(self.prev_dgv_vec.T, dgv_vec) ** 2) 
+        # 2. Determine Approximate Coupling Vector (y_k) using BPU 
+        if self.prev_dgv_vec is None:
+            # Initialization Step 
+            # "A plane made of x0 and the mean energy gradient vector was used as an initial BP."
+            mean_grad = 0.5 * (grad_1_flat + grad_2_flat)
+            
+            # Project mean_grad to be orthogonal to dgv_vec (Gram-Schmidt)
+            overlap = np.dot(mean_grad.T, dgv_vec)
+            ortho_vec = mean_grad - overlap * dgv_vec
+            
+            norm_ortho = np.linalg.norm(ortho_vec)
+            if norm_ortho < 1e-8:
+                 # Fallback if mean grad is parallel to diff grad (unlikely)
+                 ortho_vec = np.random.rand(*dgv_vec.shape)
+                 ortho_vec = ortho_vec - np.dot(ortho_vec.T, dgv_vec) * dgv_vec
+                 norm_ortho = np.linalg.norm(ortho_vec)
 
-        P_matrix = np.eye((len(dgv_vec))) -1 * np.dot(dgv_vec, dgv_vec.T) -1 * np.dot(self.approx_cdv_vec, self.approx_cdv_vec.T)
-        P_matrix = 0.5 * (P_matrix + P_matrix.T)
-        gp_grad =  2 * (energy_1 - energy_2) * dgv_vec + np.dot(P_matrix, 0.5 * (grad_1.reshape(-1, 1) + grad_2.reshape(-1, 1)))
-        
-        self.prev_dgv_vec = dgv_vec
-        gp_grad = gp_grad.reshape(len(grad_1), 3)
-        return gp_grad
+            self.approx_cdv_vec = ortho_vec / norm_ortho # Initial y_0
+            
+        else:
+            # Update Step using Eq 4 
+            # y_k = [ (y_{k-1}.x_k) * x_{k-1} - (x_{k-1}.x_k) * y_{k-1} ] / normalization
+            
+            x_k = dgv_vec
+            x_prev = self.prev_dgv_vec
+            y_prev = self.prev_y_vec
+            
+            dot_yx = np.dot(y_prev.T, x_k)
+            dot_xx = np.dot(x_prev.T, x_k)
+            
+            numerator = dot_yx * x_prev - dot_xx * y_prev
+            norm_num = np.linalg.norm(numerator)
+            
+            if norm_num < 1e-8:
+                 # If x_k didn't change much, keep y_prev orthogonalized to x_k
+                 numerator = y_prev - np.dot(y_prev.T, x_k) * x_k
+                 norm_num = np.linalg.norm(numerator)
 
+            self.approx_cdv_vec = numerator / norm_num # y_k
+
+        # Store vectors for next step
+        self.prev_dgv_vec = dgv_vec.copy()
+        self.prev_y_vec = self.approx_cdv_vec.copy()
+        
+        # 3. Construct Projection Matrix P for MECI 
+        # Projects out BOTH dgv (x) and approx_cdv (y) directions
+        P_matrix = np.eye(len(dgv_vec)) \
+                   - np.dot(dgv_vec, dgv_vec.T) \
+                   - np.dot(self.approx_cdv_vec, self.approx_cdv_vec.T)
+        
+        # 4. Compose Gradient Projection (GP) Gradient
+        # Force to reduce energy gap: 2 * (E1 - E2) * dgv
+        # Force to minimize mean energy on intersection space (N-2 dim): P * mean_grad
+        mean_grad = 0.5 * (grad_1_flat + grad_2_flat)
+        
+        gap_force = 2.0 * (energy_1 - energy_2) * dgv_vec
+        seam_force = np.dot(P_matrix, mean_grad)
+        
+        gp_grad = gap_force + seam_force
+        
+        return gp_grad.reshape(len(grad_1), 3)
 
     def calc_hess(self, hess_1, hess_2):
+        # Approximate Hessian for GP method
+        # Projects the mean Hessian onto the intersection space
         mean_hess = 0.5 * (hess_1 + hess_2)
-        P_matrix = np.eye((len(self.prev_dgv_vec))) -1 * np.dot(self.prev_dgv_vec, self.prev_dgv_vec.T) -1 * np.dot(self.approx_cdv_vec, self.approx_cdv_vec.T)
-        P_matrix = 0.5 * (P_matrix + P_matrix.T)
         
-        gp_hess = np.dot(P_matrix, np.dot(mean_hess, P_matrix))
+        # Need current P_matrix. Reconstruct it from stored vectors.
+        if self.approx_cdv_vec is None or self.prev_dgv_vec is None:
+             # Should not happen if calc_grad is called first
+             return mean_hess
+             
+        dgv_vec = self.prev_dgv_vec
+        cdv_vec = self.approx_cdv_vec
+        
+        P_matrix = np.eye(len(dgv_vec)) \
+                   - np.dot(dgv_vec, dgv_vec.T) \
+                   - np.dot(cdv_vec, cdv_vec.T)
+                   
+        # Projected Mean Hessian + Gap Penalty Curvature
+        proj_hess = np.dot(P_matrix, np.dot(mean_hess, P_matrix))
+        gap_curvature = 2.0 * np.dot(dgv_vec, dgv_vec.T)
+        
+        gp_hess = proj_hess + gap_curvature
         return gp_hess

multioptpy/ModelFunction/opt_mesx.py

@@ -2,13 +2,13 @@ import numpy as np
 
 class OptMESX:
     def __init__(self):
-        #ref.: Chemical Physics Letters 674 (2017) 141-145
-       
-        self.switch_threshold = 5e-4
-        self.alpha = 1e-3
+        # ref.: J. Am. Chem. Soc. 2015, 137, 3433-3445 
+        # MESX optimization using Gradient Projection (GP) method.
+        # Only the difference gradient vector (DG or f) is projected out.
         return
     
     def calc_energy(self, energy_1, energy_2):
+        # The objective is to minimize the mean energy on the seam.
         tot_energy = (energy_1 + energy_2) / 2.0 
         print("energy_1:", energy_1, "hartree")
         print("energy_2:", energy_2, "hartree")
@@ -16,32 +16,64 @@ class OptMESX:
         return tot_energy
         
     def calc_grad(self, energy_1, energy_2, grad_1, grad_2):
+        # 1. Calculate Difference Gradient Vector (DGV) / f vector
         delta_grad = grad_1 - grad_2
         norm_delta_grad = np.linalg.norm(delta_grad)
+        
         if norm_delta_grad < 1e-8:
             dgv_vec = np.zeros_like(delta_grad)
         else:
             dgv_vec = delta_grad / norm_delta_grad
+        
+        # Ensure correct shape for matrix operations
         dgv_vec = dgv_vec.reshape(-1, 1)
+        grad_1 = grad_1.reshape(-1, 1)
+        grad_2 = grad_2.reshape(-1, 1)
+        
+        # 2. Define Projection Matrix P for MESX
+        # Projects out the component along the difference vector (degenerate lifting direction)
+        # P = I - v * v.T
+        P_matrix = np.eye(len(dgv_vec)) - np.dot(dgv_vec, dgv_vec.T)
         
-        P_matrix = np.eye((len(dgv_vec))) -1 * np.dot(dgv_vec, dgv_vec.T)
-        P_matrix = 0.5 * (P_matrix + P_matrix.T)
-        gp_grad =  2 * (energy_1 - energy_2) * dgv_vec + np.dot(P_matrix, 0.5 * (grad_1.reshape(-1, 1) + grad_2.reshape(-1, 1)))
+        # 3. Calculate Mean Gradient
+        mean_grad = 0.5 * (grad_1 + grad_2)
         
-        gp_grad = gp_grad.reshape(len(grad_1), 3)
-        return gp_grad
+        # 4. Compose Gradient Projection (GP) Gradient 
+        # Force to reduce energy gap: 2 * (E1 - E2) * dgv
+        # Force to minimize mean energy on seam: P * mean_grad
+        gap_force = 2.0 * (energy_1 - energy_2) * dgv_vec
+        seam_force = np.dot(P_matrix, mean_grad)
+        
+        gp_grad = gap_force + seam_force
+        
+        return gp_grad.reshape(-1, 3)
     
     def calc_hess(self, grad_1, grad_2, hess_1, hess_2):
+        # Approximate Hessian for GP method
         delta_grad = grad_1 - grad_2
         norm_delta_grad = np.linalg.norm(delta_grad)
+        
         if norm_delta_grad < 1e-8:
             dgv_vec = np.zeros_like(delta_grad)
         else:
             dgv_vec = delta_grad / norm_delta_grad
-        delta_grad = delta_grad.reshape(-1, 1)
+            
         dgv_vec = dgv_vec.reshape(-1, 1)
-        P_matrix = np.eye((len(dgv_vec))) -1 * np.dot(dgv_vec, dgv_vec.T)
-        P_matrix = 0.5 * (P_matrix + P_matrix.T)
-        gp_hess = 2.0 * np.dot(delta_grad, dgv_vec.T) + np.dot(P_matrix, 0.5 * (hess_1 + hess_2))
-        return gp_hess
-        
+        
+        # Projection Matrix
+        P_matrix = np.eye(len(dgv_vec)) - np.dot(dgv_vec, dgv_vec.T)
+        
+        # Mean Hessian
+        mean_hess = 0.5 * (hess_1 + hess_2)
+        
+        # Projected Mean Hessian
+        # This describes curvature along the seam.
+        proj_hess = np.dot(P_matrix, np.dot(mean_hess, P_matrix))
+        
+        # Gap Curvature (Penalty term approximation)
+        # Adds large curvature along the difference vector to enforce the gap constraint strongly.
+        gap_curvature = 2.0 * np.dot(dgv_vec, dgv_vec.T)
+        
+        gp_hess = proj_hess + gap_curvature
+        
+        return gp_hess

multioptpy/ModelFunction/opt_mesx_2.py

@@ -2,48 +2,65 @@ import numpy as np
 
 class OptMESX2:
     def __init__(self):
-        #ref.: Theor Chem Acc 99, 95–99 (1998)
-       
-        self.switch_threshold = 5e-4
-        self.alpha = 1e-3
+        # ref.: Theor Chem Acc 99, 95–99 (1998)
+        # This reference describes the Gradient Projection method.
+        # The implementation has been corrected to follow the standard GP formulation
+        # as described in J. Am. Chem. Soc. 2015, 137, 3433-3445 .
         return
     
     def calc_energy(self, energy_1, energy_2):
         tot_energy = (energy_1 + energy_2) / 2.0 
         print("energy_1:", energy_1, "hartree")
         print("energy_2:", energy_2, "hartree")
-        print("energy_1 - energy_2:", abs(energy_1 - energy_2), "hartree")
+        print("|energy_1 - energy_2|:", abs(energy_1 - energy_2), "hartree")
         return tot_energy
         
     def calc_grad(self, energy_1, energy_2, grad_1, grad_2):
-        grad_1 = grad_1.reshape(-1, 1)
-        grad_2 = grad_2.reshape(-1, 1)
-        
+        # 1. Difference Vector (normalized)
         delta_grad = grad_1 - grad_2
         norm_delta_grad = np.linalg.norm(delta_grad)
+        
         if norm_delta_grad < 1e-8:
-            projection = np.zeros_like(delta_grad)
+            dgv_vec = np.zeros_like(delta_grad)
         else:
-            projection = np.sum(grad_1 * delta_grad) / norm_delta_grad
+            dgv_vec = delta_grad / norm_delta_grad
             
-        parallel = grad_1 - delta_grad * projection / norm_delta_grad
+        dgv_vec = dgv_vec.reshape(-1, 1)
+        grad_1_flat = grad_1.reshape(-1, 1)
+        grad_2_flat = grad_2.reshape(-1, 1)
+
+        # 2. Projection Matrix (P = I - v v^T)
+        P_matrix = np.eye(len(dgv_vec)) - np.dot(dgv_vec, dgv_vec.T)
         
-        gp_grad = (energy_1 - energy_2) * 140 * delta_grad + 1.0 * parallel
+        # 3. Mean Gradient
+        mean_grad = 0.5 * (grad_1_flat + grad_2_flat)
         
-        gp_grad = gp_grad.reshape(-1, 3)
-        return gp_grad
+        # 4. Recomposed Gradient 
+        # Replaces the arbitrary '140' factor with the analytical gap force 2(E1-E2)
+        gap_force = 2.0 * (energy_1 - energy_2) * dgv_vec
+        seam_force = np.dot(P_matrix, mean_grad)
+        
+        gp_grad = gap_force + seam_force
+        
+        return gp_grad.reshape(-1, 3)
     
     def calc_hess(self, grad_1, grad_2, hess_1, hess_2):
+        # Robust Hessian construction for GP
         delta_grad = grad_1 - grad_2
         norm_delta_grad = np.linalg.norm(delta_grad)
         if norm_delta_grad < 1e-8:
             dgv_vec = np.zeros_like(delta_grad)
         else:
             dgv_vec = delta_grad / norm_delta_grad
-        delta_grad = delta_grad.reshape(-1, 1)
+            
         dgv_vec = dgv_vec.reshape(-1, 1)
-        P_matrix = np.eye((len(dgv_vec))) -1 * np.dot(dgv_vec, dgv_vec.T)
-        P_matrix = 0.5 * (P_matrix + P_matrix.T)
         
-        gp_hess = 2.0 * np.dot(delta_grad, dgv_vec.T) + np.dot(P_matrix, 0.5 * (hess_1 + hess_2))
+        P_matrix = np.eye(len(dgv_vec)) - np.dot(dgv_vec, dgv_vec.T)
+        mean_hess = 0.5 * (hess_1 + hess_2)
+        
+        # Projected Mean Hessian + Gap Curvature
+        proj_hess = np.dot(P_matrix, np.dot(mean_hess, P_matrix))
+        gap_curvature = 2.0 * np.dot(dgv_vec, dgv_vec.T)
+        
+        gp_hess = proj_hess + gap_curvature
         return gp_hess

multioptpy/Optimizer/crsirfo.py

@@ -0,0 +1,182 @@
+import numpy as np
+import scipy.linalg
+from multioptpy.Optimizer.rsirfo import RSIRFO
+
+class CRSIRFO(RSIRFO):
+    def __init__(self, constraints=None, **config):
+        """
+        Constrained RS-I-RFO Optimizer (CRS-I-RFO)
+        """
+        super().__init__(**config)
+        self.constraints_obj = constraints
+        self.null_space_basis = None
+        self.svd_threshold = config.get("svd_threshold", 1e-5)
+
+    def _get_null_space_basis(self, geom):
+        if self.constraints_obj is None:
+            return np.eye(len(geom) * 3)
+            
+        geom_reshaped = geom.reshape(-1, 3)
+        B_mat = self.constraints_obj._get_all_constraint_vectors(geom_reshaped)
+        
+        if B_mat is None or len(B_mat) == 0:
+            return np.eye(len(geom) * 3)
+
+        norms = np.linalg.norm(B_mat, axis=1)
+        norms[norms < 1e-12] = 1.0 
+        B_mat_normalized = B_mat / norms[:, np.newaxis]
+
+        try:
+            U, S, Vt = scipy.linalg.svd(B_mat_normalized.T, full_matrices=True)
+            max_s = S[0] if len(S) > 0 else 1.0
+            threshold = max(self.svd_threshold, max_s * 1e-6)
+            rank = np.sum(S > threshold)
+            null_space_basis = U[:, rank:]
+            
+            if null_space_basis.shape[1] == 0:
+                self.log("Warning: System is fully constrained.", force=True)
+                return np.zeros((len(geom)*3, 0))
+
+            return null_space_basis
+            
+        except np.linalg.LinAlgError:
+            return np.eye(len(geom) * 3)
+
+    def run(self, geom_num_list, B_g, pre_B_g=[], pre_geom=[], B_e=0.0, pre_B_e=0.0, pre_move_vector=[], initial_geom_num_list=[], g=[], pre_g=[]):
+        self.log(f"\n{'='*50}\nCRS-I-RFO Iteration {self.iteration}\n{'='*50}", force=True)
+        
+        if self.Initialization:
+            self.prev_eigvec_min = None
+            self.prev_eigvec_size = None
+            self.predicted_energy_changes = []
+            self.actual_energy_changes = []
+            self.prev_geometry = None
+            self.prev_gradient = None
+            self.prev_energy = None
+            self.proj_grad_converged = False
+            self.iteration = 0
+            self.Initialization = False
+        
+        # --- 0. SHAKE-like Correction & Gradient Transport ---
+        gradient_full = np.asarray(B_g).ravel()
+        original_shape = geom_num_list.shape
+        geom_flat = geom_num_list.ravel()
+        
+        if self.constraints_obj is not None:
+            geom_reshaped = geom_num_list.reshape(-1, 3)
+            corrected_geom_3d = self.constraints_obj.adjust_init_coord(geom_reshaped)
+            corrected_geom_flat = corrected_geom_3d.ravel()
+            
+            shake_displacement = corrected_geom_flat - geom_flat
+            diff_norm = np.linalg.norm(shake_displacement)
+            
+            if diff_norm > 1e-6:
+                self.log(f"SHAKE Correction: {diff_norm:.6e}", force=True)
+                H_eff = self.hessian
+                if self.bias_hessian is not None:
+                    H_eff += self.bias_hessian
+                grad_correction = np.dot(H_eff, shake_displacement)
+                gradient_full += grad_correction
+            
+            geom_num_list = corrected_geom_3d.reshape(original_shape)
+
+        # --- 1. Hessian Update ---
+        if self.prev_geometry is not None and self.prev_gradient is not None and len(pre_g) > 0 and len(pre_geom) > 0:
+            self.update_hessian(geom_num_list, g, pre_geom, pre_g)
+
+        hessian_full = self.hessian
+        if self.bias_hessian is not None:
+             hessian_full += self.bias_hessian
+             
+        current_energy = B_e
+
+        # --- 2. Projection to Subspace ---
+        U = self._get_null_space_basis(geom_num_list.reshape(-1, 3))
+        
+        if U.shape[1] == 0:
+             return np.zeros_like(gradient_full).reshape(-1, 1)
+
+        gradient_sub = np.dot(U.T, gradient_full)
+        hessian_sub = np.dot(U.T, np.dot(hessian_full, U))
+        
+        subspace_dim = len(gradient_sub)
+        grad_sub_norm = np.linalg.norm(gradient_sub)
+        
+        self.log(f"Subspace Dim: {subspace_dim}, Projected Grad Norm: {grad_sub_norm:.6e}", force=True)
+
+        # === CRITICAL FIX: Explicit Convergence Check in Subspace ===
+        # If the projected gradient is effectively zero, we are done.
+        # Don't try to calculate RFO step, it will be numerically unstable.
+        if grad_sub_norm < self.gradient_norm_threshold:
+            self.log(f"*** CONVERGED in Subspace (Grad: {grad_sub_norm:.6e}) ***", force=True)
+            self.proj_grad_converged = True
+            
+            # Reset history to clean state
+            self.prev_geometry = geom_num_list
+            self.prev_gradient = B_g
+            self.prev_energy = current_energy
+            
+            return np.zeros_like(gradient_full).reshape(-1, 1)
+        # ============================================================
+
+        # --- 3. RFO in Subspace ---
+        hessian_sub = 0.5 * (hessian_sub + hessian_sub.T)
+        
+        eigvals_sub, eigvecs_sub = self.compute_eigendecomposition_with_shift(hessian_sub)
+        
+        # Trust Radius
+        if not self.Initialization and self.prev_energy is not None:
+            actual_energy_change = B_e - self.prev_energy
+            if len(self.actual_energy_changes) >= 3:
+                self.actual_energy_changes.pop(0)
+            self.actual_energy_changes.append(actual_energy_change)
+            
+            if self.predicted_energy_changes:
+                min_eigval = eigvals_sub[0] if len(eigvals_sub) > 0 else None
+                self.adjust_trust_radius(
+                    actual_energy_change,
+                    self.predicted_energy_changes[-1],
+                    min_eigval,
+                    grad_sub_norm
+                )
+
+        P_rfo = np.eye(subspace_dim)
+        root_num = 0
+        i = 0
+        while root_num < len(self.roots) and i < len(eigvals_sub):
+            if np.abs(eigvals_sub[i]) > 1e-10:
+                trans_vec = eigvecs_sub[:, i]
+                if self.NEB_mode:
+                    P_rfo -= np.outer(trans_vec, trans_vec)
+                else:
+                    P_rfo -= 2 * np.outer(trans_vec, trans_vec)
+                root_num += 1
+            i += 1
+            
+        H_star_sub = np.dot(P_rfo, hessian_sub)
+        H_star_sub = 0.5 * (H_star_sub + H_star_sub.T)
+        grad_star_sub = np.dot(P_rfo, gradient_sub)
+        
+        eigvals_star, eigvecs_star = self.compute_eigendecomposition_with_shift(H_star_sub)
+        eigvals_star, eigvecs_star = self.filter_small_eigvals(eigvals_star, eigvecs_star)
+        
+        step_sub = self.get_rs_step(eigvals_star, eigvecs_star, grad_star_sub)
+        
+        # --- 4. Reconstruct Step ---
+        step_full = np.dot(U, step_sub)
+        
+        predicted_energy_change = self.rfo_model(gradient_sub, hessian_sub, step_sub)
+        
+        if len(self.predicted_energy_changes) >= 3:
+            self.predicted_energy_changes.pop(0)
+        self.predicted_energy_changes.append(predicted_energy_change)
+        
+        if self.actual_energy_changes and len(self.predicted_energy_changes) > 1:
+            self.evaluate_step_quality()
+            
+        self.prev_geometry = geom_num_list
+        self.prev_gradient = B_g
+        self.prev_energy = current_energy
+        self.iteration += 1
+        
+        return -1 * step_full.reshape(-1, 1)