PySCF GPU Interface API#

GPU-accelerated PySCF interface for quantum chemistry calculations.

Main Functions#

mmml.pyscf4gpuInterface.calcs.compute_dft(args, calcs, extra=None)#

Compute DFT properties using GPU4PySCF.

Parameters:

  • args – Parsed command line arguments or dummy args object

  • calcs – List of calculation types to perform

  • extra – Extra arguments for specific calculations

Returns:

Dictionary containing calculation results

mmml.pyscf4gpuInterface.calcs.setup_mol(atoms, basis, xc, spin, charge, log_file='./pyscf.log', verbose=6, lebedev_grids=(99, 590), scf_tol=1e-10, scf_max_cycle=50, cpscf_tol=1e-3, conv_tol=1e-10, conv_tol_cpscf=1e-3)#

Set up molecular system and GPU4PySCF engine.

Parameters:

  • atoms – Molecular geometry (string or PySCF mol object)

  • basis – Basis set name

  • xc – Exchange-correlation functional

  • spin – Spin multiplicity

  • charge – Total charge

  • log_file – Log file path

  • verbose – Verbosity level

  • lebedev_grids – Grid settings (nrad, nleb)

  • scf_tol – SCF convergence tolerance

  • scf_max_cycle – Maximum SCF iterations

  • cpscf_tol – CPSCF convergence tolerance

  • conv_tol – General convergence tolerance

  • conv_tol_cpscf – CPSCF convergence tolerance

Returns:

Tuple of (engine, mol)

Saving Results#

Use mmml.pyscf4gpuInterface.calcs.save_output() to persist dictionaries of results (produced by compute_dft()) that contain primarily numpy/cupy arrays.

mmml.pyscf4gpuInterface.calcs.save_output(output_path, data, save_option='pkl')#

Save a dictionary to disk with one of the supported formats.

Parameters:

  • output_path – Output file path

  • data – Dictionary of results (np/cupy arrays preferred)

  • save_option – One of 'pkl', 'npz', or 'hdf5'

  • pkl: Pickle entire dict. Best for arbitrary Python objects.

  • npz: Save only array-like entries as separate arrays (compressed).

  • hdf5: Save only array-like entries as datasets (good for large data/partial IO).

Parquet/Feather are intentionally not supported here because they are columnar, tabular formats and not suitable for heterogeneous dicts of arrays.

Examples#

# Pickle (full dict)
python -m mmml.pyscf4gpuInterface.calcs \
  --mol "O 0.000 0.000 0.000; H 0.000 0.757 0.586; H 0.000 -0.757 0.586" \
  --energy --output results/out.pkl --save_option pkl

# Compressed array bundle
python -m mmml.pyscf4gpuInterface.calcs \
  --mol "O 0.000 0.000 0.000; H 0.000 0.757 0.586; H 0.000 -0.757 0.586" \
  --energy --dens_esp --output results/out.npz --save_option npz

# HDF5 datasets
python -m mmml.pyscf4gpuInterface.calcs \
  --mol "O 0.000 0.000 0.000; H 0.000 0.757 0.586; H 0.000 -0.757 0.586" \
  --energy --output results/out.h5 --save_option hdf5

Calculation Types#

Available calculation types (from mmml.pyscf4gpuInterface.enums.CALCS):

  • ENERGY: Compute total energy

  • OPTIMIZE: Geometry optimization

  • GRADIENT: Nuclear gradients

  • HESSIAN: Second derivatives

  • HARMONIC: Harmonic vibrational analysis

  • THERMO: Thermodynamic properties

  • DENS_ESP: Density and ESP on grid

  • IR: Infrared frequencies and intensities

  • SHIELDING: NMR shielding tensors

  • POLARIZABILITY: Polarizability tensor

  • INTERACTION: Interaction energies

Command Line Interface#

python -m mmml.pyscf4gpuInterface.calcs \
  --mol "O 0.000 0.000 0.000; H 0.000 0.757 0.586; H 0.000 -0.757 0.586" \
  --basis def2-tzvp \
  --xc wB97m-v \
  --spin 0 \
  --charge 0 \
  --energy \
  --dens_esp \
  --save_option npz \
  --output results/out.npz

Output Format#

The compute_dft function returns a dictionary containing:

  • mol: PySCF molecular object

  • calcs: List of performed calculations

  • energy: Total energy (if ENERGY in calcs)

  • esp: ESP values on grid (if DENS_ESP in calcs)

  • esp_grid: Grid coordinates (if DENS_ESP in calcs)

  • R: Nuclear coordinates in Angstrom

  • Z: Nuclear charges

  • gradient: Nuclear gradients (if GRADIENT in calcs)

  • hessian: Hessian matrix (if HESSIAN in calcs)

  • freq: Vibrational frequencies (if HARMONIC in calcs)

  • thermo: Thermodynamic properties (if THERMO in calcs)

Prerequisites#

  • CUDA-compatible GPU

  • gpu4pyscf package

  • PySCF

  • Optional: ASE for geometry optimization