Struct QEqSolver 

pub struct QEqSolver<'p> { /* private fields */ }

The main solver for charge equilibration calculations.

This struct holds references to atomic parameters and solver options, providing methods to perform QEq calculations on molecular systems. It implements an iterative SCF procedure to solve the non-linear charge equilibration equations.

Implementations

impl<'p> QEqSolver<'p>

pub fn new(parameters: &'p Parameters) -> Self

Creates a new QEqSolver with default options.

Arguments

• parameters - A reference to the Parameters containing element data.

Returns

A new QEqSolver instance with default SolverOptions.

Examples

use cheq::get_default_parameters;
use cheq::QEqSolver;

let params = get_default_parameters();
let solver = QEqSolver::new(params);

pub fn with_options(self, options: SolverOptions) -> Self

Configures the solver with custom options.

This method allows setting non-default solver parameters such as tolerance and maximum iterations. It consumes the solver and returns a new instance with the updated options.

Arguments

• options - The SolverOptions to apply to the solver.

Returns

A new QEqSolver instance with the specified options.

Examples

use cheq::get_default_parameters;
use cheq::{QEqSolver, SolverOptions};

let params = get_default_parameters();
let options = SolverOptions {
    max_iterations: 100,
    tolerance: 1e-6,
    ..Default::default()
};

let solver = QEqSolver::new(params).with_options(options);

pub fn solve<A: AtomView>( &self, atoms: &[A], total_charge: f64, ) -> Result<CalculationResult, CheqError>

Solves the charge equilibration equations for a given molecular system.

This method performs the SCF iterative procedure to compute partial atomic charges that equalize the chemical potential across all atoms, subject to the total charge constraint. The process involves building and solving a linear system in each iteration, with special handling for hydrogen atoms whose hardness depends on their charge.

Arguments

• atoms - A slice of atom data implementing the AtomView trait.
• total_charge - The desired total charge of the system.

Returns

A Result containing CalculationResult with the computed charges and metadata on success, or a CheqError on failure.

Errors

• CheqError::NoAtoms - If the input atom list is empty.
• CheqError::ParameterNotFound - If an atom’s parameters are missing.
• CheqError::NotConverged - If the SCF procedure fails to converge within the maximum iterations.
• CheqError::LinalgError - If the linear system solver encounters an error.

Examples

use cheq::get_default_parameters;
use cheq::QEqSolver;
use cheq::Atom;

// 1. Setup parameters and solver
let params = get_default_parameters();
let solver = QEqSolver::new(params);

// 2. Define a molecule (e.g., H2)
let atoms = vec![
    Atom { atomic_number: 1, position: [0.0, 0.0, 0.0] },
    Atom { atomic_number: 1, position: [0.74, 0.0, 0.0] },
];

// 3. Run calculation
let result = solver.solve(&atoms, 0.0).unwrap();

assert_eq!(result.charges.len(), 2);
println!("Charges: {:?}", result.charges);

pub fn solve_in_field<A: AtomView>( &self, atoms: &[A], total_charge: f64, external: &ExternalPotential, ) -> Result<CalculationResult, CheqError>

Solves the charge equilibration equations in the presence of an external electrostatic field.

This method extends the standard QEq calculation to include the effect of an external electrostatic environment on the charge distribution. The external potential modifies the effective electronegativity of each atom, allowing the QEq subsystem to polarize in response to its surroundings.

Arguments

• atoms - A slice of atom data implementing the AtomView trait.
• total_charge - The desired total charge of the QEq subsystem.
• external - The external electrostatic potential acting on the system.

Returns

A Result containing CalculationResult with the computed charges and metadata on success, or a CheqError on failure.

Errors

• CheqError::NoAtoms - If the input atom list is empty.
• CheqError::ParameterNotFound - If parameters are missing for any atom (QEq or external).
• CheqError::NotConverged - If the SCF procedure fails to converge.
• CheqError::LinalgError - If the linear system solver encounters an error.

Examples

use cheq::{get_default_parameters, QEqSolver, Atom, ExternalPotential, PointCharge};

let params = get_default_parameters();
let solver = QEqSolver::new(params);

// A simple diatomic molecule
let ligand = vec![
    Atom { atomic_number: 6, position: [0.0, 0.0, 0.0] },
    Atom { atomic_number: 8, position: [1.2, 0.0, 0.0] },
];

// An external positive charge nearby
let external = ExternalPotential::from_point_charges(vec![
    PointCharge::new(7, [3.0, 0.0, 0.0], 0.5),
]);

let result = solver.solve_in_field(&ligand, 0.0, &external).unwrap();

// The oxygen should become more negative due to the nearby positive charge
println!("C charge: {:.4}, O charge: {:.4}", result.charges[0], result.charges[1]);