qstack.fields.hirshfeld

Hirshfeld partitioning and atomic charge analysis.

qstack.fields.hirshfeld.hirshfeld_charges(mol, cd, dm_atoms=None, atm_bas=None, dominant=True, occupations=False, grid_level=3)[source]

Compute atomic charges or occupations using Hirshfeld partitioning.

Partitions the molecular electron density among atoms using Hirshfeld weights based on free atom densities. Can work with either density-fitting coefficients or density matrices, and supports both standard and dominant partitioning.

Parameters:

  • mol (pyscf Mole) – pyscf Mole object.

  • cd (numpy ndarray or list) – Density representation as: - 1D array: Density-fitting coefficients - 2D array: Density matrix in AO basis - list: Multiple densities (returns list of results).

  • dm_atoms (dict, optional) – Pre-computed atomic density matrices from spherical_atoms. If None, computed automatically. Defaults to None.

  • atm_bas (str or dict, optional) – Basis set for atomic density matrices. If None, uses mol.basis. Defaults to None.

  • dominant (bool) – If True, uses dominant (all-or-nothing) partitioning; if False, uses standard Hirshfeld weights. Defaults to True.

  • occupations (bool) – If True, returns atomic electron populations; if False, returns atomic charges (Z - N). Defaults to False.

  • grid_level (int) – DFT grid level for numerical integration. Defaults to 3.

Returns:

Atomic charges or occupations. - Single 1D array if cd is a single density. - List of 1D arrays if cd is a list of densities.

Return type:

numpy ndarray or list

qstack.fields.hirshfeld.spherical_atoms(elements, atm_bas)[source]

Compute density matrices for spherically averaged isolated atoms.

For each element, creates an isolated atom calculation with appropriate spin and computes its density matrix using atomic Hartree-Fock initial guess.

Parameters:

  • elements (list of str or set) – Element symbols to compute density matrices for.

  • atm_bas (str or dict) – Basis set name (e.g., ‘def2-svp’) or pyscf basis dictionary.

Returns:

Dictionary mapping element symbols (str) to atomic density matrices (numpy 2D ndarrays).

Return type:

dict