tessl/pypi-pyscf

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

—

Pending

Overview

Eval results

Files

Molecular Structure and Basis Sets

Name: tessl/pypi-pyscf
Author: tessl

Core functionality for defining molecular systems, atomic coordinates, basis sets, and Gaussian type orbitals that form the foundation for all quantum chemistry calculations in PySCF.

Capabilities

Molecule Creation

Main interface for creating molecular systems with atomic coordinates, basis sets, and molecular properties.

def M(**kwargs):
    """
    Main driver to create Molecule object (mol) or Material crystal object (cell).
    
    Parameters:
    - atom: str or list, atomic coordinates in various formats
    - basis: str or dict, basis set specification
    - charge: int, molecular charge (default: 0)
    - spin: int, spin multiplicity - 1 (default: 0)
    - unit: str, coordinate unit ('Bohr' or 'Angstrom', default: 'Angstrom')
    - symmetry: bool or str, use molecular symmetry (default: False)
    - verbose: int, output verbosity level (default: 3)
    
    Returns:
    Mole object for molecules or Cell object for crystals (if 'a' parameter provided)
    """

class Mole:
    """
    Main molecule class for quantum chemistry calculations.
    
    Attributes:
    - atom: atomic coordinates and symbols
    - basis: basis set specification
    - charge: molecular charge
    - spin: number of unpaired electrons
    - natm: number of atoms
    - nelectron: number of electrons
    - nelec: tuple of (alpha, beta) electrons
    """
    
    def build(self):
        """Build molecule and initialize internal data structures."""
    
    def RHF(self):
        """Create restricted Hartree-Fock object."""
    
    def UHF(self):
        """Create unrestricted Hartree-Fock object."""
    
    def RKS(self, xc='lda'):
        """Create restricted Kohn-Sham DFT object."""
    
    def UKS(self, xc='lda'):
        """Create unrestricted Kohn-Sham DFT object."""
    
    def ROHF(self):
        """Create restricted open-shell Hartree-Fock object."""
    
    def GHF(self):
        """Create generalized Hartree-Fock object."""
    
    def ROKS(self, xc='lda'):
        """Create restricted open-shell Kohn-Sham DFT object."""
    
    def GKS(self, xc='lda'):
        """Create generalized Kohn-Sham DFT object."""
    
    # Core molecular properties
    def copy(self, deep=True):
        """Create copy of molecule object."""
    
    def atom_coord(self, atm_id=None, unit='Angstrom'):
        """Get atomic coordinates."""
    
    def atom_charge(self, atm_id=None):
        """Get atomic charges."""
    
    def energy_nuc(self):
        """Calculate nuclear repulsion energy."""
    
    def tot_electrons(self):
        """Calculate total number of electrons."""
    
    # Basis set information  
    def nao_nr(self, cart=None):
        """Number of AO functions (non-relativistic)."""
    
    def nao_cart(self):
        """Number of Cartesian AO functions."""
    
    def ao_labels(self, fmt=True):
        """Get AO labels."""
    
    # Integral evaluation
    def intor(self, intor, comp=None, hermi=0, shls_slice=None):
        """General integral evaluation interface."""

Atomic Coordinate Handling

Functions for parsing, formatting, and manipulating atomic coordinates in various formats.

def format_atom(atoms, origin=0, axes=None, unit='Angstrom'):
    """
    Format and validate atomic coordinates.
    
    Parameters:
    - atoms: str or list, atomic coordinates
    - origin: array-like, coordinate origin (default: [0,0,0])
    - axes: array-like, coordinate system axes
    - unit: str, coordinate unit ('Bohr' or 'Angstrom')
    
    Returns:
    list of [symbol, [x, y, z]] entries
    """

def atom_types(atoms, basis=None, magmom=None):
    """
    Determine unique atom types in molecular system.
    
    Parameters:
    - atoms: atomic coordinate specification
    - basis: basis set specification
    - magmom: magnetic moments
    
    Returns:
    list of unique atom types
    """

Basis Set Management

Functions for loading, parsing, and manipulating basis set definitions from various sources.

def parse(string, symb=None, optimize=True):
    """
    Parse basis set definition from string format.
    
    Parameters:
    - string: str, basis set definition
    - symb: str, element symbol
    - optimize: bool, optimize basis set contractions
    
    Returns:
    list of basis functions
    """

def load(filename_or_basisname, symb, optimize=True):
    """
    Load basis sets from files or built-in library.
    
    Parameters:
    - filename_or_basisname: str, file path or basis set name
    - symb: str, element symbol
    - optimize: bool, optimize contractions
    
    Returns:
    list of basis functions
    """

def load_ecp(filename_or_basisname, symb):
    """
    Load effective core potentials.
    
    Parameters:
    - filename_or_basisname: str, file path or ECP name
    - symb: str, element symbol
    
    Returns:
    dict of ECP specification
    """

def optimize_contraction(basis):
    """Optimize basis set contractions for efficiency."""

# Built-in basis set aliases (extensive collection)
ALIAS: dict # Standard basis set aliases including:
            # Pople: '631g', '6311g', '631gs', '631gss', '6311gss' 
            # Correlation-consistent: 'ccpvdz', 'ccpvtz', 'ccpvqz', 'ccpv5z'
            # Def2: 'def2svp', 'def2tzvp', 'def2tzvpp', 'def2qzvp'
            # STO: 'sto3g', 'sto6g'
            # Relativistic: various 'dk' variants

Gaussian Type Orbitals

Core functions for Gaussian type orbital properties, normalization, and transformations.

def gto_norm(l, expnt):
    """
    Normalization factor for Gaussian type orbitals.
    
    Parameters:
    - l: int, angular momentum quantum number
    - expnt: float, Gaussian exponent
    
    Returns:
    float, normalization factor
    """

def gaussian_int(n, alpha):
    """
    Analytical Gaussian integral calculation.
    
    Parameters:
    - n: int, power in integrand
    - alpha: float, Gaussian exponent
    
    Returns:
    float, integral value
    """

def cart2sph(l, c_tensor=None, normalized=None):
    """
    Cartesian to spherical harmonic transformation matrix.
    
    Parameters:
    - l: int, angular momentum
    - c_tensor: array-like, transformation coefficients
    - normalized: bool, use normalized spherical harmonics
    
    Returns:
    transformation matrix
    """

Integral Evaluation

Functions for evaluating integrals over Gaussian type orbitals at various levels.

def getints(intor, atm, bas, env, shls_slice=None, comp=None, hermi=0, aosym='s1'):
    """
    General integral calculation interface.
    
    Parameters:
    - intor: str, integral type
    - atm: ndarray, atomic information
    - bas: ndarray, basis set information  
    - env: ndarray, environment array
    - shls_slice: tuple, shell slice for partial integrals
    - comp: int, number of components
    - hermi: int, hermiticity (0=no, 1=hermitian, 2=anti-hermitian)
    - aosym: str, AO symmetry ('s1', 's2ij', 's2kl', 's4', 's8')
    
    Returns:
    ndarray, integral values
    
    Supported integral types:
    1-electron: int1e_ovlp, int1e_kin, int1e_nuc, int1e_rinv
    1e derivatives: int1e_ipovlp, int1e_ipkin, int1e_ipnuc  
    2-electron: int2e, int2e_ip1, int2e_ip2, int2e_sph
    3-center: int3c2e, int3c2e_ip1, int3c2e_sph
    ECP: ECPscalar, ECPso
    Spinor: various _spinor variants
    """

def getints_by_shell(intor, shls, atm, bas, env, comp=1):
    """Evaluate integrals for specific shells."""

def make_cintopt(atm, bas, env, intor):
    """Create optimization objects for integral evaluation."""

def eval_gto(mol, eval_name, coords, comp=None, shls_slice=None, non0tab=None, ao_loc=None, cutoff=None, out=None):
    """
    Evaluate Gaussian type orbitals at specified coordinates.
    
    Parameters:
    - mol: Mole object
    - eval_name: str, evaluation type
    - coords: array-like, evaluation coordinates
    - comp: int, component to evaluate
    - shls_slice: tuple, shell slice
    - non0tab: screening table for efficiency
    - ao_loc: AO location array
    - cutoff: float, cutoff threshold
    - out: ndarray, output array
    
    Returns:
    ndarray, GTO values at coordinates
    
    Supported evaluation types:
    GTOval_sph, GTOval_cart: Basic GTO values
    GTOval_ip_sph, GTOval_ip_cart: First derivatives
    GTOval_deriv1 through GTOval_deriv4: Higher derivatives
    GTOval_*_spinor: Spinor variants
    """

def make_screen_index(mol, coords, shls_slice=None, cutoff=1e-8):
    """Create screening arrays for efficient GTO evaluation."""

Usage Examples

Basic Molecule Creation

import pyscf

# Simple molecule from string
mol = pyscf.M(atom='H 0 0 0; H 0 0 1.4', basis='6-31g')

# Molecule with charge and spin
mol = pyscf.M(
    atom='C 0 0 0; O 0 0 1.4',
    basis='cc-pvdz',
    charge=0,
    spin=0  # singlet
)

# From list format
atoms = [
    ['H', [0.0, 0.0, 0.0]],
    ['H', [0.0, 0.0, 1.4]]
]
mol = pyscf.M(atom=atoms, basis='sto-3g')

Advanced Basis Set Usage

# Mixed basis sets
mol = pyscf.M(
    atom='H 0 0 0; He 0 0 2',
    basis={'H': '6-31g', 'He': 'cc-pvdz'}
)

# Custom basis set
custom_basis = pyscf.gto.basis.parse('''
H    S
     13.00773000              0.01968500
      1.96206100              0.13797700
      0.44453100              0.47814800
H    S
      0.12194300              1.00000000
''')
mol = pyscf.M(atom='H 0 0 0; H 0 0 1.4', basis={'H': custom_basis})

Coordinate Manipulation

# Different units
mol_bohr = pyscf.M(
    atom='H 0 0 0; H 0 0 2.6',  # in Bohr
    basis='sto-3g',
    unit='Bohr'
)

# With symmetry
mol_sym = pyscf.M(
    atom='N 0 0 0; H 1 1 1; H 1 -1 -1; H -1 1 -1; H -1 -1 1',
    basis='6-31g',
    symmetry=True
)

Types

from typing import Union, Dict, List, Tuple
import numpy as np
ndarray = np.ndarray

class MoleBase:
    """Base class for molecular systems providing common functionality."""

# Basis set format types
BasisSpec = Union[str, Dict[str, Union[str, List]], List]

# Atomic coordinate types  
AtomSpec = Union[str, List[List[Union[str, List[float]]]]]

# Physical constants and configuration
BOHR: float = 0.52917721092  # Bohr to Angstrom conversion
BASE: int = 0  # C-style 0-based indexing (can be 1 for Fortran-style)
NORMALIZE_GTO: bool = True  # Enable GTO normalization

# Nuclear models
NUC_POINT: int = 1  # Point nuclear model
NUC_GAUSS: int = 2  # Gaussian nuclear model  
NUC_FRAC_CHARGE: int = 3  # Fractional charge model
NUC_ECP: int = 4  # ECP nuclear model

Install with Tessl CLI