qrunch.chemistry.embedded_atoms.bond_capacity_electronegativity_equilibration

Bond capacity electronegativity equilibration (EEQBC) charge model and charge-change selector.

This module implements the bond capacity electronegativity equilibration charge model (EEQBC) [FMullerHG25].

EEQBC replaces the global charge coupling of ordinary QEq/EEQ with a distance-dependent Maxwell capacitance matrix. This strongly suppresses artificial long-range charge transfer between distant fragments, which makes charge-difference based active-atom selection far less prone to selecting chemically irrelevant, distant atoms.

Functions

calculate_eeqbc_charges(atomic_numbers, ...)

Compute atomic partial charges using the bond capacity electronegativity equilibration model.

Classes

`AtomicChargeCalculator`	Computes geometry-dependent atomic partial charges for a molecule.
`BondCapacityElectronegativityEquilibrationChargeChangeSelector`	Selects atoms whose EEQBC partial charges change significantly across reaction images.
`EEQBCChargeCalculator`	Bond capacity electronegativity equilibration (EEQBC) atomic charge calculator.

class AtomicChargeCalculator

Bases: Protocol

Computes geometry-dependent atomic partial charges for a molecule.

__init__(*args, **kwargs)

calculate_charges(molecule: Molecule, total_charge: int) → ndarray[tuple[Any, ...], dtype[float64]]

Compute atomic partial charges for a molecule.

Parameters:

molecule (Molecule) – The molecule to compute charges for.
total_charge (int) – Total charge of the system in elementary charges.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

class BondCapacityElectronegativityEquilibrationChargeChangeSelector

Bases: PrimaryEmbeddedAtomsSelector

Selects atoms whose EEQBC partial charges change significantly across reaction images.

Uses the bond capacity electronegativity equilibration model (EEQBC), which introduces a distance-dependent Maxwell capacitance matrix. Compared to ordinary QEq/EEQ, EEQBC strongly suppresses artificial long-range charge transfer between distant fragments, so charge-difference based selection is far less likely to select chemically irrelevant, distant spectator atoms.

__init__(total_charge: int = 0, charge_threshold: float = 0.05, charge_calculator: AtomicChargeCalculator = EEQBCChargeCalculator()) → None

Parameters:

total_charge (int)
charge_threshold (float)
charge_calculator (AtomicChargeCalculator)

Return type:

None

charge_calculator: AtomicChargeCalculator = EEQBCChargeCalculator()

charge_threshold: float = 0.05

scores(reaction: Reaction, prepared_data: Sequence[PreparedRestrictedData] | Sequence[PreparedUnrestrictedData] | None = None, molecular_configurations: Sequence[MolecularConfiguration] | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Score atoms by their largest partial-charge change.

Parameters:

reaction (Reaction) – The reaction to analyze.
prepared_data (Sequence[PreparedRestrictedData] | Sequence[PreparedUnrestrictedData] | None) – Not used by this selector.
molecular_configurations (Sequence[MolecularConfiguration] | None) – Not used by this selector.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

select(reaction: Reaction, prepared_data: Sequence[PreparedRestrictedData] | Sequence[PreparedUnrestrictedData] | None = None, molecular_configurations: Sequence[MolecularConfiguration] | None = None) → set[int]

Select atoms whose partial charge changes by at least charge_threshold across images.

Parameters:

reaction (Reaction) – The reaction to analyze.
prepared_data (Sequence[PreparedRestrictedData] | Sequence[PreparedUnrestrictedData] | None) – Not used by this selector.
molecular_configurations (Sequence[MolecularConfiguration] | None) – Not used by this selector.

Return type:

set[int]

total_charge: int = 0

class EEQBCChargeCalculator

Bases: AtomicChargeCalculator

Bond capacity electronegativity equilibration (EEQBC) atomic charge calculator.

__init__() → None

Return type:: None

calculate_charges(molecule: Molecule, total_charge: int) → ndarray[tuple[Any, ...], dtype[float64]]

Compute EEQBC atomic partial charges for a molecule.

Parameters:

molecule (Molecule) – The molecule to compute charges for.
total_charge (int) – Total charge of the system in elementary charges.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

calculate_eeqbc_charges(atomic_numbers: Sequence[int], positions: ndarray[tuple[Any, ...], dtype[float64]], total_charge: int = 0) → ndarray[tuple[Any, ...], dtype[float64]]

Compute atomic partial charges using the bond capacity electronegativity equilibration model.

The implementation uses a distance dependent Maxwell capacitance matrix C combined with a Gaussian Coulomb matrix J to form the symmetric EEQBC matrix A = I + C .* J (Hadamard product), and the charges are obtained from the augmented, total-charge constrained linear system.

Parameters:

atomic_numbers (Sequence[int]) – Atomic numbers of the atoms, length number_of_atoms.
positions (ndarray[tuple[Any, ...], dtype[float64]]) – Cartesian coordinates in Angstrom, shape (number_of_atoms, 3).
total_charge (int) – Total charge of the system in elementary charges.

Return type:

ndarray[tuple[Any, …], dtype[float64]]