PySCF Numerical and Derivative Implementation

This page is an implementation reference for the molecular backend. Construct a calculation with make_cider_calc() and extract fixed-density data with get_descriptors(). The objects below implement those public interfaces.

Blockwise XC integration

ciderpress.pyscf.numint connects PySCF’s atom-centered quadrature to the feature settings stored in a mapped model. For each grid block it:

1. evaluates the density, gradient, and, for meta-GGA models, kinetic-energy density from the density matrix;

2. evaluates semilocal, NLDF, and SDMX feature blocks in their serialized order;

3. applies the mapped model to obtain an energy density and feature derivatives; and

4. applies the adjoint of every feature operation to assemble the matrix XC potential returned to PySCF.

The restricted and unrestricted routes use the same feature plans. The unrestricted route retains separate alpha- and beta-spin arrays until the model’s spin-combination rule is applied.

ciderpress.pyscf.numint.nr_rks(ni, mol, grids, xc_code, dms, relativity=0, hermi=1, max_memory=2000, verbose=None)

Internal restricted numerical-integration entry point. It returns the electron count, XC energy, and matrix potential for one or more density matrices.

ciderpress.pyscf.numint.nr_uks(ni, mol, grids, xc_code, dms, relativity=0, hermi=1, max_memory=2000, verbose=None)

Internal spin-polarized counterpart of nr_rks().

class ciderpress.pyscf.numint.CiderNumInt

PySCF NumInt implementation that owns the mapped evaluator and the feature generators selected from its settings. The constructor make_cider_calc() selects the appropriate NLDF or SDMX path.

NLDF grid and convolution

ciderpress.pyscf.gen_cider_grid extends a PySCF molecular grid with radial and spherical-harmonic indexing needed by the nonlocal evaluator. The indexer records how PySCF’s sorted quadrature points map to atom-centered radial/angular shells; feature generation and its adjoint must use the same mapping.

class ciderpress.pyscf.gen_cider_grid.CiderGrids

Atom-centered integration grid carrying the CIDER radial/angular indexer. It is constructed by the decorated calculation when its model requires NLDFs.

ciderpress.pyscf.nldf_convolutions builds the auxiliary Gaussian representation of the density-dependent kernel and evaluates its forward and backward contractions. Its exponent grid, angular cutoff, interpolation scheme, and low-density cutoffs are the numerical approximations to the feature definition.

class ciderpress.pyscf.nldf_convolutions.PySCFNLDFInitializer

Stores the serialized NLDFSettings and numerical options until the molecule and CIDER grid are available.

class ciderpress.pyscf.nldf_convolutions.PyscfNLDFGenerator

Molecular wrapper around the common LCAO NLDF generator. Its forward operation produces grid features; its backward operation returns the corresponding density and exponent derivatives.

SDMX feature evaluation

ciderpress.pyscf.sdmx evaluates the optimized smoothed density-matrix features used by CIDER24X. These features contract the one-particle density matrix with smoothed atom-centered orbital quantities.

class ciderpress.pyscf.sdmx.PySCFSDMXInitializer

Defers construction of the SDMX generator until the molecule and spin layout are known.

class ciderpress.pyscf.sdmx.EXXSphGenerator

Evaluates SDMX features and applies their adjoint contribution to the density-matrix potential.

ciderpress.pyscf.sdmx_slow is the reference formulation used to check the optimized contractions, and it also supplies the base class for the periodic SDMX generator in ciderpress.pyscf.pbc.sdmx_fft and for descriptor extraction. Molecular calculation setup uses the optimized ciderpress.pyscf.sdmx path. The current SDMX interface provides energies and potentials; its property scope is listed in Energies and Derivative Properties.

Nuclear-gradient response

ciderpress.pyscf.rks_grad supplies restricted analytical nuclear gradients. In addition to the usual AO and quadrature response, an NLDF gradient includes motion of the atom-centered CIDER grid, auxiliary-basis response, interpolation response, and the adjoint nonlocal potential.

class ciderpress.pyscf.rks_grad.Gradients

Restricted CIDER gradient implementation selected by the decorated SCF object.

class ciderpress.pyscf.rks_grad.DFGradients

Restricted gradient implementation including the response terms required by a density-fitted calculation.

ciderpress.pyscf.uks_grad carries the same response terms for separate alpha and beta densities.

class ciderpress.pyscf.uks_grad.Gradients

Unrestricted CIDER gradient implementation.

class ciderpress.pyscf.uks_grad.DFGradients

Unrestricted density-fitted CIDER gradient implementation.

See Numerical Evaluation of NLDF Features for the molecular NLDF algorithm, Numerical Evaluation in PySCF and GPAW for the backend comparison, and Extending CiderPress for guidance on extending the implementation.