## Phase 121: Kalika Machine Learning Potentials & Materials Informatics — Equivariant Neural Network Potentials, Crystal Graph Networks, Generative Models & High-Throughput Screening

The fastest-growing methodology in computational materials science. Machine
learning interatomic potentials (MLIPs) achieve near-DFT accuracy at a fraction
of the cost, enabling simulations at length and time scales previously
inaccessible. Crystal graph neural networks predict materials properties
directly from structure, generative models propose novel candidates, and
high-throughput screening pipelines automate the discovery cycle. This phase
targets parity with MACE, NequIP, SchNet, CGCNN, MEGNet, M3GNet, CHGNet, matgl,
and the Materials Project ML stack, integrating tightly with the crystal
structures (Phase 117), electronic structure foundations (Phase 116) and
many-body corrections (Phase 118), phonons (Phase 119), and thermodynamics
(Phase 125) already in Kalika.

Tech split: Rust (~30%) for inference engines and descriptor computation,
TypeScript (~30%) for orchestration / pipeline / API, Python (~40%) for ML
training and model definition.

---

### 121.1 Scaffolding & Core Types (`@kalika/ml-potentials`)

#### 121.1.1 Project Setup

- [x] **121.1.1.1** Create `libs/kalika/ml-potentials/` with `project.json`,
      `package.json`, `tsconfig.json`, and `tsconfig.lib.json`. Add path mapping
      `@kalika/ml-potentials` to `tsconfig.base.json`. Configure Vitest for the
      library
- [x] **121.1.1.2** Create barrel export `src/index.ts` with organized module
      re-exports grouped by domain: types, descriptors, potentials, training,
      active-learning, graph-networks, generative, screening, benchmarking
- [x] **121.1.1.3** Set up Rust crate `crates/kalika-ml-potentials/` with
      `Cargo.toml`, `lib.rs`, napi-rs bindings scaffold, and wasm-bindgen
      feature flag for browser-targeted builds. Integrate with Nx via
      `nx:run-commands` executor

#### 121.1.2 Core Type Definitions

- [x] **121.1.2.1** Define `Descriptor` interface hierarchy: `AtomicDescriptor`
      (per-atom feature vector with atom index, element, descriptor values as
      `Float64Array`), `StructureDescriptor` (global descriptor aggregated from
      atomic descriptors, including mean/std/sum pooling variants),
      `PairDescriptor` (pairwise distance-based features), `AngularDescriptor`
      (triplet/angular features). Include metadata fields for descriptor name,
      dimensionality, cutoff radius, and parameter hash
- [x] **121.1.2.2** Define `MLPotential` interface: `predict(structure)` →
      `{ energy: number; forces: Float64Array[]; stress: Matrix3x3 }`,
      `predictBatch(structures)`, `getUncertainty(structure)` →
      `{ energyUncertainty: number; forceUncertainties: Float64Array[] }`,
      `getModelInfo()` → `ModelMetadata`, `export(format: ExportFormat)`,
      `finetune(dataset, config)`. Require all implementations to provide
      energy, forces, and stress predictions
- [x] **121.1.2.3** Define `TrainingSet` type: collection of `TrainingSample`
      entries, each containing a `Structure` (from Phase 117), DFT-computed
      energy (eV), forces (eV/A per atom), stress tensor (kBar), optional charge
      densities, and provenance metadata (DFT code, functional, k-mesh, cutoff).
      Include methods for splitting (train/val/test), stratified sampling by
      composition, augmentation, and serialization to/from extended XYZ and ASE
      databases
- [x] **121.1.2.4** Define `ActiveLearningLoop` type: encapsulating the full
      cycle — `MLPotential` model, `TrainingSet` accumulator, uncertainty
      threshold, selection strategy enum (`COMMITTEE`, `MC_DROPOUT`,
      `ENSEMBLE_DISAGREEMENT`, `D_OPTIMALITY`, `MAXVOL`), DFT calculator
      callback, convergence criteria (max iterations, target accuracy,
      uncertainty threshold), and iteration history log
- [x] **121.1.2.5** Define `TrainingConfig` type: learning rate, optimizer
      (Adam, AdamW, SGD with momentum), scheduler (cosine, one-cycle,
      reduce-on-plateau, exponential), batch size, max epochs, early stopping
      patience, loss weights (energy weight, force weight, stress weight),
      gradient clipping, weight decay, EMA decay rate, checkpoint interval,
      validation fraction, random seed
- [x] **121.1.2.6** Define `ModelCheckpoint` type: epoch number, training loss,
      validation loss, per-component MAE (energy MAE eV/atom, force MAE eV/A,
      stress MAE kBar), model weights serialization, optimizer state, scheduler
      state, training config snapshot, wall-clock time elapsed
- [x] **121.1.2.7** Define enumerations: `DescriptorType` (ACSF, SOAP, ACE, MTP,
      ZERNIKE, COULOMB_MATRIX, MBTR, LODE), `PotentialType` (MACE, NEQUIP,
      PAINN, ALLEGRO, SCHNET, DIMENET, GEMNET, SPOOKYNET, SO3NET, GAP,
      MTP_CLASSICAL, SNAP, ACE_LINEAR), `PropertyTarget` (FORMATION_ENERGY,
      BAND_GAP, BULK_MODULUS, SHEAR_MODULUS, POISSON_RATIO, DEBYE_TEMPERATURE,
      DIELECTRIC_CONSTANT, REFRACTIVE_INDEX, THERMAL_CONDUCTIVITY),
      `GenerativeModelType` (CDVAE, DIFFCSP, GAN, VAE, FLOW, RL_DESIGN)

#### 121.1.3 Utility Infrastructure

- [x] **121.1.3.1** Implement `NeighborList` class (Rust with napi-rs bindings):
      given a `Structure` and cutoff radius, compute cell-list-based neighbor
      list with periodic boundary conditions. Return per-atom neighbor indices,
      distance vectors, and distances. Support multiple cutoffs (for multi-body
      descriptors). Benchmark: < 1 ms for 1000-atom cell with 6 A cutoff
- [x] **121.1.3.2** Implement `CutoffFunction` module: smooth cutoff functions
      used universally in descriptors and potentials — cosine cutoff f_c(r) =
      0.5(1 + cos(pi \* r / r_c)), polynomial cutoff (p = 2..6), exponential
      cutoff, and Tersoff-style cutoff. Each with first and second derivatives
      for force/stress computation
- [x] **121.1.3.3** Implement `RadialBasisExpansion` module: expand interatomic
      distances into basis function vectors — Gaussian RBF (evenly spaced
      centers), Bernstein polynomials, Bessel functions (first kind, spherical),
      Chebyshev polynomials. Configurable number of basis functions, trainable
      vs fixed centers/widths
- [x] **121.1.3.4** Implement `SphericalHarmonics` module (Rust): real and
      complex spherical harmonics Y_l^m(theta, phi) up to l_max = 12. Include
      associated Legendre polynomials, normalization conventions (orthonormal,
      Condon-Shortley), gradient with respect to Cartesian coordinates. Verify
      orthonormality via numerical integration tests
- [x] **121.1.3.5** Implement `WignerSymbols` module (Rust): Wigner 3j symbols,
      Clebsch-Gordan coefficients, Wigner D-matrices D^l\_{mm'}(alpha, beta,
      gamma). Precompute and cache for l_max up to 6. Verify symmetry properties
      and orthogonality relations in tests
- [x] **121.1.3.6** Implement `ElementEmbedding` module: learnable and fixed
      element feature vectors — one-hot encoding (up to Z=118), atomic
      properties vector (Z, mass, electronegativity, covalent radius, van der
      Waals radius, ionization energies, electron affinity, block index),
      MatScholar embeddings (200-dim pretrained from NLP on materials
      literature), and Megnet16 embeddings (16-dim pretrained from MEGNet).
      Provide factory function to select embedding type by name
- [x] **121.1.3.7** Implement `PeriodicTable` lookup module: fast lookup of
      elemental properties needed across all ML models — atomic mass, covalent
      radius, van der Waals radius, Pauling electronegativity, Allred-Rochow
      electronegativity, first through fourth ionization energies, electron
      affinity, melting point, boiling point, density, crystal structure,
      ground-state magnetic ordering. Data from NIST. Cache as typed constants
- [x] **121.1.3.8** Implement structure-to-graph converter: given a `Structure`
      (Phase 117), produce a typed `CrystalGraph` object containing node
      features, edge indices, edge features, edge distance vectors, and batch
      indices. Support configurable graph construction (cutoff, Voronoi, k-NN).
      Handle supercell generation for small unit cells. Return offset vectors
      for periodic images
- [x] **121.1.3.9** Implement `AtomicData` batch collation: collate
      variable-size crystal graphs into batched tensors (padded or packed) for
      efficient GPU processing. Track per-structure boundaries (batch index
      tensor). Support dynamic batching by total atom count (rather than
      structure count) to avoid OOM on large structures

---

### 121.2 Atomic Descriptors & Representations (`@kalika/ml-descriptors`)

#### 121.2.1 Atom-Centered Symmetry Functions (ACSF / Behler-Parrinello)

- [x] **121.2.1.1** Implement G1 radial symmetry function: sum of cutoff
      functions over neighbors within r_c. Include derivative with respect to
      atomic positions for force computation
- [x] **121.2.1.2** Implement G2 radial symmetry function: G2*i = sum_j exp(-eta
      * (r*ij - R_s)^2) * f_c(r_ij). Parameterized by eta (Gaussian width) and
      R_s (center). Include analytic gradient for forces
- [x] **121.2.1.3** Implement G3 radial symmetry function (cosine variant): G3*i
      = sum_j cos(kappa * r*ij) * f_c(r_ij). Include gradient
- [x] **121.2.1.4** Implement G4 angular symmetry function: G4*i = 2^(1-zeta) \*
      sum*{j,k} (1 + lambda _ cos(theta_ijk))^zeta _ exp(-eta _ (r_ij^2 +
      r_ik^2 + r_jk^2)) _ f*c(r_ij) * f*c(r_ik) * f_c(r_jk). Parameterized by
      lambda (+/-1), zeta, eta. Include gradient
- [x] **121.2.1.5** Implement G5 angular symmetry function (narrow variant,
      excludes r*jk term): G5_i = 2^(1-zeta) \* sum*{j,k} (1 + lambda _
      cos(theta_ijk))^zeta _ exp(-eta _ (r_ij^2 + r_ik^2)) _ f_c(r_ij) \*
      f_c(r_ik). Include gradient
- [x] **121.2.1.6** Implement weighted ACSF (wACSF): element-weighted variants
      of G2 and G4 where each neighbor contribution is weighted by atomic number
      Z_j, eliminating the need for element-pair-specific parameter sets.
      Include gradient
- [x] **121.2.1.7** Implement `ACSFCalculator` class: given a `Structure` and
      parameter set (list of G2/G4/G5 parameters per element pair/triplet),
      compute the full ACSF descriptor vector for each atom. Parallelize over
      atoms. Return `AtomicDescriptor[]` with metadata
- [x] **121.2.1.8** Implement ACSF parameter generation utilities: automatic
      parameter set construction using radial distribution function analysis
      (place G2 centers at RDF peaks), logarithmic spacing in eta, and angular
      parameter grid (standard zeta = 1, 2, 4, 16; lambda = +/-1; eta = small)

#### 121.2.2 Smooth Overlap of Atomic Positions (SOAP)

- [x] **121.2.2.1** Implement SOAP density expansion: represent atomic neighbor
      density rho*i(r) as sum of Gaussians centered on neighbor positions,
      expand in radial basis functions g_n(r) and spherical harmonics Y_l^m.
      Compute expansion coefficients c*{nlm} via numerical integration on radial
      grid. Support n_max up to 12, l_max up to 9
- [x] **121.2.2.2** Implement SOAP power spectrum: compute rotationally
      invariant descriptor p*{nn'l} = sum_m c*{nlm}^\* c\_{n'lm} (the partial
      power spectrum). Flatten to vector, optionally normalize. This is the
      standard SOAP descriptor used in GAP. Include gradient w.r.t. atomic
      positions
- [x] **121.2.2.3** Implement SOAP bispectrum: three-body rotationally invariant
      descriptor b\_{n1n2n3,l1l2l3} constructed from triple products of
      expansion coefficients contracted with Clebsch-Gordan coefficients. Higher
      body-order information than power spectrum alone
- [x] **121.2.2.4** Implement compressed SOAP: apply PCA or random projection to
      reduce SOAP descriptor dimensionality from O(n_max^2 \* l_max) to a
      configurable target dimension (typically 100-300) while preserving kernel
      similarity. Compute projection matrix from representative dataset
- [x] **121.2.2.5** Implement multi-species SOAP: extend density expansion with
      per-element channels (separate densities for each element), cross-element
      power spectrum terms, and element-averaged descriptors. Support up to 10
      distinct elements in a single descriptor calculation
- [x] **121.2.2.6** Implement SOAP kernel: compute similarity between two atomic
      environments as dot-product of normalized SOAP vectors, raised to integer
      power zeta (zeta = 2, 4 typical). Implement average kernel (average over
      atoms in structure) for structure-level comparison

#### 121.2.3 Atomic Cluster Expansion (ACE)

- [x] **121.2.3.1** Implement ACE basis functions: one-particle basis
      phi\_{znlm}(r*ij) = R_nl(r_ij) * Y*l^m(r_hat_ij) * delta(z_j, z) where
      R_nl are orthogonal radial basis functions, Y_l^m are spherical harmonics,
      and z indexes element type. Compute up to n_max = 8, l_max = 4
- [x] **121.2.3.2** Implement ACE A-basis (atomic base): A*{znlm,i} = sum_j
      phi*{znlm}(r_ij) — sum of one-particle basis over neighbors of atom i.
      This is the fundamental building block for body-ordered descriptors
- [x] **121.2.3.3** Implement ACE product basis (body-ordered descriptors):
      B*{v,i} = product over nu (body order) of A*{z_nu, n_nu, l_nu, m_nu, i},
      contracted with generalized Clebsch-Gordan coupling coefficients to
      produce rotationally invariant descriptors at each body order (2-body,
      3-body, 4-body, etc.)
- [x] **121.2.3.4** Implement ACE descriptor selection: given a maximum body
      order (correlation order nu), maximum polynomial degree, and angular
      momentum budget, enumerate all valid ACE basis functions satisfying
      selection rules (rotational invariance, parity, total degree constraint).
      Prune redundant functions using rank analysis of the correlation matrix
- [x] **121.2.3.5** Implement ACE evaluator (Rust): given precomputed basis
      specification and linear coefficients, evaluate total energy as linear
      combination of ACE descriptors. Compute forces via backward
      differentiation through the product/sum chain. Target: < 5 ms for 100-atom
      cell with nu_max = 3, l_max = 3

#### 121.2.4 Moment Tensor Potentials (MTP) Descriptors

- [x] **121.2.4.1** Implement moment tensor M*{mu,nu}(r_ij): the fundamental MTP
      building block, defined as M*{mu,nu,i} = sum_j f_mu(r_ij) \* r_ij^{otimes
      nu} where f_mu is a radial basis function and r_ij^{otimes nu} is the
      nu-fold outer product of the displacement vector. Compute for nu = 0
      (scalar), 1 (vector), 2 (matrix)
- [x] **121.2.4.2** Implement MTP basis function contraction: contract moment
      tensors to produce rotationally invariant descriptors by taking traces,
      dot products, and determinants of the tensor products. Enumerate all
      independent contractions up to a given level (MTP level 8, 16, 20, 24, 28)
- [x] **121.2.4.3** Implement MTP descriptor calculator: compute the full set of
      MTP descriptors for each atom in a structure, returning
      `AtomicDescriptor[]`. Include gradient computation for forces via the
      chain rule through moment tensor contractions

#### 121.2.5 Additional Descriptor Types

- [x] **121.2.5.1** Implement Zernike descriptors: expand neighbor density in 3D
      Zernike polynomials Z\_{nlm}(r) (orthogonal on the unit ball). Compute
      rotationally invariant power spectrum from Zernike coefficients.
      Configurable n_max, l_max
- [x] **121.2.5.2** Implement Coulomb matrix: construct matrix C\_{ij} = Z*i *
      Z*j / |R_i - R_j| (off-diagonal), 0.5 * Z_i^2.4 (diagonal). Implement
      three variants: sorted (by row norm), random (averaged over permutations),
      and eigenvalue spectrum. Suitable for small molecules and clusters
- [x] **121.2.5.3** Implement Many-Body Tensor Representation (MBTR): compute
      distribution of 1-body (element), 2-body (distance), and 3-body (angle)
      features using kernel density estimation with Gaussian broadening. Return
      as discretized vector on a grid. Include weighting schemes (unity, inverse
      distance, exponential decay)
- [x] **121.2.5.4** Implement LODE (Long-Distance Equivariant) descriptors:
      extend SOAP-like density expansion to capture long-range electrostatic
      interactions by using 1/r^p (p = 1 for Coulomb) as the atom density
      instead of Gaussians. Compute via Ewald summation or smooth PME for
      periodic structures. Include power spectrum construction

#### 121.2.6 Descriptor Analysis & Selection

- [x] **121.2.6.1** Implement descriptor PCA: given a set of atomic descriptors
      computed over a training set, compute principal components, explained
      variance ratio, and project descriptors to reduced dimension. Visualize
      descriptor space via 2D PCA projection
- [x] **121.2.6.2** Implement CUR decomposition for descriptor selection: select
      a maximally informative subset of descriptor columns (features) and rows
      (environments) using CUR matrix decomposition with leverage score
      sampling. Return selected feature indices and representative environment
      indices
- [x] **121.2.6.3** Implement farthest-point sampling (FPS) in descriptor space:
      iteratively select the point farthest from all previously selected points
      in descriptor space (using Euclidean or kernel distance). Use for training
      set construction and selecting diverse representative environments
- [x] **121.2.6.4** Implement descriptor sensitivity analysis: for each
      descriptor component, compute sensitivity = partial E / partial d_i
      averaged over training set. Identify low-sensitivity descriptors for
      pruning. Compute correlation matrix between descriptor components to
      detect redundancy
- [x] **121.2.6.5** Implement descriptor caching infrastructure: compute
      descriptors once for a training set and serialize to disk (HDF5 or
      memory-mapped NumPy arrays). On reload, verify descriptor parameters match
      via parameter hash. Avoids recomputation during hyperparameter tuning of
      the model (when descriptor parameters are unchanged)
- [x] **121.2.6.6** Implement descriptor benchmarking: measure computation time
      and memory usage for each descriptor type (ACSF, SOAP, ACE, MTP, MBTR,
      Coulomb matrix) on standardized benchmark structures (64-atom Si, 108-atom
      water, 256-atom alloy). Report descriptors/second and bytes/descriptor.
      Generate comparison table and recommend descriptor for each use case
      (speed-critical vs accuracy-critical)

#### 121.2.7 Descriptor Integration with Phase 117

- [x] **121.2.7.1** Implement `Structure`-to-descriptor pipeline: given any
      `Structure` object from `@kalika/crystal-structure` (Phase 117),
      automatically compute requested descriptor type. Handle
      fractional-to-Cartesian coordinate conversion, periodic boundary
      conditions, and minimum image convention. Return `AtomicDescriptor[]` with
      atom indices matching the input structure
- [x] **121.2.7.2** Implement descriptor comparison for structure matching:
      given two structures, compute descriptor similarity (kernel value or
      Euclidean distance in descriptor space). Use for structure deduplication,
      training set diversity assessment, and interpolation/extrapolation
      detection. Support SOAP kernel, MBTR distance, and ACE descriptor distance

---

### 121.3 Equivariant Neural Network Potentials (`@kalika/equivariant-nnp`)

#### 121.3.1 Equivariant Operations Library (Rust + Python)

- [x] **121.3.1.1** Implement irreducible representation (irrep) type system:
      define `Irrep(l, p)` where l is angular momentum and p is parity (+1/-1).
      Define `Irreps` as a direct sum of irreps (e.g., "0e + 1o + 2e").
      Implement parsing from string notation, dimension calculation, and
      compatibility checks for tensor products
- [x] **121.3.1.2** Implement Clebsch-Gordan tensor product layer: given two
      irrep feature tensors (l1, m1) and (l2, m2), compute output features at
      all allowed angular momenta |l1-l2| <= l <= l1+l2 using precomputed
      Clebsch-Gordan coefficients. Include trainable path weights. Support
      sparse CG product (only selected output channels). Verify E(3)
      equivariance in tests
- [x] **121.3.1.3** Implement spherical harmonics embedding: given unit vectors
      r_hat (from atom-atom displacement), compute Y_l^m(r_hat) for l = 0..l_max
      as equivariant edge features. Package as irrep tensor with proper parity
      assignment (parity = (-1)^l). Verify rotation equivariance
- [x] **121.3.1.4** Implement Wigner D-matrix rotation: given Euler angles or
      rotation matrix R, compute Wigner D^l\_{mm'}(R) for all l up to l*max.
      Apply rotation to irrep feature tensors. Use for equivariance testing:
      verify f(R * x) = D(R) \_ f(x)
- [x] **121.3.1.5** Implement equivariance test harness: given any layer/model
      that maps atomic positions → features, verify SO(3) equivariance by
      applying random rotations to inputs and comparing transformed outputs.
      Test O(3) equivariance (including inversion). Test E(3) equivariance
      (including translation). Report maximum violation magnitude. Require
      violation < 1e-5 for all models in this phase
- [x] **121.3.1.6** Implement linear equivariant layer: SO(3)-equivariant linear
      map mixing irrep channels at each l independently (block-diagonal weight
      matrix in irrep space). Trainable weights per (l_in, l_out) channel pair.
      Include bias (only for l=0 scalar channels)
- [x] **121.3.1.7** Implement equivariant activation functions: scalar
      activation (apply standard nonlinearity to l=0 channels only, leave l>0
      unchanged), gated activation (l=0 scalars gate l>0 channels via sigmoid),
      norm-based activation (apply nonlinearity to norm of each l>0 channel,
      preserve direction)

#### 121.3.2 MACE Architecture

- [x] **121.3.2.1** Implement MACE message-passing layer: for each atom i,
      construct messages from neighbors via ACE-like body-ordered product of
      neighbor features (one-particle basis → A-basis → symmetric contraction),
      coupled with Clebsch-Gordan products to maintain equivariance. Support
      correlation order nu = 1, 2, 3 (2-body, 3-body, 4-body interactions). This
      is the key innovation of MACE — capturing many-body interactions in a
      single message-passing step
- [x] **121.3.2.2** Implement MACE interaction block: radial basis expansion of
      distances → linear mixing → tensor product of node features with edge
      spherical harmonics → symmetric contraction (ACE product) → linear
      readout. Stack multiple interaction blocks (default 2). Each block refines
      equivariant node features
- [x] **121.3.2.3** Implement MACE readout: from equivariant node features at
      each layer, extract scalar (l=0) channel, apply MLP to produce per-atom
      energy contribution. Sum per-atom energies to get total energy. Forces
      computed via autograd (or explicit backward pass). Stress from virial
      theorem
- [x] **121.3.2.4** Implement MACE model assembly: combine embedding layer
      (element → one-hot or learned embedding), radial basis, spherical
      harmonics, interaction blocks (configurable depth 1-3), and readout into
      complete MACE model. Default hyperparameters: r_cut = 5.0 A, l_max = 3,
      correlation = 3, hidden irreps = "128x0e + 64x1o + 32x2e"
- [x] **121.3.2.5** Implement MACE-MP-0 pretrained model loader: parse
      pretrained weights for the 89-element universal potential trained on
      Materials Project data. Support both the "small" (interaction_cls=2, ~200K
      params) and "medium" (~1M params) variants. Verify energy/force
      predictions on reference structures (Si diamond, NaCl rocksalt, Cu FCC)
      match published values within tolerance
- [x] **121.3.2.6** Implement MACE-OFF pretrained model loader: load organic
      force field weights (MACE trained on ANI-like organic molecule datasets).
      Verify on small molecule test cases (ethanol, aspirin, uracil) against
      published reference values

#### 121.3.3 NequIP Architecture

- [x] **121.3.3.1** Implement NequIP convolution layer: equivariant message
      passing where messages are formed by tensor product of neighbor node
      features (irrep tensors) with edge spherical harmonics Y_l^m(r_hat_ij),
      weighted by learnable radial function R(r_ij) (MLP applied to radial basis
      expansion of distance). Aggregate messages via sum. Update node features
      via linear + nonlinearity
- [x] **121.3.3.2** Implement NequIP radial network: MLP that maps scalar
      distance r_ij (expanded in Bessel basis) to per-path weight scalars. One
      weight per tensor-product path (l_in, l_edge, l_out). Include layer
      normalization and SiLU activation
- [x] **121.3.3.3** Implement NequIP type embedding: learnable per-element
      embedding vector (dimension typically 16-64) concatenated with or added to
      initial node features. Support multi-element systems with arbitrary
      element combinations
- [x] **121.3.3.4** Implement NequIP full model: initial embedding → N
      interaction layers (default 5) → scalar readout → per-atom energy. Default
      irreps: "0e + 1o + 1e + 2e + 2o" with 32 features per channel. Verify E(3)
      equivariance via test harness

#### 121.3.4 PaiNN Architecture

- [x] **121.3.4.1** Implement PaiNN representation: each atom carries a scalar
      feature s_i (invariant, shape [F]) and a vector feature v_i (equivariant,
      shape [F, 3]). Initialize s_i from element embedding, v_i from zero
- [x] **121.3.4.2** Implement PaiNN message block: compute scalar messages via
      continuous-filter convolution (distance → filter MLP → element-wise
      multiply with neighbor scalar features). Compute vector messages by
      scaling neighbor vectors with radial filter and adding directional
      component (scalar feature \* unit displacement vector). Aggregate via sum
- [x] **121.3.4.3** Implement PaiNN update block: update scalar features using
      both scalar messages and the norm of vector features (equivariant →
      invariant via norm). Update vector features using gating from scalar
      channel. This coupling allows information flow between invariant and
      equivariant channels
- [x] **121.3.4.4** Implement PaiNN full model: embedding → N message+update
      blocks (default 3) → scalar readout MLP → per-atom energy. Verify
      equivariance and benchmark against NequIP on test structures

#### 121.3.5 Additional Equivariant Architectures

- [x] **121.3.5.1** Implement ALLEGRO model: strictly local equivariant
      potential — multi-layer tensor product of pair features (no message
      passing between atoms, only between layers). Each layer: pair features →
      tensor product with spherical harmonics → MLP on invariant part → new pair
      features. Final readout sums pair energies. Advantage: trivially
      parallelizable, linear scaling
- [x] **121.3.5.2** Implement SchNet model: continuous-filter convolution —
      expand interatomic distance in Gaussian RBF → MLP → filter weights →
      element-wise multiply with neighbor features → aggregate. Stack N
      interaction blocks (default 6) with residual connections. Invariant model
      (scalar features only). Include cfconv layer, interaction block, and
      output MLP
- [x] **121.3.5.3** Implement DimeNet++ model: directional message passing
      incorporating bond angles. Embedding block: atom features + RBF distance +
      spherical basis expansion of angle. Interaction block: bilinear layer
      combining message with angular basis. Output block: per-atom sum with
      element-dependent linear layers. Faster than original DimeNet via
      simplified interaction
- [x] **121.3.5.4** Implement GemNet-T model: geometric message passing with
      dihedral angles (torsions). Two-hop message passing: messages from atom j
      to atom i incorporate information about neighbors k of j, using both angle
      theta_kji and dihedral angle phi_kjil. Triplet and quadruplet interaction
      blocks with efficient spherical basis expansion
- [x] **121.3.5.5** Implement SpookyNet model: message-passing NNP with
      non-local interactions. Features: (1) local message passing layers similar
      to PaiNN, (2) non-local attention mechanism for charge/spin
      redistribution, (3) explicit nuclear charge and electronic state
      embedding, (4) separate short-range and long-range (electrostatic) energy
      contributions
- [x] **121.3.5.6** Implement SO3Net model: message passing on SO(3) group using
      spherical harmonics as basis. Rotation-equivariant convolution on the
      sphere via SO(3) Fourier transform. Edge features encoded as Wigner
      D-matrix rotations. Compare accuracy/speed with e3nn-based approaches

#### 121.3.6 Training Infrastructure

- [x] **121.3.6.1** Implement multi-target loss function: weighted sum of energy
      loss (MSE or Huber on per-atom energy), force loss (MSE on force
      components, optionally per-element weighted), and stress loss (MSE on
      Voigt components). Configurable weights with sensible defaults
      (energy_weight=1.0, force_weight=100.0, stress_weight=10.0). Support
      log-cosh loss variant for outlier robustness
- [x] **121.3.6.2** Implement optimizer configuration: Adam with configurable
      betas and eps, AdamW with weight decay, SGD with momentum and Nesterov.
      Exponential moving average (EMA) of model weights with configurable decay
      rate (default 0.999). Gradient clipping by norm (default max_norm=10.0)
- [x] **121.3.6.3** Implement learning rate schedulers: cosine annealing with
      warm restarts, one-cycle policy (linear warmup → cosine decay), reduce on
      plateau (monitor validation loss, patience=50, factor=0.5), exponential
      decay, polynomial decay. All with configurable warmup steps
- [x] **121.3.6.4** Implement training loop: batch iteration with energy/force/
      stress loss computation, backward pass, gradient clipping, optimizer step,
      EMA update, LR scheduler step, periodic validation, checkpointing, logging
      (per-epoch: train loss, val loss, energy MAE, force MAE, stress MAE, LR,
      wall time). Early stopping with configurable patience
- [x] **121.3.6.5** Implement data loading pipeline: read training data from
      extended XYZ files, ASE database, or internal TrainingSet format.
      On-the-fly augmentation (random rotation for invariant models). Dynamic
      batching by number of atoms (not number of structures) for memory
      efficiency. Stratified sampling by composition/structure type
- [x] **121.3.6.6** Implement multi-GPU training support: data-parallel training
      via PyTorch DDP. Synchronized batch normalization for layer norm. Gradient
      accumulation for effective large batch sizes. Model-parallel support for
      very large models (shard weight matrices across GPUs)
- [x] **121.3.6.7** Implement model export: serialize trained model to ONNX
      format for portable inference, TorchScript for PyTorch-native deployment.
      Include model metadata (training config, dataset provenance, accuracy
      metrics) in exported file. Validate exported model reproduces
      training-framework predictions within floating-point tolerance

---

### 121.4 Classical ML Potentials (`@kalika/classical-ml-potentials`)

#### 121.4.1 Gaussian Approximation Potentials (GAP)

- [x] **121.4.1.1** Implement SOAP kernel matrix computation: given N atomic
      environments described by SOAP power spectra, compute N x N kernel matrix
      K\_{ij} = (p_i . p_j / |p_i| |p_j|)^zeta. Support sparse kernel (only
      compute kernel between training and inducing points). Efficient
      implementation via matrix multiplication for dot-product kernel
- [x] **121.4.1.2** Implement sparse Gaussian process regression (SGPR): given
      kernel matrix K between training points and M inducing points (M << N),
      solve for GP weights alpha = (K*MM + K_MN * K*NM / sigma^2)^{-1} * K_MN \*
      y / sigma^2. Use Cholesky factorization for numerical stability. Compute
      predictive mean and variance for new points
- [x] **121.4.1.3** Implement GAP force prediction: compute kernel derivatives
      dK/dr\_{ij} analytically (chain rule through SOAP descriptor and kernel
      function). Predict forces as negative gradient of predicted energy via
      kernel gradient. Verify force consistency: numerical gradient of predicted
      energy matches predicted forces
- [x] **121.4.1.4** Implement inducing point selection for GAP: select M
      representative atomic environments from training set using CUR
      decomposition, farthest-point sampling, or k-medoids clustering in SOAP
      descriptor space. Typical M = 500-3000
- [x] **121.4.1.5** Implement multi-descriptor GAP: combine multiple SOAP
      descriptors with different cutoffs (short-range + medium-range), plus
      2-body descriptor (pair potential baseline), into a single GAP model. Each
      descriptor has its own GP with its own kernel, inducing points, and
      regularization. Total energy = sum of GP predictions
- [x] **121.4.1.6** Implement GAP uncertainty: predictive variance from GP
      posterior — high variance = extrapolation / uncertain prediction. Use as
      trigger for active learning (flag structures where uncertainty exceeds
      threshold)

#### 121.4.2 Moment Tensor Potentials (MTP) — Classical

- [x] **121.4.2.1** Implement MTP linear model: energy = sum_i sum_alpha
      theta_alpha \* B_alpha(env_i) where B_alpha are MTP basis functions
      (Section 121.2.4) and theta_alpha are linear coefficients. Fit
      coefficients via linear least squares with energy/force/stress targets and
      Tikhonov regularization (ridge regression)
- [x] **121.4.2.2** Implement MTP active learning: extrapolation grade
      gamma(structure) = max eigenvalue of the leverage matrix for the new
      structure. If gamma > gamma_threshold (default 2.0), flag structure as
      out-of-domain and trigger DFT calculation. This is the original MLIP
      active learning scheme
- [x] **121.4.2.3** Implement MTP level selection: automatically select MTP
      level (8, 12, 16, 20, 24) based on cross-validation error. Higher levels =
      more basis functions = more accurate but slower. Report accuracy-vs-speed
      tradeoff

#### 121.4.3 Spectral Neighbor Analysis Potential (SNAP)

- [x] **121.4.3.1** Implement SNAP bispectrum descriptors: compute 4D
      hyperspherical harmonic expansion of neighbor density, then bispectrum
      coefficients B*{j1,j2,j} = sum*{m,m'} U^j*{mm'} \* conj(U^{j1}*{m1,m1'}) _
      conj(U^{j2}\_{m2,m2'}) _ CG(j1m1,j2m2|jm) \* CG(j1m1',j2m2'|jm'), where
      U^j are expansion coefficients on Wigner-U matrices. Compute for j_max = 4
      (SNAP) or j_max = 2 (quadratic SNAP)
- [x] **121.4.3.2** Implement linear SNAP model: energy = sum_i sum_k beta_k \*
      B_k(env_i) + beta_0. Fit beta via weighted least squares. Include
      per-element coefficients for multi-component systems. Compute forces via
      analytic bispectrum gradients
- [x] **121.4.3.3** Implement quadratic SNAP (qSNAP): extend linear SNAP with
      quadratic terms — energy includes cross-products B_k \* B_l. Significantly
      more accurate but more expensive. Implement efficient evaluation avoiding
      redundant products

#### 121.4.4 ACE Linear Models

- [x] **121.4.4.1** Implement linear ACE potential: energy = sum_i sum_v c_v \*
      B_v(env_i) where B_v are ACE basis functions (121.2.3). Fit coefficients
      c_v via regularized linear regression. This is the linear (non-neural) ACE
      approach, competitive with GAP at lower cost
- [x] **121.4.4.2** Implement recursive ACE evaluation (Rust): evaluate ACE
      descriptors and energy using the recursive evaluation scheme (avoid
      explicit tensor products by recursing through body orders). Target: 10x
      faster than naive product evaluation for nu_max = 4

#### 121.4.5 Kernel Methods & Uncertainty

- [x] **121.4.5.1** Implement kernel library: dot-product kernel k(x,y) =
      (x.y)^n, polynomial kernel k(x,y) = (alpha * x.y + c)^d, RBF kernel k(x,y)
      = exp(-||x-y||^2 / 2*sigma^2), Matern kernel (nu=1.5, 2.5), periodic
      kernel for angular features. All with analytic gradients for force
      prediction
- [x] **121.4.5.2** Implement ensemble uncertainty quantification: train N
      models (default 5) with different random seeds / data splits /
      architectures. Prediction = ensemble mean. Uncertainty = ensemble standard
      deviation. Support both classical and neural network models
- [x] **121.4.5.3** Implement last-layer Bayesian uncertainty: for neural
      network potentials, treat the last linear layer as Bayesian (fit posterior
      over weights using Laplace approximation or variational inference). Cheap
      uncertainty estimate without full ensemble
- [x] **121.4.5.4** Implement committee model: N independently trained models
      that vote on predictions. Compute committee disagreement for energy,
      forces, and stress. Use maximum force disagreement across atoms as the
      primary uncertainty metric for active learning triggers

---

### 121.5 Universal Pretrained Potentials (`@kalika/pretrained-potentials`)

#### 121.5.1 CHGNet (Charge-Informed Graph Neural Network)

- [x] **121.5.1.1** Implement CHGNet architecture: graph neural network with
      atom, bond, and angle interaction layers. Atom features include element
      embedding and predicted atomic charges (via charge readout head). Bond
      features include distance RBF expansion. Angle features include angle
      Fourier expansion. Key innovation: explicit charge degree of freedom
      enables correct description of charge transfer and oxidation state effects
- [x] **121.5.1.2** Implement CHGNet pretrained model loader: load weights
      trained on Materials Project Trajectory Dataset (MPtrj, ~1.6M structures,
      89 elements). Verify predictions on reference structures (LiFePO4
      formation energy, BaTiO3 phonon stability, Fe2O3 magnetic ground state)
      match published values
- [x] **121.5.1.3** Implement CHGNet charge prediction: extract predicted Bader-
      like atomic charges from the charge readout head. Use charges for
      oxidation state assignment and electrostatic interaction estimation.
      Validate against DFT Bader charges on reference oxides

#### 121.5.2 M3GNet (Materials 3-Body Graph Network)

- [x] **121.5.2.1** Implement M3GNet architecture: graph network with three-body
      interactions — node (atom) features, edge (bond) features, and triple
      (angle) features updated in each interaction layer. Edge updates use
      neighbor atom features + distance. Triple updates use edge features + bond
      angle. Node updates aggregate edge information. Stack 3 interaction layers
- [x] **121.5.2.2** Implement M3GNet pretrained model loader: load weights
      trained on Materials Project (~188K structures for initial release).
      Verify energy/force accuracy on reference set. Support matgl (Materials
      Graph Library) format for weight loading
- [x] **121.5.2.3** Implement M3GNet structure relaxation: use M3GNet as
      calculator in a geometry optimizer (BFGS or FIRE from Phase 116) to
      rapidly relax crystal structures. Compare relaxed lattice parameters
      against experimental values for benchmark set

#### 121.5.3 ALIGNN-FF

- [x] **121.5.3.1** Implement ALIGNN architecture: construct line graph (graph
      of edges) from crystal graph. Apply GNN layers alternating between atom
      graph and line graph — atom graph captures bonding, line graph captures
      angular interactions. Edge-gated graph convolution. Multi-layer (default 4
      atom + 4 line graph layers)
- [x] **121.5.3.2** Implement ALIGNN-FF pretrained model loader: load
      force-field variant weights trained on JARVIS-DFT dataset. Verify on
      JARVIS benchmark structures. Support both energy-only and energy+force
      model variants

#### 121.5.4 Fine-Tuning & Transfer Learning

- [x] **121.5.4.1** Implement fine-tuning workflow: take any pretrained
      universal potential (MACE-MP-0, CHGNet, M3GNet), freeze early layers,
      unfreeze last N layers, fine-tune on domain-specific DFT data with reduced
      learning rate. Configurable: which layers to freeze, learning rate
      schedule (warmup + cosine decay), regularization toward pretrained weights
      (elastic weight consolidation)
- [x] **121.5.4.2** Implement transfer learning with head replacement: replace
      the final readout head of a pretrained model with a new randomly
      initialized head, fine-tune only the head initially, then progressively
      unfreeze deeper layers. Track per-layer gradient magnitudes to detect when
      unfreezing helps
- [x] **121.5.4.3** Implement domain adaptation evaluation: compare fine-tuned
      model vs trained-from-scratch on same domain-specific dataset. Report
      learning curves (accuracy vs training set size) to quantify transfer
      learning benefit. Expect fine-tuned models to reach target accuracy with
      5-10x less data

---

### 121.6 Active Learning & Dataset Construction (`@kalika/active-learning`)

#### 121.6.1 Active Learning Loop

- [x] **121.6.1.1** Implement `ActiveLearningRunner` class: orchestrate the full
      active learning cycle — (1) train initial model on seed dataset, (2) run
      MD or structure sampling with model, (3) compute uncertainty for sampled
      structures, (4) select most uncertain/informative structures, (5) dispatch
      to DFT calculator, (6) add DFT results to training set, (7) retrain model,
      (8) check convergence. Iterate until convergence criterion met. Log all
      iterations with accuracy metrics
- [x] **121.6.1.2** Implement convergence criteria: (a) validation MAE below
      target (e.g., force MAE < 30 meV/A), (b) maximum uncertainty across
      sampled structures below threshold, (c) no new structures selected for N
      consecutive iterations, (d) maximum number of DFT calculations budget
      exhausted. Support combinations with AND/OR logic
- [x] **121.6.1.3** Implement active learning history tracker: record for each
      iteration: number of structures added, DFT cost (CPU-hours estimated),
      model accuracy (train/val MAE for energy/force/stress), maximum
      uncertainty, diversity of selected structures (descriptor space coverage).
      Plot learning curves (accuracy vs DFT cost)

#### 121.6.2 Selection Strategies

- [x] **121.6.2.1** Implement query-by-committee selection: train N models
      (committee, N=3-10) on same data with different random seeds. For each
      candidate structure, compute committee disagreement (standard deviation of
      predicted energy/force). Select structures with highest disagreement.
      Configurable: selection batch size, disagreement metric (energy, max
      force, mean force)
- [x] **121.6.2.2** Implement ensemble disagreement: similar to committee but
      using single model with MC dropout. At inference time, apply dropout
      multiple times (T=20-50 forward passes), compute mean and variance of
      predictions. High variance = high uncertainty. More compute-efficient than
      full committee
- [x] **121.6.2.3** Implement D-optimality selection: select structures that
      maximize the determinant of the information matrix X^T X (in descriptor
      space). Equivalent to maximizing the volume of the confidence ellipsoid.
      Use greedy algorithm: iteratively add structure that maximally increases
      det(X^T X)
- [x] **121.6.2.4** Implement MaxVol submatrix selection: select structures
      whose descriptor vectors form a maximum-volume submatrix of the full
      descriptor matrix. Use the MaxVol algorithm (alternating optimization).
      Related to D-optimality but with different optimization strategy
- [x] **121.6.2.5** Implement farthest-point sampling in descriptor space:
      iteratively select the structure whose descriptor is farthest (in
      Euclidean or kernel distance) from all previously selected structures.
      Good for initial coverage of configuration space before switching to
      uncertainty-based selection

#### 121.6.3 Dataset Construction

- [x] **121.6.3.1** Implement random displacement generator: given an
      equilibrium structure, generate perturbed structures by displacing atoms
      with Gaussian noise (sigma = 0.01-0.1 A). Reject unphysical configurations
      (atoms too close). Generate configurable number of displaced structures
      per seed
- [x] **121.6.3.2** Implement MD snapshot sampler: run short MD trajectories
      (NVT/NPT) at multiple temperatures using current ML potential or classical
      force field. Save snapshots at regular intervals. Sample from low-T
      (harmonic regime) through high-T (anharmonic regime) trajectories
- [x] **121.6.3.3** Implement rattled structure generator: apply random
      displacements following a Maxwell-Boltzmann distribution at a target
      temperature. More physically motivated than uniform Gaussian noise.
      Support element-specific displacement magnitudes (heavier atoms = smaller
      displacements)
- [x] **121.6.3.4** Implement strained cell generator: apply uniform volumetric
      strain (-5% to +5%), uniaxial strain along each axis, and shear strain to
      the unit cell. Generate structures at each strain level. Essential for
      training stress predictions and elastic property accuracy
- [x] **121.6.3.5** Implement data augmentation: apply random rotations and
      reflections to structures (preserves physics but increases diversity for
      non-equivariant models). Apply random permutations of equivalent atoms.
      For equivariant models, augmentation is unnecessary by construction —
      detect and skip
- [x] **121.6.3.6** Implement on-the-fly ML training during MD (VASP ML_FF
      style): during MD simulation, maintain an ML model that is periodically
      retrained. At each step, predict with ML model. If uncertainty exceeds
      threshold, pause MD, run DFT for current configuration, add to training
      set, retrain, resume MD. Log DFT/ML ratio over simulation time

#### 121.6.4 Data Quality

- [x] **121.6.4.1** Implement outlier detection: identify training structures
      with anomalously high loss (energy or force error > 5 sigma from mean).
      Flag for manual inspection — may indicate DFT convergence failure, wrong
      magnetic state, or data corruption. Compute Cook's distance for influence
      analysis
- [x] **121.6.4.2** Implement data cleaning pipeline: remove duplicate
      structures (within RMSD tolerance), filter structures with unphysical
      energies (above convex hull by > 5 eV/atom), remove structures with SCF
      convergence issues (from DFT logs). Report cleaning statistics
- [x] **121.6.4.3** Implement stratified sampling validator: check that training
      set covers the intended composition/structure space uniformly. Report
      coverage gaps (compositions with < N representatives, structure types with
      < M examples). Suggest targeted DFT calculations to fill gaps

---

### 121.7 Crystal Graph Neural Networks — Property Prediction (`@kalika/crystal-gnn`)

#### 121.7.1 Graph Construction

- [x] **121.7.1.1** Implement distance-based graph construction: given a crystal
      structure, build graph with atoms as nodes and edges connecting atoms
      within distance cutoff r_c (default 8.0 A). Handle periodic boundary
      conditions (include image atoms). Return adjacency list with edge
      distances and offset vectors. Deduplicate self-loops
- [x] **121.7.1.2** Implement Voronoi-based graph construction: construct
      Voronoi tessellation of the crystal structure, create edges between atoms
      sharing a Voronoi face. Edge weight = solid angle of shared face /
      distance. Advantage: adaptive connectivity without arbitrary cutoff
- [x] **121.7.1.3** Implement k-nearest-neighbor graph construction: connect
      each atom to its k nearest neighbors (default k=12). Handle periodic
      images. More uniform connectivity than distance cutoff but may miss
      important longer-range interactions
- [x] **121.7.1.4** Implement line graph construction (for ALIGNN): given the
      crystal graph G, construct line graph L(G) where nodes of L(G) are edges
      of G, and edges of L(G) connect two edges of G that share a node. Include
      bond angle as edge feature in L(G). Handle periodic boundary conditions
      correctly

#### 121.7.2 Feature Engineering for Graph Networks

- [x] **121.7.2.1** Implement node (atom) feature vector: one-hot element
      encoding (up to 100 elements), atomic number, electronegativity (Pauling),
      covalent radius, atomic mass, ionization energy, electron affinity, group,
      period, block (s/p/d/f one-hot), valence electron count, oxidation states.
      Configurable which features to include. Default dimension ~92
- [x] **121.7.2.2** Implement edge (bond) feature vector: Gaussian expansion of
      interatomic distance (N Gaussians with centers 0-8 A, sigma=0.5 A, default
      N=80), bond type estimate (ionic/covalent/metallic from electronegativity
      difference), Voronoi solid angle (if Voronoi graph). Support learnable
      distance expansion
- [x] **121.7.2.3** Implement angle feature vector (for DimeNet/GemNet/ALIGNN):
      spherical Bessel expansion of bond angle theta (J Bessel functions,
      default J=8), Fourier expansion of dihedral angle phi, and joint
      radial-angular basis (distance \* angle)
- [x] **121.7.2.4** Implement global (state) feature vector: composition-level
      features — average electronegativity, electronegativity range, average
      ionic radius, packing fraction, number of elements, total electrons. Used
      as global conditioning in MEGNet

#### 121.7.3 CGCNN (Crystal Graph Convolutional Neural Network)

- [x] **121.7.3.1** Implement CGCNN convolution layer: for each atom i,
      z*i^{(t+1)} = z_i^{(t)} + sum_j sigma(z_i^{(t)} W_f + z_j^{(t)} W_f +
      e*{ij} V*f + b_f) \* g(z_i^{(t)} W_s + z_j^{(t)} W_s + e*{ij} V*s + b_s)
      where sigma is sigmoid, g is softplus, e*{ij} is edge feature, W and V are
      learnable weights. Stack R convolution layers (default R=3)
- [x] **121.7.3.2** Implement CGCNN pooling and readout: average pool atom
      features across all atoms in the unit cell to get a fixed-length crystal
      representation. Apply two-layer MLP with dropout to predict target
      property. Support both regression (formation energy, band gap) and
      classification (metal/insulator)
- [x] **121.7.3.3** Implement iCGCNN (improved CGCNN): extend CGCNN with
      Voronoi-based graph, additional node features (coordination number, local
      geometry descriptor), edge features (Voronoi solid angle, face area), and
      batch normalization. Typically 5-10% better than vanilla CGCNN

#### 121.7.4 MEGNet (MatErials Graph Network)

- [x] **121.7.4.1** Implement MEGNet graph network layer: update edges via MLP
      using [e_ij, v_i, v_j, u] (edge feature, sender node, receiver node,
      global state). Update nodes by aggregating (mean) updated edge features
      from neighbors + MLP with [v_i, mean(e_ij), u]. Update global state via
      MLP with [u, mean(v_i), mean(e_ij)]. This is the full Graph Network
      architecture from Battaglia et al.
- [x] **121.7.4.2** Implement MEGNet full model: initial embedding (atom, bond,
      state) → 3 graph network layers → Set2Set pooling (attention-based
      aggregation, more expressive than mean pooling) → MLP readout. Support
      multi-target prediction by sharing graph network backbone with
      task-specific readout heads
- [x] **121.7.4.3** Implement MEGNet formation energy model: configure MEGNet
      for formation energy prediction. Include elemental reference energy
      subtraction (E_f = E_total - sum_i n_i \* E_i_ref). Validate against
      Materials Project formation energies (test MAE < 40 meV/atom on MP
      benchmark)

#### 121.7.5 ALIGNN (Atomistic Line Graph Neural Network)

- [x] **121.7.5.1** Implement ALIGNN edge-gated graph convolution: compute edge
      gates g_ij = sigmoid(MLP(e_ij)), update node features via x_i = x_i +
      sum_j g_ij \* MLP(x_j). The gating mechanism allows the network to weight
      messages by bond strength/type
- [x] **121.7.5.2** Implement ALIGNN alternating update scheme: alternate
      between atom graph convolution (update atom features using bond
      information) and line graph convolution (update bond features using angle
      information). 4 alternating layers (default). The line graph pass is what
      distinguishes ALIGNN from other GNNs — it explicitly models angular
      interactions
- [x] **121.7.5.3** Implement ALIGNN full model with multi-task readout: atom
      graph + line graph construction → ALIGNN layers → mean pooling → separate
      MLPs for each target property. Support joint training on formation energy,
      band gap, bulk modulus, shear modulus with task-specific loss weights

#### 121.7.6 Multi-Task & Interpretability

- [x] **121.7.6.1** Implement multi-task crystal property predictor: shared GNN
      backbone (CGCNN, MEGNet, or ALIGNN) with separate readout heads for each
      property. Joint training with task-specific loss weights and gradient
      normalization (GradNorm) to balance learning across tasks. Support
      regression and classification tasks simultaneously
- [x] **121.7.6.2** Implement atom importance / attribution: given a trained GNN
      and a prediction, compute per-atom contribution to the prediction via (a)
      gradient-based saliency (|dProperty/dAtomFeature|), (b) integrated
      gradients, (c) attention weights (if attention-based model), (d) SHAP
      values via KernelSHAP. Visualize important atoms on the crystal structure
- [x] **121.7.6.3** Implement uncertainty quantification for property
      prediction: ensemble (5 models with different seeds), MC dropout (T=30
      forward passes), evidential regression (predict mean + variance directly).
      Calibration analysis: plot predicted uncertainty vs actual error, compute
      calibration metrics (ENCE, PICP). Flag predictions with high uncertainty

---

### 121.8 Generative Models for Materials Design (`@kalika/generative-materials`)

#### 121.8.1 Crystal Diffusion Variational Autoencoder (CDVAE)

- [x] **121.8.1.1** Implement CDVAE encoder: GNN-based encoder that maps a
      crystal structure (atom types, fractional coordinates, lattice parameters)
      to a latent space z. Use multi-layer GNN (similar to DimeNet++) operating
      on the periodic crystal graph. Output: mean and log-variance for
      variational inference (VAE reparameterization trick)
- [x] **121.8.1.2** Implement CDVAE decoder — composition predictor: from latent
      z, predict the number of atoms N and the composition (element type per
      atom) using a classifier head. Apply charge neutrality constraint as a
      post-processing step
- [x] **121.8.1.3** Implement CDVAE decoder — lattice predictor: from latent z,
      predict lattice parameters (a, b, c, alpha, beta, gamma) using an MLP.
      Enforce positive lengths and valid angles (0 < alpha, beta, gamma < 180).
      Optionally predict in terms of lattice vector components directly
- [x] **121.8.1.4** Implement CDVAE decoder — coordinate denoising diffusion:
      starting from noisy coordinates (Gaussian noise on fractional positions),
      iteratively denoise using a score network conditioned on z. T diffusion
      steps (default T=1000). The score network is a GNN that predicts the noise
      to remove at each step. Handle periodicity (wrap coordinates to [0,1])
- [x] **121.8.1.5** Implement CDVAE training: ELBO loss = reconstruction loss
      (composition cross-entropy + coordinate MSE + lattice MSE) + KL
      divergence + diffusion score matching loss. Two-stage training: first
      train encoder/decoder without diffusion, then fine-tune with diffusion.
      Validate by generating structures and checking validity metrics
- [x] **121.8.1.6** Implement CDVAE generation pipeline: sample z from prior
      N(0,I) → predict composition → predict lattice → run diffusion denoising →
      output crystal structure. Support conditional generation (fix composition
      or lattice and generate coordinates, or fix z neighborhood for
      interpolation). Generate batch of N candidates

#### 121.8.2 DiffCSP (Diffusion for Crystal Structure Prediction)

- [x] **121.8.2.1** Implement DiffCSP joint diffusion process: simultaneously
      diffuse lattice parameters (in lattice matrix representation) and
      fractional coordinates. Forward process adds noise, reverse process
      denoises. Handle periodicity of fractional coordinates via wrapped normal
      distribution on torus [0,1)^3
- [x] **121.8.2.2** Implement DiffCSP score network: equivariant GNN that
      predicts score (gradient of log probability) for both coordinates and
      lattice at each diffusion timestep t. Condition on composition (atom types
      are fixed). Use multi-resolution time embedding
- [x] **121.8.2.3** Implement DiffCSP sampling: given composition (element types
      and counts), sample initial noisy coordinates and lattice from prior → run
      reverse diffusion for T steps → output predicted crystal structure.
      Support multiple samples per composition for ensemble prediction

#### 121.8.3 Other Generative Architectures

- [x] **121.8.3.1** Implement crystal VAE: variational autoencoder operating on
      crystal graph representation. Encoder: GNN → latent z. Decoder: z → atom
      types (categorical) + coordinates (continuous) + lattice (continuous).
      Loss: ELBO with reconstruction + KL. Simpler than CDVAE but less powerful
      for coordinate generation
- [x] **121.8.3.2** Implement crystal GAN: generator maps random noise z →
      crystal features (composition, lattice, coordinates). Discriminator
      classifies real vs generated crystals. Use Wasserstein GAN with gradient
      penalty for training stability. Condition on target property for
      property-directed generation
- [x] **121.8.3.3** Implement normalizing flow for crystal generation:
      invertible neural network mapping between simple prior and crystal
      distribution. Use coupling layers adapted for periodic coordinates.
      Advantage: exact likelihood computation. Handle variable atom count via
      padding + masking
- [x] **121.8.3.4** Implement reinforcement learning for materials design: agent
      proposes crystal modifications (element substitution, lattice distortion,
      atom addition/removal), environment evaluates using ML surrogate (GNN
      property predictor), reward = target property value. Policy gradient
      (REINFORCE) or PPO optimization. Constraint penalties for unphysical
      structures

#### 121.8.4 Inverse Design & Validation

- [x] **121.8.4.1** Implement inverse design pipeline: given target property
      constraints (e.g., band gap 1.0-1.5 eV, formation energy < -1.0 eV/atom),
      use generative model conditioned on targets to propose candidate
      structures. Rank by ML-predicted properties. Filter by validity checks.
      Output top-K candidates with confidence scores
- [x] **121.8.4.2** Implement constraint satisfaction checker: verify generated
      structures satisfy physical constraints — (a) charge neutrality (sum of
      oxidation states = 0), (b) Pauling rules (coordination consistent with
      radius ratios), (c) composition constraints (valid stoichiometry), (d)
      minimum interatomic distance (> 0.5 \* sum of covalent radii), (e)
      reasonable density (within 3x of known materials)
- [x] **121.8.4.3** Implement structure validity metrics: (a) validity rate
      (fraction of generated structures passing physical checks), (b) coverage
      (fraction of test-set structure types represented in generated set), (c)
      novelty (fraction of generated structures not in training set, by
      structure matching), (d) uniqueness (fraction of non-duplicate generated
      structures). Report all four for model evaluation
- [x] **121.8.4.4** Implement diversity metrics: (a) compositional diversity
      (number of distinct compositions in generated set), (b) structural
      diversity (average pairwise RMSD between generated structures), (c)
      property diversity (range and standard deviation of predicted properties),
      (d) crystal system diversity (distribution over 7 crystal systems).
      Compare against training set distribution

---

### 121.9 High-Throughput Screening Pipelines (`@kalika/screening`)

#### 121.9.1 Workflow Engine

- [x] **121.9.1.1** Implement `ScreeningPipeline` class: define a sequential
      funnel of screening stages, each with a filter criterion and a calculator.
      Structures flow through stages — each stage filters or ranks, reducing the
      candidate set. Configurable: stage order, filter thresholds, calculator
      (ML model, analytical formula, or DFT callback). Track provenance (which
      stage admitted/rejected each candidate)
- [x] **121.9.1.2** Implement `ScreeningStage` interface: `evaluate(structures)`
      → `{ passed: Structure[], failed: Structure[], scores: Map }`. Support
      filter stages (binary pass/fail based on threshold), ranking stages (score
      and take top-K), and compute stages (add new properties to structure
      metadata without filtering)
- [x] **121.9.1.3** Implement pipeline execution engine: run stages
      sequentially, passing filtered output of stage N as input to stage N+1.
      Support parallel evaluation within a stage (batch processing). Report
      funnel statistics at each stage (input count, pass rate, wall time). Save
      intermediate results for resume-on-failure
- [x] **121.9.1.4** Implement pipeline result aggregator: collect all candidates
      that pass the full funnel, with all computed properties, stage-by-stage
      scores, and provenance. Export as CSV, JSON, or to results database.
      Generate summary statistics and distribution plots for key properties

#### 121.9.2 Composition Space Enumeration

- [x] **121.9.2.1** Implement element substitution generator: given a prototype
      structure (e.g., perovskite ABX3), enumerate candidate compositions by
      substituting each site with compatible elements (respecting oxidation
      state, ionic radius range, electronegativity constraints). Generate all
      valid A-B-X combinations for a given prototype
- [x] **121.9.2.2** Implement prototype filling: given a crystal structure
      prototype (Strukturbericht or AFLOW prototype), fill Wyckoff positions
      with elements from a specified pool, respecting charge neutrality and site
      multiplicity. Enumerate all combinatorially valid fillings
- [x] **121.9.2.3** Implement alloy composition sampling: for multi-component
      alloys (e.g., high-entropy alloys), sample composition space uniformly
      using Dirichlet distribution or grid sampling on the composition simplex.
      Generate special quasi-random structures (SQS) at each composition using
      the mcsqs algorithm (or imported SQS from Phase 117)
- [x] **121.9.2.4** Implement composition filter: given a pool of candidate
      compositions, filter by (a) element availability/cost, (b) toxicity
      (exclude Cd, Tl, Pb optionally), (c) radioactivity (exclude Tc, Pm,
      actinides optionally), (d) known stable compounds in ICSD/MP (prefer novel
      compositions), (e) charge neutrality with common oxidation states

#### 121.9.3 Stability Screening

- [x] **121.9.3.1** Implement convex hull construction: given formation energies
      for a set of compositions in a chemical system (e.g., Li-Fe-O), construct
      the convex hull in composition-energy space using QHull. Identify stable
      phases (on the hull) and metastable phases (above the hull). Compute
      energy above hull (E_hull) for each candidate
- [x] **121.9.3.2** Implement stability filter: pass candidates with E_hull
      below threshold (default < 50 meV/atom for thermodynamically accessible
      metastability). Support ML-predicted formation energies (from GNN property
      predictor) for fast screening, with DFT refinement for promising
      candidates
- [x] **121.9.3.3** Implement decomposition analysis: for each candidate,
      compute the decomposition products (which stable phases it would decompose
      into) and the decomposition energy. Identify decomposition pathway. Flag
      candidates that decompose into hazardous or volatile products

#### 121.9.4 Electronic Screening

- [x] **121.9.4.1** Implement band gap filter: predict band gap using ML model
      (GNN), filter by target range (e.g., 1.0-2.0 eV for photovoltaics, > 3.0
      eV for wide-gap semiconductors, 0 for metals). Support direct vs indirect
      gap classification
- [x] **121.9.4.2** Implement effective mass estimator: from ML-predicted band
      structure (or analytical model), estimate electron and hole effective
      masses. Filter by mobility criterion (low effective mass = high mobility).
      Support isotropic and anisotropic effective mass tensors
- [x] **121.9.4.3** Implement electronic screening composite: combine band gap,
      effective mass, and dielectric constant predictions into application-
      specific figures of merit — photovoltaic efficiency (Shockley-Queisser
      limit), thermoelectric power factor, transparent conductor figure of merit

#### 121.9.5 Mechanical Screening

- [x] **121.9.5.1** Implement elastic stability filter: predict elastic
      constants (via ML or analytical model), check Born stability criteria
      (positive definite elastic constant matrix for the crystal system). Reject
      mechanically unstable candidates
- [x] **121.9.5.2** Implement mechanical property filter: from elastic
      constants, compute Voigt-Reuss-Hill averages of bulk modulus K, shear
      modulus G, Young's modulus E, Poisson's ratio v. Filter by target ranges
      (e.g., K > 100 GPa for hard materials, v < 0.3 for auxetic candidates).
      Compute Pugh ratio (K/G) for ductility/brittleness classification

#### 121.9.6 Thermodynamic Screening

- [x] **121.9.6.1** Implement phonon stability filter: predict phonon band
      structure using ML potential (from Phase 119 integration) or surrogate
      model. Check for imaginary frequencies (dynamical instability). Pass only
      structures with all-positive phonon frequencies. Allow soft modes below a
      tolerance (e.g., imaginary frequency < 0.5 THz may be numerical artifact)
- [x] **121.9.6.2** Implement thermal stability estimator: from phonon density
      of states, estimate Debye temperature. From formation energy and entropy
      estimates, predict stability at operating temperature using quasi-harmonic
      free energy. Filter candidates stable above minimum operating temperature

#### 121.9.7 Multi-Objective Optimization

- [x] **121.9.7.1** Implement Pareto front construction: given candidates with
      multiple computed properties, identify the Pareto-optimal set (no
      candidate dominates another on all objectives). Support 2-objective,
      3-objective, and N-objective Pareto analysis. Visualize 2D and 3D Pareto
      fronts
- [x] **121.9.7.2** Implement Bayesian optimization for targeted search: given a
      surrogate model (GNN predictor) and a target property, use Bayesian
      optimization (Gaussian process + expected improvement acquisition
      function) to efficiently search composition/structure space. Support
      multi-objective BO (expected hypervolume improvement). Batch BO for
      parallel evaluation
- [x] **121.9.7.3** Implement results database: store screening results with
      full provenance — candidate structure, all computed properties, screening
      stage results, ML model versions, DFT parameters (if DFT was used). Query
      by property ranges, composition, structure type. Export to Materials
      Project-compatible format

#### 121.9.8 DFT Job Generation

- [x] **121.9.8.1** Implement batch DFT input generator: for candidates passing
      ML screening, generate DFT input files — VASP INCAR/POSCAR/KPOINTS/POTCAR
      templates, Quantum ESPRESSO input files, or ABINIT input files. Apply
      standardized settings (PBE functional, sufficient k-mesh, appropriate
      cutoff). Generate job submission scripts for HPC clusters
- [x] **121.9.8.2** Implement DFT result parser: parse completed DFT
      calculations (VASP vasprun.xml, QE output, ABINIT output), extract energy,
      forces, stress, band gap, density of states. Add parsed results back to
      screening database. Flag failed calculations for re-submission with
      adjusted parameters

---

### 121.10 Materials Descriptors & Feature Engineering (`@kalika/materials-features`)

#### 121.10.1 Compositional Descriptors

- [x] **121.10.1.1** Implement Magpie feature generator: for a given
      composition, compute the 145 Magpie features — statistics (mean, std, min,
      max, range, mode) of elemental properties (atomic number, Mendeleev
      number, atomic weight, melting point, column, row, covalent radius,
      electronegativity, NSvalence, NPvalence, NDvalence, NFvalence, NValence,
      NsUnfilled, NpUnfilled, NdUnfilled, NfUnfilled, NUnfilled, GSvolume_pa,
      GSbandgap, GSmagmom, SpaceGroupNumber). Include stoichiometry-weighted and
      unweighted variants
- [x] **121.10.1.2** Implement element property statistics: given composition
      and a property table (electronegativity, radius, ionization energy, etc.),
      compute statistical descriptors: weighted mean, weighted std, min, max,
      range, mode, geometric mean, harmonic mean, entropy of mixing, Herfindahl
      index (concentration measure). Support custom property tables
- [x] **121.10.1.3** Implement composition-based feature vector: combine Magpie
      features, element property statistics, stoichiometric features (number of
      elements, entropy of mixing, fraction of s/p/d/f elements), and valence
      electron counts into a unified feature vector. Configurable which feature
      groups to include. Default: all groups, ~250 features

#### 121.10.2 Structural Descriptors

- [x] **121.10.2.1** Implement packing fraction descriptor: compute atomic
      packing fraction (sum of atomic sphere volumes / cell volume) using
      covalent, ionic, or van der Waals radii. Compute Voronoi cell volumes for
      each atom and site-specific packing efficiency
- [x] **121.10.2.2** Implement Voronoi tessellation features: for each atom,
      compute Voronoi cell and extract: coordination number, Voronoi cell
      volume, face areas (distribution statistics), solid angles (distribution
      statistics), effective coordination number (entropy-based). Aggregate to
      structure-level via mean/std/min/max pooling
- [x] **121.10.2.3** Implement bond statistics features: compute all pairwise
      distances within cutoff, group by element pair, compute per-pair
      statistics (mean bond length, std, min, max, count). Compute global bond
      order parameter and distortion index (deviation from ideal coordination
      geometry)
- [x] **121.10.2.4** Implement structural complexity descriptors: Shannon
      information entropy of the crystal structure (based on Wyckoff
      multiplicities), topological complexity index, number of symmetry-
      inequivalent sites, space group number as categorical feature

#### 121.10.3 Electronic & Orbital Descriptors

- [x] **121.10.3.1** Implement orbital field matrix (OFM): construct matrix
      where rows and columns correspond to valence orbital types (s, p, d, f)
      and entries are sums of orbital-orbital interactions weighted by
      coordination. Flatten to vector as structural fingerprint. Captures
      electronic structure without DFT
- [x] **121.10.3.2** Implement sine/cosine matrix (periodic structure
      fingerprint): extension of Coulomb matrix to periodic structures — replace
      1/r*{ij} with functions of the fractional coordinate differences using
      sine/cosine to handle periodicity: M*{ij} = Z*i * Z*j * [sin^2(pi * dx/a)
      + sin^2(pi * dy/b) + sin^2(pi * dz/c)]^{-1}. Eigenvalue spectrum as
      fingerprint
- [x] **121.10.3.3** Implement JARVIS-CFID descriptors: Classical Force-Field
      Inspired Descriptors from JARVIS-ML. Include radial distribution function
      features, angular distribution function features, dihedral distribution
      features, and nearest-neighbor statistics. ~1557 features per structure

#### 121.10.4 Spectral Fingerprints

- [x] **121.10.4.1** Implement XRD pattern fingerprint: simulate powder X-ray
      diffraction pattern (from Phase 117 structure factor calculation),
      discretize on 2-theta grid (5-90 degrees, 0.1 degree resolution), and use
      as fingerprint vector. Normalize by maximum intensity. Include Gaussian
      peak broadening. Use for structure similarity and duplicate detection
- [x] **121.10.4.2** Implement RDF fingerprint: compute pair distribution
      function g(r), discretize on radial grid (0-10 A, 0.1 A bins), use as
      fingerprint. Per-element-pair variants for multi-component systems. Smooth
      with Gaussian kernel

#### 121.10.5 Feature Selection & Model Selection

- [x] **121.10.5.1** Implement mutual information feature selection: compute
      mutual information I(feature_i; target) for each feature, rank by
      relevance. Account for feature-feature redundancy using minimum Redundancy
      Maximum Relevance (mRMR) criterion. Return selected feature subset
- [x] **121.10.5.2** Implement L1 regularization feature selection: train linear
      model (LASSO) with L1 penalty, use non-zero coefficients to identify
      important features. Sweep regularization strength via cross-validation.
      Return features with non-zero weight at optimal lambda
- [x] **121.10.5.3** Implement recursive feature elimination (RFE): train model,
      remove least important feature (by weight magnitude or permutation
      importance), retrain, repeat until desired feature count reached. Report
      accuracy vs feature count curve
- [x] **121.10.5.4** Implement SHAP-based feature importance: compute SHAP
      values for each feature using TreeSHAP (for tree models) or KernelSHAP
      (for any model). Report global feature importance (mean |SHAP|),
      interaction effects, and per-prediction explanations
- [x] **121.10.5.5** Implement cross-validated model selection: compare Random
      Forest, Gradient Boosting (XGBoost/LightGBM), kernel ridge regression, and
      neural network on the feature matrix. Use nested cross-validation (inner
      loop for hyperparameter tuning, outer loop for performance estimation).
      Report test metrics (MAE, RMSE, R^2) with confidence intervals

---

### 121.11 Benchmarking & Validation (`@kalika/ml-benchmarks`)

#### 121.11.1 MatBench Benchmark Suite

- [x] **121.11.1.1** Implement MatBench data loader: load the 13 MatBench
      benchmark tasks from JSON/CSV — (1) phonons (last phonon peak), (2) jdft2d
      (exfoliation energy), (3) dielectric (refractive index), (4) log_gvrh
      (log10 shear modulus), (5) log_kvrh (log10 bulk modulus), (6) perovskites
      (formation energy), (7) mp_gap (band gap), (8) mp_e_form (formation
      energy), (9) mp_is_metal (metal/insulator), (10) glass (metallic glass
      formability), (11) expt_gap (experimental band gap), (12) expt_is_metal
      (experimental metal/insulator), (13) steels (yield strength). Parse
      structures and targets, provide 5-fold cross-validation splits matching
      official splits
- [x] **121.11.1.2** Implement MatBench evaluation harness: for each task, train
      model on training split, predict on test split, compute metrics (MAE for
      regression, AUC-ROC for classification). Average over 5 folds. Report
      results in MatBench leaderboard format. Compare against published
      baselines (CGCNN, MEGNet, ALIGNN, coGN, coNGN, MODNet)
- [x] **121.11.1.3** Implement MatBench result submission formatter: generate
      JSON output conforming to MatBench submission format for inclusion in the
      official leaderboard. Include model description, hyperparameters, per-fold
      predictions, and aggregate metrics

#### 121.11.2 ML Potential Accuracy Benchmarks

- [x] **121.11.2.1** Implement energy-volume curve benchmark: for each test
      structure, compute energy at 11 volumes (0.90 to 1.10 of equilibrium, 2%
      steps) using ML potential and DFT reference. Fit Birch-Murnaghan EOS to
      both curves. Compare equilibrium volume V_0, bulk modulus K_0, and K_0'
      (pressure derivative). Report relative errors
- [x] **121.11.2.2** Implement force/stress accuracy benchmark: on held-out test
      set, compute MAE and RMSE for (a) per-atom forces (eV/A), (b) stress
      tensor components (kBar), (c) per-atom energy (eV/atom). Report overall
      and per-element breakdown. Generate parity plots (ML predicted vs DFT
      reference)
- [x] **121.11.2.3** Implement training curve analysis: train ML potential on
      subsets of increasing size (10%, 20%, ..., 100% of training data).
      Evaluate on fixed test set at each size. Plot accuracy vs training set
      size. Quantify data efficiency (how much data needed to reach target
      accuracy). Compare data efficiency across model architectures
- [x] **121.11.2.4** Implement extrapolation test: evaluate ML potential on
      structures outside the training distribution — (a) unseen compositions
      (elements not in training set), (b) extreme pressures (compressed/
      expanded cells beyond training range), (c) high-temperature MD snapshots
      (beyond training temperature range), (d) defective structures (vacancies,
      interstitials not in training). Report accuracy degradation and
      uncertainty increase

#### 121.11.3 Phonon Benchmark

- [x] **121.11.3.1** Implement phonon dispersion benchmark: compute phonon
      dispersion curves using ML potential (finite displacement method from
      Phase 119) for a set of benchmark structures (Si, GaAs, NaCl, MgO, Al, Cu,
      diamond, BN, SiC). Compare against DFT reference phonon dispersions.
      Report band-by-band frequency RMSE and visual overlay plots
- [x] **121.11.3.2** Implement phonon DOS benchmark: compute phonon density of
      states from ML potential and DFT. Compare peak positions, peak widths, and
      integrated quantities (Debye temperature, heat capacity at 300 K,
      zero-point energy). Report percent errors

#### 121.11.4 MD Stability Benchmark

- [x] **121.11.4.1** Implement MD stability test: run NVT molecular dynamics for
      100 ps at target temperature (e.g., 300 K, 1000 K) using ML potential.
      Monitor for unphysical events: (a) atoms closer than 0.5 A, (b) energy
      drift > 1 meV/atom/ps, (c) temperature deviation > 20% from target, (d)
      bond breaking (coordination number change > 2), (e) cell explosion (volume
      increase > 50%). Report pass/fail and time-to-failure for each criterion
- [x] **121.11.4.2** Implement long-time stability test: run NVE MD for 1 ns
      with ML potential. Monitor total energy conservation (drift per ns).
      Compare energy conservation against classical force field (reference) and
      assess whether ML potential is suitable for long dynamical simulations
- [x] **121.11.4.3** Implement elevated-temperature stability test: run NVT MD
      at progressively increasing temperatures (300 K → 3000 K in 100 K steps)
      for 10 ps each. Identify temperature at which ML potential becomes
      unstable (melting is fine, unphysical events are not). Report maximum
      stable temperature for each test structure

#### 121.11.5 Cross-Model Comparison

- [x] **121.11.5.1** Implement model comparison framework: given multiple
      trained ML potentials (different architectures, hyperparameters, or
      training data), evaluate all on the same benchmark suite. Generate
      comparison table with accuracy (energy MAE, force MAE, stress MAE), speed
      (inference ms/atom), memory usage (MB for 1000-atom cell), and training
      cost (GPU-hours). Rank models by Pareto optimality (accuracy vs speed)
- [x] **121.11.5.2** Implement statistical significance testing: for each pair
      of models, compute paired t-test or Wilcoxon signed-rank test on
      per-structure errors. Report p-values and effect sizes. Correct for
      multiple comparisons (Bonferroni). Flag differences that are statistically
      significant at p < 0.05
- [x] **121.11.5.3** Implement benchmark report generator: compile all benchmark
      results into a structured report — tables, parity plots, learning curves,
      error distributions, stability timelines. Export as JSON
      (machine-readable) and HTML (human-readable) with interactive plots
      (Plotly)

---
