{"id":8518,"library":"pyscf","title":"PySCF: Python-based Simulations of Chemistry Framework","description":"PySCF is an open-source, Python-based framework for *ab initio* quantum chemistry simulations. It offers a comprehensive suite of electronic structure methods, including Hartree-Fock, Density Functional Theory (DFT), MP2, Coupled Cluster, and various multi-reference methods, for both molecular and periodic systems. The library is actively developed, with version 2.12.1 being the current stable release, and minor versions released roughly every 3-4 months, indicating a robust and ongoing development cycle.","status":"active","version":"2.12.1","language":"en","source_language":"en","source_url":"https://github.com/pyscf/pyscf","tags":["chemistry","quantum chemistry","computational chemistry","materials science","simulation","physics","electronic structure"],"install":[{"cmd":"pip install pyscf","lang":"bash","label":"Stable release"},{"cmd":"pip install pyscf[all]","lang":"bash","label":"Install with all extensions (e.g., dispersion, dmrgscf)"}],"dependencies":[{"reason":"Core numerical operations and array manipulation.","package":"numpy","optional":false},{"reason":"Advanced scientific computing and linear algebra routines.","package":"scipy","optional":false},{"reason":"Efficient handling and storage of large datasets, often used for checkpointing and temporary files.","package":"h5py","optional":false},{"reason":"DMRG solver extension. Required for PySCF's `dmrgscf` module.","package":"block2","optional":true},{"reason":"GPU acceleration for certain PySCF functionalities.","package":"gpu4pyscf","optional":true}],"imports":[{"note":"Commonly imported module for Gaussian Type Orbitals, used to define molecular systems.","symbol":"gto","correct":"from pyscf import gto"},{"note":"Module for Self-Consistent Field methods like Hartree-Fock and DFT.","symbol":"scf","correct":"from pyscf import scf"},{"note":"Module for Coupled Cluster methods.","symbol":"cc","correct":"from pyscf import cc"},{"note":"While `pyscf.Mole().build()` works, `gto.M()` or `pyscf.M()` is a more concise and common shortcut for initializing a molecule.","wrong":"mol = pyscf.Mole(atom='...').build()","symbol":"M","correct":"mol = gto.M(atom='O 0 0 0; H 0 1 0; H 0 0 1', basis='ccpvdz')"}],"quickstart":{"code":"from pyscf import gto, scf\n\n# Define a molecule (e.g., Water)\nmol = gto.M(\n    atom = 'O 0 0 0; H 0 0.757 0.587; H 0 -0.757 0.587',\n    basis = 'sto-3g')\n\n# Perform a Restricted Hartree-Fock (RHF) calculation\nmf = scf.RHF(mol).run()\n\n# Print the RHF energy\nprint(f'RHF Energy: {mf.e_tot} Hartree')","lang":"python","description":"This quickstart defines a water molecule using the `gto` module and then performs a Restricted Hartree-Fock (RHF) calculation using the `scf` module. It demonstrates the basic workflow of defining a system and running a mean-field calculation, printing the total energy."},"warnings":[{"fix":"Upgrade PySCF to version 2.12.1 or newer. If issues persist, reinstall PySCF in an environment with your target NumPy version already installed (`pip install --no-cache-dir --force-reinstall pyscf`).","message":"PySCF versions prior to 2.6.1 and 2.12.1 may have compatibility issues with NumPy 2.x due to significant API, ABI, and type promotion changes in NumPy 2.0. This can lead to `ImportError` or unexpected numerical behavior.","severity":"breaking","affected_versions":"<2.6.1, <2.12.1"},{"fix":"Always call `mol.build()` after directly changing any attributes of a `gto.Mole` or `gto.Cell` instance. The `gto.M()` shortcut implicitly calls `build()`.","message":"When modifying attributes of a `gto.Mole` object (e.g., `mol.atom`, `mol.basis`, `mol.charge`) after its initial creation, you must call `mol.build()` again for the changes to be applied and internal data structures to be refreshed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Apply linear dependency removal using `mf.apply(scf.addons.remove_linear_dep_)` or enable partial Cholesky orthonormalization. For example: `mf = scf.RHF(mol).apply(scf.addons.remove_linear_dep_).run()`","message":"In SCF calculations, particularly with large or diffuse basis sets, linear dependencies in the atomic orbital basis can cause convergence issues or failures with the default generalized eigenvalue solver (SciPy's `eigh`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully review the documentation for specific post-SCF methods when using smearing. If possible, avoid smearing for molecular systems or when subsequent methods explicitly require integer occupations.","message":"Many PySCF functions, especially post-SCF methods, assume integer occupations. Combining them with mean-field calculations that utilize smearing (e.g., Fermi-Dirac smearing for metals) may lead to unexpected results or errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use a larger basis set (e.g., a double-zeta or triple-zeta quality basis set like 6-31g, def2-svp, or cc-pvdz). Minimal basis sets are generally not suitable for correlated methods as they lack the flexibility to describe electron correlation.","cause":"This error often occurs in post-Hartree-Fock calculations (e.g., CCSD(T)) when using minimal basis sets (e.g., STO-3G) where the number of virtual orbitals (specifically alpha virtual orbitals) becomes zero, leading to an attempted division by zero in certain energy expressions.","error":"ZeroDivisionError: division by zero"},{"fix":"Ensure that PySCF and NumPy are compatible. The most robust solution is to create a new Python environment, install NumPy first (preferably the latest compatible version), and then install PySCF: `conda create -n pyscf_env python=3.x numpy scipy h5py` then `conda activate pyscf_env` then `pip install pyscf`.","cause":"This typically indicates a binary incompatibility (ABI break) between the installed PySCF package (or its compiled C extensions) and the installed NumPy version. NumPy 2.0 introduced significant ABI changes.","error":"ImportError: numpy.core.multiarray failed to import"},{"fix":"Consult the PySCF documentation or GitHub issues for known workarounds or specific auxiliary basis set recommendations for your system. If possible, try disabling density fitting for that particular step or exploring alternative implementations if available within PySCF for your specific calculation type.","cause":"While density fitting (DF) generally speeds up calculations, specific combinations of methods and systems can sometimes lead to suboptimal performance, or even slower execution, particularly for certain linear response methods like TDA (Time-Dependent Adiabatic approximation) with DF.","error":"[UNEXPECTED BEHAVIOR] Density fitted TDA is extremely slow."}]}