PyFock
An efficient and fully parallelized pure python DFT and electronic structure code with GPU acceleration
Install / Use
/learn @manassharma07/PyFockREADME
PyFock
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]
[![Documentation][docs-shield]][documentation-url]
About The Project
![PyFock Screenshot][product-screenshot]
PyFock is a pure Python quantum chemistry package that enables efficient Kohn-Sham density functional theory (DFT) calculations for molecular systems. Unlike traditional quantum chemistry codes written in Fortran or C/C++, PyFock is written entirely in Python—including all performance-critical molecular integral evaluations—while achieving computational efficiency comparable to established codes like PySCF and Psi4.
What Makes PyFock Different?
- 100% Pure Python: All code, including computationally intensive molecular integrals, is written in Python
- High Performance: Achieves efficiency comparable to C/C++ backends through Numba JIT compilation, NumPy, NumExpr, SciPy, and CuPy
- GPU Acceleration: Leverages CUDA via Numba and CuPy for up to 14× speedup on large systems
- Easy Installation: Simple
pip installon all major operating systems (Linux, macOS, Windows) - Accessible: Designed for education, prototyping, and community development
- Near-Quadratic Scaling: ~O(N²·⁰⁵) scaling through density fitting with Cauchy-Schwarz screening
- Gaussian-Type Orbitals: Employs GTOs as basis functions for molecular calculations
- Efficient Parallelization: Multi-core CPU support and multi-GPU acceleration capabilities
Performance Highlights
- Numerical accuracy: Consistent with PySCF (< 10⁻⁷ Ha)
- Parallel efficiency: Comparable to state-of-the-art C++ backends on multicore CPUs
- GPU speedup: Up to 14× faster than 4-core CPU execution for large systems
- Scaling: Near-quadratic ~O(N²·⁰⁵) for electron repulsion integrals (Coulomb term)
- XC evaluation: Sub-quadratic scaling ~O(N¹·²⁵⁻¹·⁵) for exchange-correlation contributions
Key Features
- ✅ Pure Python Implementation: Including molecular integral evaluations (overlap, kinetic, nuclear attraction, electron repulsion integrals)
- ✅ Density Fitting: Efficient density fitting approximation with Cauchy-Schwarz screening
- ✅ GPU Acceleration: Full GPU support for integral evaluation, XC term, and matrix operations
- ✅ Multiple Integration Schemes:
- Classical Taketa-Huzinaga-O-ohata scheme
- Rys quadrature method (roots 1–10) for efficient ERI evaluation
- ✅ XC Functionals: Support for LDA and GGA functionals via LibXC integration
- ✅ DIIS Convergence: Direct inversion of iterative subspace for SCF acceleration
- ✅ Parallel Execution: Multi-core CPU and multi-GPU support via Numba and Joblib
- ✅ Modular Design: Standalone integral modules for benchmarking and embedding
- ✅ Web-based GUI: Interactive interface for visualization and input generation
- ✅ Cartesian and Spherical Basis: Support for both CAO and SAO representations
- ✅ Cross-Platform: Works on Linux, macOS, and Windows
Installation
Basic Installation
PyFock can be easily installed via pip:
pip install pyfock
Installing from GitHub (Latest Development Version)
To get the latest development version directly from GitHub:
pip install git+https://github.com/manassharma07/pyfock.git
Or clone the repository and install locally:
git clone https://github.com/manassharma07/pyfock.git
cd pyfock
pip install -e .
Installing LibXC (Required Dependency)
PyFock requires LibXC for exchange-correlation functionals. The installation method depends on your system:
Using Conda (Recommended - Easiest Method)
conda install -c conda-forge pylibxc -y
On Ubuntu/Debian
sudo apt-get install libxc-dev
pip install pylibxc2
On macOS
brew install libxc
pip install pylibxc2
Note: The conda method is recommended as it works reliably across all platforms.
Optional Dependencies
For GPU acceleration:
pip install cupy-cuda11x # Replace 11x with your CUDA version
Quick Start
Here's a minimal example to get you started with PyFock:
from pyfock import Basis, Mol, DFT
# Define molecule from XYZ file
mol = Mol(coordfile='h2o.xyz')
# Set up basis sets
basis = Basis(mol, {'all': Basis.load(mol=mol, basis_name='def2-SVP')})
auxbasis = Basis(mol, {'all': Basis.load(mol=mol, basis_name='def2-universal-jfit')})
# Configure DFT calculation (PBE functional)
funcx = 101 # PBE exchange (LibXC code)
funcc = 130 # PBE correlation (LibXC code)
dftObj = DFT(mol, basis, auxbasis, xc=[funcx, funcc])
# Set calculation parameters
dftObj.conv_crit = 1e-7
dftObj.max_itr = 20
dftObj.ncores = 4
# Run SCF calculation
energy, dmat = dftObj.scf()
print(f"Total Energy: {energy} Ha")
Usage
Computing Molecular Integrals
PyFock provides standalone access to all molecular integrals:
from pyfock import Integrals, Basis, Mol
mol = Mol(coordfile='h2o.xyz')
basis = Basis(mol, {'all': Basis.load(mol=mol, basis_name='def2-SVP')})
# One-electron integrals
S_ovlp = Integrals.overlap_mat_symm(basis)
V_kin = Integrals.kin_mat_symm(basis)
V_nuc = Integrals.nuc_mat_symm(basis, mol)
# Two-electron integrals (classical scheme)
ERI_slow = Integrals.conv_4c2e_symm(basis)
# Two-electron integrals (Rys quadrature - faster)
ERI_fast = Integrals.rys_4c2e_symm(basis)
# Three-center integrals for density fitting
ERI_3c2e = Integrals.rys_3c2e_symm(basis)
# Two-center integrals
ERI_2c2e = Integrals.rys_2c2e_symm(basis)
GPU-Accelerated Integrals
# GPU versions (returns CuPy arrays in device memory)
S_ovlp_gpu = Integrals.overlap_mat_symm_cupy(basis)
V_kin_gpu = Integrals.kin_mat_symm_cupy(basis)
V_nuc_gpu = Integrals.nuc_mat_symm_cupy(basis, mol)
ERI_3c2e_gpu = Integrals.rys_3c2e_symm_cupy(basis)
Converting Between Cartesian and Spherical Basis
# Convert from Cartesian to Spherical atomic orbitals
V_kin_CAO = Integrals.kin_mat_symm(basis)
c2sph_mat = basis.cart2sph_basis()
V_kin_SAO = np.dot(c2sph_mat, np.dot(V_kin_CAO, c2sph_mat.T))
Subset Evaluation
# Evaluate integrals for a subset of basis functions
S_ovlp_subset = Integrals.overlap_mat_symm(basis, slice=[0, 5, 0, 5])
# slice = [row_start, row_end, col_start, col_end]
Full DFT Calculation Example
from pyfock import Basis, Mol, DFT
# Initialize molecule
xyzFilename = 'benzene.xyz'
mol = Mol(coordfile=xyzFilename)
# Set up basis sets
basis_set_name = 'def2-SVP'
auxbasis_name = 'def2-universal-jfit'
basis = Basis(mol, {'all': Basis.load(mol=mol, basis_name=basis_set_name)})
auxbasis = Basis(mol, {'all': Basis.load(mol=mol, basis_name=auxbasis_name)})
# Configure XC functional (PBE)
funcx = 101 # Exchange
funcc = 130 # Correlation
funcidcrysx = [funcx, funcc]
# Initialize DFT object
dftObj = DFT(mol, basis, auxbasis, xc=funcidcrysx)
# Configure convergence and parallelization
dftObj.conv_crit = 1e-7
dftObj.max_itr = 20
dftObj.ncores = 4
# Run calculation
energyCrysX, dmat = dftObj.scf()
print(f"SCF Energy: {energyCrysX} Ha")
Generating Visualization Files
from pyfock import Utils
# Generate cube files for molecular orbitals and density
Utils.write_density_cube(dftObj, filename='benzene_density.cube')
Graphical User Interface
PyFock includes a web-based GUI for interactive calculations and visualization:
🌐 Try it online: https://pyfock-gui.bragitoff.com
GUI Features
- Interactive 3D Visualization: View molecules and molecular orbitals using Py3Dmol
- Easy Configuration: Select basis sets, functionals, and calculation parameters
- Automatic Cube File Generation: HOMO, LUMO, and density visualizations
- Input Script Generator: Export Python code for local execution
- PySCF Validation: Built-in comparison with PySCF for accuracy verification
- Molecule Library: Pre-loaded common molecules or custom XYZ input
Running GUI Locally
The GUI source code is available on GitHub and can be run locally:
`
