matterviz 0.3.5 → 0.3.6

package/dist/convex-hull/helpers.js

@@ -1,689 +0,0 @@
-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 };
-}
-// 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 === true ||
-        (typeof entry.e_above_hull === `number` && entry.e_above_hull < 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;
-// 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 = Boolean(entry.is_stable) || entry.e_above_hull === 0;
-    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;
-}
-// 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 !== undefined ? 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) {
-        if (!entry.visible)
-            continue;
-        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.e_above_hull === 0 ? 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); // Moderate pulse amplitude
-        const hl_opacity = opacity * (0.5 + 0.5 * pulse_val); // Smooth opacity variation
-        // Draw pulsating ring
-        ctx.lineWidth = (1.5 + 1 * 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 function entry_has_temperature(entry, T) {
-    return 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 || !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 || !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(``);
-}