Crate cheq 

A high-performance Rust library for calculating dynamic partial atomic charges using the Charge Equilibration (QEq) method.

Cheq: Charge Equilibration for Molecular Dynamics

Cheq implements the robust and general Charge Equilibration (QEq) method proposed by Rappé and Goddard (1991) to predict the self-consistent, geometry-dependent partial charges of atoms in a molecular system.

Unlike fixed-charge force fields, QEq allows atomic charges to dynamically respond to changes in molecular geometry and external fields, which is essential for accurate molecular dynamics (MD) simulations, particularly for systems like ceramics, polymers, and biological molecules where charge transfer is significant.

The method relies solely on atomic properties (electronegativity, hardness, and radius) and the molecular geometry to achieve charge neutrality.

Quickstart

The primary entry point is the QEqSolver, which requires a set of Parameters (atomic data) and a slice of atoms with coordinates.

use cheq::{get_default_parameters, QEqSolver, Atom, SolverOptions};
use approx::assert_relative_eq;

// 1. Set up the parameters and solver.
//    (Parameters include chi, J, radius, and n for each element)
let params = get_default_parameters();
let options = SolverOptions::default(); // Use default convergence criteria
let solver = QEqSolver::new(params).with_options(options);

// 2. Define the molecular system (Water molecule geometry).
let bond_length = 0.9575;
let angle = 104.45f64.to_radians();

let atoms = vec![
    Atom { atomic_number: 8, position: [0.0, 0.0, 0.0] },         // Oxygen
    Atom { atomic_number: 1, position: [bond_length, 0.0, 0.0] }, // Hydrogen 1
    Atom { atomic_number: 1, position: [
        bond_length * angle.cos(),
        bond_length * angle.sin(),
        0.0,
    ]},                                                           // Hydrogen 2
];

// 3. Solve for partial charges (total charge Q_tot = 0.0).
let result = solver.solve(&atoms, 0.0).unwrap();

// 4. Inspect the results.
let q_o = result.charges[0];
let q_h1 = result.charges[1];

assert!(q_o < 0.0);   // Oxygen is negative
assert!(q_h1 > 0.0);  // Hydrogen is positive
assert_relative_eq!(q_o + 2.0 * q_h1, 0.0, epsilon = 1e-9); // Charge conservation
println!("Charges (O, H1, H2): ({:.3}, {:.3}, {:.3})", q_o, q_h1, result.charges[2]);

Structs

Atom

A concrete representation of an atom with atomic number and position.

CalculationResult

The result of a charge equilibration calculation.

ElementData

Atomic parameters for an element used in charge equilibration calculations.

Parameters

A collection of atomic parameters for multiple elements.

QEqSolver

The QEqSolver struct for performing charge equilibration calculations.

SolverOptions

The SolverOptions struct for configuring solver parameters.

Enums

CheqError

The primary error type for all fallible operations in the cheq library.

Traits

AtomView

A trait for viewing atom data without owning it.

Functions

get_default_parameters

Provides a thread-safe, cached reference to the default atomic parameters.