tessl/pypi-pyscf

Python-based quantum chemistry framework providing electronic structure methods for molecular simulations

—

Pending

Overview

Eval results

Files

SCF Methods

Name: tessl/pypi-pyscf
Author: tessl

Self-consistent field methods including Hartree-Fock and density functional theory that form the foundation for quantum chemistry calculations, with support for restricted, unrestricted, and relativistic variants.

Capabilities

Hartree-Fock Methods

Core self-consistent field methods for solving the electronic Schrödinger equation at the mean-field level.

class RHF:
    """
    Restricted Hartree-Fock for closed-shell systems.
    
    Attributes:
    - mol: Mole object
    - conv_tol: float, convergence tolerance (default: 1e-10)
    - max_cycle: int, maximum SCF iterations (default: 50)
    - init_guess: str, initial guess method ('minao', 'atom', '1e', 'chkfile')
    - mo_coeff: ndarray, molecular orbital coefficients
    - mo_energy: ndarray, orbital energies
    - mo_occ: ndarray, orbital occupations
    """
    
    def __init__(self, mol):
        """Initialize RHF object."""
    
    def run(self, dm0=None):
        """Run SCF calculation and return self."""
    
    def kernel(self, dm0=None):
        """SCF kernel returning converged energy."""

class UHF:
    """
    Unrestricted Hartree-Fock for open-shell systems.
    
    Allows different spatial orbitals for alpha and beta electrons.
    """

class ROHF:
    """
    Restricted open-shell Hartree-Fock.
    
    Constrains paired electrons to same spatial orbitals while allowing
    unpaired electrons in singly occupied orbitals.
    """

class GHF:
    """
    Generalized Hartree-Fock with complex orbitals.
    
    Most general HF method allowing complex orbital coefficients
    and spin-unrestricted alpha/beta mixing.
    """

def HF(mol, *args):
    """
    Generic HF method selector based on molecule properties.
    
    Automatically selects RHF for closed-shell, UHF for open-shell systems.
    """

Density Functional Theory

Kohn-Sham density functional theory methods with extensive exchange-correlation functional support.

class RKS:
    """
    Restricted Kohn-Sham DFT for closed-shell systems.
    
    Attributes:
    - xc: str, exchange-correlation functional ('lda', 'pbe', 'b3lyp', etc.)
    - grids: Grids object for numerical integration
    - nlc: str, non-local correlation functional
    - omega: float, range-separation parameter for RSH functionals
    """
    
    def __init__(self, mol, xc='lda'):
        """Initialize RKS object with XC functional."""

class UKS:
    """Unrestricted Kohn-Sham DFT for open-shell systems."""

class ROKS:
    """Restricted open-shell Kohn-Sham DFT."""

class GKS:
    """Generalized Kohn-Sham with complex orbitals."""

def KS(mol, *args):
    """Generic KS method selector based on molecule properties."""

Relativistic Methods

Relativistic enhancements for heavy elements including scalar and spin-orbit coupling effects.

class DHF:
    """
    Dirac-Hartree-Fock for fully relativistic calculations.
    
    Includes both scalar relativistic and spin-orbit coupling effects
    using 4-component spinor basis.
    """

class X2C:
    """
    Exact two-component relativistic method.
    
    Provides scalar relativistic effects with 2-component efficiency
    by exact decoupling of positive/negative energy states.
    """

def sfx2c1e(mf):
    """
    Spin-free X2C with 1-electron X-matrix approximation.
    
    Efficient approximation including scalar relativistic effects
    in the 1-electron integrals only.
    """

SCF Enhancement Methods

Techniques for improving SCF convergence, stability, and computational efficiency.

def density_fit(mf, auxbasis=None, with_df=None, only_dfj=False):
    """
    Add density fitting (RI) acceleration to SCF method.
    
    Parameters:
    - mf: SCF object to enhance
    - auxbasis: str, auxiliary basis set name
    - with_df: DF object for custom density fitting
    - only_dfj: bool, fit only Coulomb integrals (default: False)
    
    Returns:
    density-fitted SCF object
    """

def newton(mf):
    """
    Second-order Newton-Raphson SCF acceleration.
    
    Uses exact Hessian for quadratic convergence near minimum.
    Significantly faster convergence for well-behaved systems.
    """

def fast_newton(mf):
    """
    Fast Newton-Raphson with approximate Hessian.
    
    Uses approximate Hessian construction for improved efficiency
    while maintaining enhanced convergence properties.
    """

DIIS Convergence Acceleration

Direct inversion in iterative subspace methods for SCF convergence acceleration.

class DIIS:
    """
    Direct Inversion in Iterative Subspace extrapolation.
    
    Standard DIIS using Fock matrix commutators as error vectors.
    """

class CDIIS:
    """
    Commutator DIIS for SCF acceleration.
    
    Uses [F,DS] commutators as error metric for extrapolation.
    Most common DIIS variant for SCF calculations.
    """

class EDIIS:
    """
    Energy DIIS for difficult SCF cases.
    
    Uses energy changes rather than commutators as error metric.
    Useful for cases where standard DIIS fails.
    """

class ADIIS:
    """
    Augmented DIIS combining DIIS and EDIIS.
    
    Adaptively switches between DIIS and EDIIS based on
    convergence behavior for robust SCF convergence.
    """

Utility Functions

Helper functions for SCF calculations, analysis, and data management.

def get_init_guess(mol, key='minao'):
    """
    Generate initial guess for SCF orbitals.
    
    Parameters:
    - mol: Mole object
    - key: str, guess method ('minao', 'atom', '1e', 'huckel')
    
    Returns:
    ndarray, initial density matrix
    """

def spin_square(mo_coeff, s, mo_occ):
    """
    Calculate spin contamination and total spin.
    
    Parameters:
    - mo_coeff: orbital coefficients
    - s: overlap matrix
    - mo_occ: orbital occupations
    
    Returns:
    tuple of (S^2, 2S+1) values
    """

def analyze(mf, verbose=None, **kwargs):
    """
    Analyze SCF results including Mulliken populations and orbital energies.
    """

Usage Examples

Basic SCF Calculations

import pyscf

# Restricted Hartree-Fock
mol = pyscf.M(atom='H2O', basis='6-31g')
mf = mol.RHF()
mf.run()
print(f"RHF energy: {mf.e_tot}")

# Unrestricted for open-shell
mol_radical = pyscf.M(atom='OH', basis='6-31g', spin=1)
mf = mol_radical.UHF()
mf.run()
print(f"UHF energy: {mf.e_tot}")

DFT Calculations

# Restricted Kohn-Sham with different functionals
mol = pyscf.M(atom='CH4', basis='cc-pvdz')

# LDA functional
mf_lda = mol.RKS(xc='lda')
mf_lda.run()

# GGA functional
mf_pbe = mol.RKS(xc='pbe')
mf_pbe.run()

# Hybrid functional
mf_b3lyp = mol.RKS(xc='b3lyp')
mf_b3lyp.run()

# Range-separated hybrid
mf_camb3lyp = mol.RKS(xc='camb3lyp')
mf_camb3lyp.run()

Advanced SCF Options

# Custom convergence settings
mol = pyscf.M(atom='H2', basis='cc-pvtz')
mf = mol.RHF()
mf.conv_tol = 1e-12
mf.max_cycle = 100
mf.init_guess = 'atom'
mf.run()

# With density fitting acceleration
mf_df = pyscf.scf.density_fit(mf, auxbasis='cc-pvtz-jkfit')
mf_df.run()

# Newton-Raphson acceleration
mf_newton = pyscf.scf.newton(mf)
mf_newton.run()

Relativistic Calculations

# X2C for scalar relativistic effects
mol_heavy = pyscf.M(atom='Au 0 0 0; H 0 0 1.5', basis='cc-pvdz-pp')
mf_x2c = pyscf.scf.X2C(mol_heavy).RHF()
mf_x2c.run()

# Dirac-Hartree-Fock for full relativistic treatment
mf_dhf = mol_heavy.DHF()
mf_dhf.run()

Types

from typing import Union, Tuple, TypedDict
from typing_extensions import Literal
import numpy as np
ndarray = np.ndarray

# SCF base classes
class SCF:
    """Base SCF class with common functionality."""

# Functional specifications for DFT
XCFunctional = Union[str, Tuple[str, float]]

# Convergence status
class ConvergenceError(RuntimeError):
    """Raised when SCF fails to converge."""

# Common SCF result structure
SCFResult = TypedDict('SCFResult', {
    'converged': bool,
    'e_tot': float,
    'mo_energy': ndarray,
    'mo_coeff': ndarray,
    'mo_occ': ndarray
})

Install with Tessl CLI