matterviz 0.3.6 → 0.3.7

package/dist/convex-hull/barycentric-coords.js

@@ -0,0 +1,182 @@
+import { compute_e_form_per_atom, find_lowest_energy_unary_refs } from './thermodynamics';
+import { is_unary_entry } from './helpers';
+// --- Ternary coordinates ---
+export const TRIANGLE_VERTICES = [
+    [1, 0],
+    [0.5, Math.sqrt(3) / 2],
+    [0, 0],
+];
+export function composition_to_barycentric_3d(composition, elements) {
+    if (elements.length !== 3) {
+        throw new Error(`Ternary system requires exactly 3 elements, got ${elements.length}`);
+    }
+    const amounts = elements.map((el) => composition[el] || 0);
+    const total = amounts.reduce((sum, amt) => sum + amt, 0);
+    if (total === 0) {
+        throw new Error(`Composition has no elements from the ternary system: ${elements.join(`-`)}`);
+    }
+    const normalized = amounts.map((amount) => amount / total);
+    return [normalized[0], normalized[1], normalized[2]];
+}
+// map barycentric coordinates to triangular 2D coordinates
+export function barycentric_to_ternary_xy(barycentric) {
+    const [v0, v1, v2] = TRIANGLE_VERTICES;
+    const [a, b, c] = barycentric;
+    const x = v0[0] * a + v1[0] * b + v2[0] * c;
+    const y = v0[1] * a + v1[1] * b + v2[1] * c;
+    return [x, y];
+}
+// map barycentric coordinates to ternary 3D coordinates
+export function barycentric_to_ternary_xyz(barycentric, formation_energy) {
+    const [x, y] = barycentric_to_ternary_xy(barycentric);
+    return { x, y, z: formation_energy };
+}
+export function get_triangle_centroid() {
+    const [v0, v1, v2] = TRIANGLE_VERTICES;
+    const centroid_x = (v0[0] + v1[0] + v2[0]) / 3;
+    const centroid_y = (v0[1] + v1[1] + v2[1]) / 3;
+    return { x: centroid_x, y: centroid_y, z: 0 };
+}
+export function calculate_face_normal(p1, p2, p3) {
+    const edge1 = { x: p2.x - p1.x, y: p2.y - p1.y, z: p2.z - p1.z };
+    const edge2 = { x: p3.x - p1.x, y: p3.y - p1.y, z: p3.z - p1.z };
+    const nx = edge1.y * edge2.z - edge1.z * edge2.y;
+    const ny = edge1.z * edge2.x - edge1.x * edge2.z;
+    const nz = edge1.x * edge2.y - edge1.y * edge2.x;
+    const magnitude = Math.hypot(nx, ny, nz);
+    if (magnitude === 0)
+        return { x: 0, y: 0, z: 1 };
+    return { x: nx / magnitude, y: ny / magnitude, z: nz / magnitude };
+}
+export const calculate_face_centroid = (p1, p2, p3) => ({
+    x: (p1.x + p2.x + p3.x) / 3,
+    y: (p1.y + p2.y + p3.y) / 3,
+    z: (p1.z + p2.z + p3.z) / 3,
+});
+export function get_ternary_3d_coordinates(entries, elements, el_refs) {
+    if (elements.length !== 3) {
+        throw new Error(`Ternary convex hull requires exactly 3 elements, got ${elements.length}`);
+    }
+    // Filter to entries within the ternary system first (use Set for O(1) lookups)
+    const element_set = new Set(elements);
+    const within_system = entries.filter((entry) => Object.keys(entry.composition).every((el) => element_set.has(el)));
+    if (within_system.length === 0) {
+        throw new Error(`No entries found within the ternary system: ${elements.join(`-`)}`);
+    }
+    // Check if we have formation energies - provide detailed diagnostics if missing
+    const entries_with_e_form = within_system.filter((entry) => typeof entry.e_form_per_atom === `number` && Number.isFinite(entry.e_form_per_atom));
+    // If none have e_form_per_atom, try to derive them using refs; only error if we can't
+    const refs = el_refs ?? find_lowest_energy_unary_refs(entries);
+    if (entries_with_e_form.length === 0) {
+        const missing_refs = elements.filter((el) => !refs[el]);
+        if (missing_refs.length > 0) {
+            throw new Error([
+                `Ternary convex hull requires formation energies (e_form_per_atom) for z-axis positioning, but none of the ${within_system.length} entries in the ${elements.join(`-`)} system have this field.`,
+                `\nCannot compute formation energies because elemental references are missing for: ${missing_refs.join(`, `)}.`,
+                `To fix: Ensure your dataset includes stable unary (single-element) entries for each element.`,
+            ].join(`\n`));
+        }
+        // proceed; values will be computed during mapping below
+    }
+    // Map entries to ternary plot coordinates
+    const result = within_system.map((entry) => {
+        const barycentric = composition_to_barycentric_3d(entry.composition, elements);
+        const e_form_per_atom = typeof entry.e_form_per_atom === `number` && Number.isFinite(entry.e_form_per_atom)
+            ? entry.e_form_per_atom
+            : (compute_e_form_per_atom(entry, refs) ?? NaN);
+        const xyz = barycentric_to_ternary_xyz(barycentric, e_form_per_atom);
+        const is_element = is_unary_entry(entry);
+        return { ...entry, ...xyz, is_element };
+    });
+    return result;
+}
+export function get_triangle_edges() {
+    const [v0, v1, v2] = TRIANGLE_VERTICES.map(([x, y]) => ({ x, y, z: 0 }));
+    return [
+        [v0, v1],
+        [v1, v2],
+        [v2, v0],
+    ];
+}
+export function get_triangle_vertical_edges(min_z, max_z) {
+    const vertices = TRIANGLE_VERTICES.map(([x, y]) => ({ x, y, z: 0 }));
+    return vertices.map((vertex) => [
+        { ...vertex, z: min_z },
+        { ...vertex, z: max_z },
+    ]);
+}
+// --- N-dimensional barycentric coordinates (for 5+ element systems) ---
+// Convert composition to N-dimensional barycentric coordinates
+// Returns array of length N where coords sum to 1 (all N coords are explicit)
+// The last coordinate represents formation energy when used in hull calculations
+export function composition_to_barycentric_nd(composition, elements) {
+    const n = elements.length;
+    if (n < 2) {
+        throw new Error(`Barycentric coordinates require at least 2 elements, got ${n}`);
+    }
+    // NaN and undefined/missing elements are treated as 0
+    const amounts = elements.map((el) => {
+        const val = composition[el];
+        return val == null || Number.isNaN(val) ? 0 : val;
+    });
+    let total = 0;
+    const negative = [];
+    for (let idx = 0; idx < amounts.length; idx++) {
+        if (amounts[idx] < 0)
+            negative.push(elements[idx]);
+        else
+            total += amounts[idx];
+    }
+    if (negative.length > 0) {
+        throw new Error(`Composition contains negative amounts for: ${negative.join(`, `)}`);
+    }
+    if (total === 0) {
+        throw new Error(`Composition has no elements from the system: ${elements.join(`-`)}`);
+    }
+    return amounts.map((amount) => amount / total);
+}
+// --- Quaternary coordinates ---
+export const TETRAHEDRON_VERTICES = [
+    [1, 0, 0],
+    [0.5, Math.sqrt(3) / 2, 0],
+    [0.5, Math.sqrt(3) / 6, Math.sqrt(6) / 3],
+    [0, 0, 0],
+];
+export function composition_to_barycentric_4d(composition, elements) {
+    if (elements.length !== 4) {
+        throw new Error(`Quaternary barycentric coordinates require exactly 4 elements`);
+    }
+    const amounts = elements.map((el) => composition[el] || 0);
+    const total = amounts.reduce((sum, amount) => sum + amount, 0);
+    if (total === 0) {
+        throw new Error(`Composition has no elements from the quaternary system: ${elements.join(`-`)}`);
+    }
+    return amounts.map((amount) => amount / total);
+}
+// map barycentric coordinates to tetrahedral 3D coordinates
+export function barycentric_to_tetrahedral(barycentric) {
+    if (barycentric.length !== 4) {
+        throw new Error(`Tetrahedral coordinates require exactly 4D barycentric input, got ${barycentric.length}`);
+    }
+    let [x, y, z] = [0, 0, 0];
+    for (let idx = 0; idx < 4; idx++) {
+        x += barycentric[idx] * TETRAHEDRON_VERTICES[idx][0];
+        y += barycentric[idx] * TETRAHEDRON_VERTICES[idx][1];
+        z += barycentric[idx] * TETRAHEDRON_VERTICES[idx][2];
+    }
+    return { x, y, z };
+}
+export function compute_4d_coords(entries, elements) {
+    if (elements.length !== 4) {
+        throw new Error(`Quaternary convex hull requires exactly 4 elements`);
+    }
+    // Use Set for O(1) lookups instead of O(n) includes
+    const element_set = new Set(elements);
+    const within_system = entries.filter((entry) => Object.keys(entry.composition).every((el) => element_set.has(el)));
+    return within_system.map((entry) => {
+        const barycentric_4d = composition_to_barycentric_4d(entry.composition, elements);
+        const tetrahedral = barycentric_to_tetrahedral(barycentric_4d);
+        const is_element = is_unary_entry(entry);
+        return { ...entry, ...tetrahedral, is_element };
+    });
+}

package/dist/convex-hull/demo-temperature.d.ts

@@ -0,0 +1,6 @@
+import type { PhaseData } from './types';
+export declare const demo_temperatures: number[];
+type Composition = Record<string, number>;
+export declare function make_demo_phase(composition: Composition, seed: number, entropy_boost?: number): PhaseData;
+export declare function create_temp_ternary_entries_li_fe_o(): PhaseData[];
+export {};

package/dist/convex-hull/demo-temperature.js

@@ -0,0 +1,40 @@
+export const demo_temperatures = Array.from({ length: 13 }, (_, idx) => 300 + idx * 100);
+function seeded_random(seed) {
+    const x_val = Math.sin(seed * 9999) * 10000;
+    return x_val - Math.floor(x_val);
+}
+export function make_demo_phase(composition, seed, entropy_boost = 0) {
+    const n_elements = Object.keys(composition).length;
+    const energy = -0.3 * n_elements - seeded_random(seed) * 0.5;
+    const entropy_coef = 0.5 + n_elements * 0.3 + seeded_random(seed + 1) * 2 + entropy_boost;
+    return {
+        composition,
+        energy,
+        temperatures: demo_temperatures,
+        free_energies: demo_temperatures.map((temp_kelvin) => energy +
+            entropy_coef * temp_kelvin * 0.0001 -
+            0.00005 * temp_kelvin * Math.log(temp_kelvin)),
+    };
+}
+export function create_temp_ternary_entries_li_fe_o() {
+    return [
+        ...[`Li`, `Fe`, `O`].map((element, idx) => make_demo_phase({ [element]: 1 }, idx)),
+        ...[
+            [`Li`, `Fe`],
+            [`Li`, `O`],
+            [`Fe`, `O`],
+        ].flatMap(([element_a, element_b], idx) => [0.33, 0.5, 0.67].flatMap((fraction, jdx) => [
+            make_demo_phase({ [element_a]: fraction, [element_b]: 1 - fraction }, 100 + idx * 10 + jdx),
+            make_demo_phase({ [element_a]: fraction, [element_b]: 1 - fraction }, 200 + idx * 10 + jdx, 3),
+        ])),
+        ...[
+            { Li: 0.33, Fe: 0.33, O: 0.34 },
+            { Li: 0.5, Fe: 0.25, O: 0.25 },
+            { Li: 0.25, Fe: 0.5, O: 0.25 },
+            { Li: 0.25, Fe: 0.25, O: 0.5 },
+        ].flatMap((composition, idx) => [
+            make_demo_phase(composition, 300 + idx),
+            make_demo_phase(composition, 400 + idx, 4),
+        ]),
+    ];
+}

package/dist/convex-hull/gas-thermodynamics.d.ts

@@ -0,0 +1,16 @@
+import type { GasAnalysis, GasSpecies, GasThermodynamicsConfig, GasThermodynamicsProvider, PhaseData } from './types';
+import type { ElementSymbol } from '../element';
+export declare const R_EV_PER_K = 0.00008617333262;
+export declare const P_REF = 1;
+export declare const DEFAULT_ELEMENT_TO_GAS: Readonly<Partial<Record<ElementSymbol, GasSpecies>>>;
+export declare const GAS_STOICHIOMETRY: Readonly<Record<GasSpecies, Partial<Record<ElementSymbol, number>>>>;
+export declare function create_default_gas_provider(): GasThermodynamicsProvider;
+export declare function get_default_gas_provider(): GasThermodynamicsProvider;
+export declare function compute_gas_chemical_potential(provider: GasThermodynamicsProvider, gas: GasSpecies, T: number, P: number): number;
+export declare function compute_element_chemical_potential(provider: GasThermodynamicsProvider, gas: GasSpecies, element: ElementSymbol, T: number, P: number): number;
+export declare function analyze_gas_data(entries: PhaseData[], config: GasThermodynamicsConfig): GasAnalysis;
+export declare function get_effective_pressures(config: GasThermodynamicsConfig): Record<GasSpecies, number>;
+export declare function compute_gas_correction(entry: PhaseData, config: GasThermodynamicsConfig, T: number, pressures: Record<GasSpecies, number>): number;
+export declare function apply_gas_corrections(entries: PhaseData[], config: GasThermodynamicsConfig | undefined, T: number): PhaseData[];
+export declare function format_chemical_potential(mu: number, decimals?: number): string;
+export declare function format_pressure(P: number): string;

package/dist/convex-hull/gas-thermodynamics.js

@@ -0,0 +1,314 @@
+// Gas phase thermodynamics for convex hull calculations
+// Enables atmosphere-controlled phase diagram analysis
+import { count_atoms_in_composition } from '../composition';
+import { DEFAULT_GAS_PRESSURES, GAS_SPECIES } from './types';
+// 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 = {
+    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 = {
+    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 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 = {
+    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 = {
+    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, T) {
+    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() {
+    return {
+        get_standard_chemical_potential(gas, T) {
+            // μ°(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() {
+            return [...GAS_SPECIES];
+        },
+        get_temperature_range() {
+            return [0, 2000];
+        },
+    };
+}
+// Singleton default provider
+let default_provider = null;
+// Get the default gas thermodynamics provider (lazy initialization)
+export function get_default_gas_provider() {
+    default_provider ??= create_default_gas_provider();
+    return default_provider;
+}
+// Gas Chemical Potential Calculations
+// Number of atoms in each gas molecule
+const GAS_NUM_ATOMS = {
+    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, gas, T, P) {
+    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, gas, element, T, P) {
+    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, config) {
+    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();
+    for (const entry of entries) {
+        for (const el of Object.keys(entry.composition)) {
+            if ((entry.composition[el] ?? 0) > 0) {
+                all_elements.add(el);
+            }
+        }
+    }
+    // Find elements that come from enabled gases
+    const gas_elements = [];
+    const relevant_gases = [];
+    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) {
+    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] = 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, config, T, pressures) {
+    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;
+        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, config, T) {
+    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, decimals = 3) {
+    return `${mu >= 0 ? `+` : ``}${mu.toFixed(decimals)} eV`;
+}
+// Format pressure for display (scientific notation for very small/large values)
+export function format_pressure(P) {
+    if (P >= 0.01 && P < 100) {
+        return `${P.toPrecision(3)} bar`;
+    }
+    return `${P.toExponential(2)} bar`;
+}

package/dist/convex-hull/helpers.d.ts

@@ -0,0 +1,114 @@
+import { type D3InterpolateName } from '../colors';
+import type { EnergyModeInfo } from './';
+import type { ElementSymbol } from '../element';
+import type { ConvexHullConfig, GasAnalysis, GasThermodynamicsConfig, HighlightStyle, MarkerSymbol, PhaseData } from './types';
+import { DEFAULT_GAS_TEMP } from './types';
+export { DEFAULT_GAS_TEMP };
+export declare const HULL_STABILITY_TOL = 0.000001;
+export declare function compute_hull_stability(raw_distance: number, exclude_from_hull?: boolean, tol?: number): {
+    e_above_hull: number;
+    is_stable: boolean;
+};
+type StabilityEntry = {
+    is_stable?: boolean;
+    e_above_hull?: number;
+};
+export declare const entry_is_stable: (entry: StabilityEntry, tol?: number) => boolean;
+export declare const is_on_hull: (entry: PhaseData, tol?: number) => boolean;
+export declare const get_arity: (entry: PhaseData) => number;
+export declare const is_unary_entry: (entry: PhaseData) => boolean;
+export declare const entry_is_unstable: (entry: StabilityEntry) => boolean;
+export declare const entry_is_visible: (entry: StabilityEntry, show_stable: boolean, show_unstable: boolean) => boolean;
+export declare const visible_entries: <Entry extends StabilityEntry>(entries: readonly Entry[], show_stable: boolean, show_unstable: boolean) => Entry[];
+export declare function get_energy_color_scale(color_mode: `stability` | `energy`, color_scale: D3InterpolateName, plot_entries: {
+    e_above_hull?: number;
+}[]): ((value: number) => string) | null;
+export declare function get_point_color_for_entry(entry: {
+    is_stable?: boolean;
+    e_above_hull?: number;
+}, color_mode: `stability` | `energy`, colors: ConvexHullConfig[`colors`] | undefined, energy_scale: ((value: number) => string) | null): string;
+export declare function parse_hull_entries_from_drop(event: DragEvent): Promise<PhaseData[] | null>;
+export declare function calc_max_hull_dist_in_data(processed_entries: PhaseData[]): number;
+export declare function compute_auto_hull_dist_threshold(n_entries: number, max_hull_dist_in_data: number, static_default: number): number;
+export declare function auto_threshold_reset(default_threshold: number): (next_source: unknown, current_threshold: number, next_auto_threshold: number) => number | undefined;
+export declare function current_entry<Entry extends {
+    entry_id?: string;
+}>(entry: Entry | null | undefined, entries: readonly Entry[]): Entry | null;
+export declare function build_entry_tooltip_text(entry: PhaseData): string;
+export declare function find_hull_entry_at_mouse<T extends {
+    x: number;
+    y: number;
+    z: number;
+    size?: number;
+    is_stable?: boolean;
+    e_above_hull?: number;
+}>(canvas: HTMLCanvasElement | undefined, event: MouseEvent, plot_entries: T[], project_point: (x: number, y: number, z: number) => {
+    x: number;
+    y: number;
+}): T | null;
+export declare function calculate_modal_side(wrapper: HTMLDivElement | undefined): boolean;
+export declare function compute_energy_mode_info(entries: PhaseData[], // Array of phase entries to analyze
+find_lowest_energy_unary_refs_fn: (entries: PhaseData[]) => Record<string, PhaseData>, // Function to find unary references
+energy_source_mode: `precomputed` | `on-the-fly`): EnergyModeInfo;
+export declare function get_effective_entries(entries: PhaseData[], // Original phase entries
+energy_mode: `precomputed` | `on-the-fly`, // Energy source mode (precomputed or on-the-fly)
+unary_refs: Record<string, PhaseData>, // Unary reference entries for energy computation
+compute_e_form_fn: (entry: PhaseData, unary_refs: Record<string, PhaseData>) => number | null): PhaseData[];
+export declare function copy_entry_to_clipboard(entry: PhaseData, position: {
+    x: number;
+    y: number;
+}, on_feedback: (visible: boolean, pos: {
+    x: number;
+    y: number;
+}) => void): Promise<void>;
+export declare const DEFAULT_HIGHLIGHT_STYLE: Required<HighlightStyle>;
+export declare const merge_highlight_style: (custom_style: HighlightStyle | undefined) => Required<HighlightStyle>;
+export declare function is_entry_highlighted<T extends {
+    entry_id?: string;
+    structure_id?: string;
+}>(entry: T, highlighted_list: (string | T)[]): boolean;
+export declare function get_fractional_composition(composition: Record<string, number>): Record<string, number>;
+export interface PolymorphStats {
+    total: number;
+    higher: number;
+    lower: number;
+    equal: number;
+}
+export declare function get_composition_label_entries<T extends PhaseData>(entries: Iterable<T>): T[];
+export declare function compute_all_polymorph_stats(all_entries: PhaseData[]): Map<string, PolymorphStats>;
+export declare function draw_highlight_effect(ctx: CanvasRenderingContext2D, projected: {
+    x: number;
+    y: number;
+}, size: number, container_scale: number, pulse_time: number, style: Required<HighlightStyle>): void;
+export declare function draw_selection_highlight(ctx: CanvasRenderingContext2D, projected: {
+    x: number;
+    y: number;
+}, base_size: number, container_scale: number, pulse_time: number, pulse_opacity: number): void;
+export declare function get_canvas_text_color(dark_mode: boolean, element?: HTMLElement | null): string;
+export declare function create_marker_path(size: number, marker?: MarkerSymbol): Path2D;
+export interface TemperatureAnalysis {
+    has_temp_data: boolean;
+    available_temperatures: number[];
+}
+export declare function analyze_temperature_data(entries: PhaseData[]): TemperatureAnalysis;
+export declare const entry_has_temperature: (entry: PhaseData, T: number) => boolean;
+export declare function get_energy_at_temperature(entry: PhaseData, T: number): number;
+export declare function can_interpolate_at_temperature(entry: PhaseData, T: number, max_gap: number): boolean;
+export declare function interpolate_energy_at_temperature(entry: PhaseData, T: number, max_gap: number): number | null;
+export interface TemperatureFilterOptions {
+    interpolate?: boolean;
+    max_interpolation_gap?: number;
+}
+export declare function filter_entries_at_temperature(entries: PhaseData[], T: number, options?: TemperatureFilterOptions): PhaseData[];
+export declare function safe_analyze_gas_data(entries: PhaseData[], config?: GasThermodynamicsConfig): GasAnalysis;
+export declare function safe_apply_gas_corrections(entries: PhaseData[], config: GasThermodynamicsConfig | undefined, T: number): PhaseData[];
+export declare function get_gas_corrected_entries(entries: PhaseData[], gas_config: GasThermodynamicsConfig | undefined, gas_pressures: Partial<Record<string, number>>, temperature: number): {
+    entries: PhaseData[];
+    analysis: GasAnalysis;
+    merged_config: GasThermodynamicsConfig | undefined;
+};
+export declare function get_entry_label(entry: {
+    reduced_formula?: string;
+    name?: string;
+    composition: Record<string, number>;
+}, elements?: ElementSymbol[]): string;