Numerical Evaluation in PySCF and GPAW

CiderPress uses a common mapped-model layer with separate molecular and plane-wave feature generators. Their shared evaluation contract begins with the feature definitions in Electronic Features in CiderPress; the Version-J convolution is derived in Numerical Evaluation of NLDF Features.

Mapped-model contract

Let \(\mathbf X_0[z](\mathbf r)\) denote the ordered raw features stored in a model. The numerical variables \(z\) include the spin densities and their semilocal ingredients. For an SDMX model, \(z\) also includes the one-particle density matrix. Each mapped kernel evaluates

\[\mathbf X_0 \xrightarrow{\mathcal N} \overline{\mathbf X}_0 \xrightarrow{\mathcal T_\kappa} \mathbf X_{1,\kappa} \xrightarrow{f_\kappa} e_\kappa,\]

where \(\mathcal N\) is the model’s physical normalization and \(\mathcal T_\kappa\) is the bounded feature map associated with kernel \(\kappa\). The total energy is

\[E_{\mathrm{xc}} = \int \mathrm d^3\mathbf r\, e_{\mathrm{xc}}(\mathbf r), \qquad e_{\mathrm{xc}}=\sum_\kappa e_\kappa.\]

FeatNormalizerList applies \(\mathcal N\), and each mapped kernel stores an instance of FeatureList to evaluate the transformation \(\mathcal T_\kappa\). The evaluator propagates derivatives back through both layers to obtain

\[v_i(\mathbf r) = \frac{\partial e_{\mathrm{xc}}(\mathbf r)} {\partial X_{0,i}(\mathbf r)}.\]

The feature generator then applies its discrete adjoint:

\[\frac{\delta E_{\mathrm{xc}}}{\delta z} = \sum_i \left(D_z X_{0,i}\right)^{\!*}v_i + \left.\frac{\partial E_{\mathrm{xc}}}{\partial z} \right|_{\mathbf X_0}.\]

The last term is present when an energy baseline depends explicitly on the density variables. This notation covers local density and gradient potentials, the generalized Kohn–Sham kinetic-energy-density term, and the density-matrix potential produced by SDMX.

Mapped evaluators

Mapped evaluators provide efficient implementations of trained functionals. There are two types of mapped evaluator in CiderPress:

  • MappedXC applies baselines expressed through the feature array. Packaged CIDER23X and CIDER24X models use this representation. This evaluator returns derivatives with respect to normalized features; the backend reverses normalization to obtain \(v_i\).

  • MappedXC2 evaluates mapped kernels whose multiplicative and additive baselines depend directly on the density, gradient, and/or kinetic-energy density. CIDER26XC uses this representation. [1] This evaluator returns both feature derivatives and a separate vrho_tuple containing the explicit derivatives of the baselines.

The kernel mode stored in the model determines its spin contraction. SEP evaluates a contribution for each spin channel; NPOL takes the mean of the normalized features over spin before evaluating the transformed features. CIDER26XC uses separate-spin exchange kernels and a spin-averaged feature vector for its correlation kernel, consistent with the energy form in the CIDER26XC manuscript. [1]

PySCF molecular path

make_cider_calc() installs CiderNumInt on a PySCF RKS or UKS object. The numerical integrator selects feature generators from the settings loaded with the model and assembles \(\mathbf X_0\) in serialized order.

Semilocal and SDMX features can be evaluated on the current quadrature block. An NLDF couples different grid points, so nr_rks() and nr_uks() use three passes over grids:

  1. Evaluate the density ingredients on the complete molecular quadrature grid and call LCAONLDFGenerator.get_features in ciderpress/dft/lcao_nldf_generator.py.

  2. Evaluate the mapped energy and feature derivatives block by block. Store the weighted NLDF derivatives on the complete grid.

  3. Call LCAONLDFGenerator.get_potential once, add its density, gradient, and kinetic-energy-density contributions, and contract the completed potential with the atomic orbitals.

For SDMX, EXXSphGenerator constructs features from the density matrix and adds the returned adjoint directly to the AO matrix. [2] Restricted and unrestricted calculations use arrays of shape (nspin, nfeature, ngrid); the mapped kernel’s serialized mode performs the spin contraction.

The mapped evaluators return an energy per unit volume. PySCF’s numerical integration interface expects exc per particle, so eval_xc_cider in ciderpress/pyscf/numint.py divides the mapped result by the total density. PySCF then accumulates \(\sum_g w_g n_g\,\mathtt{exc}_g\).

Analytical molecular gradients differentiate the atom-centered quadrature and the NLDF auxiliary representation in ciderpress.pyscf.rks_grad and ciderpress.pyscf.uks_grad. The implementation details are given in PySCF Numerical and Derivative Implementation.

GPAW plane-wave and PAW path

get_cider_functional() constructs a CiderGGA or CiderMGGA functional. Its smooth-grid calculation proceeds as follows:

  1. ciderpress.gpaw.cider_fft collects the spin density, gradient contractions, and kinetic-energy density required by the model.

  2. NLDFSplinePlan generates the Version-J source coefficients. LibCiderPW performs the fixed-kernel FFT convolutions, and target interpolation produces the NLDF block.

  3. CiderKernel assembles and normalizes the feature array, evaluates the mapped kernels, and adds their energy density directly to GPAW’s e_g array.

  4. The target and source interpolation adjoints and the backward convolution add the NLDF contribution to GPAW’s smooth potential. The same reciprocal kernels supply the cell derivative used for stress.

For PAW calculations, ciderpress.gpaw.cider_paw augments the convolution source and projects the returned fields onto atomic support grids. The all-electron and pseudo on-site evaluations add their energy, potential, force, and stress corrections to the smooth-grid result. This PASDW construction was introduced with the periodic CIDER23X implementation. [3]

The PAW/PASDW equations, radial reconstruction, and implementation classes are documented in GPAW FFT, PAW, and Radial Implementation. GPAW does not implement the SDMX descriptors used by CIDER24X.