pyef.utility

Utility module for pyEF package.

This module contains all utility functions, classes, and constants used throughout the pyEF package for processing quantum chemistry calculations and electric field analysis.

Physical Constants

All constants are in SI units unless otherwise specified.

Atomic Data

  • PERIODIC_TABLE: Element symbols mapped to atomic numbers

  • ATOMIC_MASS_DICT: Element properties (mass, atomic number, covalent radius, valence)

  • VDW_RADII_DICT: Van der Waals radii for elements

Sources:

Module Contents

Classes

MoldenObject

MultiwfnInterface

Interface class for Multiwfn charge partitioning and multipole calculations.

Functions

get_openbabel_charges(xyz_path[, charge_model, ...])

Calculate partial atomic charges using OpenBabel charge models.

list_openbabel_charge_models()

List available OpenBabel charge models.

Attributes

COULOMB_CONSTANT

ANGSTROM_TO_M

BOHR_TO_M

BOHR_TO_ANGSTROM

ELEMENTARY_CHARGE

VM_TO_VA

PERIODIC_TABLE

ATOMIC_MASS_DICT

VDW_RADII_DICT

COULOMB_CONSTANT = 8987551000.0
ANGSTROM_TO_M = 1e-10
BOHR_TO_M = 5.291772109e-11
BOHR_TO_ANGSTROM = 0.529177210903
ELEMENTARY_CHARGE = 1.6023e-19
VM_TO_VA = 1e-10
PERIODIC_TABLE
ATOMIC_MASS_DICT
VDW_RADII_DICT
class MoldenObject(xyzfile, moldenfile)
countBasis(spherical=True)
build_core_map(family)

Build a {symbol: core_electrons} dictionary for a given ECP family

build_hybrid_core_map(name, cutoff_Z, heavy_family, base_maps)

Build core-electron map for hybrid family Elements with Z <= cutoff_Z ?~F~R core=0 Elements with Z > cutoff_Z ?~F~R use heavy_family core mapping

fix_ECPmolden(owd, ECP)

Fix ECP artifacts in TeraChem Molden files for Multiwfn compatibility.

Performs three corrections: 1. Replaces full atomic numbers with valence electron counts for ECP atoms 2. Adds [Pseudo] section listing ECP atoms (required by Multiwfn) 3. Removes any incorrectly added [5d]/[7f]/[9g] tags (TeraChem writes

Cartesian basis functions which is the Molden default)

class MultiwfnInterface(config=None)

Interface class for Multiwfn charge partitioning and multipole calculations.

This class encapsulates all interactions with the Multiwfn external program, providing methods for charge partitioning, multipole moment calculations, and parsing of Multiwfn output files.

dict_of_calcs

Mapping of charge scheme names to Multiwfn command codes

Type:

dict

dict_of_multipole

Mapping of multipole schemes to Multiwfn command sequences

Type:

dict

config

Configuration dictionary with Multiwfn settings

Type:

dict

CHARGE_SCHEMES
MULTIPOLE_SCHEMES
run_multiwfn(command, input_commands, output_file=None, description='Multiwfn calculation', capture_output=True)

Centralized Multiwfn runner with proper error handling and output display.

Parameters:

  • command (str) – The shell command to run Multiwfn (e.g., “multiwfn file.molden”)

  • input_commands (list of str) – List of commands to send to Multiwfn’s stdin

  • output_file (str, optional) – Path to redirect stdout to a file

  • description (str, optional) – Description of the calculation for error messages

  • capture_output (bool, optional) – If True, capture and display output. If False, let it stream to terminal

Returns:

(stdout, stderr, returncode) from the Multiwfn process

Return type:

tuple

Raises:

RuntimeError – If Multiwfn fails with non-zero exit code

partitionCharge(multipole_bool, f, multiwfn_path, charge_type, owd, molden_filename=None, xyz_filename=None)

Partition electron density using Multiwfn to generate partial charges or multipole moments.

This is the centralized interface for all charge partitioning schemes (Hirshfeld, CHELPG, etc.). Checks if calculation was previously completed and reuses results unless rerun=True.

Parameters:

  • multipole_bool (bool) – True to compute multipole moments, False for monopoles only

  • f (str) – Complete path to folder containing the calculation

  • multiwfn_path (str) – Path to Multiwfn executable

  • charge_type (str) – Partitioning scheme (e.g., ‘Hirshfeld’, ‘CHELPG’, ‘Hirshfeld_I’)

  • owd (str) – Original working directory

  • molden_filename (str, optional) – Name of the molden file (not full path, just filename). If None, uses self.config[‘molden_filename’]

  • xyz_filename (str, optional) – Name of the xyz file (not full path, just filename). If None, uses self.config[‘xyzfilename’]

Returns:

Computation time in seconds, 0 if calculation was previously completed (skipped), or -1 if calculation failed

Return type:

float

Notes

For Hirshfeld-I calculations, atmrad files are automatically loaded from pyef.resources.atmrad (bundled with the package).

static count_atoms(xyz_filename)

Count number of atoms in XYZ file (mapcount replacement).

static getmultipoles(multipole_name)

Parse multipole moments from Multiwfn output file.

Parameters:

multipole_name (str) – Path to multipole moment output file from Multiwfn.

Returns:

List of dictionaries containing multipole data for each atom: - ‘Index’: atom index (str) - ‘Element’: element symbol (str) - ‘Atom_Charge’: atomic charge (float) - ‘Dipole_Moment’: dipole moment vector [x, y, z] (list of float) - ‘Quadrupole_Moment’: 3x3 quadrupole tensor (np.ndarray)

Return type:

list of dict

Notes

Parses Multiwfn output format with sections separated by asterisks. Extracts monopole (charge), dipole, and quadrupole moments for each atom.

get_openbabel_charges(xyz_path, charge_model='gasteiger', output_path=None)

Calculate partial atomic charges using OpenBabel charge models.

This provides an alternative to Multiwfn for simpler charge models when quantum chemistry-derived charges are not needed.

Parameters:

  • xyz_path (str) – Path to XYZ coordinate file (or other format OpenBabel can read).

  • charge_model (str, optional) – Charge model to use. Options: - ‘gasteiger’: Gasteiger-Marsili electronegativity equalization (default) - ‘mmff94’: MMFF94 partial charges - ‘eem’: Electronegativity Equalization Method - ‘qeq’: Charge Equilibration method - ‘qtpie’: QTPIE charges - ‘none’: No charges (all zeros)

  • output_path (str or None, optional) – If provided, write charges to file in Multiwfn-compatible format. If None, only return the DataFrame (default: None).

Returns:

DataFrame with columns [‘Atom’, ‘x’, ‘y’, ‘z’, ‘charge’] Compatible with pyEF charge file format.

Return type:

pd.DataFrame

Raises:

  • ImportError – If OpenBabel (openbabel) is not installed.

  • ValueError – If an unsupported charge model is specified.

  • FileNotFoundError – If the input XYZ file does not exist.

Examples

>>> # Get Gasteiger charges
>>> charges_df = get_openbabel_charges('molecule.xyz')

>>> # Get MMFF94 charges and save to file
>>> charges_df = get_openbabel_charges('molecule.xyz', 'mmff94', 'charges.txt')

>>> # Use with Electrostatics for ESP calculation
>>> charges_df = get_openbabel_charges('molecule.xyz', 'gasteiger', 'ChargesGasteiger.txt')

Notes

Supported charge models and their typical use cases: - gasteiger: Fast, reasonable for organic molecules. Based on electronegativity. - mmff94: Force field charges, good for drug-like molecules. - eem: Similar to gasteiger but with different parameterization. - qeq: Good for extended systems, metals.

The output format matches Multiwfn’s charge file format: Atom x y z charge

list_openbabel_charge_models()

List available OpenBabel charge models.

Returns:

List of available charge model names.

Return type:

list of str

Notes

Common models include: - gasteiger: Gasteiger-Marsili charges (fast, electronegativity-based) - mmff94: MMFF94 force field charges - eem: Electronegativity Equalization Method - qeq: Charge Equilibration - qtpie: QTPIE method