matterviz 0.3.6 → 0.4.0

package/dist/src/lib/convex-hull/helpers.ts

@@ -1,932 +0,0 @@
-import { type D3InterpolateName, get_d3_interpolator } from '$lib/colors'
-import { ELEM_SYMBOL_TO_NAME } from '$lib/composition'
-import type { EnergyModeInfo } from '$lib/convex-hull'
-import type { ElementSymbol } from '$lib/element'
-import { format_fractional, format_num, symbol_map } from '$lib/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 type {
-  ConvexHullConfig,
-  GasAnalysis,
-  GasThermodynamicsConfig,
-  HighlightStyle,
-  MarkerSymbol,
-  PhaseData,
-} from './types'
-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: number,
-  exclude_from_hull?: boolean,
-  tol: number = HULL_STABILITY_TOL,
-): { e_above_hull: number; is_stable: boolean } {
-  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 }
-}
-
-type StabilityEntry = { is_stable?: boolean; e_above_hull?: number }
-
-export const entry_is_stable = (
-  entry: StabilityEntry,
-  tol: number = HULL_STABILITY_TOL,
-): boolean =>
-  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: PhaseData, tol: number = HULL_STABILITY_TOL): boolean =>
-  !entry.exclude_from_hull && entry_is_stable(entry, tol)
-
-export const get_arity = (entry: PhaseData): number =>
-  Object.values(entry.composition).filter((count) => count > 0).length
-
-export const is_unary_entry = (entry: PhaseData) => get_arity(entry) === 1
-
-export const entry_is_unstable = (entry: StabilityEntry): boolean => !entry_is_stable(entry)
-
-export const entry_is_visible = (
-  entry: StabilityEntry,
-  show_stable: boolean,
-  show_unstable: boolean,
-): boolean => (entry_is_stable(entry) ? show_stable : show_unstable)
-
-export const visible_entries = <Entry extends StabilityEntry>(
-  entries: readonly Entry[],
-  show_stable: boolean,
-  show_unstable: boolean,
-): Entry[] => entries.filter((entry) => entry_is_visible(entry, show_stable, show_unstable))
-
-// Energy color scale factory (shared)
-export function get_energy_color_scale(
-  color_mode: `stability` | `energy`,
-  color_scale: D3InterpolateName,
-  plot_entries: { e_above_hull?: number }[],
-): ((value: number) => string) | null {
-  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: { is_stable?: boolean; e_above_hull?: number },
-  color_mode: `stability` | `energy`,
-  colors: ConvexHullConfig[`colors`] | undefined,
-  energy_scale: ((value: number) => string) | null,
-): string {
-  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: DragEvent,
-): Promise<PhaseData[] | null> {
-  event.preventDefault()
-  const file = event.dataTransfer?.files?.[0]
-  if (!file?.name.endsWith(`.json`)) return null
-  try {
-    const data = JSON.parse(await file.text()) as PhaseData[]
-    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: PhaseData[]): number {
-  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: number,
-  max_hull_dist_in_data: number,
-  static_default: number,
-): number {
-  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: number) {
-  let source: unknown
-  let auto_threshold = default_threshold
-  let initialized = false
-  return (next_source: unknown, current_threshold: number, next_auto_threshold: number) => {
-    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 extends { entry_id?: string }>(
-  entry: Entry | null | undefined,
-  entries: readonly Entry[],
-): Entry | null {
-  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: PhaseData): string {
-  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 as ElementSymbol] ?? ``) : ``
-
-  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<
-  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 {
-  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: HTMLDivElement | undefined): boolean {
-  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: 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`, // User-specified energy source mode preference
-): EnergyModeInfo {
-  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<string>()
-  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: 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, // Function to compute formation energy per atom
-): PhaseData[] {
-  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: PhaseData,
-  position: { x: number; y: number },
-  on_feedback: (visible: boolean, pos: { x: number; y: number }) => void,
-): Promise<void> {
-  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: Required<HighlightStyle> = {
-  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: HighlightStyle | undefined,
-): Required<HighlightStyle> => ({
-  ...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<T extends { entry_id?: string; structure_id?: string }>(
-  entry: T,
-  highlighted_list: (string | T)[],
-): boolean {
-  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: Record<string, number>,
-): Record<string, number> {
-  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: Record<string, number> = {}
-  for (const [elem, amt] of Object.entries(composition)) {
-    // Only include positive amounts in fractional composition
-    if (amt > 0) fractional[elem] = amt / total
-  }
-  return fractional
-}
-
-export interface PolymorphStats {
-  total: number
-  higher: number
-  lower: number
-  equal: number
-}
-
-// Energy metric types for consistent polymorph comparison
-type EnergyMetric = `e_form_per_atom` | `energy_per_atom` | `e_above_hull` | null
-
-// Check if value is a finite number
-const is_finite = (val: unknown): val is number =>
-  typeof val === `number` && Number.isFinite(val)
-
-// Compute energy_per_atom from total energy and composition
-function compute_energy_per_atom(entry: PhaseData): number | null {
-  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: PhaseData, metric: EnergyMetric): number | null {
-  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: PhaseData): number {
-  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: Record<string, number>): string {
-  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<T extends PhaseData>(entries: Iterable<T>): T[] {
-  const label_entry_by_composition = new Map<string, T>()
-
-  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: PhaseData[]): EnergyMetric {
-  // 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: PhaseData[],
-): Map<string, PolymorphStats> {
-  const stats_map = new Map<string, PolymorphStats>()
-  const zero_stats = { total: 0, higher: 0, lower: 0, equal: 0 }
-
-  // Group entries by fractional composition (normalized stoichiometry)
-  const composition_groups = new Map<string, PhaseData[]>()
-  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: string, alpha: number): string {
-  // 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: CanvasRenderingContext2D,
-  projected: { x: number; y: number },
-  size: number,
-  container_scale: number,
-  pulse_time: number,
-  style: Required<HighlightStyle>,
-): void {
-  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: CanvasRenderingContext2D,
-  projected: { x: number; y: number },
-  base_size: number,
-  container_scale: number,
-  pulse_time: number,
-  pulse_opacity: number,
-): void {
-  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: boolean,
-  element?: HTMLElement | null,
-): string {
-  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: number, marker: MarkerSymbol = `circle`): Path2D {
-  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 as keyof typeof symbol_map]
-  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
-}
-
-// Temperature-dependent free energy helpers (use integer K values for exact matching)
-
-// Result of analyzing entries for temperature-dependent data
-export interface TemperatureAnalysis {
-  has_temp_data: boolean
-  available_temperatures: number[] // sorted unique T values (union across all entries)
-}
-
-// 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: PhaseData[]): TemperatureAnalysis {
-  const unique_temperatures = new Set<number>()
-  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: PhaseData): boolean {
-  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: PhaseData, T: number): boolean =>
-  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: PhaseData, T: number): number {
-  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: PhaseData,
-  T: number,
-): { T_low: number; T_high: number; E_low: number; E_high: number } | null {
-  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: PhaseData,
-  T: number,
-  max_gap: number,
-): boolean {
-  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: PhaseData,
-  T: number,
-  max_gap: number,
-): number | null {
-  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
-}
-
-// Options for temperature filtering
-export interface TemperatureFilterOptions {
-  // Enable linear interpolation for missing temperatures (default: true)
-  interpolate?: boolean
-  // Maximum temperature gap (in Kelvin) allowed for interpolation (default: 500K)
-  max_interpolation_gap?: number
-}
-
-const DEFAULT_TEMP_FILTER_OPTIONS: Required<TemperatureFilterOptions> = {
-  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: PhaseData[],
-  T: number,
-  options: TemperatureFilterOptions = {},
-): PhaseData[] {
-  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: PhaseData[],
-  config?: GasThermodynamicsConfig,
-): GasAnalysis {
-  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: PhaseData[],
-  config: GasThermodynamicsConfig | undefined,
-  T: number,
-): PhaseData[] {
-  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: PhaseData[],
-  gas_config: GasThermodynamicsConfig | undefined,
-  gas_pressures: Partial<Record<string, number>>,
-  temperature: number,
-): {
-  entries: PhaseData[]
-  analysis: GasAnalysis
-  merged_config: GasThermodynamicsConfig | undefined
-} {
-  if (!gas_config?.enabled_gases?.length) {
-    return {
-      entries,
-      analysis: {
-        has_gas_dependent_elements: false,
-        gas_elements: [],
-        relevant_gases: [],
-      },
-      merged_config: undefined,
-    }
-  }
-
-  const merged_config: GasThermodynamicsConfig = {
-    ...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: { reduced_formula?: string; name?: string; composition: Record<string, number> },
-  elements?: ElementSymbol[],
-): string {
-  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 as ElementSymbol) - elements.indexOf(el2 as ElementSymbol),
-    )
-  }
-  return pairs
-    .map(([el, amt]) => (Math.abs(amt - 1) < 1e-6 ? el : `${el}${format_num(amt, `.2~`)}`))
-    .join(``)
-}