Struct QEqSolver 

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

The QEqSolver struct for performing charge equilibration calculations.

This is the main solver that implements the SCF iterative procedure to compute partial atomic charges based on the QEq method. 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, 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, QEqSolver, SolverOptions};

let params = get_default_parameters();
let options = SolverOptions { tolerance: 1e-8, max_iterations: 50, lambda_scale: 1.0 };
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

This function can return the following errors:

• CheqError::NoAtoms if the atom slice is empty.
• CheqError::ParameterNotFound if parameters for an atom’s element are missing.
• CheqError::LinalgError if the linear system cannot be solved due to numerical issues.
• CheqError::NotConverged if the SCF procedure does not converge within the maximum iterations.

Examples

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

let params = get_default_parameters();
let solver = QEqSolver::new(&params);
let atoms = vec![
    Atom { atomic_number: 6, position: [0.0, 0.0, 0.0] },
    Atom { atomic_number: 8, position: [1.128, 0.0, 0.0] },
];
let result = solver.solve(&atoms, 0.0).unwrap();
assert_eq!(result.charges.len(), 2);