dft implementation

Author: EBB2675

src/nomad_simulations/schema_packages/model_method.py

@@ -1,3 +1,4 @@
+from collections.abc import Sequence
 from itertools import accumulate, chain, tee
 from typing import TYPE_CHECKING, Union
 
@@ -972,3 +973,116 @@ class ForceCalculations(NumericalSettings):
 
     def normalize(self, archive, logger) -> None:
         super().normalize(archive, logger)
+
+
+class FrozenCore(NumericalSettings):
+    """
+    Section defining the frozen-core approximation settings for molecular electronic-structure methods.
+
+    In the frozen-core approximation, selected inner-shell (core) orbitals are excluded from
+    the orbital optimization or post-SCF correlation treatment, retaining them at their
+    reference-determinant (e.g., Hartree-Fock or Kohn-Sham) values. This significantly
+    reduces the number of 'valence' orbitals, lowering computational cost.
+
+    The frozen-core scheme can be specified either by enumerating the exact orbitals to
+    freeze or by using simple threshold rules based on quantum numbers or atomic numbers.
+
+    """
+
+    ####  MolecularOrbitalsState has not been implemented yet.
+    # core_orbitals_ref = Quantity(
+    #     type=MolecularOrbitalsState,
+    #     shape=['n_frozen_core_orbitals'],
+    #     description="""
+    #     References to the atomic OrbitalsState sections to keep frozen.
+    #     """,
+    # )
+
+    per_atom_n_threshold = Quantity(
+        type=np.int32,
+        shape=['*'],
+        description="""
+        For each atom (in input order), maximum principal quantum number *n*
+        that will be **frozen**.  -1 means “no freezing for that atom”.
+        """,
+    )
+
+    per_atom_z_threshold = Quantity(
+        type=np.int32,
+        shape=['*'],
+        description="""
+        Alternative per-atom rule: freeze all core shells with atomic number Z ≤ value.
+        Entries of 0 disable the rule for that atom.
+        """,
+    )
+
+
+class IntegralDecomposition(ArchiveSection):
+    """
+    A general class for integral decomposition techniques that approximate
+    Coulomb and/or exchange integrals to reduce computational cost in quantum
+    chemistry.
+
+    Captures common families such as RIJ, RIJK, RIJCOSX, SENEX, and Cholesky
+    Decomposition (CD / CD_F12). The `approximated_term` encodes which part of
+    the electronic structure workload is approximated. This class self-normalizes
+    legacy/narrow settings to lossless semantics:
+      • RIJ        → J only                      → 'coulomb'
+      • RIJK       → J and K together            → 'jk'
+      • RIJCOSX    → J (RI) + K (COSX)           → 'jk'
+      • CD         → ERI-tensor level            → 'two_electron'
+      • CD_F12     → explicit-correlation terms  → 'explicit_correlation'
+
+    Typical references:
+      - F. Weigend, M. Häser, The RI-MP2 method: Algorithmic
+        implementation of efficient, approximate MP2 theories,
+        Theor. Chem. Acc. 97, 331-340 (1997).
+      - S. Hättig, F. Weigend, J. Chem. Phys. 113, 5154 (2000). (RI-J)
+      - Neese et al., “Chain-of-spheres algorithms for HF exchange,”
+        Chem. Phys. 356 (2008), 98-109.
+    """
+
+    approximation_type = Quantity(
+        type=MEnum('RIJ', 'RIJK', 'RIJCOSX', 'SENEX', 'CD', 'CD_F12'),
+        description="""
+        RIJ     : also known as RIJONX, where only Coulomb integrals are approximated.
+        RIJK    : both Coulomb and exchange integrals.
+        RIJCOSX : RIJ for Coulomb and COSX for HF exchange.
+        SENEX   : Similar to COSX, relevant for Turbomole.
+        CD      : Cholesky decomposition of the two-electron integral tensor
+        CD_F12  : Cholesky decomposition specialized for F12/explicit-correlation integrals
+        """,
+    )
+
+    approximated_term = Quantity(
+        type=MEnum(
+            'coulomb',  # J only
+            'exchange',  # K only
+            'jk',  # J and K together (e.g., RIJK/RIJCOSX)
+            'two_electron',  # ERI-level (e.g., plain CD)
+            'mp2',
+            'cc',
+            'explicit_correlation',
+        ),
+        description="""
+        The targeted term(s) being approximated. If not provided, it will be
+        inferred from `approximation_type`. For backward compatibility, narrow
+        values are safely widened (e.g., RIJK + 'exchange' → 'jk').
+        """,
+    )
+
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)
+
+        _TERM_BY_TYPE = {
+            'RIJ': 'coulomb',
+            'RIJK': 'jk',
+            'RIJCOSX': 'jk',
+            'CD': 'two_electron',
+            'CD_F12': 'explicit_correlation',
+        }
+
+        if self.approximated_term is None:
+            inferred = _TERM_BY_TYPE.get(self.approximation_type)
+            if inferred is not None:
+                self.approximated_term = inferred

src/nomad_simulations/schema_packages/numerical_settings.py

@@ -0,0 +1,94 @@
+# LibXC Functional Canonicalization
+
+This module converts **code-specific exchange–correlation (XC) labels** into a **canonical, LibXC-grounded representation**.  
+It accepts aliases such as `PBE`, hybrids like `B3LYP`, or composite forms like `SCAN+rVV10`, and produces normalized **LibXC components** (`XCComponent` instances) with consistent metadata (`family`, `kind`, `id`, etc.).
+
+---
+
+## Aim
+
+1. **Unify XC naming** across electronic-structure codes by resolving them to LibXC identifiers.  
+2. **Make functional components explicit** — making functional components explicit as far as LibXC exposes them.  
+3. **Preserve hybrid parameters** when available (`α`, `ω`, SR/LR fractions).  
+4. **Provide a single canonical label** (`functional_key`) for user-facing filtering, while keeping full LibXC detail internally.
+
+> **Background:**  
+> [LibXC](https://libxc.gitlab.io/) is the reference library defining the mathematical kernels for all standard density functionals (LDA, GGA, meta-GGA, hybrids).  
+> It distinguishes each kernel by a stable name like `XC_GGA_X_PBE` and a numeric ID.  
+> This canonicalization follows the same separation principle: each kernel is treated as one building block.
+
+---
+
+## Input Forms Accepted
+
+- **Human-readable aliases:** `LDA`, `PBE`, `PW91`, `TPSS`, `SCAN`, `r2SCAN`, `B3LYP`, etc.  
+- **Hybrid or range-separated forms:** `PBE0`, `HSE06`, `LC-ωPBE`, `CAM-B3LYP`, etc.  
+- **Raw LibXC labels:** `XC_GGA_X_PBE`, `XC_GGA_C_PBE`, `XC_HYB_GGA_XC_B3LYP`, etc.  
+
+The module is code-agnostic — any parser providing a string can normalize it through this interface.
+
+---
+
+## Canonicalization Pipeline
+
+### 1. Tokenization & Normalization
+- Input strings are uppercased, `ω` is normalized to `W`, all text in parentheses is dropped, and separators (`space`, `+`, `/`, `_`, `-`, `,`) are removed. Tokenization splits on `[+/,\s]+`.
+- Known suffixes like `-D3` or `+VV10` are recognized but **not yet parsed into separate dispersion or nonlocal correlation models** — they remain part of the functional key.
+
+### 2. Alias Expansion → LibXC Components
+Aliases are expanded using a curated lookup table (`expand.py`):
+
+| Input Alias | Expanded Components |
+|--------------|---------------------|
+| `PBE` | `XC_GGA_X_PBE`, `XC_GGA_C_PBE` |
+| `SVWN` | `XC_LDA_X`, `XC_LDA_C_VWN` |
+| `TPSS` | `XC_MGGA_X_TPSS`, `XC_MGGA_C_TPSS` |
+
+This ensures consistent resolution against LibXC definitions.
+
+### 3. Registry Lookup (`registry.py`)
+Each expanded label is matched against a lightweight internal registry (`xc_registry_min.json`)  
+to populate standard LibXC metadata:
+
+- **`family`** → `LDA`, `GGA`, `meta-GGA`, `hybrid-GGA`, `hybrid-meta-GGA`  
+- **`kind`** → `exchange`, `correlation`, or `xc`  
+- **`libxc_id`** → stable LibXC numeric identifier  
+- **`display_name`** → human-readable name (e.g., “Perdew, Burke & Ernzerhof”)
+
+### 4. Component Construction (`build.py`)
+Each resolved label becomes an `XCComponent`, carrying:
+- canonical label (`XC_GGA_X_PBE`)  
+- LibXC ID and family/kind metadata  
+- optional hybrid parameters (`fraction_exact_exchange`, `range_separation_parameter`)  
+- numerical `weight` (default 1.0)
+
+### 5. Attachment to DFT Section
+During `DFT.normalize()`:
+- If `xc.components` is empty but a `functional_key` is provided,  
+  it is expanded into canonical LibXC components and attached.  
+- The **highest Jacob’s ladder family** among components sets `jacobs_ladder`.  
+- If a unique hybrid fraction (`α`) is found, it is propagated to `exact_exchange_mixing_factor`.
+
+---
+
+## Canonical Functional Key (`functional_key`)
+
+While LibXC defines each **exchange**, **correlation**, and **hybrid** kernel separately  
+(e.g., `XC_GGA_X_PBE`, `XC_GGA_C_PBE`), users typically refer to these collectively using one name — e.g., “PBE”.
+
+This canonicalization introduces:
+
+- **`functional_key`** → one user-facing alias representing the entire functional  
+  *(e.g., `PBE`, `PBE0`, `B3LYP`, `SCAN+rVV10`)*  
+- **`components`** → explicit LibXC-resolved kernels underneath  
+  *(e.g., `["XC_GGA_X_PBE", "XC_GGA_C_PBE"]`)*
+
+Example:
+```text
+PBE    → functional_key = "PBE"
+          components = ["XC_GGA_X_PBE", "XC_GGA_C_PBE"]
+
+B3LYP  → functional_key = "B3LYP"
+          components = ["XC_HYB_GGA_XC_B3LYP"]
+
+

src/nomad_simulations/schema_packages/utils/libxc/README.md

@@ -0,0 +1,109 @@
+{
+  "BASE": {
+    "LDA": ["XC_LDA_X", "XC_LDA_C_PW"],
+    "LSDA": ["XC_LDA_X", "XC_LDA_C_VWN"],
+    "SVWN": ["XC_LDA_X", "XC_LDA_C_VWN"],
+    "SVWN5": ["XC_LDA_X", "XC_LDA_C_VWN"],
+    "VWN": ["XC_LDA_X", "XC_LDA_C_VWN"],
+    "PW92": ["XC_LDA_C_PW"],
+    "PZ81": ["XC_LDA_X", "XC_LDA_C_PZ"],
+    "PBE": ["XC_GGA_X_PBE", "XC_GGA_C_PBE"],
+    "PBESOL": ["XC_GGA_X_PBE_SOL", "XC_GGA_C_PBE_SOL"],
+    "REVPBE": ["XC_GGA_X_RPBE", "XC_GGA_C_PBE"],
+    "RPBE": ["XC_GGA_X_RPBE", "XC_GGA_C_PBE"],
+    "PW91": ["XC_GGA_X_PW91", "XC_GGA_C_PW91"],
+    "BLYP": ["XC_GGA_X_B88", "XC_GGA_C_LYP"],
+    "BP86": ["XC_GGA_X_B88", "XC_GGA_C_P86"],
+    "BOP": ["XC_GGA_X_BOP", "XC_GGA_C_PBE"],
+    "OLYP": ["XC_GGA_X_OPTX", "XC_GGA_C_LYP"],
+    "PBEINT": ["XC_GGA_X_PBEINT", "XC_GGA_C_PBEINT"],
+    "PBEALPHA": ["XC_GGA_X_PBE_A", "XC_GGA_C_PBE"],
+    "WC": ["XC_GGA_X_WC"],
+    "HTBS": ["XC_GGA_X_HTBS", "XC_GGA_C_PBE"],
+    "MPW91": ["XC_GGA_X_MPW91", "XC_GGA_C_PW91"],
+    "MPWPW": ["XC_GGA_X_MPW91", "XC_GGA_C_PW91"],
+    "MPWLYP": ["XC_GGA_X_MPW91", "XC_GGA_C_LYP"],
+    "SOGGA": ["XC_GGA_X_SOGGA", "XC_GGA_C_SOGGA11"],
+    "SOGGA11": ["XC_GGA_X_SOGGA11", "XC_GGA_C_SOGGA11"],
+    "SOGGA11-X": ["XC_GGA_X_SOGGA11"],
+    "REVTCA": ["XC_GGA_C_REVTPSS"],
+    "TPSS": ["XC_MGGA_X_TPSS", "XC_MGGA_C_TPSS"],
+    "REVTPSS": ["XC_MGGA_X_REVTPSS", "XC_MGGA_C_TPSS"],
+    "PKZB": ["XC_MGGA_X_PKZB", "XC_MGGA_C_PKZB"],
+    "BRX": ["XC_MGGA_X_BR89"],
+    "SCAN": ["XC_MGGA_X_SCAN", "XC_MGGA_C_SCAN"],
+    "SCAN-L": ["XC_MGGA_X_SCANL", "XC_MGGA_C_SCAN"],
+    "R2SCAN": ["XC_MGGA_X_R2SCAN", "XC_MGGA_C_R2SCAN"],
+    "M06-L": ["XC_MGGA_X_M06_L", "XC_MGGA_C_M06_L"],
+    "M11-L": ["XC_MGGA_X_M11_L", "XC_MGGA_C_M11_L"],
+    "MN15-L": ["XC_MGGA_X_MN15_L", "XC_MGGA_C_MN15_L"],
+    "TPSSLOC": ["XC_MGGA_X_TPSS", "XC_MGGA_C_TPSS"],
+    "B97M-V": ["XC_MGGA_X_B97M_V", "XC_NLC_XC_VV10"],
+    "B97M-RV": ["XC_MGGA_X_B97M_RV", "XC_NLC_XC_RVV10"]
+  },
+  "HYB": {
+    "PBE0": ["XC_HYB_GGA_XC_PBEH", "XC_HYB_GGA_XC_PBE0", "XC_HYB_GGA_XC_PBE0_13"],
+    "PBEH": ["XC_HYB_GGA_XC_PBEH", "XC_HYB_GGA_XC_PBE0", "XC_HYB_GGA_XC_PBE0_13"],
+    "B3LYP": ["XC_HYB_GGA_XC_B3LYP", "XC_HYB_GGA_XC_B3LYPS"],
+    "B3PW91": ["XC_HYB_GGA_XC_B3PW91"],
+    "B3PW": ["XC_HYB_GGA_XC_B3PW91"],
+    "B97-1": ["XC_HYB_GGA_XC_B97_1"],
+    "B97-2": ["XC_HYB_GGA_XC_B97_2"],
+    "O3LYP": ["XC_HYB_GGA_XC_O3LYP"],
+    "X3LYP": ["XC_HYB_GGA_XC_X3LYP"],
+    "MPW1PW": ["XC_HYB_GGA_XC_MPW1PW"],
+    "MPW3PW": ["XC_HYB_GGA_XC_MPW3PW"],
+    "BHANDH": ["XC_HYB_GGA_XC_BHANDH"],
+    "BHANDHLYP": ["XC_HYB_GGA_XC_BHANDHLYP"],
+    "HSE03": ["XC_HYB_GGA_XC_HSE03"],
+    "HSE06": ["XC_HYB_GGA_XC_HSE06"],
+    "HSE": ["XC_HYB_GGA_XC_HSE06", "XC_HYB_GGA_XC_HSE03", "XC_HYB_GGA_XC_HSE12", "XC_HYB_GGA_XC_HSE_SOL"],
+    "CAM-B3LYP": ["XC_HYB_GGA_XC_CAM_B3LYP"],
+    "LC-ωPBE": ["XC_HYB_GGA_XC_LC_WPBE"],
+    "WPBEH": ["XC_HYB_GGA_XC_WPBEH"],
+    "N12-SX": ["XC_HYB_GGA_XC_N12_SX"],
+    "APFD": ["XC_HYB_GGA_XC_APFD"],
+    "SCAN0": ["XC_HYB_MGGA_X_SCAN0", "XC_MGGA_C_SCAN"],
+    "R2SCAN0": ["XC_HYB_MGGA_XC_R2SCAN0", "XC_HYB_MGGA_X_REVSCAN0"],
+    "M06": ["XC_HYB_MGGA_X_M06", "XC_HYB_MGGA_C_M06"],
+    "M06-2X": ["XC_HYB_MGGA_X_M06_2X", "XC_HYB_MGGA_C_M06_2X"],
+    "M08-HX": ["XC_HYB_MGGA_X_M08_HX", "XC_HYB_MGGA_C_M08_HX"],
+    "M08-SO": ["XC_HYB_MGGA_X_M08_SO", "XC_HYB_MGGA_C_M08_SO"],
+    "M11": ["XC_HYB_MGGA_X_M11", "XC_HYB_MGGA_C_M11"],
+    "MN15": ["XC_HYB_MGGA_X_MN15", "XC_HYB_MGGA_C_MN15"],
+    "ωB97X-D": ["XC_HYB_MGGA_X_WB97X_D"],
+    "ωB97X-V": ["XC_HYB_MGGA_X_WB97X_V", "XC_NLC_XC_VV10"],
+    "ωB97M-V": ["XC_HYB_MGGA_X_WB97M_V", "XC_NLC_XC_VV10"]
+  },
+  "FALLBACK_BY_RUNG": {
+    "hybrid-GGA": [
+      ["XC_HYB_GGA_XC_PBE0"],
+      ["XC_HYB_GGA_XC_B3LYP"],
+      ["XC_HYB_GGA_XC_HSE06"]
+    ],
+    "hybrid-meta-GGA": [
+      ["XC_HYB_MGGA_X_SCAN0", "XC_MGGA_C_SCAN"],
+      ["XC_HYB_MGGA_X_M06", "XC_HYB_MGGA_C_M06"]
+    ],
+    "meta-GGA": [
+      ["XC_MGGA_X_SCAN", "XC_MGGA_C_SCAN"],
+      ["XC_MGGA_X_TPSS", "XC_MGGA_C_TPSS"]
+    ],
+    "GGA": [
+      ["XC_GGA_X_PBE", "XC_GGA_C_PBE"],
+      ["XC_GGA_X_B88", "XC_GGA_C_LYP"]
+    ]
+  },
+  "RUNG_HINT": {
+    "revTCA": "GGA",
+    "B97M-V": "meta-GGA",
+    "B97M-rV": "meta-GGA",
+    "ωPBEh": "hybrid-GGA",
+    "N12-SX": "hybrid-GGA",
+    "APFD": "hybrid-GGA",
+    "ωB97X-D": "hybrid-meta-GGA",
+    "ωB97X-V": "hybrid-meta-GGA",
+    "ωB97M-V": "hybrid-meta-GGA"
+  },
+  "version": 1
+}

src/nomad_simulations/schema_packages/utils/libxc/__init__.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+from .registry import lookup_by_id, lookup_by_label
+
+
+class XCComponentSpec(TypedDict):
+    libxc_id: int
+    canonical_label: str
+    display_name: str
+    family: str
+    kind: str
+    weight: float
+
+
+def spec_from_label(label: str, *, weight: float = 1.0) -> XCComponentSpec | None:
+    """
+    Build a plain-data specification for an XCComponent from a LibXC-style label.
+
+    Returns:
+        XCComponentSpec if found, otherwise None.
+    """
+    rec = lookup_by_label(label)
+    if not rec:
+        return None
+
+    return XCComponentSpec(
+        libxc_id=rec['id'],
+        canonical_label=rec['label'],
+        display_name=rec['name'],
+        family=rec['family'],
+        kind=rec['kind'],
+        weight=float(weight),
+    )
+
+
+def spec_from_id(xc_id: int, *, weight: float = 1.0) -> XCComponentSpec | None:
+    """
+    Build a plain-data specification for an XCComponent from a LibXC integer ID.
+
+    Returns:
+        XCComponentSpec if found, otherwise None.
+    """
+    rec = lookup_by_id(xc_id)
+    if not rec:
+        return None
+    return spec_from_label(rec['label'], weight=weight)