API Reference

This page documents the main classes and functions for computing electric fields, electrostatic potentials, and partial charges.

Quick Reference

Function	Key Inputs	Output	Requirements
getEfield()	charge_types, input_bond_indices, multiwfn_path	DataFrame with E-field (V/Å)	Molden + XYZ files
getESP()	charge_types, multiwfn_path	DataFrame with ESP (V)	esp_atom_idx at init
getCharges()	charge_types, multiwfn_path, write_pdb	DataFrame with charges	Molden + XYZ files
getElectrostatic_stabilization()	substrate_idxs, charge_type, multipole_order	DataFrame with energies (kcal/mol)	Molden + XYZ files

Electrostatics Class

The Electrostatics class in pyef.analysis is the main interface for all calculations.

Initialization

from pyef.analysis import Electrostatics

es = Electrostatics(
    molden_paths,      # List of .molden file paths
    xyz_paths,         # List of .xyz file paths
    esp_atom_idx=None, # Atom indices for ESP (0-indexed)
    ptchg_paths=None,  # Point charge files for QM/MM
    **kwargs           # Configuration options (see below)
)

Required parameters:

• molden_paths (list of str): Paths to molden files, one per structure

• xyz_paths (list of str): Paths to XYZ files, one per structure

Optional parameters:

• esp_atom_idx (list of int): Atom indices for ESP calculations (0-indexed)

• ptchg_paths (list): Point charge file paths for QM/MM calculations

Configuration kwargs

The following keyword arguments can be passed to the Electrostatics constructor to configure the calculation behavior. All are optional and have sensible defaults.

ECP (Effective Core Potential) Options:

Parameter	Type	Default	Description
hasECP	bool	False	Set to True if your QM calculation used Effective Core Potentials. When enabled, pyEF will automatically reformat molden files to fix ECP-related artifacts that make them incompatible with Multiwfn.
ECP	str	"lacvps"	The ECP basis set family used in the QM calculation. Only relevant when hasECP=True. See supported ECPs below.

Supported ECP basis set families:

ECP Value	Description
"lacvps"	LACVPS (default). Hybrid ECP: all-electron for elements with Z ≤ 18 (up to Ar), LANL2DZ ECP for heavier elements. Common for TeraChem calculations with transition metals.
"lacvp"	LACVP. Hybrid ECP: all-electron for elements with Z ≤ 10 (up to Ne), LANL2DZ ECP for heavier elements.
"lanl2dz"	LANL2DZ (Los Alamos National Laboratory 2-Double-Zeta). Widely used ECP for transition metals.
"def2"	def2-type ECPs (e.g., def2-SVP, def2-TZVP). Stuttgart/Cologne group ECPs used in the Ahlrichs basis set family.
"crenbl"	CRENBL (Christiansen, Ross, Ermler, Nash, Bursten, Large-core). Shape-consistent relativistic ECPs.
"stuttgart_rsc"	Stuttgart RSC (Relativistic Small Core). Energy-consistent ECPs from the Stuttgart/Cologne group.

Example with ECP:

# For a TeraChem calculation that used LACVPS basis set
es = Electrostatics(molden_paths, xyz_paths, hasECP=True, ECP="lacvps")

# For a calculation that used def2-type ECPs
es = Electrostatics(molden_paths, xyz_paths, hasECP=True, ECP="def2")

Dielectric and Environment Options:

Parameter	Type	Default	Description
dielectric	float	1	Dielectric constant for the environment. Common values: 1.0 (vacuum), 2-4 (protein interior), 20-40 (protein-solvent interface), 78.5 (water). Can also be overridden per method call.
dielectric_scale	float	1	Scaling factor applied to point charges in the dielectric treatment. Can also be overridden per method call.
changeDielectBoundBool	bool	False	When True, uses dielectric=1 for atoms that are directly bonded, applying the dielectric scaling only to non-bonded interactions. Useful for modeling distinct dielectric boundaries.
excludeAtomfromEcalc	list	[]	List of atom indices to exclude from E-field calculations. Typically used to exclude substrate atoms when probing only the environment’s contribution. Can also be set via setExcludeAtomFromCalc().

QM/MM Point Charge Options:

Parameter	Type	Default	Description
includePtChgs	bool	False	Include QMMM point charges in ESP/E-field calculations. Point charge files must be provided via ptchg_paths or ptChgfp.
ptChgfp	str	''	Legacy API: a single point charge filename applied to all jobs. Prefer using ptchg_paths instead.

Computation Options:

Parameter	Type	Default	Description
rerun	bool	False	Force recalculation of charges even if cached results exist. By default, pyEF caches Multiwfn charge results and reuses them on subsequent runs.
maxIHirshBasis	int	12000	Maximum number of basis functions allowed for Hirshfeld-I analysis. Increase for very large systems.
maxIHirshFuzzyBasis	int	6000	Maximum number of basis functions allowed for fuzzy Hirshfeld-I analysis.
skip_missing_files	bool	False	When True, skip jobs where required input files are missing instead of raising an error. Useful for batch processing where some calculations may have failed.

Visualization Options:

Parameter	Type	Default	Description
visualize_ef	bool	False	Create PDB files with atom-wise electric field contributions in the B-factor column.
visualize_charges	bool	False	Create PDB files with partial charges in the B-factor column.
visualize_per_bond	bool	False	Create separate PDB files for each bond in E-field calculations.

Legacy/Compatibility Options:

Parameter	Type	Default	Description
molden_filename	str	'final_optim.molden'	Molden filename for backward compatibility with older directory-based workflows.
xyzfilename	str	'final_optim.xyz'	XYZ filename for backward compatibility with older directory-based workflows.

getEfield() - Electric Field

df = es.getEfield(
    charge_types='Hirshfeld_I',   # Charge scheme(s)
    Efielddata_filename='ef',     # Output filename prefix
    multiwfn_path=None,           # Path to Multiwfn executable
    input_bond_indices=[],        # [(atom1, atom2), ...] per structure
    auto_find_bonds=False,        # Auto-detect bonds to adjacent atoms
    multipole_bool=False,         # Use multipole expansion
    save_atomwise_decomposition=False,  # Save per-atom contributions
    visualize=None,               # Create PDB visualization files
    dielectric=1,                 # Dielectric constant
    dielectric_scale=1,           # Dielectric scaling for point charges
    includePtChgs=None,           # Override point charge setting
    ptchg_paths=None,             # Override point charge file paths
    pdb_charge_paths=None         # Use charges from PDB B-factor column
)

Parameters:

• charge_types (str or list): Charge scheme(s) to use (first entry used if list)

• Efielddata_filename (str): Output CSV filename prefix (default: 'ef')

• multiwfn_path (str): Path to Multiwfn executable

• input_bond_indices (list of tuples): Bond pairs as (atom1, atom2) per structure

• auto_find_bonds (bool): Automatically find bonds to adjacent atoms (default: False)

• multipole_bool (bool): True for multipole expansion, False for monopole (default: False)

• save_atomwise_decomposition (bool): Save per-atom E-field breakdown (default: False)

• visualize (bool or None): Create PDB files with E-field data in B-factor column

• dielectric (float): Dielectric constant (default: 1)

• dielectric_scale (float): Scaling factor for point charges (default: 1)

• includePtChgs (bool or None): Override the class-level point charge inclusion setting

• ptchg_paths (list or None): Override point charge file paths

• pdb_charge_paths (str or list): Read charges from PDB B-factor column instead of computing them (monopole only)

Returns: DataFrame with electric field results. If save_atomwise_decomposition=True, returns a tuple (total_df, atomwise_df).

getESP() - Electrostatic Potential

df = es.getESP(
    charge_types='CM5',          # Charge scheme(s)
    ESPdata_filename='ESP',      # Output filename prefix
    multiwfn_path='None',        # Path to Multiwfn executable
    use_multipole=False,         # Use multipole expansion
    include_decay=False,         # Include distance-sorted ESP decay
    include_coord_shells=False,  # Include coordination shell ESP
    visualize=None,              # Create PDB visualization files
    dielectric=1,                # Dielectric constant
    dielectric_scale=1,          # Dielectric scaling for point charges
    includePtChgs=None,          # Override point charge setting
    ptchg_paths=None             # Override point charge file paths
)

Parameters:

• charge_types (str or list): Charge scheme(s) to use

• ESPdata_filename (str): Output CSV filename prefix (default: 'ESP')

• multiwfn_path (str): Path to Multiwfn executable

• use_multipole (bool): Use multipole expansion instead of monopole (default: False)

• include_decay (bool): Include distance-sorted ESP decay analysis (default: False)

• include_coord_shells (bool): Include coordination shell ESP breakdown (default: False)

• visualize (bool or None): Create PDB files with ESP in B-factor column

• dielectric (float): Dielectric constant (default: 1)

• dielectric_scale (float): Scaling factor for point charges (default: 1)

• includePtChgs (bool or None): Override the class-level point charge inclusion setting

• ptchg_paths (list or None): Override point charge file paths

Returns: DataFrame with ESP results

Note: Requires esp_atom_idx to be set during initialization.

getCharges() - Partial Charges

df = es.getCharges(
    charge_types='Hirshfeld_I',        # Charge scheme(s)
    multiwfn_path=None,                # Path to Multiwfn executable
    output_filename='charges',         # Output filename prefix
    write_pdb=False,                   # Write PDB files with charges
    pdb_bfactor=True                   # Store charges in B-factor column
)

Parameters:

• charge_types (str or list): Charge scheme(s) to use

• multiwfn_path (str): Path to Multiwfn executable

• output_filename (str): Output CSV filename prefix (default: 'charges')

• write_pdb (bool): If True, write PDB files with charges in B-factor column (default: False)

• pdb_bfactor (bool): Store charges in B-factor column of PDB (default: True)

Returns: DataFrame with columns: Job, Charge_Type, Atom_Index, Element, x, y, z, Charge, Molden_Path, XYZ_Path

getElectrostatic_stabilization() - Electrostatic Stabilization

df = es.getElectrostatic_stabilization(
    multiwfn_path=None,                   # Path to Multiwfn executable
    substrate_idxs=[],                    # Substrate atom indices per structure
    charge_type='Hirshfeld_I',            # Charge scheme
    name_dataStorage='estatic',           # Output filename prefix
    env_idxs=None,                        # Environment atom indices (default: all non-substrate)
    save_atomwise_decomposition=False,    # Save per-atom contributions
    visualize=None,                       # Create PDB visualization files
    multipole_order=2,                    # 1=monopole, 2=dipole, 3=quadrupole
    substrate_multipole_order=None,       # Override multipole order for substrate
    env_multipole_order=None,             # Override multipole order for environment
    dielectric=1,                         # Dielectric constant
    dielectric_scale=1,                   # Dielectric scaling for point charges
    includePtChgs=None,                   # Override point charge setting
    ptchg_paths=None                      # Override point charge file paths
)

Parameters:

• multiwfn_path (str): Path to Multiwfn executable

• substrate_idxs (list): List of atom indices for the substrate, one list per structure

• charge_type (str): Charge scheme (default: 'Hirshfeld_I'). Must be Hirshfeld, Hirshfeld_I, or Becke for multipole_order >= 2

• name_dataStorage (str): Output filename prefix (default: 'estatic')

• env_idxs (list or None): Environment atom indices. If None, uses all non-substrate atoms

• save_atomwise_decomposition (bool): Save per-atom energy breakdown (default: False)

• visualize (bool or None): Create PDB files with stabilization data

• multipole_order (int): Multipole expansion order (default: 2):

  • 1: Monopole only (charge-charge interactions)

  • 2: Monopole + dipole (charge-charge, charge-dipole, dipole-dipole)

  • 3: Monopole + dipole + quadrupole (all terms up to quadrupole-quadrupole)

• substrate_multipole_order (int or None): Override multipole_order for the substrate only

• env_multipole_order (int or None): Override multipole_order for the environment only

• dielectric (float): Dielectric constant (default: 1)

• dielectric_scale (float): Scaling factor for point charges (default: 1)

• includePtChgs (bool or None): Include point charges as part of the environment

• ptchg_paths (list or None): Override point charge file paths

Returns: DataFrame with electrostatic stabilization energies (kcal/mol). If save_atomwise_decomposition=True, returns a tuple (total_df, atomwise_df).

Charge Schemes

Available schemes:

Charge Type	Description	Notes
Hirshfeld_I	Iterative Hirshfeld	Recommended for most systems
Hirshfeld	Standard Hirshfeld partitioning	Fast, good for most systems
RESP	Restrained ESP fitting	Standard for force field development
CHELPG	ESP fitting (Breneman)	Good for molecular mechanics
MK	Merz-Kollmann ESP fitting	Alternative ESP method
CM5	Charge Model 5	Good balance of accuracy/speed
ADCH	Atomic dipole corrected Hirshfeld	Recommended by Multiwfn
Mulliken	Mulliken population	Fast but basis-set dependent
Lowdin	Löwdin population	Orthogonalized basis
Voronoi	Voronoi deformation density	Space partitioning method
SCPA	Ros & Schuit modified Mulliken	Modified Mulliken scheme
Becke	Becke partitioning with dipole corr.	Real-space integration
EEM	Electronegativity equalization	⚠️ Requires bonded atoms (fails for ionic)
PEOE	Gasteiger charges	⚠️ Missing parameters for Na, transition metals

Multipole-capable schemes (for multipole_bool=True or use_multipole=True):

• Hirshfeld, Hirshfeld_I, Becke

Module Reference

Command-line interface (CLI) entry point

welcome()

Print first to welcome the user while it waits to load the modules

read_config(config_file)

parse_job_batch_file(file_path)

Parse a CSV file and extract specific columns as lists and tuples. The input file allows Python style comments on any line.

Parameters:

file_path (str) – The file path of the CSV file to be parsed.

Returns:

• analysis_types (list of str) – List of analysis types (‘ef’, ‘esp’, ‘estab’, or combinations like ‘ef+esp’).

• molden_paths (list of str) – List of paths to .molden files.

• xyz_paths (list of str) – List of paths to .xyz files.

• metal_indices (list of int or None) – List containing metal atom indices. None if metal indices are not provided.

• bond_indices (list of tuples or None) – List of bond tuples for each job. None if bond indices are not provided.

Notes

New format (required): - analysis_type, path_to_molden, path_to_xyz, [bond_tuples or metal_index] - Examples:

• ef, /path/to/optim.molden, /path/to/optim.xyz, (25, 26), (25, 27)

• esp, /path/to/optim.molden, /path/to/optim.xyz, 30

• estab, /path/to/optim.molden, /path/to/optim.xyz

• ef+esp, /path/to/optim.molden, /path/to/optim.xyz, 35

read_file_lines(file_path)

Reads in auxiliary files containing job information

run_analysis(job_name, molden_paths, xyz_paths, analysis_types, metal_indices, bond_indices, dielectric, geom_flag, multiwfn_path, charge_types=['Hirshfeld_I'], multipole_bool=True, use_multipole=False, save_atomwise_decomposition=False, substrate_idxs=None, env_idxs=None, multipole_order=2, include_ptchgs=False, ptchg_file='', dielectric_scale=1.0, use_ecp=False, exclude_atoms=[])

Main function for running the pyEF workflow.

Parameters:

• job_name (str) – Name for output files

• molden_paths (list of str) – List of paths to .molden files

• xyz_paths (list of str) – List of paths to .xyz files

• analysis_types (list of str) – List of analysis types per job (‘ef’, ‘esp’, ‘estab’, or combinations)

• metal_indices (list of int or None) – List of metal atom indices (only required for ESP analysis or auto-finding bonds)

• bond_indices (list of tuples) – List of bond pairs (required for E-field if metal_indices not provided)

• dielectric (float) – Dielectric constant

• geom_flag (bool) – Run geometry checks

• multiwfn_path (str) – Path to Multiwfn executable

• charge_types (list of str, optional) – Charge partitioning schemes (default: [‘Hirshfeld_I’])

• multipole_bool (bool, optional) – Use multipole expansion for E-field (default: True)

• use_multipole (bool, optional) – Use multipole expansion for ESP (default: False)

• save_atomwise_decomposition (bool, optional) – Save atom-wise decomposition to CSV (default: False)

• substrate_idxs (list or None, optional) – Substrate atom indices for estab calculation (default: None)

• env_idxs (list or None, optional) – Environment atom indices for estab calculation (default: None)

• multipole_order (int, optional) – Multipole expansion order (default: 2)

• include_ptchgs (bool, optional) – Include MM point charges from QM/MM calculations (default: False)

• ptchg_file (str, optional) – Filename of point charge file (default: ‘’) File is looked for in the same directory as each job’s molden file. Example: ‘pointcharges.txt’ will look for this file in each job directory.

• dielectric_scale (float, optional) – Dielectric scaling factor for MM charges (default: 1.0)

• use_ecp (bool, optional) – Use effective core potential (ECP) correction for molden files (default: False)

• exclude_atoms (list of int or list of lists, optional) – Atom indices to exclude from E-field calculations (default: []) Can be either: - Flat list [0, 1, 2] for same exclusions across all jobs - Nested list [[0, 1], [2, 3], []] for different exclusions per job

Multiwfn Interface Module

This module provides a clean interface to the Multiwfn external quantum chemistry analysis program for charge partitioning and multipole moment calculations.

Classes

MultiwfnInterface

Main interface class for running Multiwfn calculations

Functions

getmultipoles

Static function to parse multipole moment output files

class MoldenObject(file_path_xyz, molden_filename)

Bases: object

Helper class for parsing molden files to count basis functions.

countBasis()

Count the number of basis functions in the molden file.

class MultiwfnInterface(config=None)

Bases: object

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 = {'ADCH': '11', 'AIM': '14', 'Becke': '10', 'CHELPG': '12', 'CM5': '16', 'EEM': '17', 'Hirshfeld': '1', 'Hirshfeld_I': '15', 'Lowdin': '6', 'MK': '13', 'Mulliken': '5', 'PEOE': '19', 'RESP': '18', 'SCPA': '7', 'Voronoi': '2'}

MULTIPOLE_SCHEMES = {'Becke': ['1', '2'], 'Hirshfeld': ['3', '2'], 'Hirshfeld_I': ['4', '1', '2']}

static get_monopole_commands(charge_type)

Get the Multiwfn command sequence for a given charge type.

This is the single source of truth for all Multiwfn monopole charge calculation commands. Different charge types require different menu navigation sequences in Multiwfn.

Parameters:

charge_type (str) – The charge partitioning scheme name

Returns:

Command sequence to send to Multiwfn stdin

Return type:

list of str

Raises:

ValueError – If charge_type is ‘AIM’ (not supported in menu 7)

__init__(config=None)

Initialize the Multiwfn interface.

Parameters:

config (dict, optional) – Configuration dictionary with keys: - molden_filename: Name of molden file - xyzfilename: Name of XYZ geometry file - rerun: Whether to rerun existing calculations - hasECP: Whether calculation used ECP - maxIHirshFuzzyBasis: Max basis functions for Hirshfeld-I fuzzy - maxIHirshBasis: Max basis functions for Hirshfeld-I

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.