Skip to content

README.md

Latest commit

 

History

History
133 lines (93 loc) · 4.6 KB

README.md

File metadata and controls

133 lines (93 loc) · 4.6 KB
Raw

PyXDM

CI License: GPL v3

PyXDM Logo

PyXDM is a Python package for calculating XDM (Exchange-hole Dipole Moment) moments using atoms-in-molecules (AIM) partitioning schemes.

Features

  • XDM multipole moments: dipole, quadrupole, octupole.
  • AIM schemes: Becke, Hirshfeld, Hirshfeld-I, Iterative Stockholder, MBIS.

Installation

Create a conda environment with all the required dependencies:

conda env create -f environment.yaml
conda activate pyxdm

Install pyxdm in interactive mode within the activated environment:

pip install -e .

For developers:

pip install -e .[dev]
# Or install development dependencies separately:
pip install -r dev/requirements-dev.txt

Usage

Command Line Interface

After installation, use the pyxdm command:

pyxdm <wfn_file> [optional]

Arguments

Positional
  • <wfn_file>: Path to the wavefunction file (Molden, WFN, etc.)
Optional
  • --mesh <file>: Integration mesh read from a file instead of a HORTON grid (see Mesh and weight files)
  • --weights <file>: Atomic weights on the --mesh points read from a file, used as the external partitioning scheme (see Mesh and weight files)
  • --scheme <schemes>: Partitioning scheme(s) to use, separated by comma. If not specified, all available schemes are calculated. Available schemes: becke, hirshfeld, hirshfeld_i, is, mbis
  • --proatomdb <path>: Path to proatom database file (required for Hirshfeld schemes)
  • --grid <quality>: Grid quality for numerical integration. Options: coarse, medium, fine, veryfine, ultrafine, insane (default: fine)
  • --xdm-moments <orders>: Order(s) of multipole moments to calculate (default: 1 2 3)
  • --radial-moments <orders>: Order(s) of radial moments to calculate (default: none)
  • --aniso: Calculate anisotropic multipole moments (default: False)
  • --output <file>, -o <file>: Output HDF5 file to save calculated data (default: <input_basename>.h5)

Examples

Basic usage with MBIS scheme:

pyxdm orca.molden.input --scheme mbis

Calculate multiple schemes with custom grid granularity:

pyxdm orca.molden.input --scheme mbis,becke --grid ultrafine

Mesh and weight files

--mesh and --weights are plain text files; lines starting with # are ignored.

  • Mesh: one integration point per line, x y z w, with the Cartesian coordinates in bohr and the integration weight, so that sum_i w_i f(r_i) approximates the integral of f over all space.
  • Weights: one line per mesh point, in the same order as the mesh, and one column per atom, in the order of the wavefunction file. Each column holds the weight of that atom at each point; at every point the weights of all atoms usually sum to 1.
pyxdm molecule.molden.input --mesh mesh.txt --weights weights.txt

Python API

You can also use PyXDM as a library in your own Python scripts:

from pyxdm.core import XDMSession

session = XDMSession('examples/water/orca.molden.input')
session.load_molecule()
session.setup_grid()
session.setup_calculator()
session.setup_partition_schemes(['mbis'])
xdm_results = session.calculator.calculate_xdm_moments(
    partition_obj=session.partitions['mbis'],
    grid=session.grid,
    order=[1, 2, 3],
    anisotropic=False,
)

Troubleshooting

ImportError when importing HORTON (libint2 not found)

On some systems, HORTON is compiled against a versioned libint2 (e.g. libint2.so.2 on Linux, libint2.2.dylib on macOS), but conda-forge only installs the unversioned library. If you see an error like:

ImportError: libint2.so.2: cannot open shared object file: No such file or directory

Create the missing symlink manually:

# Linux
ln -sf "$CONDA_PREFIX/lib/libint2.so" "$CONDA_PREFIX/lib/libint2.so.2"

# macOS
ln -sf "$CONDA_PREFIX/lib/libint2.dylib" "$CONDA_PREFIX/lib/libint2.2.dylib"

Acknowledgments

Some implementations in this package, such as the Newton-Raphson algorithm for the Becke-Roussel (BR) exchange model, are based on postg. As a state-of-the-art package for XDM calculations, postg serves as an essential reference for accuracy and methodology. The aim of this package is mainly to provide easy-to-use access to a broader range of partitioning schemes beyond Hirshfeld.