Historical task source. The Eve task board holds current task state.
<!-- prettier-ignore-start -->
Phase 125: Kalika Thermodynamics & Phase Diagrams — CALPHAD, Cluster Expansion, Phase Diagram Computation, Alloy Thermodynamics & Solution Models#
Builds the thermodynamic modeling and phase diagram computation stack for materials science. Covers Gibbs energy models (ideal/regular/sub-regular solutions, compound energy formalism, quasichemical models), phase equilibrium solvers (global minimization, tangent plane criterion, Newton-Raphson for CALPHAD), phase diagram mapping for binary through multicomponent systems, thermodynamic database I/O (TDB/PanDat/FactSage), cluster expansion with Monte Carlo for first-principles phase diagrams, ab initio thermodynamics bridging DFT to finite-temperature stability, DICTRA-style diffusion modeling, classical nucleation theory with precipitation kinetics, and solidification simulation (Scheil, back-diffusion, dendrite tip kinetics). Targets parity with Thermo-Calc, OpenCalphad, pyCalphad, ATAT, and MatCalc.
125.1 Scaffolding & Core Types (@kalika/thermodynamics)#
125.1.1 Project Setup#
- 125.1.1.1 Create
libs/kalika/thermodynamics/withproject.json,package.json(name:@kalika/thermodynamics),tsconfig.json, andtsconfig.lib.json— configure Nx build with esbuild executor, vitest for testing, and path mapping intsconfig.base.json - 125.1.1.2 Create
libs/kalika/thermodynamics-rs/Rust crate for performance-critical phase equilibrium solvers — configureCargo.tomlwith napi-rs bindings, integrate into Nx vianx:run-commandsexecutor, expose native bindings to TypeScript through@kalika/thermodynamics - 125.1.1.3 Create barrel export
src/index.tsexporting all public modules: types, Gibbs energy models, equilibrium solver, phase diagram mapper, database I/O, cluster expansion, diffusion, nucleation, and solidification
125.1.2 Core Type Definitions#
- 125.1.2.1 Define
Componenttype: chemical element or species with name, atomic mass, reference state (crystal structure + phase label), standard enthalpy, standard entropy, and SGTE Gibbs energy polynomial coefficients — plusComponentSetfor ordered collections with mole fraction validation (sum to 1.0 within tolerance) - 125.1.2.2 Define
Phasetype: thermodynamic phase with name, model type (ideal/regular/sublattice/quasichemical/associate), constituent components, sublattice description (if applicable: number of sublattices, site ratios, allowed species per sublattice), stability range (T_min/T_max/P_min/P_max), and magnetic properties (Curie/Neel temperature, magnetic moment) - 125.1.2.3 Define
GibbsEnergyinterface:evaluate(T: number, P: number, composition: Float64Array): numberreturning J/mol, plus partial derivativesdG_dT(= -S),dG_dP(= V),dG_dx_i(= mu_i), and second derivativesd2G_dT2(= -Cp/T),d2G_dx_i_dx_jfor stability analysis — all with analytic implementations, not finite differences - 125.1.2.4 Define
EquilibriumResulttype: temperature, pressure, component amounts, list of stable phases each with phase fraction, internal composition (mole fractions or site fractions), chemical potentials of all components, Gibbs energy of the system, degrees of freedom (Gibbs phase rule: F = C - P + 2), and convergence metadata (iterations, residual norm) - 125.1.2.5 Define
PhaseDiagramtype: collection of phase regions (each with bounding vertices/edges in T-x or P-T space, list of stable phases within the region), invariant points (eutectic/peritectic/etc. with type label, T, compositions of all coexisting phases), tie-lines, and rendering metadata — supporting binary (T-x), ternary (isothermal triangle), and P-T diagrams - 125.1.2.6 Define
ThermodynamicDatabasetype: collection of assessed component data (SGTE polynomials), phase definitions with model parameters, interaction parameters organized by system (binary, ternary), metadata (assessor, year, reference, quality rating), and query API:getPhase(name),getInteraction(phase, components),getSubsystems(components) - 125.1.2.7 Define
TDBEntrytype: single parameter entry in TDB format — parameter type (G, L, TC, BMAGN, V0, etc.), phase name, constituent array, order (for Redlich-Kister L parameters), temperature range, polynomial coefficients, and reference string - 125.1.2.8 Define shared numeric types:
Temperature(Kelvin, with validation > 0),Pressure(Pa),MoleFraction(0 to 1),SiteFraction(0 to 1 per sublattice),ChemicalPotential(J/mol),Enthalpy(J/mol),Entropy(J/mol/K),HeatCapacity(J/mol/K), and unit-safe arithmetic operations between them
125.1.3 Utility Infrastructure#
- 125.1.3.1 Implement polynomial evaluation engine: Horner's method for SGTE-style polynomials G(T) = a + bT + cT*ln(T) + sum(d_n * T^n) with arbitrary number of terms, supporting first and second derivatives with respect to T analytically — optimized for repeated evaluation across temperature sweeps
- 125.1.3.2 Implement composition space utilities: mole fraction to weight fraction conversion, mole fraction to site fraction mapping for sublattice models, composition normalization, binary/ternary composition coordinate transforms (Cartesian to barycentric and back), and Gibbs triangle coordinate system for ternary visualization
- 125.1.3.3 Implement numerical differentiation fallback: central difference (4th-order accurate) for Gibbs energy derivatives when analytic derivatives are not available — with adaptive step size selection (h ~ eps^{1/3} _ |x| for first derivative, eps^{1/4} _ |x| for second) and Richardson extrapolation for improved accuracy
- 125.1.3.4 Implement matrix utilities for equilibrium solver: LU decomposition with partial pivoting for Jacobian solve, condition number estimation, singular value decomposition for rank-deficient systems (near phase boundaries), and sparse matrix support for multicomponent systems with many phases
125.2 Gibbs Energy Models (@kalika/thermodynamics)#
125.2.1 Reference State Energies#
- 125.2.1.1 Implement SGTE pure element Gibbs energy database: store Dinsdale polynomial coefficients G(T) = a + bT + cTln(T) + dT^2 + eT^3 + fT^(-1) + g*T^7 + ... for all 78 SGTE elements across all assessed phases (FCC_A1, BCC_A2, HCP_A3, LIQUID, etc.) with correct temperature range segmentation (e.g., Fe-BCC below 1811K vs. above)
- 125.2.1.2 Implement lattice stability computation: G_phase(T) - G_SER(T) for any element in any phase relative to its Stable Element Reference (SER) state — essential for computing end-member energies in sublattice models where components appear in non-reference structures
- 125.2.1.3 Implement enthalpy, entropy, and heat capacity from SGTE polynomials: H(T) = G - T*(dG/dT), S(T) = -dG/dT, Cp(T) = -T*(d2G/dT2) — derived analytically from the polynomial coefficients, with validation against published SGTE tabulated values for Fe, Al, Cu, Ti, Ni at 298K, 1000K, 2000K
- 125.2.1.4 Implement temperature range handling: each SGTE polynomial is valid only within a specific T range (e.g., 298.15-1811K for BCC Fe), with different polynomial coefficients above and below transition temperatures — implement piecewise evaluation with smooth continuity verification at range boundaries
125.2.2 Ideal Solution Model#
- 125.2.2.1 Implement ideal solution Gibbs energy: G_ideal = sum_i x_i * G_i_ref(T,P) + R*T _ sum_i x_i _ ln(x_i), where G_i_ref are SGTE reference energies, R = 8.314462 J/mol/K — with proper handling of x_i = 0 (limit x*ln(x) -> 0) to avoid NaN, and analytic first/second derivatives with respect to T and x_i
- 125.2.2.2 Implement ideal solution chemical potential: mu_i = G_i_ref + RTln(x_i) — derived analytically from partial molar Gibbs energy, with validation: mu_i -> -infinity as x_i -> 0 (Henry's law limit), and mu_i = G_i_ref when x_i = 1 (Raoult's law)
- 125.2.2.3 Implement ideal solution activity: a_i = x_i for ideal solution (Raoult's law), with activity coefficient gamma_i = 1 — providing the baseline against which excess quantities are measured
125.2.3 Regular Solution Model#
- 125.2.3.1 Implement regular solution excess Gibbs energy: Gexcess = sum_i sum{j>i} x_i _ x_j _ L_ij, where L_ij is a constant (temperature- independent) interaction parameter — with total G = G_ideal + G_excess, and analytic partial derivatives dG_excess/dx_i for chemical potential computation
- 125.2.3.2 Implement miscibility gap detection for regular solution: d2G/dx2 < 0 implies thermodynamic instability (spinodal); compute spinodal composition from d2G/dx2 = 0 (yields x_spinodal = 0.5 +/- sqrt(0.25 - RT/(2*L)) for symmetric regular solution) and binodal from common tangent construction
- 125.2.3.3 Implement critical temperature for regular solution: T_c = L/(2R) for symmetric regular solution where the miscibility gap closes — with generalization to asymmetric regular solutions
125.2.4 Sub-Regular (Redlich-Kister) Model#
- 125.2.4.1 Implement Redlich-Kister polynomial excess Gibbs energy: G_excess_ij = x_i _ x_j _ sum_v (^v)L_ij * (x_i - x_j)^v, where (^v)L_ij are the v-th order interaction parameters (v=0 is regular solution, v=1 is sub-regular, etc.) — typically truncated at v=2 or v=3, with each (^v)L_ij itself a polynomial in T: a + bT + cT*ln(T) + ...
- 125.2.4.2 Implement Redlich-Kister partial derivatives: analytic dG_excess/dx_i for chemical potential computation — the derivative of the Redlich-Kister sum requires careful index manipulation since x_i appears both explicitly and through the constraint sum(x) = 1
- 125.2.4.3 Implement Muggianu extrapolation for ternary and higher-order systems: extend binary Redlich-Kister interactions to ternary compositions using the Muggianu geometric model — Gexcess = sum{i<j} (x_i + x_j)^2 / 4 _ sum_v (^v)L_ij _ (x_i' - x_j')^v where x_i' = x_i / (x_i + x_j) _ 2, plus optional ternary interaction parameter L_ijk _ x_i _ x_j _ x_k
- 125.2.4.4 Implement Kohler and Toop extrapolation alternatives: Kohler (symmetric, using binary compositions at same ratio) and Toop (asymmetric, one component treated differently) extrapolation methods — user-selectable per ternary system depending on chemical asymmetry
125.2.5 Compound Energy Formalism (CEF / Sublattice Model)#
- 125.2.5.1 Implement sublattice model data structures: define sublattice configuration with number of sublattices s, site ratios a_s (e.g., (1)(1) for B2, (1)(3) for L1_2, (0.25)(0.75)(1) for sigma phase), allowed species per sublattice, and site fraction variables y_i^s with constraint sum_i y_i^s = 1 for each sublattice s
- 125.2.5.2 Implement end-member surface of reference: G_SER = sum over all end-member configurations (one species selected per sublattice) of product(y_i^s for each sublattice) * G_endmember — where G_endmember is the Gibbs energy of the compound with that specific sublattice occupancy, assessed from DFT or experimental data
- 125.2.5.3 Implement ideal mixing contribution on sublattices: G_ideal = R*T * sum_s a_s _ sum_i y_i^s _ ln(y_i^s), where the sum is over each sublattice s and each species i on that sublattice, weighted by site ratio a_s — this captures the configurational entropy of random mixing within each sublattice independently
- 125.2.5.4 Implement excess Gibbs energy for sublattice model: Gexcess = sum of interaction terms between species on the same sublattice using Redlich-Kister polynomials, multiplied by product of site fractions on all other sublattices — e.g., for (A,B)(C,D): L{A,B:C} _ y_A^1 _ y_B^1 _ y_C^2 _ sum_v (^v)L * (y_A^1 - y_B^1)^v
- 125.2.5.5 Implement site fraction to mole fraction conversion: x_i = sum_s a_s * y_i^s / sum_s a_s (for element i), handling the case where element i appears on multiple sublattices — and the inverse mapping (mole fraction to site fraction) which requires solving a nonlinear system when a component can occupy multiple sublattices
- 125.2.5.6 Implement CEF partial derivatives: dG/dy_i^s for the Newton-Raphson equilibrium solver — requires chain rule through the product terms in the surface of reference, the logarithmic ideal term, and the Redlich-Kister excess terms, all with respect to site fractions subject to the sublattice sum constraints
- 125.2.5.7 Implement common sublattice model configurations: FCC_A1 (1 sublattice + 1 interstitial: (A,B)_1(Va,C)_c), BCC_A2 (similarly), B2/BCC_B2 ((A,B)_0.5(A,B)_0.5(Va,C)_3), L1_2/FCC_L12 ((A,B)_0.25(A,B)_0.75(Va,C)_1), sigma phase ((A,B)_10(A,B)_4(A,B)_16), Laves C14/C15 — with correct site ratios and species assignments per the SGTE convention
125.2.6 Ionic Liquid Model#
- 125.2.6.1 Implement two-sublattice ionic liquid model: (cations)_P (anions,Va,neutral)_Q, where P and Q are composition-dependent to maintain charge neutrality: P = sum_j |z_j| _ y_j + Q _ y_Va (charge balance equation), Q = sum_i |z_i| * y_i — supporting metallic liquid (P=Q=1 with hypothetical charges) and ionic melt (real charges) regimes
- 125.2.6.2 Implement ionic liquid Gibbs energy: surface of reference with charge-weighted products of site fractions, ideal entropy of mixing on each sublattice, and excess interactions — with proper handling of the vacancy species on the anion sublattice (representing metallic bonding limit) and neutral species (associates)
125.2.7 Associate Solution Model#
- 125.2.7.1 Implement associate solution model: treat a liquid as an ideal or non-ideal solution of molecular species (associates) such as SiO2, CaO, Ca2SiO4, etc. — the composition of the liquid in terms of associates is determined by internal equilibrium (minimizing G with respect to associate fractions subject to element balance), with the overall Gibbs energy computed from the equilibrium associate distribution
- 125.2.7.2 Implement associate equilibrium solver: given total element composition and temperature, solve for associate mole fractions by minimizing G = sum_i n_i * G_i(T) + R*T _ sum_i n_i _ ln(x_i) + G_excess subject to element balance constraints, using Lagrange multipliers or substitution — iterative Newton-Raphson with line search for convergence
125.2.8 Modified Quasichemical Model (MQM)#
- 125.2.8.1 Implement modified quasichemical model for liquids: define pair fractions Xij (fraction of nearest-neighbor i-j pairs), relate to component fractions via coordination number Z: Z_i * x_i = 2X_ii + sum*{j!=i} X_ij — the pair distribution is determined by minimizing G with respect to pair fractions at fixed composition
- 125.2.8.2 Implement MQM Gibbs energy: G = sumi n_i * G_i_ref + RT * sum_i n_i * ln(x_i) - RT * [n_pair/2 * ln(eta)] + sum{i<=j} (n_ij/2) * Delta_g_ij, where Delta_g_ij is the pair exchange energy parameterized as a polynomial in pair fractions, and eta is the pair distribution normalization — capturing short-range order (SRO) that regular/sub-regular models miss
- 125.2.8.3 Implement coordination number model: composition-dependent coordination numbers Z_i(x) that vary between Z_i^{ii} (pure i coordination) and Z_i^{ij} (dilute i in j coordination) — essential for accurate SRO in systems with large size mismatch (e.g., Fe-C, Al-Si)
- 125.2.8.4 Implement MQM equilibrium pair distribution solver: minimize G with respect to pair fractions X_ij at fixed composition and temperature — the "quasichemical" equilibrium K_ij = X_ij^2 / (X_ii * X_jj) = exp(-Delta_g_ij / RT), solved iteratively with Newton-Raphson
125.2.9 Magnetic Contribution#
- 125.2.9.1 Implement Inden-Hillert-Jarl magnetic Gibbs energy model: G_mag = RT * ln(beta + 1) * f(tau), where tau = T/T_c is the reduced temperature, T_c is the Curie (or Neel) temperature, beta is the average magnetic moment per atom, and f(tau) is the Inden polynomial: f(tau < 1) = 1 - [79tau^(-1)/(140p) + (474/497)(1/p - 1)*(tau^3/6 + tau^9/135 + tau^15/600)] / A, f(tau >= 1) = -(tau^(-5)/10 + tau^(-15)/315 + tau^(-25)/1500) / A, with p = 0.28 for FCC, p = 0.40 for BCC
- 125.2.9.2 Implement composition-dependent magnetic properties: T_c(x) and beta(x) as functions of composition using Redlich-Kister polynomials — TDB parameters TC and BMAGN, interpolated across composition space just like excess Gibbs energy parameters
- 125.2.9.3 Implement antiferromagnetic treatment: for antiferromagnetic phases, T_c is negative in the database (convention), use |T_c| for tau computation and divide beta by the antiferromagnetic factor (typically -1 for BCC, -3 for FCC) — matching Thermo-Calc convention
125.2.10 Pressure-Dependent Terms#
- 125.2.10.1 Implement pressure contribution to Gibbs energy: G(T,P) = G(T, P_ref) + integral from P_ref to P of V(T,P') dP', where V(T,P) is the molar volume — requiring an equation of state (EOS) for V(T,P)
- 125.2.10.2 Implement Murnaghan equation of state: V(P) = V_0 * (1 + B'*P/B_0)^(-1/B'), integrated to give the pressure-Gibbs energy contribution — where V_0 is zero-pressure molar volume, B_0 is bulk modulus, and B' is pressure derivative of bulk modulus (typically 4-5)
- 125.2.10.3 Implement third-order Birch-Murnaghan EOS: P(V) = (3*B_0/2) * [(V_0/V)^(7/3) - (V_0/V)^(5/3)] _ {1 + 3/4_(B'-4)_ [(V_0/V)^(2/3) - 1]} — invert numerically for V(P), then integrate for G(P), with thermal expansion via V_0(T) = V_0(298) _ exp(integral of alpha(T) dT)
- 125.2.10.4 Implement thermal expansion model: alpha(T) = a + b*T + c/T^2 (common parametrization), with V_0(T) from integration — the TDB parameters V0, VA, VB, VC for the pressure model
125.2.11 Heat Capacity Models#
- 125.2.11.1 Implement Einstein heat capacity model: C_v = 3R * (theta_E/T)^2 * exp(theta_E/T) / (exp(theta_E/T) - 1)^2, where theta_E is the Einstein temperature — integrate to get G contribution: G_Einstein = 3R*T * ln(1 - exp(-theta_E/T)) + (3/2)Rtheta_E (zero- point energy)
- 125.2.11.2 Implement Debye heat capacity model: C_v = 9R * (T/theta_D)^3 * integral from 0 to theta_D/T of x^4exp(x)/ (exp(x)-1)^2 dx, where theta_D is the Debye temperature — with numerical integration (Gauss-Legendre quadrature), and analytic low-T (T << theta_D: C_v ~ (12/5)pi^4R*(T/theta_D)^3) and high-T (T >> theta_D: C_v ~ 3R) limits
- 125.2.11.3 Implement Debye-Gruneisen model for pressure dependence: theta_D(V) = theta_D_0 * (V_0/V)^gamma, where gamma is the Gruneisen parameter — coupling thermal and pressure models for high-pressure thermodynamics
125.2.12 Order-Disorder Model#
- 125.2.12.1 Implement order-disorder partitioning model: for phases that exhibit ordering (e.g., FCC -> L1_2, BCC -> B2), the Gibbs energy is partitioned as G_ordered = G_disordered(x) + Delta_G_ord(y) where Delta_G_ord = G_sublattice(y) - G_sublattice(y=x) — ensuring that the ordered model reduces to the disordered model when site fractions equal mole fractions (no ordering)
- 125.2.12.2 Implement order parameter tracking: define long-range order parameter eta = (y_A^1 - y_A^2) / (y_A^1 + y_A^2) for a two-sublattice model — compute equilibrium eta at each T by minimizing G with respect to site fractions, detecting the order-disorder transition temperature where eta -> 0 continuously (second-order) or discontinuously (first-order)
- 125.2.12.3 Implement reciprocal parameter handling: for the ordered sublattice model, the interaction parameters must satisfy the reciprocal relation to ensure that the disordered state is correctly recovered — implement automatic reciprocal parameter generation from the assessed ordered model parameters
125.3 Phase Equilibrium Computation (@kalika/thermodynamics)#
125.3.1 Gibbs Energy Minimization#
- 125.3.1.1 Implement global Gibbs energy minimization (Rust): given T, P, and overall composition n = {n_1, ..., n_C}, minimize G_total = sum_phi (n_phi _ G_phi(T, P, x_phi)) subject to mass balance (sum_phi n_phi _ x_i_phi = n_i for all components i) and non-negativity (n_phi >= 0, x_i_phi >= 0) — the fundamental CALPHAD equilibrium problem
- 125.3.1.2 Implement convex hull construction in G-x space: for binary systems, compute G(x) for each phase across composition range, construct lower convex hull — the hull facets define two-phase regions (tie-lines), hull vertices define single-phase regions, and hull edges give equilibrium compositions
- 125.3.1.3 Implement tangent plane distance criterion: for a candidate equilibrium, compute the tangent plane to the Gibbs energy surface at the current solution, check if any composition point lies below this plane (negative tangent plane distance = unstable solution, a new phase should appear) — the standard test for global optimality of the equilibrium
- 125.3.1.4 Implement grid-based global search: discretize composition space, evaluate G for all phases at each grid point, identify approximate global minimum, then refine with local Newton-Raphson — the two-stage approach that avoids convergence to local minima, with adaptive grid refinement near phase boundaries
125.3.2 Equilibrium Solver (Newton-Raphson)#
- 125.3.2.1 Implement Newton-Raphson equilibrium solver (Rust): solve the nonlinear system of equations: dG/dn_i_phi = mu_i for all components i and phases phi (equal chemical potential condition), sum_phi n_i_phi = n_i (mass balance) — Jacobian matrix J with analytic entries from second derivatives of Gibbs energy, line search for globalization
- 125.3.2.2 Implement site fraction solver for sublattice models (Rust): solve for equilibrium site fractions y_i^s within each phase by minimizing G with respect to y subject to sublattice sum constraints (sum_i y_i^s = 1 for each s) — using Lagrange multipliers or substitution to eliminate constraints, then Newton-Raphson on reduced system
- 125.3.2.3 Implement phase addition/removal logic: when tangent plane criterion detects instability, add the most unstable phase to the equilibrium set; when a phase fraction goes negative during iteration, remove it (dormant phase) — maintain a list of active and dormant phases with automatic reactivation check at each step
- 125.3.2.4 Implement convergence acceleration: damped Newton steps with adaptive damping factor, trust region method for robustness near phase boundaries, and BFGS quasi-Newton update when Jacobian evaluation is expensive — targeting convergence in < 20 iterations for typical CALPHAD systems
- 125.3.2.5 Implement initial guess strategies: for the first equilibrium calculation, use ideal solution approximation; for stepping calculations (T sweep, composition sweep), use extrapolation from previous converged solution — critical for computational efficiency in phase diagram mapping
125.3.3 Thermodynamic Properties at Equilibrium#
- 125.3.3.1 Implement chemical potential computation: mu_i = dG/dn_i at equilibrium — directly available from the Lagrange multipliers of the equilibrium solver (the mu_i are the multipliers for the mass balance constraints), with validation that mu_i is identical in all phases containing component i (equilibrium condition)
- 125.3.3.2 Implement activity and activity coefficient: a_i = exp((mu_i - mu_i_ref) / RT), gamma_i = a_i / x_i — where mu_i_ref is the chemical potential of component i in its reference state (pure substance in the same phase, or Henry's law reference for dilute solutes)
- 125.3.3.3 Implement phase fraction computation: lever rule for binary systems (f_alpha = (x - x_beta) / (x_alpha - x_beta)), generalized to multicomponent via mass balance solution — the n_phi from the equilibrium solver directly give phase amounts
- 125.3.3.4 Implement driving force computation: for a metastable phase phi not present in the equilibrium, compute Delta_G_df = G_phi(T,P,x_eq) - sum_i x_i * mu_i — the energy benefit of forming the phase, used to assess how far the system is from precipitating a new phase
- 125.3.3.5 Implement enthalpy, entropy, and heat capacity at equilibrium: H = G + T*S, S = -dG/dT (computed at fixed equilibrium phase fractions AND accounting for composition changes with T), Cp = dH/dT — requiring re-equilibration at T +/- dT for numerical derivatives that account for phase fraction changes
125.3.4 Phase Boundary Detection#
- 125.3.4.1 Implement tie-line computation: for binary two-phase regions, the tie-line connects equilibrium compositions x_alpha and x_beta at given T — compute by solving the equal chemical potential equations mu_i^alpha(x_alpha) = mu_i^beta(x_beta) for all components
- 125.3.4.2 Implement tie-triangle computation for ternary systems: three-phase equilibrium gives a tie-triangle with vertices at the three equilibrium compositions — compute by solving the multicomponent equal chemical potential system with three phases simultaneously
- 125.3.4.3 Implement miscibility gap detection: find compositions where d2G/dx2 = 0 (spinodal) and where the common tangent construction gives two distinct tangent points (binodal) — for both binary (1D search) and ternary (2D spinodal surface) systems
- 125.3.4.4 Implement invariant reaction detection: eutectic (L -> alpha + beta), eutectoid (gamma -> alpha + beta), peritectic (L + alpha -> beta), peritectoid (alpha + gamma -> beta), monotectic (L1 -> L2 + alpha) — detected as points where the number of phases equals C+1 (zero degrees of freedom in binary), with automatic reaction type classification
- 125.3.4.5 Implement invariant temperature determination: given an identified invariant reaction, precisely locate the invariant temperature by bracketing and bisection (or Newton-Raphson) on the condition that all C+1 phases are in equilibrium simultaneously — accuracy to 0.01K
125.3.5 T_0 Line and Para-Equilibrium#
- 125.3.5.1 Implement T_0 line computation: find T_0(x) where G_alpha(T_0, x) = G_beta(T_0, x) for the same composition x — the composition at which both phases have equal Gibbs energy without diffusion (massive transformation), computed by Newton-Raphson on G_alpha - G_beta = 0 at each composition
- 125.3.5.2 Implement para-equilibrium computation: constrained equilibrium where only interstitial elements (C, N) redistribute between phases while substitutional elements (Fe, Mn, Cr) are frozen at the bulk composition — solve the subset of chemical potential equations for interstitials only, used for rapid phase transformations in steels
- 125.3.5.3 Implement constrained equilibrium framework: generalized solver that allows freezing arbitrary degrees of freedom (para-equilibrium, quasi-para-equilibrium, ortho-equilibrium as special cases) — enabling modeling of partial equilibrium states during kinetically limited transformations
125.4 Phase Diagram Types (@kalika/thermodynamics)#
125.4.1 Binary Phase Diagrams (T-x)#
- 125.4.1.1 Implement binary phase diagram mapper: T-x stepping algorithm — at each temperature T, compute equilibrium for a fine grid of compositions, identify phase boundaries (compositions where phase set changes), connect boundaries across temperature steps to form the phase diagram — with adaptive step refinement near invariant reactions and phase boundaries
- 125.4.1.2 Implement binary phase diagram by phase boundary tracking: alternative to stepping — start from a known point on a phase boundary, follow the boundary curve by predictor-corrector method (predict next boundary point by extrapolation, correct by equilibrium calculation) — more efficient than stepping for smooth boundaries
- 125.4.1.3 Implement binary phase diagram region labeling: assign phase labels to each region of the diagram (e.g., "L", "L + FCC", "BCC + FCC", "FCC"), detect and label invariant horizontal lines (eutectic, peritectic), and generate the rendered diagram with proper annotation
- 125.4.1.4 Implement binary phase diagram validation: verify Gibbs phase rule compliance (F = C - P + 2: single-phase regions are 2D, two-phase regions are bounded by curves, three-phase equilibria are horizontal lines), check that all phase boundaries are connected, and validate against known diagrams (Fe-C, Cu-Zn, Al-Cu)
125.4.2 Ternary Phase Diagrams#
- 125.4.2.1 Implement ternary isothermal section: at fixed T, compute equilibrium across the ternary composition triangle (Gibbs triangle) on a triangular grid, identify single-phase, two-phase (tie-lines), and three-phase (tie-triangles) regions — with Delaunay triangulation of phase boundary points for smooth rendering
- 125.4.2.2 Implement ternary liquidus projection: project the liquidus surface (temperature of first solid formation) onto the composition triangle — showing primary solidification fields, univariant lines (monovariant eutectic/peritectic troughs), and invariant points (ternary eutectics/peritectics), with isotherms on the liquidus surface
- 125.4.2.3 Implement ternary isopleth (vertical section): cut through the ternary system along a line in composition space (e.g., constant ratio of two components), plot T vs. composition along the section — showing phase fields and their boundaries, noting that tie-lines generally do NOT lie in the section plane
- 125.4.2.4 Implement ternary phase diagram coordinate transforms: Cartesian to barycentric coordinates and back, equilateral triangle rendering with axis labels, gridlines in composition space, and proper handling of the constraint x_A + x_B + x_C = 1
125.4.3 Multicomponent Diagrams#
- 125.4.3.1 Implement quaternary and higher-order phase diagram sections: for N > 3 components, compute equilibrium along user-specified composition paths or sections (fixing N-2 compositional degrees of freedom to get a 2D plot) — e.g., pseudo-binary sections in multicomponent alloys
- 125.4.3.2 Implement property diagram: plot phase fraction vs. T, or component concentration in each phase vs. T, or enthalpy vs. T at fixed overall composition — the standard Thermo-Calc "property diagram" showing how phase amounts and compositions evolve during heating/cooling
- 125.4.3.3 Implement step diagram: at fixed composition, step through temperature (or pressure) in small increments, compute full equilibrium at each step, record all phase fractions and compositions — the workhorse calculation for predicting phase evolution in specific alloys
125.4.4 Pressure-Temperature Diagrams#
- 125.4.4.1 Implement unary P-T phase diagram: for a single component, map phase boundaries in P-T space using Clausius-Clapeyron equation dP/dT = Delta_S / Delta_V at the phase boundary, with numerical integration from a known reference point — producing the classic phase diagram with solid/liquid/gas regions and triple/critical points
- 125.4.4.2 Implement binary P-T sections: at fixed composition, map phase stability in P-T space — relevant for geochemistry (mantle mineralogy) and high-pressure materials science
125.4.5 Electrochemical & Stability Diagrams#
- 125.4.5.1 Implement Ellingham diagram: plot Delta_G of oxide formation reactions (2M + O2 -> 2MO) vs. temperature for multiple metals — including the CO/CO2 and H2/H2O lines for determining reducing conditions, with correct slope changes at melting/boiling points of metal or oxide
- 125.4.5.2 Implement Pourbaix diagram (potential-pH): compute electrochemical equilibria for M-H2O system as function of pH and electrode potential E — identify stability regions (immunity: metal stable, corrosion: dissolved ions stable, passivation: solid oxide/ hydroxide stable) from Nernst equation E = E_0 - (RT/nF) * ln(Q) and solubility equilibria
- 125.4.5.3 Implement Pourbaix diagram line computation: for each equilibrium reaction, compute the E-pH line: E = a - bpH + clog([M^n+]) — horizontal lines (redox, pH-independent), vertical lines (acid-base, E-independent), and sloped lines (combined redox + acid-base), with proper handling of the H2O stability window (O2/H2O and H2/H2O lines)
- 125.4.5.4 Implement multicomponent Pourbaix diagram: extend to systems with multiple metals (e.g., Fe-Cr-H2O for stainless steel corrosion) — requiring coupled equilibrium calculation across all metal species at each (E, pH) point
- 125.4.5.5 Implement predominance area diagram (Kellogg diagram): plot log(pO2) vs. log(pS2) (or other gas partial pressures) showing stability fields of metal, oxide, sulfide, and sulfate phases — used in pyrometallurgy for roasting/smelting process design
- 125.4.5.6 Implement chemical potential diagram: plot mu_A vs. mu_B showing phase stability regions — each region is a phase (or phase assemblage) where that set minimizes G at the given chemical potentials, boundaries are phase transitions
125.5 Thermodynamic Database Format (@kalika/thermodynamics)#
125.5.1 TDB File Reader#
- 125.5.1.1 Implement TDB tokenizer: lexical analysis of Thermo-Calc TDB format — recognize keywords (ELEMENT, SPECIES, PHASE, CONSTITUENT, PARAMETER, FUNCTION, TYPE_DEFINITION, DEFAULT_COMMAND), handle multi-line continuation ($ or N/Y flags), strip comments (starting with $), and handle the free-form whitespace-insensitive syntax
- 125.5.1.2 Implement TDB ELEMENT and SPECIES parsing: parse
ELEMENT name ref_state mass H298 S298entries for pure elements andSPECIES name constituent_formulaentries for molecular species (e.g.,SPECIES AL2O3 AL2O3orSPECIES VA VACUUM) - 125.5.1.3 Implement TDB PHASE and TYPE_DEFINITION parsing: parse
PHASE name type_def #sublattices sites(1) sites(2) ...and the associated TYPE_DEFINITION entries that specify the thermodynamic model (e.g., GES A_P_D for CALPHAD with magnetic contribution, or MQMQA for quasichemical) — correctly mapping type codes to model implementations - 125.5.1.4 Implement TDB CONSTITUENT parsing: parse
CONSTITUENT phase_name :species1,species2:species3,species4: ...defining which species are allowed on each sublattice — building the sublattice model structure for each phase - 125.5.1.5 Implement TDB PARAMETER parsing: parse
PARAMETER type (phase,constituent_array;order) range_low range_high expression;entries — supporting parameter types G (Gibbs energy), L (interaction), TC (Curie temperature), BMAGN (magnetic moment), V0/VA/VB (volume), with the expression parsed as a polynomial in T with ln(T) terms - 125.5.1.6 Implement TDB FUNCTION parsing: parse named functions
FUNCTION name range_low range_high expression; ...with piecewise temperature ranges — these are referenced by PARAMETER entries and must be resolved during database assembly - 125.5.1.7 Implement TDB expression parser: parse arithmetic expressions with operators (+, -, *, /, **), built-in functions (LN, LOG, EXP, SIN, COS, SINH, COSH, ABS, ERF), the temperature variable T, and function references (e.g., GHSERFE for Fe SER Gibbs energy) — building an expression tree that can be evaluated at any T
- 125.5.1.8 Implement complete TDB file reader: orchestrate the above parsers to read a full TDB file, resolve all function references, build the ThermodynamicDatabase object — with comprehensive error reporting (line number, context) for malformed entries, and validation of internal consistency (all referenced functions exist, all phases have constituents)
125.5.2 TDB File Writer#
- 125.5.2.1 Implement TDB file writer: serialize a ThermodynamicDatabase to valid TDB format — ELEMENT block, SPECIES block, TYPE_DEFINITION block, PHASE block, CONSTITUENT block, FUNCTION block, PARAMETER block — with correct formatting, line continuation, and ordering (elements first, then phases, then functions, then parameters by system complexity)
- 125.5.2.2 Implement TDB round-trip validation: read a TDB file, write it back, read the written file, and verify that all parameters match to machine precision — test with SGTE SSUB5, COST507, and user-provided TDB files
125.5.3 Alternative Database Formats#
- 125.5.3.1 Implement PanDat/CompuThermo format reader: parse the PanDat database format (used by CompuTherm Pandat software) — similar to TDB but with different syntax for phase definitions, interaction parameters, and model specifications
- 125.5.3.2 Implement FactSage ChemSage format reader: parse the ChemSage .dat format (used by FactSage/ChemApp) — different data organization with species-based rather than phase-based parameter storage, and different polynomial conventions
- 125.5.3.3 Implement custom JSON thermodynamic database format: define a JSON schema for thermodynamic data that maps directly to the internal ThermodynamicDatabase type — supporting schema versioning, human-readable parameter documentation, and easy programmatic generation from DFT/ experimental data pipelines
125.5.4 Database Validation & Management#
- 125.5.4.1 Implement thermodynamic consistency checks: verify Gibbs- Duhem relation (sum_i x_i * d_mu_i = 0 at constant T, P), check that Cp > 0 for all phases at all T in range, verify that G is continuous (no jumps at polynomial range boundaries), and check that entropy approaches zero as T -> 0 (third law)
- 125.5.4.2 Implement database merging: combine assessed parameter sets from different sources (e.g., Al-Cu from one assessment + Cu-Fe from another) — detecting conflicts (overlapping parameters for same system), preferring higher-quality assessments, and filling in missing ternary interactions with Muggianu extrapolation from binaries
- 125.5.4.3 Implement SGTE pure element database (built-in): embed the complete SGTE Unary 6.0 (or later) dataset as a built-in database — providing lattice stability data for all 78 assessed elements as the default reference for any calculation
- 125.5.4.4 Implement assessed binary/ternary system library: curate and embed assessed parameters for common engineering systems — Fe-C, Fe-Cr, Fe-Ni, Al-Cu, Al-Si, Al-Mg, Cu-Zn, Ti-Al, Ni-Al, and key ternary systems (Fe-Cr-Ni, Al-Cu-Mg, Ti-Al-V) — with full source references
125.6 Cluster Expansion (@kalika/cluster-expansion)#
125.6.1 Project Setup#
- 125.6.1.1 Create
libs/kalika/cluster-expansion/withproject.json,package.json(name:@kalika/cluster-expansion),tsconfig.json— configure with vitest, barrel export insrc/index.ts, and dependency on@kalika/thermodynamicsfor thermodynamic types and@kalika/crystal(Phase 116) for lattice structures
125.6.2 Cluster Identification#
- 125.6.2.1 Implement cluster definition: a cluster is a set of lattice
sites {i_1, i_2, ..., i_n} with cluster size n (pair: n=2, triplet: n=3,
quadruplet: n=4) — define
Clustertype with site indices, spatial coordinates, distance matrix between sites, and multiplicity (number of symmetry-equivalent clusters per lattice site) - 125.6.2.2 Implement cluster enumeration on crystal lattice: given a crystal structure (FCC, BCC, HCP, etc.) and maximum cluster size and distance cutoffs, enumerate all symmetry-distinct clusters — using space group operations to identify equivalence classes, sorted by size then maximum pair distance within the cluster
- 125.6.2.3 Implement symmetry-distinct cluster identification: given the space group of the parent lattice, apply all symmetry operations to each candidate cluster, identify the canonical representative of each equivalence class — using a canonical form (sorted site indices after symmetry reduction) to efficiently detect duplicates
- 125.6.2.4 Implement cluster orbit generation: for each symmetry- distinct cluster, generate all symmetry-equivalent instances (the orbit) — needed for computing cluster correlation functions as averages over all instances of each cluster type in a supercell
125.6.3 Correlation Functions#
- 125.6.3.1 Implement site occupation variables: for a binary alloy A-B, define sigma_i = +1 if site i is occupied by A, sigma_i = -1 if site i is occupied by B — generalizable to multicomponent via orthogonal point functions (Sanchez-de Fontaine basis: sigma_i^(n) for n = 0, 1, ..., K-1 for K components)
- 125.6.3.2 Implement cluster correlation function: xi_alpha = average over all clusters in orbit alpha of product(sigma_i for i in cluster) — for a specific configuration (supercell with definite A/B assignment), compute by iterating over all symmetry-equivalent clusters and averaging the product of occupation variables
- 125.6.3.3 Implement correlation function matrix: for a set of structures (supercells with different configurations), build the correlation matrix Pi where Pi*{s,alpha} = xi_alpha for structure s — this matrix is the design matrix for the ECI fitting problem E_s = sum_alpha m_alpha * J_alpha * xi*{alpha,s}
- 125.6.3.4 Implement efficient correlation function computation: for large supercells, use lookup tables for cluster membership and incremental updates when a single site is flipped (for Monte Carlo) — O(1) per flip rather than O(N) recomputation
125.6.4 Structure Enumeration#
- 125.6.4.1 Implement supercell generation: given a parent lattice and
target supercell size (number of atoms), enumerate all Hermite normal form
(HNF) supercell matrices, apply lattice symmetry to identify
symmetry-distinct supercells — matching the approach in ATAT's
enumanduncleprograms - 125.6.4.2 Implement configuration enumeration: for a given supercell, enumerate all symmetry-inequivalent atomic configurations (A/B arrangements) — using Polya counting for the total number, and systematic enumeration with canonical form identification (matching Hart & Forcade's algorithm for multicomponent systems)
- 125.6.4.3 Implement structure selection for DFT training: from the enumerated structures, select a training set that spans the correlation function space — using farthest-point sampling in correlation space, D-optimal design, or ground-state-informed selection (include known ground states and structures near convex hull)
125.6.5 ECI Fitting#
- 125.6.5.1 Implement least-squares ECI fitting: given the correlation matrix Pi and DFT energies E, solve E = Pi * J for the effective cluster interactions J — ordinary least squares (J = (Pi^T Pi)^{-1} Pi^T E) with leave-one-out cross-validation (LOOCV) score to assess predictive quality
- 125.6.5.2 Implement cross-validation for cluster selection: test different sets of clusters (varying max cluster size and distance cutoffs), fit ECIs for each, compute LOOCV and k-fold CV scores — select the cluster set that minimizes CV error, balancing model complexity against prediction accuracy (typically CV error < 5 meV/atom for good fits)
- 125.6.5.3 Implement compressive sensing / LASSO for ECI fitting:
L1-regularized regression (minimize ||E - Pi*J||^2 + lambda * ||J||_1) to
automatically select relevant clusters by driving most ECIs to zero —
using coordinate descent or LARS algorithm, with lambda selected by CV,
matching the approach in ATAT's
clusterexpansionwith-csflag - 125.6.5.4 Implement Bayesian ECI fitting: automatic relevance determination (ARD) prior on ECIs, with Bayesian evidence maximization to determine regularization strengths — providing uncertainty estimates on each ECI and Bayesian model comparison between cluster sets
- 125.6.5.5 Implement ECI validation metrics: prediction error on held- out structures, formation energy prediction vs. DFT for structures not in the training set, ground state preservation (does the CE predict the same ground states as DFT?), and the ECI spectrum (magnitude vs. cluster size/distance — should decay with increasing cluster size)
125.6.6 Ground State Search#
- 125.6.6.1 Implement ground state search by enumeration: for small supercells (up to ~20 atoms), enumerate all configurations, evaluate CE energy, construct the formation energy convex hull — identify ground state structures at each composition
- 125.6.6.2 Implement genetic algorithm ground state search: for larger systems where enumeration is infeasible, use genetic algorithm (GA) with configuration as genome (site occupations), CE energy as fitness, crossover (swap sublattice blocks), mutation (random site flips) — run at each composition to find the lowest-energy configuration
- 125.6.6.3 Implement simulated annealing ground state search: start from random configuration, apply Metropolis Monte Carlo at decreasing temperature — efficient alternative to GA for finding ground states in large supercells, with multiple independent runs for confidence
125.6.7 Monte Carlo Simulation#
- 125.6.7.1 Implement canonical Monte Carlo with CE Hamiltonian (Rust): at fixed composition and temperature, perform Metropolis MC with site swap moves (swap an A and B atom) — accept with probability min(1, exp(-Delta_E / kT)) where Delta_E is computed from the CE using incremental correlation function updates, O(1) per move
- 125.6.7.2 Implement semi-grand canonical Monte Carlo (Rust): at fixed chemical potential difference Delta_mu = mu_A - mu_B and temperature, perform MC with site flip moves (change A to B or vice versa) — accept with probability min(1, exp(-(Delta_E - Delta_mu * Delta_N) / kT)), allowing composition to fluctuate
- 125.6.7.3 Implement Wang-Landau sampling: flat-histogram MC method to compute the density of states g(E) directly — iteratively refine g(E) by random walk in energy space with acceptance probability proportional to 1/g(E), updating g(E) at each step, with modification factor f decreased when histogram is flat — enabling computation of entropy S(T) and free energy F(T) = -kT*ln(Z) at all temperatures from a single simulation
- 125.6.7.4 Implement MC thermodynamic averages: compute and accumulate energy <E>, energy squared <E^2>, composition <x>, composition squared <x^2>, and order parameters during MC — derive heat capacity Cv = (<E^2> - <E>^2) / kT^2, susceptibility chi = (<x^2> - <x>^2) * N / kT, and free energy via thermodynamic integration
- 125.6.7.5 Implement order-disorder transition detection from MC: compute long-range order parameter (sublattice occupation difference) vs. temperature, detect transition temperature from: (a) peak in heat capacity, (b) inflection in order parameter, (c) Binder cumulant crossing for finite-size scaling — classify as first-order (discontinuous jump, latent heat) or second-order (continuous, divergent Cv)
- 125.6.7.6 Implement short-range order (SRO) from MC: compute Warren- Cowley SRO parameters alpha_i = 1 - P_AB(r_i) / (x_A * x_B) for each coordination shell r_i — negative alpha = ordering tendency, positive alpha = clustering tendency — measure at each T to track SRO evolution above the ordering temperature
125.6.8 Phase Diagram from CE+MC#
- 125.6.8.1 Implement free energy from thermodynamic integration: compute F(T) at multiple temperatures by integrating <E(T')> from high-T reference (ideal solution, known analytically) down to target T — enabling Gibbs free energy comparison between phases for phase diagram construction
- 125.6.8.2 Implement CE+MC phase diagram construction: at each temperature, compute free energies of all competing phases (disordered, various ordered structures), construct common tangent (equal chemical potential), determine phase boundaries — producing a first-principles phase diagram without CALPHAD parameters
- 125.6.8.3 Implement ATAT/MAPS compatibility: import/export cluster expansion data in ATAT format (clusters.out, eci.out, lat.in, str_enum.out) — enabling interoperability with the widely-used ATAT toolkit for validation and comparison
125.7 Ab Initio Thermodynamics (@kalika/thermodynamics)#
125.7.1 Formation Energy#
- 125.7.1.1 Implement formation energy computation: Delta_H_f = E(compound) - sum_i x_i * E_i(reference), where E(compound) is the DFT total energy per atom and E_i(reference) is the DFT energy of element i in its standard reference state — with proper handling of the reference state (typically the ground state crystal structure: FCC-Cu, BCC-Fe, HCP-Ti, diamond-Si, etc.)
- 125.7.1.2 Implement convex hull construction: given formation energies at multiple compositions, construct the convex hull in (composition, formation energy) space — hull vertices are thermodynamically stable phases, points above the hull are metastable, and the "energy above hull" (E_hull) quantifies metastability (compounds with E_hull < ~50 meV/atom are often synthesizable)
- 125.7.1.3 Implement energy above hull computation: for any composition/ energy point, compute the perpendicular distance to the convex hull in the (x, Delta_H_f) space — using the facet decomposition of the hull and linear interpolation between hull vertices at the target composition
- 125.7.1.4 Implement decomposition pathway analysis: for a metastable compound, identify the thermodynamically favored decomposition products (the hull facet below the compound) and the decomposition energy — e.g., "Li2MnO3 decomposes to LiMnO2 + Li2O with Delta_E = -15 meV/atom"
125.7.2 Finite-Temperature Stability#
- 125.7.2.1 Implement vibrational free energy from phonons: F_vib(T) = integral over phonon DOS of [hbaromega/2 + kT * ln(1 - exp(-hbaromega/kT))] * g(omega) d(omega) — using phonon DOS from the phonon module (Phase 119 if available) or from Einstein/Debye model with fitted theta_D
- 125.7.2.2 Implement electronic free energy: F_el(T) = E_el(T) - TS_el(T), where S_el = -k_B * integral [fln(f) + (1-f)*ln(1-f)] * g(E) dE with f the Fermi-Dirac distribution — computed from the electronic density of states g(E) around the Fermi level, significant for metals at high T
- 125.7.2.3 Implement configurational free energy from cluster expansion: F_config(T) computed via thermodynamic integration of MC results from Section 125.6 — the key entropic contribution for alloy phase stability, capturing both ideal and excess configurational entropy
- 125.7.2.4 Implement magnetic entropy contribution: S_mag = R * ln(2*S+1) at high T (full disorder), reduced at low T by magnetic ordering — interpolated using the Inden-Hillert-Jarl model from Section 125.2.9, or computed from DFT magnetic ground state + spin dynamics
- 125.7.2.5 Implement total Gibbs free energy: G(T,P) = E_DFT + F_vib(T) + F_el(T) + F_config(T) + F_mag(T) + P*V(T,P) — combining all contributions for a complete ab initio prediction of phase stability at finite temperature and pressure
125.7.3 Quasi-Harmonic Approximation#
- 125.7.3.1 Implement quasi-harmonic approximation (QHA): compute phonon frequencies at multiple volumes, fit F_vib(V,T), add E_el(V) to get F(V,T), minimize F with respect to V at each T to get the equilibrium volume V_eq(T), thermal expansion alpha(T), bulk modulus B(T), and free energy G(T,P) = F(V_eq, T) + P*V_eq
- 125.7.3.2 Implement equation of state fitting: fit E(V) data to Birch-Murnaghan, Vinet, or Murnaghan EOS to extract V_0, B_0, B' — with statistical comparison between EOS forms (F-test, BIC) to select the best fit
- 125.7.3.3 Implement thermal expansion from QHA: alpha(T) = (1/V) _ (dV/dT)_P = gamma _ C_v / (B * V), where gamma is the thermodynamic Gruneisen parameter — computed from the volume dependence of phonon frequencies, with validation against experimental thermal expansion data
125.7.4 Reaction Thermodynamics#
- 125.7.4.1 Implement reaction free energy computation: for a reaction A + B -> C + D, compute Delta_G_rxn(T) = sum(G_products) - sum(G_reactants), where each G includes all finite-temperature contributions — identify the temperature at which Delta_G_rxn = 0 (equilibrium temperature) and the direction of spontaneity at each T
- 125.7.4.2 Implement metastability analysis: distinguish kinetic stability (high activation barrier, slow decomposition) from thermodynamic stability (on the convex hull) — compute decomposition driving force and estimate kinetic barrier from nudged elastic band (NEB) or from empirical correlations with E_hull
125.8 Diffusion & DICTRA-style Modeling (@kalika/thermodynamics)#
125.8.1 Diffusion Coefficients#
- 125.8.1.1 Implement Arrhenius diffusion coefficient: D(T) = D_0 * exp(-Q / RT), where D_0 is the pre-exponential factor and Q is the activation energy — with database of assessed D_0 and Q values for common systems (C in Fe, self-diffusion in FCC metals, etc.)
- 125.8.1.2 Implement vacancy mechanism diffusion: D = f _ a^2 _ nu _ exp(-E_m / kT) _ exp(-E_f / kT) * C_coord, where f is the correlation factor (0.7815 for FCC, 0.7272 for BCC), a is lattice parameter, nu is attempt frequency, E_m is migration barrier, E_f is vacancy formation energy — all computable from DFT
- 125.8.1.3 Implement Darken equation for interdiffusion: D_tilde = (x_B _ D_A_ + x_A _ D_B_) _ (1 + d_ln_gamma / d_ln_x) — relating intrinsic diffusivities D_A_, D_B* (tracer) to the measurable interdiffusion coefficient, with the thermodynamic factor from CALPHAD Gibbs energy (d2G/dx2 / RT)
- 125.8.1.4 Implement Manning's random alloy model: for multicomponent diffusion, compute the off-diagonal Onsager coefficients L_ij from the tracer diffusivities D_i* using Manning's equations — providing the full diffusion mobility matrix without requiring independent measurement of each L_ij
125.8.2 Multicomponent Diffusion#
- 125.8.2.1 Implement Onsager formalism: multicomponent flux J_i = -sum_j L_ij _ grad(mu_j), where L_ij is the Onsager mobility matrix (symmetric, positive semi-definite) — transform between the Onsager (mobility) and Fick (diffusivity) representations using the thermodynamic factor matrix: D_ij = sum_k L_ik _ d2G/dx_k*dx_j / (c * RT)
- 125.8.2.2 Implement multicomponent diffusion coefficient matrix: the (C-1) x (C-1) interdiffusion matrix D_tilde_ij in the volume-fixed reference frame — computed from CALPHAD mobility database parameters (activation energy and pre-exponential for each M_i as function of composition) and CALPHAD thermodynamic factor
- 125.8.2.3 Implement composition-dependent mobilities: atomic mobility M_i(T, x) = (1/RT) _ M_i_0 _ exp(-Q_i / RT), where M_i_0 and Q_i are Redlich-Kister functions of composition — the DICTRA mobility database format, stored and assessed similarly to thermodynamic parameters
125.8.3 1D Diffusion Simulation#
- 125.8.3.1 Implement 1D finite difference diffusion solver: solve dc_i/dt = d/dx (sum_j D_ij * dc_j/dx) on a 1D grid with Crank-Nicolson (implicit) time stepping — supporting diffusion couple geometry (two semi-infinite alloys joined at x=0), thin film geometry (finite source), and carburization/decarburization boundary conditions
- 125.8.3.2 Implement variable grid (Murray-Landis transformation): for moving boundary problems (e.g., growing precipitate), transform to a grid that moves with the interface — the Landau transform xi = x / X(t) where X(t) is the interface position, converting the moving boundary problem to a fixed-domain problem with an extra advection term
- 125.8.3.3 Implement sharp interface model with local equilibrium: DICTRA-style — at each interface between phases, assume local thermodynamic equilibrium (compositions given by tie-line at the local T), compute interfacial flux balance (mass conservation across interface), and solve for interface velocity v = (J_left - J_right) / (c_left - c_right) — coupling the diffusion PDE with CALPHAD equilibrium at every time step
- 125.8.3.4 Implement homogenization model: for dendritic microstructures, solve diffusion within a representative volume element with periodic boundary conditions — simulating homogenization heat treatment of cast alloys, predicting time to achieve desired compositional uniformity
125.8.4 Diffusion-Controlled Transformations#
- 125.8.4.1 Implement Kirkendall effect: compute marker velocity v_K = (D_A* - D_B*) * (dc/dx) — predicting Kirkendall void formation in diffusion couples where intrinsic diffusivities differ significantly (e.g., Cu-Ni, Cu-Zn)
- 125.8.4.2 Implement uphill diffusion: in spinodal decomposition, D_eff < 0 (negative interdiffusion coefficient when d2G/dx2 < 0) — causing diffusion up the concentration gradient, amplifying compositional fluctuations — simulate with the Cahn-Hilliard equation: dc/dt = M * laplacian(mu) where mu = dF/dc - 2*kappa * laplacian(c)
- 125.8.4.3 Implement diffusion-controlled growth kinetics: for a planar interface, compute the parabolic growth rate x(t) = alpha * sqrt(D*t), where alpha is determined by the Stefan condition (mass balance at the interface) — enabling comparison with DICTRA results and experimental measurements
125.9 Nucleation & Precipitation (@kalika/thermodynamics)#
125.9.1 Classical Nucleation Theory (CNT)#
- 125.9.1.1 Implement critical nucleus computation: r* = 2*gamma / Delta_G_v, where gamma is the interfacial energy (J/m^2) and Delta_G_v is the volumetric driving force (J/m^3) — Delta_G_v computed from CALPHAD driving force (125.3.3.4) divided by molar volume, gamma from database or estimated from broken-bond model
- 125.9.1.2 Implement nucleation barrier: Delta_G* = (16pigamma^3) / (3*Delta_G_v^2) for spherical nucleus — with corrections for non- spherical nucleus geometry (lens-shaped for grain boundary, cap-shaped for heterogeneous) and elastic strain energy contribution Delta_G_el = (delta^2 _ E _ V) / (1 - nu) for coherent precipitates (where delta is the misfit strain)
- 125.9.1.3 Implement nucleation rate: J = Z _ beta_ _ N_0 _ exp(-Delta_G* / kT), where Z = sqrt(Delta_G* / (3pikTn^2)) is the Zeldovich factor (probability that a critical nucleus grows rather than dissolves), beta* = 4pir*^2 * D*c / a^4 is the attachment rate of atoms to the critical nucleus, and N_0 is the number of nucleation sites
- 125.9.1.4 Implement incubation time: tau = 1 / (2 _ Z^2 _ beta*) — the time delay before steady-state nucleation rate is reached, accounting for the transient buildup of the subcritical cluster distribution — with the time-dependent nucleation rate J(t) = J_ss * exp(-tau / t)
125.9.2 Heterogeneous Nucleation#
- 125.9.2.1 Implement heterogeneous nucleation on grain boundaries: Delta_G*_het = Delta_G*_hom _ f(theta), where f(theta) = (2 + cos(theta)) _ (1 - cos(theta))^2 / 4 is the catalytic factor depending on the contact angle theta between precipitate and matrix at the grain boundary — with theta determined by the ratio of boundary energies (Young's equation)
- 125.9.2.2 Implement nucleation on dislocations: reduced nucleation barrier due to elastic strain energy of the dislocation — Delta_G*_disl = Delta_G*_hom - Delta_G_strain, with the strain energy contribution from the dislocation stress field reducing the elastic misfit energy for precipitates forming in the dislocation core
- 125.9.2.3 Implement nucleation site density: N_0 = f(site_type) — bulk sites (N_0 ~ 10^28 /m^3, one per atom), grain boundary (N_0 ~ grain boundary area * site density ~ 10^24 /m^3 for 10 um grain size), dislocation (N_0 ~ dislocation density ~ 10^14 /m^3 for annealed metal) — with user-configurable microstructural parameters
125.9.3 Precipitation Kinetics (KWN Model)#
- 125.9.3.1 Implement KWN (Kampmann-Wagner numerical) model: track the size distribution of precipitates as a discrete histogram of particle classes — at each time step: (a) nucleate new particles at size r* with rate J, (b) grow/shrink all particles according to dr/dt = D/(r) * (c_inf - c_eq(r)) / (c_p - c_eq(r)) where c_eq(r) includes the Gibbs-Thomson effect, (c) update matrix composition by mass balance
- 125.9.3.2 Implement Gibbs-Thomson effect: the equilibrium solubility at a curved interface c_eq(r) = c_eq(inf) * exp(2gammaV_m / (r*RT)) — small particles have higher equilibrium solubility, driving Ostwald ripening (larger particles grow at the expense of smaller ones)
- 125.9.3.3 Implement multi-class precipitate model: discretize the particle size distribution into N classes (typically 100-500), track the number density in each class, handle class boundaries and particle transfer between classes during growth — with adaptive class spacing (finer near r*) for numerical accuracy
- 125.9.3.4 Implement KWN output: time evolution of mean precipitate radius, volume fraction, number density, size distribution, matrix supersaturation, and derived properties (yield strength contribution) — enabling prediction of precipitation hardening during aging heat treatment
125.9.4 Coarsening#
- 125.9.4.1 Implement LSW (Lifshitz-Slyozov-Wagner) coarsening theory: mean radius evolution r_bar(t)^3 - r_bar(t_0)^3 = K * (t - t_0), where K = (8gammaV_mDc_eq) / (9*RT) — the cube-root time law for diffusion-controlled coarsening, with the predicted self-similar steady- state size distribution (LSW distribution, maximum at r/r_bar = 1.5)
- 125.9.4.2 Implement modified coarsening for finite volume fraction: the LSW theory assumes infinitely dilute precipitates — corrections by Ardell, Brailsford-Wynblatt, and TIDC (trans-interface diffusion- controlled) models that account for finite volume fraction effects on coarsening kinetics and the broadened size distribution
125.9.5 Phase Transformation Kinetics#
- 125.9.5.1 Implement JMAK (Johnson-Mehl-Avrami-Kolmogorov) kinetics: f(t) = 1 - exp(-kt^n), where f is transformed fraction, k is the rate constant (depends on nucleation rate and growth rate), and n is the Avrami exponent (n = 1+dm, where d is growth dimensionality and m is time-dependence of nucleation: n=4 for 3D growth with constant nucleation, n=3 for 3D with site saturation)
- 125.9.5.2 Implement additivity rule for non-isothermal transformation: for continuous cooling, approximate the transformation by summing isothermal increments: integral of dt/tau(T(t)) = 1 at the start of transformation, where tau(T) is the isothermal incubation time from the TTT diagram — the Scheil additivity principle
- 125.9.5.3 Implement TTT diagram computation: at each temperature T below the transformation start, compute the incubation time (1% and 99% transformed) from JMAK kinetics with temperature-dependent k(T) — the resulting C-curve reflects the competition between driving force (increases with undercooling) and diffusion (decreases with undercooling)
- 125.9.5.4 Implement CCT diagram computation: from the TTT diagram and additivity rule, compute transformation start/finish times for specified cooling rates — the CCT diagram is the experimentally relevant counterpart of the TTT diagram, used for predicting microstructure from the cooling path
- 125.9.5.5 Implement precipitation strengthening models: Orowan mechanism (sigma_Orowan = M _ G _ b / (L - 2*r) for incoherent precipitates, where L is spacing, r is radius), shearing mechanism (sigma_shear for coherent precipitates, depending on APB energy, misfit strain, modulus mismatch), and coherency strengthening — with the transition from shearing to bypassing at the critical radius
125.10 Solidification (@kalika/thermodynamics)#
125.10.1 Equilibrium and Scheil Solidification#
- 125.10.1.1 Implement lever rule solidification: at each temperature during cooling, compute full equilibrium (all solid phases + liquid in equilibrium) — the fraction solid f_s from mass balance, assuming complete diffusion in both solid and liquid (infinite time) — producing solidification path (T vs. f_s) and final phase fractions
- 125.10.1.2 Implement Scheil-Gulliver solidification model: assume no diffusion in solid, complete mixing in liquid — at each temperature step, compute equilibrium between the liquid and an infinitesimal increment of new solid, reject the solid from equilibrium (it is frozen), update liquid composition — the Scheil equation: f_s = 1 - (T_L - T)/(T_L - T_S) * ... (for multicomponent, must be done numerically step by step)
- 125.10.1.3 Implement multicomponent Scheil solidification: at each temperature step dT: (a) compute equilibrium between current liquid and all possible solid phases, (b) determine which solid phase(s) form, (c) remove solid increment from liquid, (d) update liquid composition by mass balance, (e) check for invariant reactions (eutectic, peritectic) — coupling the Scheil stepping algorithm with the CALPHAD equilibrium solver at each step
- 125.10.1.4 Implement solidification output: solidification path (T vs. f_s), liquid composition path, solid phase fractions at each T, final as-cast phase constitution, solidification range (T_liquidus - T_solidus), freezing range, and microsegregation profile (composition of solid formed at each T, which is the core-to-surface profile in a dendrite)
125.10.2 Back-Diffusion Models#
- 125.10.2.1 Implement Brody-Flemings back-diffusion model: modification of Scheil to include limited solid-state diffusion — the effective partition coefficient k_eff is replaced by a modified expression involving the Fourier number alpha = D_s _ t_f / L^2 (where D_s is solid diffusivity, t_f is local solidification time, L is half dendrite arm spacing) — the Brody-Flemings equation: c_L = c_0 _ (1 - f_s)^{(k-1)/ (1 - 2alphak)}
- 125.10.2.2 Implement Clyne-Kurz modification: corrects the Brody- Flemings model for large alpha values (alpha > 0.1 where Brody-Flemings gives unphysical results) by replacing alpha with alpha' = alpha * (1 - exp(-1/alpha)) - exp(-1/(2*alpha))/2 — valid across the full range from Scheil (alpha=0) to lever rule (alpha->infinity)
- 125.10.2.3 Implement Won-Thomas back-diffusion model: further improvement for multicomponent systems, accounting for the nonlinear composition dependence of D_s and the varying solidification rate — solving the 1D diffusion equation within the solid numerically at each Scheil step, rather than using an approximate analytical formula
125.10.3 Dendrite Growth Kinetics#
- 125.10.3.1 Implement KGT (Kurz-Giovanola-Trivedi) dendrite tip model: compute the steady-state dendrite tip velocity V and tip radius R as functions of undercooling Delta_T — using the Ivantsov solution for the thermal field around a paraboloid of revolution: Omega_T = Iv(Pe_T) where Pe_T = VR/(2alpha_T) is the thermal Peclet number, plus marginal stability criterion R = lambda* / (2*pi) (or minimum undercooling criterion)
- 125.10.3.2 Implement solutal dendrite tip kinetics: for alloy solidification, include the solutal undercooling Delta_T_c = m_L _ c_L _ (1 - 1/Iv_c) alongside thermal undercooling — the total undercooling Delta_T = Delta_T_T + Delta_T_c + Delta_T_R (curvature) + Delta_T_k (kinetic), with coupled Ivantsov solutions for thermal and solutal fields
- 125.10.3.3 Implement columnar-to-equiaxed transition (CET): predict the CET based on Hunt's criterion — equiaxed grains form ahead of the columnar front when the volume fraction of equiaxed grains exceeds ~0.5, controlled by the undercooling at the dendrite tips and the nucleation rate of equiaxed grains ahead of the columnar front
125.10.4 Eutectic and Peritectic Solidification#
- 125.10.4.1 Implement Jackson-Hunt eutectic growth model: predict the steady-state eutectic spacing lambda and growth rate V relationship: V * lambda^2 = K (constant for a given alloy) — with K computed from phase diagram slopes, compositions, and interfacial energies, and the minimum undercooling at the optimal spacing lambda_opt
- 125.10.4.2 Implement eutectic microstructure prediction: lamellar vs. rod eutectic morphology selection based on volume fraction (rod when minority phase < ~28%), with interlamellar/inter-rod spacing from Jackson-Hunt
- 125.10.4.3 Implement peritectic solidification kinetics: the peritectic reaction (L + alpha -> beta) requires diffusion through the beta shell surrounding alpha — model the growth of the beta layer with diffusion- controlled kinetics, predicting incomplete peritectic reaction (common in practice due to slow solid-state diffusion)
125.10.5 Multicomponent Solidification Integration#
- 125.10.5.1 Implement solidification path prediction for real alloys: couple Scheil or back-diffusion model with the full CALPHAD database — predict solidification sequence, phase formation temperatures, and microsegregation for real multicomponent alloys (e.g., predict that Al-7Si-0.3Mg solidifies as: primary alpha-Al, then Al-Si eutectic, then Mg2Si formation at ~555C)
- 125.10.5.2 Implement solidification property prediction: latent heat release profile L(T) = sum_phi (df_phi/dT) * Delta_H_phi, fraction solid curve f_s(T), and specific heat during solidification Cp_eff(T) = Cp_intrinsic + L(T) — the inputs needed for casting simulation (thermal modeling)
125.11 Integration & Validation (@kalika/thermodynamics)#
125.11.1 Cross-Module Integration#
- 125.11.1.1 Implement CALPHAD-to-cluster-expansion bridge: extract CALPHAD interaction parameters for a binary system, compare the predicted mixing enthalpy with cluster expansion formation energies — enabling validation of CALPHAD assessments against first-principles data and hybrid CALPHAD+CE approaches
- 125.11.1.2 Implement diffusion-precipitation coupling: connect the DICTRA-style diffusion solver (125.8) with the KWN precipitation model (125.9.3) — the diffusion field provides the local supersaturation that drives nucleation and growth, while precipitation depletes the matrix composition affecting subsequent diffusion
- 125.11.1.3 Implement solidification-precipitation coupling: after Scheil solidification predicts the as-cast microsegregation profile, use the precipitation model to predict phase evolution during subsequent heat treatment (solution treatment, aging) — the full casting-to- properties workflow
125.11.2 Benchmark Validation#
- 125.11.2.1 Implement Fe-C binary phase diagram benchmark: compute the Fe-C phase diagram using the SGTE/TCFE database parameters, compare against the well-known experimental diagram — verify eutectic temperature (1147C), eutectoid temperature (727C), eutectoid composition (0.76 wt% C), maximum carbon solubility in austenite (2.14 wt% C at eutectic T)
- 125.11.2.2 Implement Cu-Zn binary phase diagram benchmark: compute using assessed parameters, verify alpha/beta phase boundaries, the five peritectic reactions, and the order-disorder transitions (beta -> beta') — a more complex topology test than Fe-C
- 125.11.2.3 Implement Al-Cu-Mg ternary benchmark: compute the 200C isothermal section showing the theta (Al2Cu), S (Al2CuMg), and T phase fields — verify against experimental data from the ASM Alloy Phase Diagram Database, testing the ternary extrapolation and three-phase equilibrium computation
- 125.11.2.4 Implement Scheil solidification benchmark: compute Scheil solidification path for Al-7Si-0.3Mg alloy, compare predicted solidification range, eutectic fraction, and Mg2Si formation temperature against published experimental data and Thermo-Calc/JMatPro reference results
- 125.11.2.5 Implement cluster expansion benchmark: reproduce the Cu-Au cluster expansion from ATAT tutorial — verify that the fitted ECIs predict the correct ground states (L1_0 CuAu, L1_2 Cu3Au, L1_2 CuAu3) and the order-disorder transition temperatures within 50K of experiment
- 125.11.2.6 Implement Pourbaix diagram benchmark: compute the Fe-H2O Pourbaix diagram at 25C, verify the immunity/corrosion/passivation regions against the standard textbook diagram — test line slopes (59 mV/pH for H+/H2, independent of pH for Fe/Fe2+ at E = -0.44V), and triple point locations
125.11.3 Performance & Rust Integration Tests#
- 125.11.3.1 Implement equilibrium solver performance benchmark: measure time for binary equilibrium (target < 1ms), ternary equilibrium (target < 10ms), and 10-component equilibrium with 15 phases (target < 100ms) — comparing Rust solver performance against pyCalphad reference times
- 125.11.3.2 Implement the Monte Carlo performance benchmark for canonical MC with the cluster-expansion Hamiltonian on a 20×20×20 FCC supercell (32,000 sites), single-core. Restated 2026-09-18: the original "> 10,000 sweeps/second" is not physically attainable — at 32,000 sites it means 3.2×10^8 cluster-expansion ΔE evaluations per second per core (~3 ns each). Replace it with a flips-per-second target: ≥ 10^6 attempted single-flip updates/s/core (≈ 30 full sweeps/s at 32k sites) for a truncated pair+triplet cluster expansion, measured in the Rust core. Verify:
cargo bench(or a criterion bench) on the Rust MC core reports attempted flips/s/core on the 32k-site cell and asserts ≥ 10^6, with the machine and the cluster-expansion truncation recorded. - 125.11.3.3 Implement Scheil solidification performance benchmark: measure time for complete Scheil calculation with 10 components and 20 possible phases — target < 5 seconds for the full solidification path, testing the efficiency of the equilibrium solver when called thousands of times along the cooling path
- 125.11.3.4 Implement napi-rs binding tests verifying that every Rust function exposed through napi-rs produces results identical to the TypeScript reference implementation. (Blocker made visible 2026-09-18: the prior HTML comment.) napi-rs builds locally (no GPU needed). Verify: a spec calls each exposed binding and its TS reference on at least 100 seeded random inputs per function, asserts agreement to 12 significant digits (the original bar; state any function that cannot meet it and why), records the measured speedup per function (the original expectation was 10–100× for the equilibrium solver and 50–200× for MC; report the number, do not assert it), and the native module loads on both the Linux server and the Mac.
<!-- prettier-ignore-end -->