Model Objects and Mapping

Contents of a mapped functional

A mapped CIDER functional combines the scientific choices needed to evaluate one energy form:

Feature settings

FeatureSettings records the ordered semilocal, NLDF, and SDMX blocks required by the model. A backend uses these settings to construct its numerical integrator.

Normalizers and transforms

Physical normalizers convert raw electronic quantities into descriptors with the scaling behavior chosen for the functional. Bounded transforms produce the coordinates used by the regression model.

Mapped kernels and baselines

Each kernel combines a learned function with additive and multiplicative energy-density baselines. It returns the energy contribution and derivatives with respect to every raw input.

Evaluation representation

A mapped kernel can evaluate the Gaussian process predictive mean directly or use a fitted spline or neural network representation. The evaluator type is stored in the model file.

Functional metadata

The top-level object records feature settings and fitted correction metadata such as the D4 term associated with CIDER26XCCHEMD4. Full-XC models also record the additive libxc baseline used to combine their exchange and correlation components.

Loading and inspection

Use ciderpress.dft.model_utils.load_cider_model() with a packaged name or trusted explicit path:

from ciderpress.dft.model_utils import load_cider_model

model = load_cider_model("CIDER26XCSURFSCI")
print(type(model).__name__)
print(model.nfeat)
print(model.settings.sl_settings.level)
print(model.settings.nldf_settings.version)

The stored settings determine the backend requirements. A model’s short name and checksum identify the released scientific artifact; the checksum table is in Choosing a CIDER Functional.

Trainable and mapped representations

DFTKernel and DFTKernel2 hold a covariance kernel, feature transforms, control points, and energy baselines. A MOLGP or MOLGP2 combines one or more such kernels with feature settings, integrated system observations, reaction definitions, and noise assignments.

After fitting, MOLGP.map(mapping_plans) or MOLGP2.map(mapping_plans) performs the following conversion:

  1. Each mapping plan constructs a FuncEvaluator for its trained kernel.

  2. The evaluator, transforms, mode, and baselines form a mapped DFT kernel.

  3. The mapped kernels and shared settings form MappedXC or MappedXC2.

  4. Correction metadata is copied to the mapped object before YAML serialization.

The packaged families illustrate three evaluator choices. CIDER23X uses mapped spline evaluators. CIDER24X uses a neural evaluator trained to reproduce its GP. CIDER26XC stores the sparse control-point prediction in a radial-basis-function (RBF) evaluator. Here RBF denotes the squared-exponential covariance kernel evaluated directly between each feature vector and the stored GP control points. The implementation is RBFEvaluator.

Baselines and functional composition

For the original evaluator interface, DFTKernel accepts Python baseline callables from ciderpress.dft.baselines. Its local energy contribution has the form

\[e(\mathbf X)=a(\mathbf X)+m(\mathbf X)f_\mathrm{ML}(\mathbf X).\]

DFTKernel2 identifies additive and multiplicative baselines by libxc string and evaluates their energy and derivative terms through MappedDFTKernel2. This interface supplies the separate exchange and correlation components in CIDER26XC. See Energy-Density Baselines for the baseline API and From Exchange Models to Full XC for the CIDER26XC energy form.

Serialization and packaged models

Joblib files store trainable Python objects and their fitting state. Mapped YAML stores the inference object used by the calculation interfaces. Both formats reconstruct Python objects and should be loaded from trusted sources.

The package installs the mapped YAML models published with the CIDER23X, CIDER24X, and CIDER26XC work under ciderpress/data/functionals. MANIFEST.in includes these files as package data, and ciderpress.dft.model_utils resolves their short names. Choosing a CIDER Functional lists every name with its checksum. The CIDER23X and CIDER24X functional sets are also archived on Zenodo and can be fetched with scripts/download_functionals.py.

See Training and Mapping Workflow for the expected training-data boundary and Regression, Training, and Mapping APIs for the regression APIs.