matterviz 0.3.6 → 0.3.7

package/dist/convex-hull/helpers.js

@@ -0,0 +1,710 @@
+import { get_d3_interpolator } from '../colors';
+import { ELEM_SYMBOL_TO_NAME } from '../composition';
+import { format_fractional, format_num, symbol_map } from '../labels';
+import { scaleSequential } from 'd3-scale';
+import { symbol } from 'd3-shape';
+import { analyze_gas_data as _analyze_gas_data, apply_gas_corrections as _apply_gas_corrections, } from './gas-thermodynamics';
+import { DEFAULT_GAS_TEMP } from './types';
+export { DEFAULT_GAS_TEMP };
+// Tolerance for classifying a phase as on the convex hull (eV/atom)
+export const HULL_STABILITY_TOL = 1e-6;
+// Clamp raw hull distance and compute stability for a single entry.
+// Excluded entries keep their raw (possibly negative) distance and are never stable.
+export function compute_hull_stability(raw_distance, exclude_from_hull, tol = HULL_STABILITY_TOL) {
+    if (exclude_from_hull)
+        return { e_above_hull: raw_distance, is_stable: false };
+    const e_above_hull = Math.abs(raw_distance) < tol ? 0 : Math.max(0, raw_distance);
+    return { e_above_hull, is_stable: e_above_hull <= tol };
+}
+export const entry_is_stable = (entry, tol = HULL_STABILITY_TOL) => entry.is_stable === true ||
+    (entry.is_stable !== false && Math.abs(entry.e_above_hull ?? Infinity) <= tol);
+// Check if entry is on the convex hull (stable or e_above_hull ≈ 0)
+export const is_on_hull = (entry, tol = HULL_STABILITY_TOL) => !entry.exclude_from_hull && entry_is_stable(entry, tol);
+export const get_arity = (entry) => Object.values(entry.composition).filter((count) => count > 0).length;
+export const is_unary_entry = (entry) => get_arity(entry) === 1;
+export const entry_is_unstable = (entry) => !entry_is_stable(entry);
+export const entry_is_visible = (entry, show_stable, show_unstable) => (entry_is_stable(entry) ? show_stable : show_unstable);
+export const visible_entries = (entries, show_stable, show_unstable) => entries.filter((entry) => entry_is_visible(entry, show_stable, show_unstable));
+// Energy color scale factory (shared)
+export function get_energy_color_scale(color_mode, color_scale, plot_entries) {
+    if (color_mode !== `energy` || plot_entries.length === 0)
+        return null;
+    let lo = Number.POSITIVE_INFINITY;
+    let hi_raw = 0.1;
+    for (const entry of plot_entries) {
+        const val = entry.e_above_hull;
+        if (typeof val !== `number` || !Number.isFinite(val))
+            continue;
+        lo = Math.min(lo, val);
+        hi_raw = Math.max(hi_raw, val);
+    }
+    if (!Number.isFinite(lo))
+        return null;
+    const hi = Math.max(hi_raw, lo + 1e-6);
+    const interpolator = get_d3_interpolator(color_scale);
+    return scaleSequential(interpolator).domain([lo, hi]);
+}
+// Point color resolver (shared)
+export function get_point_color_for_entry(entry, color_mode, colors, energy_scale) {
+    const is_stable = entry_is_stable(entry);
+    if (color_mode === `stability`) {
+        return is_stable ? colors?.stable || `#0072B2` : colors?.unstable || `#E69F00`;
+    }
+    return energy_scale && typeof entry.e_above_hull === `number`
+        ? energy_scale(entry.e_above_hull)
+        : `#666`;
+}
+// Robust drag-and-drop JSON parsing for convex hull entries
+export async function parse_hull_entries_from_drop(event) {
+    event.preventDefault();
+    const file = event.dataTransfer?.files?.[0];
+    if (!file?.name.endsWith(`.json`))
+        return null;
+    try {
+        const data = JSON.parse(await file.text());
+        if (!Array.isArray(data) || data.length === 0)
+            return null;
+        if (!data[0].composition || typeof data[0].energy !== `number`)
+            return null;
+        return data;
+    }
+    catch (error) {
+        console.error(`Error parsing dropped file:`, error);
+        return null;
+    }
+}
+// Compute a consistent max energy threshold for controls (shared)
+export function calc_max_hull_dist_in_data(processed_entries) {
+    if (processed_entries.length === 0)
+        return 0.5;
+    let max_hull_dist = 0;
+    for (const entry of processed_entries) {
+        const val = entry.e_above_hull;
+        if (typeof val === `number` && Number.isFinite(val)) {
+            max_hull_dist = Math.max(max_hull_dist, val);
+        }
+    }
+    const max_val = max_hull_dist + 0.001;
+    return Math.max(0.1, max_val);
+}
+// Smart threshold for showing unstable entries based on entry count.
+// Few entries (≤25): show all. Many entries (≥100): use static default. Between: interpolate.
+export function compute_auto_hull_dist_threshold(n_entries, max_hull_dist_in_data, static_default) {
+    const [LOW, HIGH] = [25, 100];
+    if (n_entries <= LOW)
+        return max_hull_dist_in_data;
+    if (n_entries >= HIGH)
+        return static_default;
+    const t = (n_entries - LOW) / (HIGH - LOW);
+    return max_hull_dist_in_data * (1 - t) + static_default * t;
+}
+export function auto_threshold_reset(default_threshold) {
+    let source;
+    let auto_threshold = default_threshold;
+    let initialized = false;
+    return (next_source, current_threshold, next_auto_threshold) => {
+        if (initialized && next_source === source)
+            return undefined;
+        const user_changed = initialized && Math.abs(current_threshold - auto_threshold) > 0.001;
+        source = next_source;
+        auto_threshold = next_auto_threshold;
+        initialized = true;
+        return user_changed ? undefined : next_auto_threshold;
+    };
+}
+export function current_entry(entry, entries) {
+    if (!entry)
+        return null;
+    if (entry.entry_id) {
+        return entries.find((candidate) => candidate.entry_id === entry.entry_id) ?? null;
+    }
+    return entries.includes(entry) ? entry : null;
+}
+// Build a tooltip text for any phase entry (shared)
+export function build_entry_tooltip_text(entry) {
+    const is_element = is_unary_entry(entry);
+    const elem_symbol = is_element ? Object.keys(entry.composition)[0] : ``;
+    const elem_name = is_element ? (ELEM_SYMBOL_TO_NAME[elem_symbol] ?? ``) : ``;
+    let text = is_element
+        ? `${elem_symbol}${elem_name ? ` (${elem_name})` : ``}\n`
+        : `${entry.name || entry.reduced_formula || ``}\n`;
+    if (!is_element) {
+        const total = Object.values(entry.composition).reduce((sum, amt) => sum + amt, 0);
+        if (total > 0) {
+            const fractions = Object.entries(entry.composition)
+                .filter(([, amt]) => amt > 0)
+                .map(([el, amt]) => `${el}: ${format_fractional(amt / total)}`);
+            if (fractions.length > 1) {
+                text += `Composition: ${fractions.join(`, `)}\n`;
+            }
+        }
+    }
+    if (entry.e_above_hull !== undefined) {
+        const e_hull_str = format_num(entry.e_above_hull, `.3~`);
+        text += `E<sub>above hull</sub>: ${e_hull_str} eV/atom\n`;
+    }
+    // Fallback to energy_per_atom if e_form_per_atom is absent
+    const e_form_display = entry.e_form_per_atom ?? entry.energy_per_atom;
+    if (e_form_display !== undefined) {
+        const e_form_str = format_num(e_form_display, `.3~`);
+        text += `E<sub>form</sub>: ${e_form_str} eV/atom`;
+    }
+    if (entry.entry_id)
+        text += `\nID: ${entry.entry_id}`;
+    return text;
+}
+// Generic mouse hit-testing for projected 3D points (shared)
+export function find_hull_entry_at_mouse(canvas, event, plot_entries, project_point) {
+    if (!canvas)
+        return null;
+    const rect = canvas.getBoundingClientRect();
+    const mouse_x = event.clientX - rect.left;
+    const mouse_y = event.clientY - rect.top;
+    const container_scale = Math.min(canvas.clientWidth || 600, canvas.clientHeight || 600) / 600;
+    for (const entry of plot_entries) {
+        const projected = project_point(entry.x, entry.y, entry.z);
+        const distance = Math.hypot(mouse_x - projected.x, mouse_y - projected.y);
+        const base = entry.size ?? (entry_is_stable(entry) ? 6 : 4);
+        if (distance < base * container_scale + 5)
+            return entry;
+    }
+    return null;
+}
+// Calculate which side of the viewport has more space for modal placement
+export function calculate_modal_side(wrapper) {
+    if (!wrapper)
+        return true;
+    const rect = wrapper.getBoundingClientRect();
+    const viewport_width = globalThis.innerWidth;
+    const space_on_right = viewport_width - rect.right;
+    const space_on_left = rect.left;
+    return space_on_right >= space_on_left;
+}
+// Compute energy source mode information for convex hull entries. Returns energy mode information including capability flags and resolved mode.
+// This determines whether we can use precomputed energies or need to compute on-the-fly.
+export function compute_energy_mode_info(entries, // Array of phase entries to analyze
+find_lowest_energy_unary_refs_fn, // Function to find unary references
+energy_source_mode) {
+    const has_precomputed_e_form = entries.length > 0 && entries.every((entry) => typeof entry.e_form_per_atom === `number`);
+    const has_precomputed_hull = entries.length > 0 && entries.every((entry) => typeof entry.e_above_hull === `number`);
+    const unary_refs = find_lowest_energy_unary_refs_fn(entries);
+    const elements_in_entries = new Set();
+    for (const entry of entries) {
+        for (const el of Object.keys(entry.composition))
+            elements_in_entries.add(el);
+    }
+    let can_compute_e_form = true;
+    for (const el of elements_in_entries) {
+        if (!unary_refs[el]) {
+            can_compute_e_form = false;
+            break;
+        }
+    }
+    const can_compute_hull = can_compute_e_form;
+    // Resolve mode to avoid inconsistent states:
+    // - If full precomputed available, honor user toggle
+    // - Else if we can compute both, use on-the-fly automatically
+    // - Else fall back to precomputed (best-effort)
+    const energy_mode = has_precomputed_e_form && has_precomputed_hull
+        ? energy_source_mode
+        : can_compute_e_form && can_compute_hull
+            ? `on-the-fly`
+            : `precomputed`;
+    return {
+        has_precomputed_e_form,
+        has_precomputed_hull,
+        can_compute_e_form,
+        can_compute_hull,
+        energy_mode,
+        unary_refs,
+    };
+}
+// Compute effective entries with formation energies based on the energy mode.
+// Returns entries with formation energies populated (either precomputed or on-the-fly)
+export function get_effective_entries(entries, // Original phase entries
+energy_mode, // Energy source mode (precomputed or on-the-fly)
+unary_refs, // Unary reference entries for energy computation
+compute_e_form_fn) {
+    if (energy_mode === `precomputed`)
+        return entries;
+    return entries.map((entry) => {
+        const e_form = compute_e_form_fn(entry, unary_refs);
+        if (e_form === null)
+            return entry;
+        return { ...entry, e_form_per_atom: e_form };
+    });
+}
+// Copy text to clipboard with visual feedback
+export async function copy_entry_to_clipboard(entry, position, on_feedback) {
+    const text = build_entry_tooltip_text(entry);
+    await navigator.clipboard.writeText(text);
+    on_feedback(true, position);
+    setTimeout(() => on_feedback(false, position), 1500);
+}
+export const DEFAULT_HIGHLIGHT_STYLE = {
+    effect: `pulse`,
+    color: `#ff4444`, // Bright red for visibility
+    size_multiplier: 1.8, // Moderate base size
+    opacity: 0.85, // High visibility
+    pulse_speed: 3, // Smooth pulsing
+};
+export const merge_highlight_style = (custom_style) => ({
+    ...DEFAULT_HIGHLIGHT_STYLE,
+    ...custom_style,
+});
+// Check if entry matches any item in highlighted_list (by structure_id or entry_id)
+export function is_entry_highlighted(entry, highlighted_list) {
+    if (!highlighted_list.length)
+        return false;
+    const { entry_id, structure_id } = entry;
+    if (!entry_id && !structure_id)
+        return false;
+    return highlighted_list.some((item) => {
+        if (typeof item === `string`) {
+            return item === entry_id || item === structure_id;
+        }
+        // Object: match by structure_id if present, else fall back to entry_id
+        return item?.structure_id
+            ? structure_id === item.structure_id
+            : item?.entry_id === entry_id;
+    });
+}
+// Calculate fractional composition (normalized composition) for an entry
+export function get_fractional_composition(composition) {
+    const total = Object.values(composition).reduce((sum, amt) => sum + amt, 0);
+    if (total <= 0)
+        return {}; // Return empty object if total is zero or negative (invalid composition)
+    const fractional = {};
+    for (const [elem, amt] of Object.entries(composition)) {
+        // Only include positive amounts in fractional composition
+        if (amt > 0)
+            fractional[elem] = amt / total;
+    }
+    return fractional;
+}
+// Check if value is a finite number
+const is_finite = (val) => typeof val === `number` && Number.isFinite(val);
+// Compute energy_per_atom from total energy and composition
+function compute_energy_per_atom(entry) {
+    if (!is_finite(entry.energy))
+        return null;
+    const total_atoms = Object.values(entry.composition).reduce((sum, amt) => sum + amt, 0);
+    return total_atoms > 0 ? entry.energy / total_atoms : null;
+}
+// Get energy value for an entry using a specific metric
+// NOTE: We prioritize absolute energies (e_form_per_atom, energy_per_atom) over e_above_hull
+// because polymorphs of the same composition on the hull all have e_above_hull=0
+function get_entry_energy_by_metric(entry, metric) {
+    if (metric === `e_form_per_atom` && is_finite(entry.e_form_per_atom)) {
+        return entry.e_form_per_atom;
+    }
+    if (metric === `energy_per_atom`) {
+        return is_finite(entry.energy_per_atom)
+            ? entry.energy_per_atom
+            : compute_energy_per_atom(entry);
+    }
+    if (metric === `e_above_hull` && is_finite(entry.e_above_hull)) {
+        return entry.e_above_hull;
+    }
+    return null;
+}
+function get_label_representative_energy(entry) {
+    if (is_finite(entry.e_form_per_atom))
+        return entry.e_form_per_atom;
+    if (is_finite(entry.energy_per_atom))
+        return entry.energy_per_atom;
+    const energy_per_atom = compute_energy_per_atom(entry);
+    if (energy_per_atom !== null)
+        return energy_per_atom;
+    if (is_finite(entry.energy))
+        return entry.energy;
+    if (is_finite(entry.e_above_hull))
+        return entry.e_above_hull;
+    return Number.POSITIVE_INFINITY;
+}
+function get_fractional_composition_key(composition) {
+    return Object.entries(get_fractional_composition(composition))
+        .sort(([elem_a], [elem_b]) => elem_a.localeCompare(elem_b))
+        .map(([elem, frac]) => `${elem}:${frac.toFixed(6)}`)
+        .join(`|`);
+}
+// Pick one label target per normalized composition. Multiple polymorphs, supercell
+// formulas, or same-composition entries often project to the same screen position.
+export function get_composition_label_entries(entries) {
+    const label_entry_by_composition = new Map();
+    for (const entry of entries) {
+        const comp_key = get_fractional_composition_key(entry.composition);
+        if (!comp_key)
+            continue;
+        const existing = label_entry_by_composition.get(comp_key);
+        if (!existing ||
+            get_label_representative_energy(entry) < get_label_representative_energy(existing)) {
+            label_entry_by_composition.set(comp_key, entry);
+        }
+    }
+    return Array.from(label_entry_by_composition.values());
+}
+// Determine which energy metric to use for a composition group
+// Returns the first metric that ALL entries in the group can provide
+function select_group_energy_metric(polymorphs) {
+    // Try e_form_per_atom first (best for comparing polymorphs)
+    if (polymorphs.every((entry) => is_finite(entry.e_form_per_atom))) {
+        return `e_form_per_atom`;
+    }
+    // Try energy_per_atom (either direct field or computed from total energy)
+    if (polymorphs.every((entry) => is_finite(entry.energy_per_atom) || compute_energy_per_atom(entry) !== null))
+        return `energy_per_atom`;
+    // Last resort: e_above_hull (will fail to differentiate stable polymorphs with e_above_hull=0)
+    if (polymorphs.every((entry) => is_finite(entry.e_above_hull))) {
+        return `e_above_hull`;
+    }
+    return null; // No valid metric available for this group
+}
+// Pre-compute polymorph statistics for all entries at once (O(n²) but done once)
+// Returns a Map keyed by entry_id for O(1) lookups during hover
+export function compute_all_polymorph_stats(all_entries) {
+    const stats_map = new Map();
+    const zero_stats = { total: 0, higher: 0, lower: 0, equal: 0 };
+    // Group entries by fractional composition (normalized stoichiometry)
+    const composition_groups = new Map();
+    for (const entry of all_entries) {
+        const comp_key = get_fractional_composition_key(entry.composition);
+        const group = composition_groups.get(comp_key) ?? [];
+        if (group.length === 0)
+            composition_groups.set(comp_key, group);
+        group.push(entry);
+    }
+    // Calculate stats for each polymorph group
+    for (const polymorphs of composition_groups.values()) {
+        // Select one consistent metric for the entire composition group
+        const group_metric = select_group_energy_metric(polymorphs);
+        // If no valid metric available, set all entries in group to zero stats
+        if (group_metric === null) {
+            for (const entry of polymorphs) {
+                if (entry.entry_id)
+                    stats_map.set(entry.entry_id, zero_stats);
+            }
+            continue;
+        }
+        // Compare entries using the consistent group metric
+        for (const entry of polymorphs) {
+            if (!entry.entry_id)
+                continue;
+            const entry_energy = get_entry_energy_by_metric(entry, group_metric);
+            if (entry_energy === null) {
+                stats_map.set(entry.entry_id, zero_stats);
+                continue;
+            }
+            let [total, higher, lower, equal] = [0, 0, 0, 0];
+            for (const other of polymorphs) {
+                if (other === entry || other.entry_id === entry.entry_id)
+                    continue;
+                const other_energy = get_entry_energy_by_metric(other, group_metric);
+                if (other_energy === null)
+                    continue;
+                total++;
+                if (other_energy > entry_energy)
+                    higher++;
+                else if (other_energy < entry_energy)
+                    lower++;
+                else
+                    equal++;
+            }
+            stats_map.set(entry.entry_id, { total, higher, lower, equal });
+        }
+    }
+    return stats_map;
+}
+function apply_alpha_to_color(color, alpha) {
+    // Handle existing rgba format
+    if (color.includes(`rgba`))
+        return color.replace(/[\d.]+\)$/, `${alpha})`);
+    if (color.includes(`rgb(`)) {
+        // Convert rgb to rgba
+        return color.replace(/rgb\(/, `rgba(`).replace(/\)$/, `, ${alpha})`);
+    }
+    const hex_match = /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(color); // Convert hex to rgba
+    if (hex_match) {
+        let hex = hex_match[1];
+        // Expand short form (e.g. "03F") to full form (e.g. "0033FF")
+        if (hex.length === 3)
+            hex = hex
+                .split(``)
+                .map((char) => char + char)
+                .join(``);
+        const red = parseInt(hex.slice(0, 2), 16);
+        const green = parseInt(hex.slice(2, 4), 16);
+        const blue = parseInt(hex.slice(4, 6), 16);
+        return `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+    }
+    return color; // Return unchanged if format not recognized
+}
+export function draw_highlight_effect(ctx, projected, size, container_scale, pulse_time, style) {
+    const { effect, color: hl_color, size_multiplier, opacity, pulse_speed } = style;
+    if (effect === `pulse`) {
+        // Smooth pulsating effect with moderate size and opacity changes
+        const pulse_val = 0.5 + 0.5 * Math.sin(pulse_time * pulse_speed);
+        const hl_size = size * (size_multiplier + 0.5 * pulse_val);
+        const hl_opacity = opacity * (0.5 + 0.5 * pulse_val);
+        // Draw pulsating ring
+        ctx.lineWidth = (1.5 + pulse_val) * container_scale;
+        ctx.beginPath();
+        ctx.arc(projected.x, projected.y, hl_size, 0, 2 * Math.PI);
+        ctx.fillStyle = apply_alpha_to_color(hl_color, hl_opacity * 0.3);
+        ctx.strokeStyle = apply_alpha_to_color(hl_color, hl_opacity);
+        ctx.fill();
+        ctx.stroke();
+    }
+    else if (effect === `glow`) {
+        // Soft glow effect with layered circles for depth
+        const hl_size = size * size_multiplier;
+        // Outer soft glow
+        ctx.beginPath();
+        ctx.arc(projected.x, projected.y, hl_size * 1.3, 0, 2 * Math.PI);
+        ctx.fillStyle = apply_alpha_to_color(hl_color, opacity * 0.15);
+        ctx.fill();
+        // Inner glow with stroke
+        ctx.lineWidth = 1.5 * container_scale;
+        ctx.beginPath();
+        ctx.arc(projected.x, projected.y, hl_size, 0, 2 * Math.PI);
+        ctx.fillStyle = apply_alpha_to_color(hl_color, opacity * 0.4);
+        ctx.strokeStyle = apply_alpha_to_color(hl_color, opacity * 0.8);
+        ctx.fill();
+        ctx.stroke();
+    }
+    else if (effect === `size`) {
+        // Simple size highlight with stroke
+        const hl_size = size * size_multiplier;
+        ctx.lineWidth = 2 * container_scale;
+        ctx.beginPath();
+        ctx.arc(projected.x, projected.y, hl_size, 0, 2 * Math.PI);
+        ctx.strokeStyle = hl_color;
+        ctx.stroke();
+    }
+    // effect === `color` is handled in the main drawing code
+}
+// Draw selection highlight for currently selected entry (with pulsing animation)
+export function draw_selection_highlight(ctx, projected, base_size, container_scale, pulse_time, pulse_opacity) {
+    const highlight_size = base_size * (1.8 + 0.3 * Math.sin(pulse_time * 4));
+    ctx.fillStyle = apply_alpha_to_color(`rgba(102, 240, 255, 1)`, pulse_opacity * 0.6);
+    ctx.strokeStyle = apply_alpha_to_color(`rgba(102, 240, 255, 1)`, pulse_opacity);
+    ctx.lineWidth = 2 * container_scale;
+    ctx.beginPath();
+    ctx.arc(projected.x, projected.y, highlight_size, 0, 2 * Math.PI);
+    ctx.fill();
+    ctx.stroke();
+}
+// Get text color for canvas rendering. Canvas 2D context doesn't understand CSS functions
+// like light-dark() or var(), so we fall back to appropriate colors based on dark mode.
+export function get_canvas_text_color(dark_mode, element) {
+    const fallback = dark_mode ? `#ffffff` : `#212121`;
+    if (typeof document === `undefined`)
+        return fallback;
+    const css_value = getComputedStyle(element ?? document.documentElement)
+        .getPropertyValue(`--text-color`)
+        ?.trim();
+    // Check for unsupported CSS functions that canvas can't render
+    return css_value && !/light-dark|var\(/i.test(css_value) ? css_value : fallback;
+}
+// Create a Path2D for a marker symbol. Uses d3-shape for consistent rendering with ScatterPlot.
+export function create_marker_path(size, marker = `circle`) {
+    const safe_size = Number.isFinite(size) ? size : 0;
+    const rounded_size = Math.max(0, Number(safe_size.toFixed(3)));
+    // Capitalize first letter to get D3 symbol name (e.g. 'circle' -> 'Circle')
+    const d3_name = marker.charAt(0).toUpperCase() + marker.slice(1);
+    const symbol_type = symbol_map[d3_name];
+    const symbol_area = Math.PI * rounded_size * rounded_size;
+    const path_data = symbol_type ? symbol().type(symbol_type).size(symbol_area)() : null;
+    const path = new Path2D(path_data ?? undefined);
+    if (!path_data) {
+        path.arc(0, 0, rounded_size, 0, 2 * Math.PI);
+    }
+    return path;
+}
+// Analyze entries for temperature-dependent free energy data.
+// Returns available temperatures (union of all T values across entries) if any entries have temp data.
+export function analyze_temperature_data(entries) {
+    const unique_temperatures = new Set();
+    for (const entry of entries) {
+        if (!entry_has_temp_data(entry))
+            continue;
+        for (const temperature of entry.temperatures ?? [])
+            unique_temperatures.add(temperature);
+    }
+    const available_temperatures = [...unique_temperatures].sort((a, b) => a - b);
+    return {
+        has_temp_data: available_temperatures.length > 0,
+        available_temperatures,
+    };
+}
+// Check if an entry has valid temperature-dependent data (matching array lengths, non-empty)
+function entry_has_temp_data(entry) {
+    const { temperatures, free_energies } = entry;
+    return Boolean(temperatures?.length &&
+        free_energies?.length &&
+        temperatures.length === free_energies.length);
+}
+// Check if entry has data at exact temperature T
+export const entry_has_temperature = (entry, T) => entry_has_temp_data(entry) && (entry.temperatures?.includes(T) ?? false);
+// Get energy at temperature T (throws if T not found - validate with entry_has_temperature first)
+export function get_energy_at_temperature(entry, T) {
+    const temps = entry.temperatures ?? [];
+    const energies = entry.free_energies ?? [];
+    const idx = temps.indexOf(T);
+    if (idx === -1) {
+        throw new Error(`Temperature ${T}K not found in entry temperatures`);
+    }
+    return energies[idx];
+}
+// Find bracketing temperatures for interpolation (T_low < T < T_high)
+// Returns null if T is outside the range or no valid bracket exists
+function find_bracket_temperatures(entry, T) {
+    const temps = entry.temperatures ?? [];
+    const energies = entry.free_energies ?? [];
+    if (temps.length < 2)
+        return null;
+    // Find the largest T_low < T and smallest T_high > T
+    let T_low = -Infinity;
+    let T_high = Infinity;
+    let E_low = 0;
+    let E_high = 0;
+    // Must scan all temperatures to find the tightest bracket (arrays may be unsorted)
+    for (const [idx, temp] of temps.entries()) {
+        if (temp < T && temp > T_low) {
+            T_low = temp;
+            E_low = energies[idx];
+        }
+        else if (temp > T && temp < T_high) {
+            T_high = temp;
+            E_high = energies[idx];
+        }
+    }
+    // Must have valid brackets on both sides
+    if (!isFinite(T_low) || !isFinite(T_high))
+        return null;
+    return { T_low, T_high, E_low, E_high };
+}
+// Check if we can interpolate energy at temperature T
+// Requires temperatures both above and below T within max_gap
+export function can_interpolate_at_temperature(entry, T, max_gap) {
+    const bracket = find_bracket_temperatures(entry, T);
+    if (!bracket)
+        return false;
+    return bracket.T_high - bracket.T_low <= max_gap;
+}
+// Linearly interpolate energy at temperature T
+// Returns null if interpolation is not possible
+export function interpolate_energy_at_temperature(entry, T, max_gap) {
+    const bracket = find_bracket_temperatures(entry, T);
+    if (!bracket)
+        return null;
+    if (bracket.T_high - bracket.T_low > max_gap)
+        return null;
+    // Linear interpolation: E(T) = E_low + (E_high - E_low) * (T - T_low) / (T_high - T_low)
+    const fraction = (T - bracket.T_low) / (bracket.T_high - bracket.T_low);
+    return bracket.E_low + (bracket.E_high - bracket.E_low) * fraction;
+}
+const DEFAULT_TEMP_FILTER_OPTIONS = {
+    interpolate: true,
+    max_interpolation_gap: 500,
+};
+// Filter entries for temperature T, replacing energy with G(T) where available.
+// - Entries WITH temp data at T: use G(T) as energy
+// - Entries WITHOUT any temp data: keep with static energy (e.g., pure element refs)
+// - Entries WITH temp data but MISSING T: interpolate if enabled and possible, else excluded
+export function filter_entries_at_temperature(entries, T, options = {}) {
+    const { interpolate, max_interpolation_gap } = {
+        ...DEFAULT_TEMP_FILTER_OPTIONS,
+        ...options,
+    };
+    return entries.flatMap((entry) => {
+        // No temp data - keep with static energy
+        if (!entry_has_temp_data(entry))
+            return [entry];
+        // Exact temperature match - use G(T)
+        // Set both energy and energy_per_atom so downstream formation energy
+        // calculations use the temperature-dependent value (not stale 0K energy_per_atom)
+        if (entry_has_temperature(entry, T)) {
+            // free_energies stores per-atom values (E_0K/atom + F_vib/atom),
+            // so energy is already per-atom — set both fields to the same value
+            const energy = get_energy_at_temperature(entry, T);
+            return [{ ...entry, energy, energy_per_atom: energy }];
+        }
+        // Try interpolation if enabled
+        if (interpolate) {
+            const energy = interpolate_energy_at_temperature(entry, T, max_interpolation_gap);
+            if (energy !== null) {
+                // interpolated energy is also per-atom (interpolated from per-atom free_energies)
+                return [{ ...entry, energy, energy_per_atom: energy }];
+            }
+        }
+        // Exclude entry (has temp data but can't get energy at T)
+        return [];
+    });
+}
+// Gas-dependent chemical potential helpers
+// Analyze entries for gas-dependent elements (safe wrapper with optional config)
+// Returns information about which gases are relevant for the chemical system.
+export function safe_analyze_gas_data(entries, config) {
+    if (!config?.enabled_gases?.length) {
+        return {
+            has_gas_dependent_elements: false,
+            gas_elements: [],
+            relevant_gases: [],
+        };
+    }
+    return _analyze_gas_data(entries, config);
+}
+// Apply gas chemical potential corrections to entries (safe wrapper with optional config)
+// This adjusts formation energies based on gas atmosphere conditions (T, P).
+// Should be applied after temperature filtering.
+export function safe_apply_gas_corrections(entries, config, T) {
+    if (!config?.enabled_gases?.length)
+        return entries;
+    return _apply_gas_corrections(entries, config, T);
+}
+// Get gas-corrected entries in one call (consolidates analysis + correction)
+// Merges gas_pressures with config.pressures and applies corrections if the
+// chemical system contains gas-dependent elements. Returns original entries
+// if no gas config or no relevant gases.
+export function get_gas_corrected_entries(entries, gas_config, gas_pressures, temperature) {
+    if (!gas_config?.enabled_gases?.length) {
+        return {
+            entries,
+            analysis: {
+                has_gas_dependent_elements: false,
+                gas_elements: [],
+                relevant_gases: [],
+            },
+            merged_config: undefined,
+        };
+    }
+    const merged_config = {
+        ...gas_config,
+        pressures: { ...gas_config.pressures, ...gas_pressures },
+    };
+    const analysis = _analyze_gas_data(entries, merged_config);
+    if (!analysis.has_gas_dependent_elements) {
+        return { entries, analysis, merged_config };
+    }
+    return {
+        entries: _apply_gas_corrections(entries, merged_config, temperature),
+        analysis,
+        merged_config,
+    };
+}
+// Derive a display label for a convex hull entry, falling back to composition
+// when reduced_formula and name are both missing.
+export function get_entry_label(entry, elements) {
+    if (entry.reduced_formula)
+        return entry.reduced_formula;
+    if (entry.name)
+        return entry.name;
+    let pairs = Object.entries(entry.composition).filter(([, amt]) => amt > 0);
+    if (elements) {
+        pairs = pairs.sort(([el1], [el2]) => elements.indexOf(el1) - elements.indexOf(el2));
+    }
+    return pairs
+        .map(([el, amt]) => (Math.abs(amt - 1) < 1e-6 ? el : `${el}${format_num(amt, `.2~`)}`))
+        .join(``);
+}