feat(solver): Implement External Electrostatic Field Support

[TKanX]

Summary:

Introduces a major new feature to the cheq library: the ability to perform charge equilibration in the presence of an external electrostatic potential. This enables hybrid QEq/MM simulations, where a quantum-mechanically treated region (the QEq system) polarizes in response to a classical environment (the external field). The implementation supports contributions from both discrete point charges and a uniform electric field, which are incorporated into the QEq equations by modifying the effective electronegativity of each atom.

Changes:

• Implemented ExternalPotential and PointCharge Data Structures:

  • Created a new PointCharge struct to represent a fixed charge in the classical environment (e.g., an atom from a protein).
  • Developed a flexible ExternalPotential struct to aggregate contributions from multiple PointCharges and/or a uniform_field.
  • Provided a builder-style API for ExternalPotential (with_point_charges, with_uniform_field) for ergonomic construction.

• Introduced a New solve_in_field Solver Method:

  • Added a new public method, QEqSolver::solve_in_field, which accepts an ExternalPotential as an argument.
  • The method computes the external potential V_ext at each QEq atom's position, using the same STO/GTO shielded Coulomb formalism for consistency with internal interactions.
  • The external potential is then added to the electronegativity term in the QEq linear system (χ_i* = χ_i + V_ext_i), effectively polarizing the QEq system.

• Parallelized External Potential Calculation:

  • The calculation of the external potential, which can be computationally intensive for large environments, is parallelized using rayon for optimal performance.

• Added Comprehensive Documentation and Tests:

  • Wrote extensive RustDoc for the new ExternalPotential and PointCharge types, explaining their purpose and usage in hybrid QEq/MM contexts.
  • Added a new section to the README.md and lib.rs documentation demonstrating how to use solve_in_field.
  • Implemented a suite of unit and integration tests to verify the correctness of the implementation, including tests for polarization effects, symmetry, and handling of both point charges and uniform fields.

• Architectural Refinements:

  • The core SCF iteration logic was refactored into a private run_scf_iterations method, shared by both solve and solve_in_field to reduce code duplication.

[Copilot]

Pull request overview

This PR introduces comprehensive support for external electrostatic fields in charge equilibration calculations, enabling hybrid QEq/MM simulations. The implementation allows a quantum-mechanically treated molecular fragment (e.g., a ligand) to polarize in response to a classical environment (e.g., protein residues), without including environment atoms in the expensive QEq matrix diagonalization.

• Adds PointCharge and ExternalPotential data structures with a builder-style API for representing external electrostatic environments
• Implements a new solve_in_field solver method that modifies the effective electronegativity of QEq atoms based on external potential contributions
• Refactors core SCF iteration logic into a shared run_scf_iterations method to avoid code duplication between solve and solve_in_field

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

File	Description
src/types.rs	Adds PointCharge struct and ExternalPotential struct with builder pattern API, plus comprehensive unit tests
src/solver/implementation.rs	Implements solve_in_field method, compute_external_potential helper with parallelization, refactors SCF logic, and adds integration tests
src/lib.rs	Exports new types (ExternalPotential, PointCharge) and adds documentation example for hybrid QEq/MM usage
README.md	Updates feature list to mention external field support

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.