matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,932 @@
+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(``)
+}