Core DFT Representation
The ciderpress.dft package defines the backend-independent contract
between an electronic feature representation and a mapped XC model. A DFT
backend (PySCF or GPAW) reads the stored settings, computes the requested
raw features, calls the evaluator, and propagates the returned feature
derivatives into the Kohn-Sham effective potential.
The CIDER Framework introduces the scientific
data flow; the pages below document the corresponding objects.
Settings and numerical plans
ciderpress.dft.settings declares the semilocal, NLDF, and SDMX
features and their parameters. An instance of the FeatureSettings
object defines the set of descriptors to compute for a given ML model.
ciderpress.dft.plans implements the backend-independent parts
of the forward (feature evaluation) and adjoint (XC potential evaluation) operations.
For example, NLDFSettingsVJ defines version-j NLDF
features, and NLDFSplinePlan defines one
interpolation representation for them. The numerical algorithm is described
in Numerical Evaluation of NLDF Features.
Normalization and Transformation of Features
ciderpress.dft.feat_normalizer converts raw features into
descriptors with the uniform scaling behavior chosen for the functional.
The most common use of the feature normalizers is to transform raw features
(which might not be scale-invariant) into scale-invariant normalized
features, though it is not necessary to make every feature scale-invariant unless
you want to enforce the uniform scaling rule for exchange. See
Uniform Scaling for details. Models for the correlation
energy typically retain at least one feature that is not scale-invariant,
usually the density.
Even after normalization, features might remain unbounded, i.e. they can take
arbitrarily large values. ciderpress.dft.transform_data applies bounded
maps to the input features before passing them to the Gaussian process regression
model, thereby guaranteeing that the final features used in regression fall
inside finite intervals that are convenient for machine learning.
Model Baselines and Model Evaluation
ciderpress.dft.baselines provides additive and multiplicative
energy density baselines for model construction. Baselines are used
because it is typically easier for a model to learn the difference
between the training data and an existing functional than to learn
the full functional from scratch. Details on how the baselines
are used can be found in Training and Mapping Workflow.
The ciderpress.dft.xc_evaluator and ciderpress.dft.xc_evaluator2
modules evaluate the model baselines and the trained ML model,
and they return the predicted XC energy density
along with the derivatives with respect to input features.
The role of both XC evaluator modules is to wrap trained models into
computationally efficient, black-box interfaces for evaluating the
functionals within self-consistent DFT calculations. Depending on how
the model was mapped after training, the ML part is evaluated one of
three ways by the XC evaluator:
Via a cubic spline interpolation over the possible values of the features, with spline coefficients calculated after training and stored in the model.
Via a neural network trained to reproduce the Gaussian process and stored in the model.
Directly via the Gaussian process predictive mean formula, with kernel weights precomputed for efficiency and parallelized within the C backend. All CIDER models use a set of sparse control points to accelerate training and model evaluation, making this direct approach performant.
CIDER23X models use the cubic spline approach, CIDER24X models use the neural network approach, and CIDER26XC models use the direct evaluation approach.
Finally, ciderpress.dft.model_utils resolves packaged model names and trusted
YAML/joblib paths.
Settings, feature order, normalization, spin treatment, energy baselines, and evaluator type form part of the functional definition. Preserve them together when mapping or extending a model. The extension contract is described in Extending CiderPress.