Summary:

Introduces the core computational engine of the cheq library: a robust, self-consistent Charge Equilibration (QEq) solver. A new solver module has been created, featuring a QEqSolver that constructs and iteratively solves the QEq linear system to determine atomic partial charges. The implementation handles both linear (non-H) and non-linear (H-containing) systems, incorporates a flexible options structure, and uses the high-performance faer crate for all linear algebra operations.

Changes:

• Implemented the QEqSolver:

  • Created a QEqSolver struct responsible for orchestrating the entire charge calculation process.
  • Implemented the main solve method, which takes a slice of atoms and a total charge, and returns a CalculationResult.
  • The solver correctly handles the charge-dependent hardness of hydrogen atoms, triggering an iterative Self-Consistent Field (SCF) process until convergence is reached.

• Developed the Linear System Builder:

  • Implemented the build_system method, which dynamically constructs the QEq matrix (A) and vector (b) for each SCF iteration.
  • Diagonal Elements (Hardness): The diagonal of the matrix is populated with atomic hardness (J_ii), including the special non-linear term for hydrogen.
  • Off-Diagonal Elements (Shielding): Off-diagonal elements are populated using the gaussian_coulomb_integral function to calculate the shielded Coulomb interaction (J_ij).
  • Charge Constraint: The system is augmented with an additional row and column to enforce the total charge constraint (sum(q_i) = Q_total).

• Integrated a High-Performance Linear Algebra Backend:

  • Added the faer crate as a dependency for fast and robust linear algebra operations.
  • The solver uses faer's partial-pivoting LU decomposition (partial_piv_lu) to solve the linear system in each iteration.
  • Implemented panic-safe error handling around the solve call to gracefully manage potential linear algebra failures (e.g., singular matrices).

• Added Solver Configuration Options:

  • Created a SolverOptions struct to allow users to configure the solver's behavior, including tolerance, max_iterations, and the shielding scale factor lambda_scale.
  • The QEqSolver can be instantiated with custom options via the with_options builder method.

• Included Comprehensive Solver Tests:

  • Developed an extensive test suite covering various chemical systems:
    • Linear System: Carbon monoxide (CO).
    • Non-Linear System: Water (H₂O).
    • Symmetry: Dihydrogen (H₂).
    • Ionic System: Lithium hydride (LiH).
  • Tests verify charge conservation, chemical trends (NaCl vs. NaBr), and correct error handling for edge cases like empty input, missing parameters, and non-convergence.