matterviz 0.3.6 → 0.4.0

package/dist/src/lib/convex-hull/gas-thermodynamics.ts

@@ -1,405 +0,0 @@
-// Gas phase thermodynamics for convex hull calculations
-// Enables atmosphere-controlled phase diagram analysis
-
-import { count_atoms_in_composition } from '$lib/composition'
-import type {
-  GasAnalysis,
-  GasSpecies,
-  GasThermodynamicsConfig,
-  GasThermodynamicsProvider,
-  PhaseData,
-} from '$lib/convex-hull/types'
-import { DEFAULT_GAS_PRESSURES, GAS_SPECIES } from '$lib/convex-hull/types'
-import type { ElementSymbol } from '$lib/element'
-
-// Physical constants
-export const R_EV_PER_K = 8.617333262e-5 // Gas constant in eV/K (k_B)
-export const P_REF = 1.0 // Reference pressure in bar
-
-// Default element-to-gas mapping (which element comes from which gas)
-export const DEFAULT_ELEMENT_TO_GAS: Readonly<Partial<Record<ElementSymbol, GasSpecies>>> = {
-  O: `O2`,
-  N: `N2`,
-  H: `H2`,
-  F: `F2`,
-  C: `CO2`, // Carbon typically from CO2 in oxidizing atmospheres
-}
-
-// Stoichiometric coefficients: atoms of element per molecule of gas
-// e.g., O2 has 2 O atoms, H2O has 2 H and 1 O
-export const GAS_STOICHIOMETRY: Readonly<
-  Record<GasSpecies, Partial<Record<ElementSymbol, number>>>
-> = {
-  O2: { O: 2 },
-  N2: { N: 2 },
-  H2: { H: 2 },
-  F2: { F: 2 },
-  CO: { C: 1, O: 1 },
-  CO2: { C: 1, O: 2 },
-  H2O: { H: 2, O: 1 },
-}
-
-// Default Thermodynamic Data (abstracted - users can provide their own)
-
-// Entropy contribution T*S at various temperatures (in eV/molecule)
-// Data points at 0, 298, 300, 400, ..., 2000 K
-// This data structure allows interpolation between tabulated values
-interface TabulatedTSData {
-  temperatures: number[] // K
-  values: number[] // eV/molecule
-}
-
-// Default T*S data for common gases (in eV/molecule)
-// Source: Barin Thermochemical Tables and NBS Thermochemical Tables
-// Data compiled to match PIRO (https://github.com/GENESIS-EFRC/piro)
-// Note: These values are T*S in eV/molecule
-// oxfmt-ignore
-const DEFAULT_TS_DATA: Readonly<Record<GasSpecies, TabulatedTSData>> = {
-  O2: {
-    temperatures: [0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
-    values: [0, 0.317, 0.3192, 0.4433, 0.5718, 0.7041, 0.8396, 0.9781, 1.119, 1.2623, 1.4075, 1.5547, 1.7036, 1.8541, 2.006, 2.1594, 2.3141, 2.47, 2.6271, 2.7854],
-  },
-  H2: {
-    temperatures: [0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
-    values: [0, 0.2019, 0.2034, 0.2886, 0.3776, 0.4697, 0.5645, 0.6614, 0.7605, 0.8614, 0.964, 1.0683, 1.1741, 1.2815, 1.3902, 1.5003, 1.6116, 1.7242, 1.838, 1.9528],
-  },
-  N2: {
-    temperatures: [0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
-    values: [0, 0.2959, 0.2981, 0.4149, 0.5356, 0.6596, 0.7866, 0.9161, 1.0481, 1.1822, 1.3184, 1.4563, 1.596, 1.7372, 1.8799, 2.0239, 2.1693, 2.3158, 2.4634, 2.6122],
-  },
-  CO: {
-    temperatures: [0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
-    values: [0, 0.3054, 0.3076, 0.4275, 0.5515, 0.6788, 0.8092, 0.9423, 1.0778, 1.2155, 1.3552, 1.4967, 1.64, 1.7848, 1.9311, 2.0788, 2.2277, 2.3779, 2.5291, 2.6815],
-  },
-  CO2: {
-    temperatures: [0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
-    values: [0, 0.2202, 0.2218, 0.3113, 0.4057, 0.5042, 0.6064, 0.7116, 0.8197, 0.9303, 1.0432, 1.1582, 1.2751, 1.3938, 1.5141, 1.636, 1.7593, 1.8839, 2.0098, 2.1369],
-  },
-  H2O: {
-    temperatures: [0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
-    values: [0, 0.1946, 0.1961, 0.2749, 0.357, 0.4419, 0.5293, 0.6189, 0.7107, 0.8045, 0.9001, 0.9975, 1.0966, 1.1972, 1.2994, 1.403, 1.5079, 1.6142, 1.7216, 1.8303],
-  },
-  F2: {
-    // F2 not in Barin/NBS tables used by PIRO - approximated from similar homonuclear diatomics (O2, N2)
-    temperatures: [
-      0, 298, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600,
-      1700, 1800, 1900, 2000,
-    ],
-    values: [
-      0, 0.31, 0.312, 0.435, 0.56, 0.69, 0.82, 0.96, 1.1, 1.24, 1.38, 1.53, 1.68, 1.83,
-      1.98, 2.13, 2.29, 2.45, 2.61, 2.77,
-    ],
-  },
-}
-
-// Formation enthalpies H_f at 0K in eV/molecule
-// These are the reference energies for formation from elements
-const DEFAULT_ENTHALPY: Readonly<Partial<Record<GasSpecies, number>>> = {
-  CO: -0.5897,
-  // CO2: Base value -1.3583 eV from JANAF tables, with -0.2482 eV correction
-  // to improve accuracy for carbonate phase predictions (Wang et al., PRB 73, 195107)
-  CO2: -1.3583 - 0.2482,
-  H2O: -0.82547,
-  // O2, N2, H2, F2 are reference states with H_f = 0
-}
-
-// Interpolation Helpers
-
-// Linearly interpolate T*S value at given temperature
-function interpolate_ts(data: TabulatedTSData, T: number): number {
-  const { temperatures, values } = data
-
-  // Clamp to valid range
-  if (T <= temperatures[0]) return values[0]
-  if (T >= temperatures[temperatures.length - 1]) {
-    return values[values.length - 1]
-  }
-
-  // Find bracketing indices
-  let idx = 0
-  while (idx < temperatures.length - 1 && temperatures[idx + 1] < T) idx++
-
-  const T_low = temperatures[idx]
-  const T_high = temperatures[idx + 1]
-  const v_low = values[idx]
-  const v_high = values[idx + 1]
-
-  // Linear interpolation
-  const fraction = (T - T_low) / (T_high - T_low)
-  return v_low + fraction * (v_high - v_low)
-}
-
-// Default Provider Implementation
-
-// Create the default gas thermodynamics provider using built-in data
-export function create_default_gas_provider(): GasThermodynamicsProvider {
-  return {
-    get_standard_chemical_potential(gas: GasSpecies, T: number): number {
-      // μ°(T) = H_f - T*S
-      // For elemental gases (O2, N2, H2, F2), H_f = 0
-      const H_f = DEFAULT_ENTHALPY[gas] ?? 0
-      const TS = interpolate_ts(DEFAULT_TS_DATA[gas], T)
-      return H_f - TS
-    },
-
-    get_supported_gases(): GasSpecies[] {
-      return [...GAS_SPECIES]
-    },
-
-    get_temperature_range(): [number, number] {
-      return [0, 2000]
-    },
-  }
-}
-
-// Singleton default provider
-let default_provider: GasThermodynamicsProvider | null = null
-
-// Get the default gas thermodynamics provider (lazy initialization)
-export function get_default_gas_provider(): GasThermodynamicsProvider {
-  default_provider ??= create_default_gas_provider()
-  return default_provider
-}
-
-// Gas Chemical Potential Calculations
-
-// Number of atoms in each gas molecule
-const GAS_NUM_ATOMS: Readonly<Record<GasSpecies, number>> = {
-  O2: 2,
-  N2: 2,
-  H2: 2,
-  F2: 2,
-  CO: 2,
-  CO2: 3,
-  H2O: 3,
-}
-
-// Compute gas chemical potential at given temperature and pressure
-// Following PIRO's convention, all values are per atom:
-// μ_per_atom(T, P) = H_per_atom - (TS)_per_atom + k_B·T·ln(P/P₀) / num_atoms
-// provider - Thermodynamic data provider
-// gas - Gas species
-// T - Temperature in Kelvin
-// P - Pressure in bar
-// Returns chemical potential in eV/atom
-export function compute_gas_chemical_potential(
-  provider: GasThermodynamicsProvider,
-  gas: GasSpecies,
-  T: number,
-  P: number,
-): number {
-  const mu_standard = provider.get_standard_chemical_potential(gas, T)
-
-  // Clamp invalid/infinite pressure to reference pressure
-  const effective_P = Number.isFinite(P) && P > 0 ? P : P_REF
-
-  // μ_per_atom(T, P) = μ°_per_atom(T) + k_B·T·ln(P/P₀) / num_atoms
-  // The RT·ln(P) term must be divided by num_atoms to match PIRO's per-atom convention
-  const num_atoms = GAS_NUM_ATOMS[gas]
-  return mu_standard + (R_EV_PER_K * T * Math.log(effective_P / P_REF)) / num_atoms
-}
-
-// Compute chemical potential per atom of a specific element from a gas
-// Since compute_gas_chemical_potential returns per-atom of gas molecule,
-// we need to convert to per-atom of the specific element.
-// For O from O2: μ(O) = μ(O2)_per_atom * num_atoms(O2) / stoich(O in O2) = μ(O2)_per_atom * 2 / 2 = μ(O2)_per_atom
-// For O from CO2: μ(O) = μ(CO2)_per_atom * num_atoms(CO2) / stoich(O in CO2) = μ(CO2)_per_atom * 3 / 2
-// provider - Thermodynamic data provider
-// gas - Gas species
-// element - Element symbol
-// T - Temperature in Kelvin
-// P - Pressure in bar
-// Returns chemical potential per atom of element in eV/atom
-export function compute_element_chemical_potential(
-  provider: GasThermodynamicsProvider,
-  gas: GasSpecies,
-  element: ElementSymbol,
-  T: number,
-  P: number,
-): number {
-  const mu_gas_per_atom = compute_gas_chemical_potential(provider, gas, T, P)
-  const num_atoms = GAS_NUM_ATOMS[gas]
-  const stoich = GAS_STOICHIOMETRY[gas][element] ?? 1
-  // Convert from per-atom-of-gas to per-atom-of-element
-  return (mu_gas_per_atom * num_atoms) / stoich
-}
-
-// Gas Analysis and Corrections
-
-// Analyze entries to determine which gases are relevant for the chemical system
-export function analyze_gas_data(
-  entries: PhaseData[],
-  config: GasThermodynamicsConfig,
-): GasAnalysis {
-  const enabled_gases = config.enabled_gases ?? []
-  if (enabled_gases.length === 0) {
-    return {
-      has_gas_dependent_elements: false,
-      gas_elements: [],
-      relevant_gases: [],
-    }
-  }
-
-  // Get element-to-gas mapping
-  const element_to_gas = {
-    ...DEFAULT_ELEMENT_TO_GAS,
-    ...config.element_to_gas,
-  }
-
-  // Find all elements in the chemical system
-  const all_elements = new Set<ElementSymbol>()
-  for (const entry of entries) {
-    for (const el of Object.keys(entry.composition)) {
-      if ((entry.composition[el as ElementSymbol] ?? 0) > 0) {
-        all_elements.add(el as ElementSymbol)
-      }
-    }
-  }
-
-  // Find elements that come from enabled gases
-  const gas_elements: ElementSymbol[] = []
-  const relevant_gases: GasSpecies[] = []
-
-  for (const el of all_elements) {
-    const gas = element_to_gas[el]
-    if (gas && enabled_gases.includes(gas)) {
-      gas_elements.push(el)
-      if (!relevant_gases.includes(gas)) {
-        relevant_gases.push(gas)
-      }
-    }
-  }
-
-  return {
-    has_gas_dependent_elements: gas_elements.length > 0,
-    gas_elements,
-    relevant_gases,
-  }
-}
-
-// Get effective pressures for gases, using defaults for unspecified values
-export function get_effective_pressures(
-  config: GasThermodynamicsConfig,
-): Record<GasSpecies, number> {
-  const pressures = { ...DEFAULT_GAS_PRESSURES }
-  if (config.pressures) {
-    for (const [gas, P] of Object.entries(config.pressures)) {
-      if (Number.isFinite(P) && P > 0) {
-        pressures[gas as GasSpecies] = P
-      }
-    }
-  }
-  return pressures
-}
-
-// Compute gas chemical potential correction for an entry's energy
-// The correction accounts for the difference between the gas chemical potential
-// at the given (T, P) and the reference state (0 K, 1 bar).
-// For a compound A_x B_y where B comes from gas B2:
-// ΔE_correction = (y/2) * [μ(B2, T, P) - μ(B2, 0K, 1bar)]
-// This shifts the formation energy based on the gas atmosphere.
-export function compute_gas_correction(
-  entry: PhaseData,
-  config: GasThermodynamicsConfig,
-  T: number,
-  pressures: Record<GasSpecies, number>,
-): number {
-  const provider = config.provider ?? get_default_gas_provider()
-  const element_to_gas = {
-    ...DEFAULT_ELEMENT_TO_GAS,
-    ...config.element_to_gas,
-  }
-  const enabled_gases = new Set(config.enabled_gases ?? [])
-
-  let correction = 0
-  const n_atoms = count_atoms_in_composition(entry.composition)
-
-  for (const [el_str, amount] of Object.entries(entry.composition)) {
-    if (typeof amount !== `number` || amount <= 0) continue
-    const el = el_str as ElementSymbol
-
-    const gas = element_to_gas[el]
-    if (!gas || !enabled_gases.has(gas)) continue
-
-    const P = pressures[gas]
-    const stoich = GAS_STOICHIOMETRY[gas][el] ?? 1
-    const num_atoms = GAS_NUM_ATOMS[gas]
-
-    // Chemical potential per atom of gas at current (T, P)
-    const mu_TP = compute_gas_chemical_potential(provider, gas, T, P)
-
-    // Chemical potential per atom of gas at reference (0K, 1bar) - just H_f since T*S = 0 at 0K
-    const mu_ref = provider.get_standard_chemical_potential(gas, 0)
-
-    // Correction per atom of this element
-    // Convert from per-atom-of-gas to per-atom-of-element: multiply by num_atoms, divide by stoich
-    const delta_mu = ((mu_TP - mu_ref) * num_atoms) / stoich
-
-    // Total correction for this element in the compound (per atom of compound)
-    correction += (amount / n_atoms) * delta_mu
-  }
-
-  return correction
-}
-
-// Apply gas chemical potential corrections to elemental reference entries only.
-// IMPORTANT: Corrections are only applied to unary (single-element) entries.
-// This is thermodynamically correct because:
-// - Formation energy = E(compound) - Σ n_i * μ_i
-// - For gas-forming elements (O, N, H...), μ_i = μ(gas, T, P)
-// - For solid elements, μ_i = E(element)
-// If we applied corrections to ALL entries, they would cancel out in the
-// formation energy calculation, resulting in no change to the hull.
-// By only correcting unary references, we effectively replace the standard
-// elemental reference with the gas chemical potential at (T, P).
-export function apply_gas_corrections(
-  entries: PhaseData[],
-  config: GasThermodynamicsConfig | undefined,
-  T: number,
-): PhaseData[] {
-  if (!config?.enabled_gases?.length) return entries
-
-  const analysis = analyze_gas_data(entries, config)
-
-  // No gas-dependent elements, return entries unchanged
-  if (!analysis.has_gas_dependent_elements) return entries
-
-  const pressures = get_effective_pressures(config)
-
-  return entries.map((entry) => {
-    // Only apply corrections to unary (single-element) entries
-    // These serve as reference states for formation energy calculations
-    const elements_in_entry = Object.entries(entry.composition).filter(
-      ([, amt]) => typeof amt === `number` && amt > 0,
-    )
-    if (elements_in_entry.length !== 1) return entry // Not unary, skip
-
-    const correction = compute_gas_correction(entry, config, T, pressures)
-
-    // If no correction needed, return entry unchanged
-    if (Math.abs(correction) < 1e-12) return entry
-
-    // Apply correction to energy (update both energy and energy_per_atom
-    // so downstream formation energy calculations use the corrected value)
-    // Both fields store per-atom values, and correction is also per-atom
-    const corrected_energy = entry.energy + correction
-    return {
-      ...entry,
-      energy: corrected_energy,
-      energy_per_atom: corrected_energy,
-    }
-  })
-}
-
-// Format chemical potential for display (e.g., "-1.23 eV")
-export function format_chemical_potential(mu: number, decimals = 3): string {
-  return `${mu >= 0 ? `+` : ``}${mu.toFixed(decimals)} eV`
-}
-
-// Format pressure for display (scientific notation for very small/large values)
-export function format_pressure(P: number): string {
-  if (P >= 0.01 && P < 100) {
-    return `${P.toPrecision(3)} bar`
-  }
-  return `${P.toExponential(2)} bar`
-}