An overview of PySCF

Python-based simulations of chemistry framework (PYSCF) is a general-purpose electronic structure platform designed from the ground up to emphasize code simplicity, so as to facilitate new method development and enable flexible computational workflows. The package provides a wide range of tools to support simulations of finite-size systems, extended systems with periodic boundary conditions, low-dimensional periodic systems, and custom Hamiltonians, using mean-field and post-mean-field methods with standard Gaussian basis functions. To ensure ease of extensibility, PYSCF uses the Python language to implement almost all of its features, while computationally critical paths are implemented with heavily optimized C routines. Using this combined Python/C implementation, the package is as efficient as the best existing C or Fortran- based quantum chemistry programs.


  • Hartree-Fock (up to ~5000 basis)
    • Non-relativistic restricted open-shell, unrestricted HF
    • Scalar relativistic HF
    • 2-component relativistic HF
    • 4-component relativistic Dirac-Hartree-Fock
    • Density fitting HF
    • Second order SCF
    • General JK contraction function
    • DIIS, EDIIS, ADIIS and second order solver
    • SCF wavefunction stability analysis
    • Generalized Hartree-Fock (GHF)
  • DFT (up to ~5000 basis)
    • Non-relativistic restricted, restricted open-shell, unrestricted Kohn-Sham
    • Scalar relativistic DFT
    • Density fitting DFT
    • General XC functional evaluator (for Libxc or XcFun)
    • General AO evaluator
    • TDHF (and density-fitting TDHF)
    • TDDFT (and density-fitting TDDFT)
    • TDHF gradients
    • TDDFT gradients
  • General CASCI/CASSCF solver (up to ~3000 basis)
    • State-average CASCI/CASSCF
    • State-specific CASCI/CASSCF for excited states
    • Multiple roots CASCI
    • Support DMRG as plugin CI solver to do DMRG-CASSCF
    • Support FCIQMC as plugin CI solver to do FCIQMC-CASSCF
    • UHF-based UCASSCF
    • Density-fitting CASSCF
    • DMET-CAS and AVAS active space constructor
  • MP2 (up to ~200 occupied, ~2000 virtual orbitals)
    • Canonical MP2
    • Density-fitting MP2
    • MP2-F12
  • CCSD (up to ~100 occupied, ~1500 virtual orbitals)
    • canonical RCCSD, UCCSD
    • canonical RCCSD, UCCSD lambda solver
    • RCCSD and UCCSD 1-particle and 2-particle density matrices
    • CCSD gradients
    • RCC2
    • Density-fitting CCSD
  • CCSD(T)
    • Canonical RCCSD(T) and UCCSD(T)
    • Canonical RCCSD(T) 1- and 2-particle density matrices
    • Canonical RCCSD(T) gradients
  • CI
    • RCISD and UCISD
    • RCISD and UCISD 1, 2-particle density matrices
    • Selected-CI
    • Selected-CI 1, 2-particle density matrices
  • Full CI
    • Direct-CI solver for spin degenerated Hamiltonian
    • Direct-CI solver for spin non-degenerated Hamiltonian
    • 1, and 2-particle transition density matrices
    • 1, 2, 3, and 4-particle density matrices
    • CI wavefunction overlap
  • Gradients
    • Non-relativistic RHF gradients
    • 4-component DHF gradients
    • Non-relativistic DFT gradients
    • Non-relativistic CCSD gradients
    • Non-relativistic TDHF and TDDFT gradients
  • Hessian
    • Non-relativistic RHF hessian
    • Non-relativistic RKS hessian
  • Properties
    • Non-relativistic RHF, UHF, RKS, UKS NMR shielding
    • 4-component DHF NMR shielding
    • Non-relativistic RHF, UHF spin-spin coupling
    • 4-component DHF spin-spin coupling
    • Non-relativistic UHF, UKS hyperfine coupling
    • 4-component DHF hyperfine coupling
    • Non-relativistic UHF, UKS g-tensor
    • 4-component DHF g-tensor
    • Non-relativistic UHF zero-field splitting
    • Molecular electrostatic potential (MEP)
  • MRPT
    • Strongly contracted NEVPT2
    • IC-MPS-PT2
  • Extended systems with periodic boundary condition
    • gamma point RHF, UHF, RKS, UKS
    • gamma point TDDFT, MP2, CCSD
    • PBC RHF, UHF, RKS, UKS with k-point sampling
    • PBC RCCSD and UCCSD with k-point sampling
    • PBC k-point EOM-IP/EA-CCSD
    • PBC AO integrals
    • PBC MO integral transformation
    • PBC density fitting
    • Smearing for mean-field calculation
    • Low-dimensional (0D, 1D, 2D) PBC systems
    • TDHF and TDDFT with k-point sampling
  • AO integrals
    • Interface to call Libcint library
    • 1-electron real-GTO and spinor-GTO integrals
    • 2-electron real-GTO and spinor-GTO integrals
    • 3-center 1-electron real-GTO and spinor-GTO integrals
    • 3-center 2-electron real-GTO and spinor-GTO integrals
    • General basis value evaluator (for numeric integration)
    • PBC 1-electron integrals
    • PBC 2-electron integrals
    • F12 integrals
  • MO integrals
    • 2-electron integral transformation for any integrals provided by Libcint library
    • Support for 4-index integral transformation with 4 different orbitals
    • PBC 2-electron MO integrals
  • Localizer
    • Boys
    • Edmiston
    • Meta-Lowdin
    • Natural atomic orbital (NAO)
    • Intrinsic atomic orbital (IAO)
    • Pipek-Mezey
  • Geometry optimization
    • RHF, RKS, RCCSD with pyberny geometry optimizer
  • D2h symmetry and linear molecule symmetry
    • Molecule symmetry detection
    • Symmetry adapted basis
    • Label orbital symmetry on the fly
    • Hot update symmetry information
    • Function to symmetrize given orbital space
  • Tools
    • fcidump
    • molden
    • cubegen
    • Molpro XML reader
  • Interface to integral package Libcint
  • Interface to DMRG CheMPS2
  • Interface to DMRG Block
  • Interface to FCIQMC NECI
  • Interface to XC functional library XCFun
  • Interface to XC functional library Libxc

PySCF Python-based simulations of chemistry framework

How to use

There are two ways to access the documentation: the docstrings come with the code, and an online program reference, available from

We recommend the enhanced Python interpreter IPython and the web-based Python IDE Ipython notebook to try out the package:

>>> from pyscf import gto, scf
>>> mol = gto.M(atom='H 0 0 0; H 0 0 1.2', basis='cc-pvdz')
>>> mol.apply(scf.RHF).run()
converged SCF energy = -1.06111199785749

Pure function and Class

Class are designed to hold only the final results and the control parameters such as maximum number of iterations, convergence threshold, etc. The intermediate status are not saved in the class. If the .kernel() function is finished without any errors, the solution will be saved in the class (see documentation).

Most useful functions are implemented at module level, and can be accessed in both class and module, e.g. scf.hf.get_jk(mol, dm) and SCF(mol).get_jk(mol, dm) have the same functionality. As a result, most functions and class are pure, i.e. no status are saved, and the argument are not changed inplace. Exceptions (destructive functions and methods) are suffixed with underscore in the function name, eg mcscf.state_average_(mc) changes the attribute of its argument mc

Stream functions

For most methods, there are three stream functions to pipe computing stream:

1 .set function to update object attributes, eg mf = scf.RHF(mol).set(conv_tol=1e-5) is identical to proceed in two steps mf = scf.RHF(mol); mf.conv_tol=1e-5

2 .run function to execute the kernel function (the function arguments are passed to kernel function). If keyword arguments is given, it will first call .set function to update object attributes then execute the kernel function. Eg mf = scf.RHF(mol).run(dm_init, conv_tol=1e-5) is identical to three steps mf = scf.RHF(mol); mf.conv_tol=1e-5; mf.kernel(dm_init)

3 .apply function to apply the given function/class to the current object (function arguments and keyword arguments are passed to the given function). Eg mol.apply(scf.RHF).run().apply(mcscf.CASSCF, 6, 4, frozen=4) is identical to mf = scf.RHF(mol); mf.kernel(); mcscf.CASSCF(mf, 6, 4, frozen=4)