Eve library

phase-121.md

Tracker

Revision 1

On this page

Historical task source. The Eve task board holds current task state.

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#

  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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)#

  • 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
  • 121.2.1.2 Implement G2 radial symmetry function: G2i = sum_j exp(-eta * (rij - R_s)^2) * f_c(r_ij). Parameterized by eta (Gaussian width) and R_s (center). Include analytic gradient for forces
  • 121.2.1.3 Implement G3 radial symmetry function (cosine variant): G3i = sum_j cos(kappa * rij) * f_c(r_ij). Include gradient
  • 121.2.1.4 Implement G4 angular symmetry function: G4i = 2^(1-zeta) * sum{j,k} (1 + lambda _ cos(theta_ijk))^zeta _ exp(-eta _ (r_ij^2 + r_ik^2 + r_jk^2)) _ fc(r_ij) * fc(r_ik) * f_c(r_jk). Parameterized by lambda (+/-1), zeta, eta. Include gradient
  • 121.2.1.5 Implement G5 angular symmetry function (narrow variant, excludes rjk 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
  • 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
  • 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
  • 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)#

  • 121.2.2.1 Implement SOAP density expansion: represent atomic neighbor density rhoi(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
  • 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
  • 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
  • 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
  • 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
  • 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)#

  • 121.2.3.1 Implement ACE basis functions: one-particle basis phi_{znlm}(rij) = R_nl(r_ij) * Yl^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
  • 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
  • 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.)
  • 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
  • 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#

  • 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)
  • 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)
  • 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#

  • 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
  • 121.2.5.2 Implement Coulomb matrix: construct matrix C_{ij} = Zi * Zj / |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
  • 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)
  • 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#

  • 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
  • 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
  • 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
  • 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
  • 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)
  • 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#

  • 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
  • 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)#

  • 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
  • 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
  • 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
  • 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)
  • 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
  • 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)
  • 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#

  • 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
  • 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
  • 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
  • 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"
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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)
  • 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
  • 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
  • 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
  • 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)
  • 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)#

  • 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
  • 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 = (KMM + K_MN * KNM / sigma^2)^{-1} * K_MN * y / sigma^2. Use Cholesky factorization for numerical stability. Compute predictive mean and variance for new points
  • 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
  • 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
  • 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
  • 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#

  • 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)
  • 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
  • 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)#

  • 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)
  • 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
  • 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#

  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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)#

  • 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
  • 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
  • 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)#

  • 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
  • 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
  • 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#

  • 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)
  • 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#

  • 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)
  • 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
  • 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#

  • 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
  • 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
  • 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#

  • 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)
  • 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
  • 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)
  • 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
  • 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#

  • 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
  • 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
  • 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)
  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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)
  • 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)#

  • 121.7.3.1 Implement CGCNN convolution layer: for each atom i, zi^{(t+1)} = z_i^{(t)} + sum_j sigma(z_i^{(t)} W_f + z_j^{(t)} W_f + e{ij} Vf + b_f) * g(z_i^{(t)} W_s + z_j^{(t)} W_s + e{ij} Vs + 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)
  • 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)
  • 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)#

  • 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.
  • 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
  • 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)#

  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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)#

  • 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)
  • 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
  • 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
  • 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])
  • 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
  • 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)#

  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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)
  • 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
  • 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#

  • 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)
  • 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)
  • 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
  • 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#

  • 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
  • 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
  • 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)
  • 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#

  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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#

  • 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
  • 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#

  • 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)
  • 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#

  • 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
  • 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
  • 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#

  • 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
  • 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#

  • 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
  • 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
  • 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#

  • 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
  • 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
  • 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)
  • 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#

  • 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
  • 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} = Zi * Zj * [sin^2(pi * dx/a) + sin^2(pi * dy/b) + sin^2(pi * dz/c)]^{-1}. Eigenvalue spectrum as fingerprint
  • 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#

  • 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
  • 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#

  • 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
  • 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
  • 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
  • 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
  • 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#

  • 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
  • 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)
  • 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#

  • 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
  • 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)
  • 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
  • 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#

  • 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
  • 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#

  • 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
  • 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
  • 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#

  • 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)
  • 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
  • 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)