matterviz 0.3.6 → 0.4.0

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

@@ -0,0 +1,306 @@
+// 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 const create_default_gas_provider = () => ({
+    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;
+        // compute_gas_correction is PER-ATOM: shift energy_per_atom by it and rescale total
+        // energy by atom count so downstream formation energies use the corrected values
+        const atoms = count_atoms_in_composition(entry.composition);
+        const energy_per_atom = (entry.energy_per_atom ?? entry.energy / atoms) + correction;
+        return { ...entry, energy: energy_per_atom * atoms, energy_per_atom };
+    });
+}
+// Format chemical potential for display (e.g., "-1.23 eV")
+export const format_chemical_potential = (mu, decimals = 3) => `${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,117 @@
+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 same_entry<Entry extends {
+    entry_id?: string;
+}>(a: Entry | null | undefined, b: Entry | null | undefined): boolean;
+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;