matterviz 0.3.6 → 0.4.0

package/dist/src/lib/spectral/helpers.ts

@@ -1,1381 +0,0 @@
-// Helper utilities for band structure and DOS data processing
-import { SUBSCRIPT_MAP } from '$lib/labels'
-import { centered_frac, euclidean_dist } from '$lib/math'
-import type { Matrix3x3, Vec2, Vec3 } from '$lib/math'
-import type { AxisConfig } from '$lib/plot/types'
-import type * as types from './types'
-import type { RibbonConfig } from './types'
-
-const is_subscript_key = (key: string): key is keyof typeof SUBSCRIPT_MAP =>
-  key in SUBSCRIPT_MAP
-
-// Check if range is a valid [min, max] tuple (strict 2-element array of finite numbers)
-export const is_valid_range = (range: unknown): range is Vec2 =>
-  Array.isArray(range) &&
-  range.length === 2 &&
-  Number.isFinite(range[0]) &&
-  Number.isFinite(range[1])
-
-// Check if two ranges are approximately equal (within tolerance)
-// Returns false if either range is invalid (null, undefined, or fails is_valid_range)
-// Negative tol is clamped to 0; tol=0 checks exact equality
-export const ranges_equal = (
-  a: Vec2 | undefined | null,
-  b: Vec2 | undefined | null,
-  tol = 0.001,
-): boolean => {
-  const safe_tol = Math.max(0, tol)
-  return (
-    is_valid_range(a) &&
-    is_valid_range(b) &&
-    Math.abs(a[0] - b[0]) <= safe_tol &&
-    Math.abs(a[1] - b[1]) <= safe_tol
-  )
-}
-
-export const axis_with_range = (
-  axis: AxisConfig | undefined,
-  range: Vec2 | undefined,
-  label?: string,
-): AxisConfig => ({
-  ...axis,
-  ...(label !== undefined && { label }),
-  ...(is_valid_range(range) && { range }),
-})
-
-// Detect which plot triggered a zoom change and return the new synced range.
-// Returns null to reset to shared range, undefined for no change, or Vec2 for new zoom.
-export function detect_zoom_change(
-  bands_range: unknown,
-  dos_range: unknown,
-  shared_range: Vec2,
-  current_synced: Vec2 | null,
-  dos_enabled = true,
-): Vec2 | null | undefined {
-  const bands_valid = is_valid_range(bands_range)
-  const dos_valid = dos_enabled && is_valid_range(dos_range)
-
-  // Reset if either becomes invalid (auto-range reset) or returns to shared range
-  if (current_synced !== null) {
-    const bands_at_shared = bands_valid && ranges_equal(bands_range, shared_range)
-    const dos_at_shared = dos_valid && ranges_equal(dos_range, shared_range)
-    if (bands_at_shared || dos_at_shared || !bands_valid || (dos_enabled && !dos_valid)) {
-      return null
-    }
-  }
-
-  // Check for new zoom from either plot
-  const bands_is_new =
-    bands_valid &&
-    !ranges_equal(bands_range, shared_range) &&
-    !ranges_equal(bands_range, current_synced)
-  const dos_is_new =
-    dos_valid &&
-    !ranges_equal(dos_range, shared_range) &&
-    !ranges_equal(dos_range, current_synced)
-
-  if (bands_is_new && !dos_is_new) return bands_range
-  if (dos_is_new && !bands_is_new) return dos_range
-  return undefined // no change
-}
-
-// Physical constants for unit conversions (SI units)
-const PLANCK = 6.62607015e-34 // J⋅s
-const EV_TO_J = 1.602176634e-19 // J
-const C_LIGHT = 299792458 // m/s
-const THz_TO_HZ = 1e12
-const THz_TO_EV = (PLANCK * THz_TO_HZ) / EV_TO_J
-const THz_TO_MEV = THz_TO_EV * 1000
-const THz_TO_HA = THz_TO_EV / 27.211386245988 // Hartree
-const THz_TO_CM = THz_TO_HZ / (C_LIGHT * 100) // cm^-1 (c in cm/s)
-
-// Band structure constants
-export const IMAGINARY_MODE_NOISE_THRESHOLD = 0.005 // Clamp negatives < 0.5% as noise
-
-// Convert symmetry point symbols to pretty-printed versions.
-// Handles Greek letters (both plain and LaTeX backslash-prefixed) and subscripts.
-export function pretty_sym_point(symbol: string): string {
-  if (!symbol) return ``
-
-  // Remove underscores (htmlify maps S0 → S<sub>0</sub> but leaves S_0 as is)
-  // Replace common symmetry point names with Greek letters
-  // Handle both plain names (GAMMA) and LaTeX notation (\Gamma) from pymatgen
-  // Handle subscripts: convert S0 to S₀, K1 to K₁, Γ1 to Γ₁, etc.
-  // Use \p{L} to match any Unicode letter (not just ASCII A-Z)
-  return symbol
-    .replace(/_/g, ``)
-    .replace(/\\?GAMMA/gi, `Γ`)
-    .replace(/\\?DELTA/gi, `Δ`)
-    .replace(/\\?SIGMA/gi, `Σ`)
-    .replace(/\\?LAMBDA/gi, `Λ`)
-    .replace(
-      /(\p{L})(\d+)/gu,
-      (_, letter, num) =>
-        letter +
-        num
-          .split(``)
-          .map((digit: string) => (is_subscript_key(digit) ? SUBSCRIPT_MAP[digit] : digit))
-          .join(``),
-    )
-}
-
-// Create segment key from start and end labels
-export const get_segment_key = (start_label?: string, end_label?: string) =>
-  `${start_label ?? `null`}_${end_label ?? `null`}`
-
-// Get ordered segment keys from a band structure, preserving physical path order.
-export const get_ordered_segments = (
-  band_struct: types.BaseBandStructure | null,
-  segments: Set<string>,
-) => {
-  if (!band_struct) return Array.from(segments)
-
-  const ordered = band_struct.branches.map((branch) =>
-    get_segment_key(
-      band_struct.qpoints[branch.start_index]?.label ?? undefined,
-      band_struct.qpoints[branch.end_index]?.label ?? undefined,
-    ),
-  )
-  const remaining = Array.from(segments).filter((seg) => !ordered.includes(seg))
-  return [...ordered, ...remaining]
-}
-
-// Scale segment distances to a target x-axis range [x_start, x_end].
-// Used by both band line series and fat band ribbons for consistent x-axis positioning.
-export function scale_segment_distances(
-  segment_distances: number[],
-  x_start: number,
-  x_end: number,
-): number[] {
-  if (segment_distances.length === 0) return []
-
-  const dist_min = segment_distances[0]
-  const dist_range = (segment_distances.at(-1) ?? dist_min) - dist_min
-
-  if (dist_range === 0) {
-    // All points at same distance - place at midpoint
-    return segment_distances.map(() => (x_start + x_end) / 2)
-  }
-
-  return segment_distances.map(
-    (dist) => x_start + ((dist - dist_min) / dist_range) * (x_end - x_start),
-  )
-}
-
-// Get ribbon config for a specific band structure label.
-// Supports both single global config (with primitive keys like opacity, max_width, scale, color)
-// and per-structure config (keyed by structure label).
-// Distinguishes between a global config and a per-structure config by checking if any
-// primitive-typed keys (opacity, max_width, scale, color) exist at the top level.
-export function get_ribbon_config(
-  ribbon_config: RibbonConfig | Record<string, RibbonConfig>,
-  label: string,
-): RibbonConfig {
-  const defaults: RibbonConfig = { opacity: 0.3, max_width: 6, scale: 1 }
-  const config_record = ribbon_config as Record<string, unknown>
-
-  // Check for primitive config values (not objects) to distinguish single vs per-structure config
-  const has_primitive = [`opacity`, `max_width`, `scale`, `color`].some((key) => {
-    const value = config_record[key]
-    return value !== undefined && typeof value !== `object`
-  })
-
-  if (has_primitive) {
-    // Single global config with primitive values - apply to all structures
-    return { ...defaults, ...ribbon_config }
-  }
-
-  // Otherwise, treat as Record<string, RibbonConfig> and look up by label
-  // Empty label skips lookup and uses defaults only
-  const label_config = label ? config_record[label] : undefined
-  return {
-    ...defaults,
-    ...(label_config && typeof label_config === `object` ? label_config : {}),
-  }
-}
-
-// Extract tick positions and labels for a band structure plot.
-export function get_band_xaxis_ticks(
-  band_struct: types.BaseBandStructure,
-  branches: string[] | Set<string> = [],
-): [number[], string[]] {
-  const ticks_x_pos: number[] = []
-  const tick_labels: string[] = []
-  let prev_label = band_struct.qpoints[0]?.label || null
-  let prev_branch = band_struct.branches[0]?.name || null
-
-  // Convert branches to Set for consistent handling
-  const branches_set = Array.isArray(branches) ? new Set(branches) : branches
-
-  for (let idx = 0; idx < band_struct.qpoints.length; idx++) {
-    const point = band_struct.qpoints[idx]
-    if (point.label === null) continue
-
-    // Find which branch this point belongs to
-    const branch_names = band_struct.branches
-      .filter((branch) => branch.start_index <= idx && idx <= branch.end_index)
-      .map((branch) => branch.name)
-    const this_branch = branch_names[0] || null
-
-    if (point.label !== prev_label && prev_branch !== this_branch) {
-      // Branch transition - combine labels
-      tick_labels[tick_labels.length - 1] = `${prev_label || ``}|${point.label}`
-      ticks_x_pos[ticks_x_pos.length - 1] = band_struct.distance[idx]
-    } else if (branches_set.size === 0 || (this_branch && branches_set.has(this_branch))) {
-      tick_labels.push(point.label)
-      ticks_x_pos.push(band_struct.distance[idx])
-    }
-
-    prev_label = point.label
-    prev_branch = this_branch
-  }
-
-  return [ticks_x_pos, tick_labels.map(pretty_sym_point)]
-}
-
-// Convert frequencies from THz to specified units.
-export function convert_frequencies(
-  frequencies: number[],
-  unit: types.FrequencyUnit = `THz`,
-): number[] {
-  const conversion_factors: Record<types.FrequencyUnit, number> = {
-    THz: 1,
-    eV: THz_TO_EV,
-    meV: THz_TO_MEV,
-    Ha: THz_TO_HA,
-    'cm-1': THz_TO_CM,
-  }
-
-  const factor = conversion_factors[unit]
-  if (!factor) {
-    const valid_units = Object.keys(conversion_factors).join(`, `)
-    throw new Error(`Invalid unit: ${unit}. Must be one of ${valid_units}`)
-  }
-
-  return frequencies.map((freq) => freq * factor)
-}
-
-// Normalize DOS densities according to specified mode.
-export function normalize_densities(
-  densities: number[],
-  freqs_or_energies: number[],
-  mode: types.NormalizationMode,
-): number[] {
-  if (!mode) return densities
-
-  const normalized = [...densities]
-
-  if (mode === `max`) {
-    const max_val = Math.max(...normalized)
-    if (max_val === 0) return normalized
-    return normalized.map((dens) => dens / max_val)
-  } else if (mode === `sum`) {
-    const sum = normalized.reduce((acc, d) => acc + d, 0)
-    if (sum === 0) return normalized
-    return normalized.map((dens) => dens / sum)
-  } else if (mode === `integral`) {
-    if (freqs_or_energies.length < 2) return normalized
-    const bin_width = freqs_or_energies[1] - freqs_or_energies[0]
-    if (bin_width === 0) return normalized
-    const sum = normalized.reduce((acc, d) => acc + d, 0)
-    if (sum === 0) return normalized
-    return normalized.map((dens) => dens / (sum * bin_width))
-  }
-
-  return normalized
-}
-
-// Simple LRU cache for Gaussian smearing results
-// Key: hash of (frequencies, densities, sigma), Value: smeared densities
-const SMEARING_CACHE_MAX_SIZE = 10
-const smearing_cache = new Map<string, number[]>()
-
-// FNV-1a hash for number arrays (fast, good distribution, O(n))
-function fnv1a_hash(arr: number[]): number {
-  let hash = 2166136261 // FNV offset basis
-  for (const val of arr) {
-    // Convert float to int32 bits for consistent hashing
-    const bits = new Float64Array([val])
-    const int_view = new Uint32Array(bits.buffer)
-    hash ^= int_view[0]
-    hash = Math.imul(hash, 16777619) // FNV prime
-    hash ^= int_view[1]
-    hash = Math.imul(hash, 16777619)
-  }
-  return hash >>> 0 // Ensure unsigned
-}
-
-// Generate cache key using FNV-1a hash over full arrays (O(n), low collision risk)
-function generate_smearing_cache_key(
-  freqs_or_energies: number[],
-  densities: number[],
-  sigma: number,
-): string {
-  const len = freqs_or_energies.length
-  if (len === 0) return `0:${sigma.toFixed(6)}:0:0`
-  return `${len}:${sigma.toFixed(6)}:${fnv1a_hash(freqs_or_energies).toString(16)}:${fnv1a_hash(
-    densities,
-  ).toString(16)}`
-}
-
-// Core Gaussian smearing computation (unmemoized)
-function apply_gaussian_smearing_core(
-  freqs_or_energies: number[],
-  densities: number[],
-  sigma: number,
-): number[] {
-  const orig_sum = densities.reduce((acc, d) => acc + d, 0)
-  if (sigma <= 0 || orig_sum === 0) return densities
-
-  const smeared = Array(densities.length).fill(0)
-  const truncation_width = 4 // Truncate Gaussian at ±4σ (contribution < 0.01%)
-
-  for (let idx = 0; idx < freqs_or_energies.length; idx++) {
-    const energy = freqs_or_energies[idx]
-    const cutoff = truncation_width * sigma
-
-    for (let jdx = 0; jdx < freqs_or_energies.length; jdx++) {
-      const e_j = freqs_or_energies[jdx]
-      const delta = Math.abs(energy - e_j)
-
-      // Skip points beyond truncation width
-      if (delta > cutoff) continue
-
-      const gaussian = Math.exp(-((energy - e_j) ** 2) / (2 * sigma ** 2))
-      smeared[idx] += densities[jdx] * gaussian
-    }
-  }
-
-  // Normalize to preserve integral
-  const smeared_sum = smeared.reduce((acc, d) => acc + d, 0)
-  if (smeared_sum === 0) return densities
-  const normalization = orig_sum / smeared_sum
-  return smeared.map((dens) => dens * normalization)
-}
-
-// Apply Gaussian smearing to DOS densities with memoization.
-// Uses truncated Gaussian (±4σ) for O(n·w) complexity instead of O(n²).
-// Results are cached using an LRU cache to avoid recomputation on reactive updates.
-export function apply_gaussian_smearing(
-  freqs_or_energies: number[],
-  densities: number[],
-  sigma: number,
-): number[] {
-  // Fast path: no smearing needed
-  if (sigma <= 0) return densities
-
-  const cache_key = generate_smearing_cache_key(freqs_or_energies, densities, sigma)
-
-  // Check cache
-  const cached = smearing_cache.get(cache_key)
-  if (cached) {
-    // Move to end (LRU behavior: most recently used last)
-    smearing_cache.delete(cache_key)
-    smearing_cache.set(cache_key, cached)
-    return cached
-  }
-
-  // Compute and cache
-  const result = apply_gaussian_smearing_core(freqs_or_energies, densities, sigma)
-
-  // Evict oldest entry if cache is full (LRU: first entry is oldest)
-  if (smearing_cache.size >= SMEARING_CACHE_MAX_SIZE) {
-    const oldest_key = smearing_cache.keys().next().value
-    if (oldest_key !== undefined) smearing_cache.delete(oldest_key)
-  }
-
-  smearing_cache.set(cache_key, result)
-  return result
-}
-
-// Clear the smearing cache (useful for testing or memory management)
-export function clear_smearing_cache(): void {
-  smearing_cache.clear()
-}
-
-// Type guards for pymatgen qpoint formats
-const is_vec3 = (val: unknown): val is Vec3 =>
-  Array.isArray(val) && val.length >= 3 && val.slice(0, 3).every(Number.isFinite)
-
-interface PymatgenKpoint {
-  frac_coords: Vec3
-  label?: string | null
-}
-const is_kpoint = (val: unknown): val is PymatgenKpoint =>
-  !!val && typeof val === `object` && `frac_coords` in val && is_vec3(val.frac_coords)
-
-const is_pymatgen_format = (obj: Record<string, unknown>): boolean => {
-  // Check for explicit pymatgen markers
-  if (typeof obj[`@class`] === `string` || typeof obj[`@module`] === `string`) {
-    return true
-  }
-  // Check for pymatgen-style qpoints (phonon) or kpoints (electronic) without branches
-  const points = obj.qpoints ?? obj.kpoints
-  if (Array.isArray(points) && points.length > 0 && !Array.isArray(obj.branches)) {
-    return is_vec3(points[0]) || is_kpoint(points[0])
-  }
-  return false
-}
-
-// Extract frac_coords/label from pymatgen qpoint, matching label from labels_dict if needed
-const parse_qpoint = (
-  qpt: unknown,
-  labels_dict?: Record<string, Vec3>,
-): types.QPoint | null => {
-  const frac_coords = is_vec3(qpt)
-    ? ([qpt[0], qpt[1], qpt[2]] as Vec3)
-    : is_kpoint(qpt)
-      ? qpt.frac_coords
-      : null
-  if (!frac_coords) return null
-
-  const label =
-    (is_kpoint(qpt) && typeof qpt.label === `string` && qpt.label) ||
-    Object.entries(labels_dict ?? {}).find(
-      ([, c]) => euclidean_dist(frac_coords, c) < 1e-4,
-    )?.[0] ||
-    null
-  return { label, frac_coords }
-}
-
-// Inverse conversion factors (derived from THz_TO_* for consistency)
-const EV_TO_THZ = 1 / THz_TO_EV
-const CM_TO_THZ = 1 / THz_TO_CM
-
-// Spin key constants for pymatgen spin-polarized data
-const SPIN_UP_KEYS = [`1`, `Spin.up`]
-const SPIN_DOWN_KEYS = [`-1`, `Spin.down`]
-
-// Extract both spin channels from pymatgen spin-keyed data.
-// Returns { up: T, down: T | null } where down is null for non-spin-polarized data.
-export function extract_spin_channels<T>(data: unknown): { up: T; down: T | null } | null {
-  if (Array.isArray(data)) return { up: data as T, down: null }
-  if (data && typeof data === `object`) {
-    const record = data as Record<string, T>
-    let spin_up: T | null = null
-    let spin_down: T | null = null
-
-    // Extract spin-up channel
-    for (const key of SPIN_UP_KEYS) {
-      if (key in record) {
-        spin_up = record[key]
-        break
-      }
-    }
-    // Extract spin-down channel
-    for (const key of SPIN_DOWN_KEYS) {
-      if (key in record) {
-        spin_down = record[key]
-        break
-      }
-    }
-
-    // Fall back to first key if no spin-up key found
-    if (spin_up === null) {
-      const keys = Object.keys(record)
-      if (keys.length > 0) spin_up = record[keys[0]]
-    }
-
-    if (spin_up === null) return null
-    return { up: spin_up, down: spin_down }
-  }
-  return null
-}
-
-// Convert pymatgen PhononBandStructureSymmLine or BandStructure to matterviz format
-function convert_pymatgen_band_structure(
-  pmg: Record<string, unknown>,
-): types.BaseBandStructure | null {
-  // Support both qpoints (phonon) and kpoints (electronic)
-  const raw_qpts = (pmg.qpoints ?? pmg.kpoints) as unknown[] | undefined
-
-  // Handle bands in multiple formats:
-  // 1. Standard pymatgen: bands as dict with spin keys {1: [[...], ...]}
-  // 2. Custom phonon format: frequencies_cm as 2D array [[...], ...]
-  // 3. Already normalized: bands as 2D array [[...], ...]
-  const spin_channels = extract_spin_channels<number[][]>(pmg.bands)
-  let raw_bands = spin_channels?.up ?? null
-  let raw_spin_down_bands = spin_channels?.down ?? null
-  const has_frequencies_cm = Array.isArray(pmg.frequencies_cm)
-  if (!raw_bands && has_frequencies_cm) {
-    // Phonon format: frequencies_cm is [n_qpoints x n_branches] - needs transpose
-    const freqs = pmg.frequencies_cm as number[][]
-    if (freqs.length > 0 && Array.isArray(freqs[0])) {
-      // Transpose: [n_qpoints x n_branches] -> [n_branches x n_qpoints]
-      raw_bands = Array.from({ length: freqs[0].length }, (_, band_idx) =>
-        freqs.map((qpt_freqs) => qpt_freqs[band_idx]),
-      )
-      raw_spin_down_bands = null
-    }
-  }
-
-  const labels_dict = pmg.labels_dict as Record<string, Vec3> | undefined
-  const lattice_rec = pmg.lattice_rec as { matrix?: Matrix3x3 } | undefined
-  // Determine unit: cm-1 if frequencies_cm present, else check explicit unit or default to THz
-  const unit =
-    (pmg.unit as string | undefined)?.toLowerCase() ?? (has_frequencies_cm ? `cm-1` : `thz`)
-
-  if (
-    !Array.isArray(raw_qpts) ||
-    !Array.isArray(raw_bands) ||
-    !raw_qpts.length ||
-    !raw_bands.length
-  )
-    return null
-
-  const qpoints = raw_qpts
-    .map((qpoint) => parse_qpoint(qpoint, labels_dict))
-    .filter((qpoint): qpoint is types.QPoint => qpoint !== null)
-  if (!qpoints.length) return null
-
-  // Step distances and discontinuity detection (5x median threshold)
-  const steps = qpoints
-    .slice(1)
-    .map((qpoint, idx) => euclidean_dist(qpoints[idx].frac_coords, qpoint.frac_coords))
-  const sorted = steps.slice().sort((a, b) => a - b)
-  const threshold = (sorted[Math.floor(sorted.length / 2)] ?? 0) * 5
-  const disc_set = new Set(
-    steps
-      .map((step, idx) => (step > threshold ? idx + 1 : -1))
-      .filter((disc_idx) => disc_idx >= 0),
-  )
-
-  // Cumulative distance (skip discontinuities)
-  const distance = steps.reduce(
-    (acc, step, idx) => [...acc, disc_set.has(idx + 1) ? acc[idx] : acc[idx] + step],
-    [0],
-  )
-
-  // Use pymatgen's branches if available - they correctly handle discontinuities
-  // Otherwise, infer branches from discontinuities (robust fallback covering all qpoints)
-  const pmg_branches = pmg.branches as types.Branch[] | undefined
-  let branches: types.Branch[] = []
-
-  if (Array.isArray(pmg_branches) && pmg_branches.length > 0) {
-    // Validate and use pymatgen branches directly
-    branches = pmg_branches.filter(
-      (branch) =>
-        typeof branch.start_index === `number` &&
-        typeof branch.end_index === `number` &&
-        branch.start_index >= 0 &&
-        branch.end_index < qpoints.length &&
-        branch.start_index <= branch.end_index,
-    )
-  }
-
-  // Fallback: infer branches from discontinuities when none provided or all invalid
-  if (branches.length === 0) {
-    console.warn(
-      `Band structure missing 'branches' field - inferring from path discontinuities`,
-    )
-    // Discontinuity indices mark points where the path jumps (disc before that index)
-    // Create continuous segments between discontinuities
-    const disc_indices = [...disc_set].sort((a, b) => a - b)
-    // Segment boundaries: [0, first_disc), [first_disc, second_disc), ..., [last_disc, end]
-    const segment_starts = [0, ...disc_indices]
-    const segment_ends = [...disc_indices.map((idx) => idx - 1), qpoints.length - 1]
-
-    branches = segment_starts
-      .map((start, idx) => {
-        const end = segment_ends[idx]
-        const start_label = qpoints[start]?.label ?? `?`
-        const end_label = qpoints[end]?.label ?? `?`
-        return {
-          start_index: start,
-          end_index: end,
-          name: `${start_label}-${end_label}`,
-        }
-      })
-      .filter((branch) => branch.start_index <= branch.end_index)
-  }
-
-  if (!branches.length) {
-    branches.push({ start_index: 0, end_index: qpoints.length - 1, name: `path` })
-  }
-
-  // Convert bands to THz based on input unit
-  const convert_to_thz = (val: number): number => {
-    if (unit === `ev`) return val * EV_TO_THZ
-    if (unit === `cm-1`) return val * CM_TO_THZ
-    return val // THz (default) - no conversion
-  }
-
-  const converted_bands = raw_bands.map((band) => band.map(convert_to_thz))
-  const valid_spin_down_bands =
-    Array.isArray(raw_spin_down_bands) &&
-    raw_spin_down_bands.length === raw_bands.length &&
-    raw_spin_down_bands.every(
-      (band, band_idx) => Array.isArray(band) && band.length === raw_bands[band_idx]?.length,
-    )
-      ? raw_spin_down_bands
-      : null
-  const converted_spin_down_bands = valid_spin_down_bands?.map((band) =>
-    band.map(convert_to_thz),
-  )
-
-  return {
-    qpoints,
-    branches,
-    distance,
-    bands: converted_bands,
-    spin_down_bands: converted_spin_down_bands,
-    nb_bands: raw_bands.length,
-    labels_dict: labels_dict ?? {},
-    recip_lattice: {
-      matrix: lattice_rec?.matrix ?? [
-        [1, 0, 0],
-        [0, 1, 0],
-        [0, 0, 1],
-      ],
-    },
-  }
-}
-
-export function normalize_band_structure(bs: unknown): types.BaseBandStructure | null {
-  if (!bs || typeof bs !== `object`) return null
-
-  const band_struct = bs as Record<string, unknown>
-
-  // Check if this is pymatgen format and convert if so
-  if (is_pymatgen_format(band_struct)) {
-    return convert_pymatgen_band_structure(band_struct)
-  }
-
-  // Standard matterviz format validation
-  const { qpoints, branches, bands, distance } =
-    band_struct as Partial<types.BaseBandStructure>
-  if (
-    !Array.isArray(qpoints) ||
-    !Array.isArray(branches) ||
-    !Array.isArray(bands) ||
-    !Array.isArray(distance)
-  )
-    return null
-
-  // Validate array lengths and branch indices
-  const n_qpts = qpoints.length
-  if (
-    distance.length !== n_qpts ||
-    bands.some((band) => !Array.isArray(band) || band.length !== n_qpts) ||
-    branches.some(
-      (branch) =>
-        typeof branch.start_index !== `number` ||
-        typeof branch.end_index !== `number` ||
-        branch.start_index < 0 ||
-        branch.end_index >= n_qpts ||
-        branch.start_index > branch.end_index,
-    )
-  )
-    return null
-
-  return band_struct as unknown as types.BaseBandStructure
-}
-
-// Validate and normalize a DOS object.
-// Supports both matterviz and pymatgen formats.
-// Also auto-detects and converts cm⁻¹ to THz for legacy data (disable with auto_convert_units: false).
-export function normalize_dos(
-  dos: unknown,
-  options: { auto_convert_units?: boolean } = {},
-): types.DosData | null {
-  const { auto_convert_units = true } = options
-  if (!dos || typeof dos !== `object`) return null
-
-  const dos_obj = dos as Record<string, unknown>
-
-  // Check for pymatgen format (has @class or @module)
-  const is_pymatgen =
-    typeof dos_obj[`@class`] === `string` || typeof dos_obj[`@module`] === `string`
-
-  const { frequencies, energies, spin_polarized } = dos_obj
-
-  // Handle densities as either array or dict with spin keys (pymatgen format)
-  // Pymatgen stores densities as {1: [...], -1: [...]} or {"Spin.up": [...], ...}
-  const spin_channels = extract_spin_channels<number[]>(dos_obj.densities)
-  if (!spin_channels) return null
-
-  const densities = spin_channels.up
-  // Use extracted spin-down or fallback to explicit field (for already-normalized DosData)
-  const spin_down_densities =
-    spin_channels.down ?? (dos_obj.spin_down_densities as number[] | undefined) ?? null
-
-  if (!Array.isArray(densities)) return null
-
-  // Phonon DOS: has frequencies
-  if (Array.isArray(frequencies)) {
-    if (frequencies.length !== densities.length) return null
-
-    // Auto-detect if frequencies are in cm⁻¹ instead of THz (unless disabled)
-    // Typical phonon frequencies are < 50 THz for most materials
-    // If max frequency > 100, it's almost certainly in cm⁻¹
-    const max_freq = Math.max(...(frequencies as number[]))
-    let final_frequencies = frequencies as number[]
-
-    if (auto_convert_units && max_freq > 100) {
-      // Likely in cm⁻¹, convert to THz
-      final_frequencies = (frequencies as number[]).map((frequency) => frequency * CM_TO_THZ)
-      console.warn(
-        `Phonon DOS frequencies appear to be in cm⁻¹ (max: ${max_freq.toFixed(1)}). ` +
-          `Converting to THz (max: ${(max_freq * CM_TO_THZ).toFixed(1)} THz).`,
-      )
-    }
-
-    return { type: `phonon`, frequencies: final_frequencies, densities }
-  }
-
-  // Electronic DOS: has energies
-  if (Array.isArray(energies)) {
-    if (energies.length !== densities.length) return null
-    // Detect spin-polarized from data if not explicitly set
-    const is_spin_polarized =
-      (spin_polarized as boolean | undefined) ??
-      (spin_down_densities !== null && spin_down_densities.length === densities.length)
-    return {
-      type: `electronic`,
-      energies,
-      densities,
-      spin_down_densities: is_spin_polarized ? (spin_down_densities ?? undefined) : undefined,
-      spin_polarized: is_spin_polarized,
-    }
-  }
-
-  // For pymatgen format, log a helpful message if format wasn't recognized
-  if (is_pymatgen) {
-    console.warn(
-      `Pymatgen DOS format detected but missing required fields. ` +
-        `Expected 'frequencies' (phonon) or 'energies' (electronic) arrays.`,
-    )
-  }
-
-  return null
-}
-
-// Extract k-path points from band structure and convert to reciprocal space coordinates
-// Accepts a reciprocal lattice matrix (should include 2π factor for consistency with BZ)
-// Handles both matterviz format (qpoints as objects) and normalized pymatgen format
-// Optionally wraps fractional coordinates to first BZ (default: true)
-export function extract_k_path_points(
-  band_struct: types.BaseBandStructure,
-  recip_lattice_matrix: Matrix3x3,
-  options: { wrap_to_bz?: boolean } = {},
-): Vec3[] {
-  const { wrap_to_bz = true } = options
-  if (!band_struct?.qpoints || !recip_lattice_matrix) return []
-
-  if (
-    recip_lattice_matrix.length !== 3 ||
-    recip_lattice_matrix.some((row) => row?.length !== 3)
-  )
-    throw new Error(`reciprocal_lattice_matrix must be a 3×3 matrix`)
-
-  const [[m00, m01, m02], [m10, m11, m12], [m20, m21, m22]] = recip_lattice_matrix
-
-  return band_struct.qpoints.map((qpoint): Vec3 => {
-    let [x, y, z] = qpoint.frac_coords
-    // Wrap to first BZ if enabled (handles [0,1] vs [-0.5,0.5] convention difference)
-    if (wrap_to_bz) {
-      x = centered_frac(x)
-      y = centered_frac(y)
-      z = centered_frac(z)
-    }
-    const kx = x * m00 + y * m10 + z * m20
-    const ky = x * m01 + y * m11 + z * m21
-    const kz = x * m02 + y * m12 + z * m22
-    return [kx, ky, kz]
-  })
-}
-
-// Find the q-point index closest to a given distance along the band structure path
-export function find_qpoint_at_distance(
-  band_struct: types.BaseBandStructure,
-  target: number,
-): number | null {
-  const { distance } = band_struct
-  if (!distance?.length) return null
-
-  return distance.reduce(
-    (closest: number, dist: number, idx: number) =>
-      Math.abs(dist - target) < Math.abs(distance[closest] - target) ? idx : closest,
-    0,
-  )
-}
-
-// Find q-point index from rescaled x-coordinate (used in band structure plots)
-// This handles the case where the plot uses custom x-axis scaling per segment
-export function find_qpoint_at_rescaled_x(
-  band_struct: types.BaseBandStructure,
-  rescaled_x: number,
-  x_positions: Record<string, [number, number]>,
-): number | null {
-  if (!band_struct?.branches?.length || !x_positions) return null
-
-  // Find which segment contains this x coordinate
-  for (const branch of band_struct.branches) {
-    const start_idx = branch.start_index
-    const end_idx = branch.end_index
-    const start_label = band_struct.qpoints[start_idx]?.label ?? undefined
-    const end_label = band_struct.qpoints[end_idx]?.label ?? undefined
-    const segment_key = get_segment_key(start_label, end_label)
-
-    const segment_range = x_positions[segment_key]
-    if (!segment_range) continue
-
-    const [x_start, x_end] = segment_range
-
-    // Check if discontinuity (zero-length segment)
-    const is_discontinuity = Math.abs(x_end - x_start) < 1e-6
-    if (is_discontinuity) {
-      // For discontinuities, check if x is exactly at this point
-      if (Math.abs(rescaled_x - x_start) < 1e-6) {
-        return start_idx
-      }
-      continue
-    }
-
-    // Check if x is within this segment (with small tolerance for edges)
-    if (rescaled_x >= x_start - 1e-6 && rescaled_x <= x_end + 1e-6) {
-      // Map from rescaled x back to original distance
-      const segment_distances = band_struct.distance.slice(start_idx, end_idx + 1)
-      const dist_min = segment_distances[0]
-      const dist_max = segment_distances.at(-1) ?? dist_min
-      const dist_range = dist_max - dist_min
-
-      // Handle zero-length segments
-      if (dist_range === 0) {
-        return start_idx
-      }
-
-      // Inverse of the scaling: x = x_start + ((dist - dist_min) / dist_range) * (x_end - x_start)
-      // Solving for dist: dist = dist_min + ((x - x_start) / (x_end - x_start)) * dist_range
-      const normalized_x = (rescaled_x - x_start) / (x_end - x_start)
-      const target_dist = dist_min + normalized_x * dist_range
-
-      // Find closest qpoint in this branch to the target distance
-      let closest_idx = start_idx
-      let min_diff = Math.abs(band_struct.distance[start_idx] - target_dist)
-
-      for (let idx = start_idx; idx <= end_idx; idx++) {
-        const diff = Math.abs(band_struct.distance[idx] - target_dist)
-        if (diff < min_diff) {
-          min_diff = diff
-          closest_idx = idx
-        }
-      }
-
-      return closest_idx
-    }
-  }
-
-  // Fallback: find closest labeled point
-  let closest_idx = 0
-  let min_dist = Infinity
-
-  for (const branch of band_struct.branches) {
-    const start_idx = branch.start_index
-    const end_idx = branch.end_index
-    const start_label = band_struct.qpoints[start_idx]?.label ?? undefined
-    const end_label = band_struct.qpoints[end_idx]?.label ?? undefined
-    const segment_key = get_segment_key(start_label, end_label)
-    const segment_range = x_positions[segment_key]
-
-    if (!segment_range) continue
-
-    const [x_start, x_end] = segment_range
-
-    for (const [x_pos, idx] of [
-      [x_start, start_idx],
-      [x_end, end_idx],
-    ] as const) {
-      const dist = Math.abs(rescaled_x - x_pos)
-      if (dist < min_dist) {
-        min_dist = dist
-        closest_idx = idx
-      }
-    }
-  }
-
-  return closest_idx
-}
-
-// Type definitions for pymatgen DOS formats
-// Densities can be spin-keyed: {1: number[], -1: number[]} or {"Spin.up": number[], ...}
-type SpinDensities = Record<string, number[]>
-
-// Pymatgen Dos base class format
-export interface PymatgenDos {
-  '@class': string
-  '@module': string
-  energies: number[]
-  densities: SpinDensities | number[]
-  efermi: number
-}
-
-// Pymatgen CompleteDos format (includes projected DOS)
-export interface PymatgenCompleteDos extends PymatgenDos {
-  '@class': `CompleteDos` | `LobsterCompleteDos`
-  structure?: Record<string, unknown>
-  pdos?: Record<string, SpinDensities>[]
-  atom_dos?: Record<string, PymatgenDos>
-  spd_dos?: Record<string, PymatgenDos>
-}
-
-// Extract projected DOS from pymatgen CompleteDos format.
-// Returns a dict of label → DosData for each atom or orbital.
-// filter_keys: optional list of keys to include (e.g., ["Fe", "O"] for atoms or ["s", "p", "d"] for orbitals)
-export function extract_pdos(
-  dos: unknown,
-  pdos_type: types.PdosType,
-  filter_keys?: string[],
-): Record<string, types.ElectronicDos> | null {
-  if (!dos || typeof dos !== `object`) return null
-
-  const dos_obj = dos as Record<string, unknown>
-
-  // Get the appropriate projected DOS dict
-  const pdos_dict =
-    pdos_type === `atom`
-      ? (dos_obj.atom_dos as Record<string, PymatgenDos> | undefined)
-      : (dos_obj.spd_dos as Record<string, PymatgenDos> | undefined)
-
-  if (!pdos_dict || typeof pdos_dict !== `object`) return null
-
-  const result: Record<string, types.ElectronicDos> = {}
-
-  for (const [key, nested_dos] of Object.entries(pdos_dict)) {
-    // Apply filter if provided
-    if (filter_keys && filter_keys.length > 0 && !filter_keys.includes(key)) continue
-
-    if (!nested_dos || typeof nested_dos !== `object`) continue
-
-    const energies = nested_dos.energies
-    const spin_channels = extract_spin_channels<number[]>(nested_dos.densities)
-
-    if (!Array.isArray(energies) || !spin_channels) continue
-
-    const densities = spin_channels.up
-    if (!Array.isArray(densities) || energies.length !== densities.length) continue
-
-    const is_spin_polarized =
-      spin_channels.down !== null && spin_channels.down.length === densities.length
-
-    result[key] = {
-      type: `electronic`,
-      energies,
-      densities,
-      spin_down_densities: is_spin_polarized ? (spin_channels.down ?? undefined) : undefined,
-      spin_polarized: is_spin_polarized,
-      efermi: nested_dos.efermi,
-    }
-  }
-
-  return Object.keys(result).length > 0 ? result : null
-}
-
-// Shift a single DOS object's energies by the given amount
-const shift_dos_energies = <T extends PymatgenDos>(dos: T, shift: number): T => ({
-  ...dos,
-  efermi: dos.efermi - shift,
-  energies: dos.energies.map((energy) => energy - shift),
-})
-
-// Shift DOS energies relative to Fermi energy so E_F = 0
-// Recursively shifts nested DOS in atom_dos and spd_dos for consistency
-export function shift_to_fermi(dos: PymatgenCompleteDos): PymatgenCompleteDos {
-  const shift = dos.efermi
-
-  // Shift root DOS energies using the shared helper
-  const shifted_root = shift_dos_energies(dos, shift)
-
-  // Shift nested atom_dos if present
-  const atom_dos = dos.atom_dos
-    ? Object.fromEntries(
-        Object.entries(dos.atom_dos).map(([key, nested_dos]) => [
-          key,
-          shift_dos_energies(nested_dos, shift),
-        ]),
-      )
-    : undefined
-
-  // Shift nested spd_dos if present
-  const spd_dos = dos.spd_dos
-    ? Object.fromEntries(
-        Object.entries(dos.spd_dos).map(([key, nested_dos]) => [
-          key,
-          shift_dos_energies(nested_dos, shift),
-        ]),
-      )
-    : undefined
-
-  return {
-    ...shifted_root,
-    efermi: 0, // Explicitly set to 0 (shift_dos_energies would give efermi - shift)
-    ...(atom_dos && { atom_dos }),
-    ...(spd_dos && { spd_dos }),
-  }
-}
-
-// Generate an SVG path for a fat band ribbon.
-// Creates a closed polygon by tracing the upper edge (y - half_width) forward,
-// then tracing the lower edge (y + half_width) backward.
-// Non-finite or non-positive widths are clamped to 0.
-export function generate_ribbon_path(
-  x_values: number[],
-  y_values: number[],
-  width_values: number[],
-  x_scale_fn: (x: number) => number,
-  y_scale_fn: (y: number) => number,
-  max_width_px: number,
-  scale: number = 1,
-): string {
-  const len = x_values.length
-  if (len < 2 || len !== y_values.length || len !== width_values.length) return ``
-
-  // Normalize width values to [0, 1] range based on the max positive finite value
-  const finite_positive_widths = width_values.filter(
-    (width) => Number.isFinite(width) && width > 0,
-  )
-  if (finite_positive_widths.length === 0) return ``
-  const max_width_val = Math.max(...finite_positive_widths)
-
-  // Build upper edge path (forward direction)
-  const upper_points: string[] = []
-  const lower_points: string[] = []
-
-  for (let idx = 0; idx < x_values.length; idx++) {
-    const x_px = x_scale_fn(x_values[idx])
-    const y_data = y_values[idx]
-    const raw_width = width_values[idx] ?? 0
-    const width_normalized =
-      Number.isFinite(raw_width) && raw_width > 0 ? raw_width / max_width_val : 0
-    const half_width_px = width_normalized * max_width_px * scale
-
-    // In SVG, y increases downward, so upper edge has smaller y value
-    const y_upper_px = y_scale_fn(y_data) - half_width_px
-    const y_lower_px = y_scale_fn(y_data) + half_width_px
-
-    upper_points.push(`${x_px.toFixed(2)},${y_upper_px.toFixed(2)}`)
-    lower_points.push(`${x_px.toFixed(2)},${y_lower_px.toFixed(2)}`)
-  }
-
-  // Combine: upper edge forward, lower edge backward, close path
-  const path_parts = [
-    `M${upper_points[0]}`,
-    ...upper_points.slice(1).map((pt) => `L${pt}`),
-    ...lower_points.toReversed().map((pt) => `L${pt}`),
-    `Z`,
-  ]
-
-  return path_parts.join(` `)
-}
-
-// Extract efermi from a data source (band structure or DOS).
-// Handles both single objects with an efermi field and dicts of objects.
-// Returns undefined if no valid efermi is found or if the source is empty.
-export function extract_efermi(data: unknown): number | undefined {
-  if (!data || typeof data !== `object`) return undefined
-  const obj = data as Record<string, unknown>
-
-  // Direct efermi field on the object
-  if (`efermi` in obj && typeof obj.efermi === `number`) return obj.efermi
-
-  // Dict of objects - try to get efermi from first value
-  const values = Object.values(obj)
-  if (values.length === 0) return undefined
-
-  const first_val = values[0]
-  if (first_val && typeof first_val === `object`) {
-    const efermi = (first_val as Record<string, unknown>).efermi
-    if (typeof efermi === `number`) return efermi
-  }
-
-  return undefined
-}
-
-// Calculate fraction of |values| that are negative. Used to detect imaginary phonon modes.
-export function negative_fraction(values: number[]): number {
-  let [neg, total] = [0, 0]
-  for (const val of values) {
-    if (!Number.isFinite(val)) continue
-    const abs_val = Math.abs(val)
-    total += abs_val
-    if (val < 0) neg += abs_val
-  }
-  return total > 0 ? neg / total : 0
-}
-
-// Check if raw band structure input has electronic markers (efermi, kpoints, or electronic @class).
-// Must be called on raw input before normalization since these fields aren't preserved.
-function is_electronic_band_struct(bs: unknown): boolean {
-  if (!bs || typeof bs !== `object`) return false
-  const obj = bs as Record<string, unknown>
-  // Electronic band structures have efermi field
-  if (`efermi` in obj && typeof obj.efermi === `number`) return true
-  // Pymatgen electronic format uses kpoints (not qpoints)
-  if (`kpoints` in obj && Array.isArray(obj.kpoints) && obj.kpoints.length > 0) {
-    return true
-  }
-  // Pymatgen @class: BandStructure* but not Phonon*
-  const raw_class = obj[`@class`]
-  const py_class_name = typeof raw_class === `string` ? raw_class : ``
-  if (py_class_name.startsWith(`BandStructure`) && !py_class_name.includes(`Phonon`)) {
-    return true
-  }
-  return false
-}
-
-// Compute frequency/energy range from bands and DOS. Clamps phonon min to 0 if noise < 0.5%.
-export function compute_frequency_range(
-  band_structs: unknown,
-  doses: unknown,
-  padding_factor = 0.02,
-): [number, number] | undefined {
-  let [min_val, max_val, is_phonon] = [Infinity, -Infinity, false]
-  const all_freqs: number[] = []
-
-  // Check raw band_structs for electronic markers before normalization
-  // (normalized structures always have qpoints, so we can't detect from them)
-  let has_electronic_bs = false
-  // Support both qpoints (phonon) and kpoints (electronic) to detect single vs dict
-  const is_single_bs =
-    band_structs &&
-    typeof band_structs === `object` &&
-    (`qpoints` in band_structs || `kpoints` in band_structs)
-  if (band_structs && typeof band_structs === `object`) {
-    // Single structure check
-    if (is_electronic_band_struct(band_structs)) {
-      has_electronic_bs = true
-    } else if (!is_single_bs) {
-      // Dict of band structures - check each value
-      for (const bs_val of Object.values(band_structs)) {
-        if (is_electronic_band_struct(bs_val)) {
-          has_electronic_bs = true
-          break
-        }
-      }
-    }
-  }
-
-  const bs_list = band_structs
-    ? is_single_bs
-      ? [normalize_band_structure(band_structs)]
-      : Object.values(band_structs as object).map(normalize_band_structure)
-    : []
-
-  // If band structures exist and aren't electronic, mark as phonon
-  const has_band_structs = bs_list.some(Boolean)
-  if (has_band_structs && !has_electronic_bs) is_phonon = true
-
-  for (const bs of bs_list) {
-    if (!bs) continue
-    for (const band of bs.bands) {
-      for (const val of band) {
-        if (!Number.isFinite(val)) continue
-        all_freqs.push(val)
-        min_val = Math.min(min_val, val)
-        max_val = Math.max(max_val, val)
-      }
-    }
-  }
-
-  const dos_list = doses
-    ? `densities` in (doses as object)
-      ? [normalize_dos(doses)]
-      : Object.values(doses as object).map((dos) => normalize_dos(dos))
-    : []
-  for (const dos of dos_list) {
-    if (!dos) continue
-    // DOS type detection: explicit type field is authoritative
-    if (dos.type === `phonon`) is_phonon = true
-    if (dos.type === `electronic`) is_phonon = false
-    for (const val of dos.type === `phonon` ? dos.frequencies : dos.energies) {
-      if (!Number.isFinite(val)) continue
-      all_freqs.push(val)
-      min_val = Math.min(min_val, val)
-      max_val = Math.max(max_val, val)
-    }
-  }
-
-  if (!Number.isFinite(min_val) || !Number.isFinite(max_val)) return undefined
-  const clamp_min =
-    is_phonon &&
-    min_val < 0 && // clamp phonon noise to 0
-    negative_fraction(all_freqs) < IMAGINARY_MODE_NOISE_THRESHOLD
-  if (clamp_min) min_val = 0
-  // Calculate padding from (possibly clamped) range for consistency with Bands.svelte
-  const padding = (max_val - min_val) * padding_factor
-  return [min_val === 0 ? 0 : min_val - padding, max_val + padding]
-}
-
-// Parse axis label: "Frequency (THz)" → { name: "Frequency", unit: "THz" }
-function parse_axis_label(label: string): { name: string; unit?: string } {
-  const match = /^(.+?)\s*\(([^)]+)\)$/.exec(label)
-  return match ? { name: match[1], unit: match[2] } : { name: label }
-}
-
-const format_tooltip_line = (name: string, value: string, unit?: string) =>
-  `${name}: ${value}${unit ? ` ${unit}` : ``}`
-
-// Format DOS tooltip content from axis labels and values
-export function format_dos_tooltip(
-  x_formatted: string,
-  y_formatted: string,
-  label: string | null,
-  is_horizontal: boolean,
-  is_phonon: boolean,
-  units: types.FrequencyUnit,
-  x_axis_label: string,
-  y_axis_label: string,
-  num_series: number,
-): { title?: string; lines: string[] } {
-  const x_parsed = parse_axis_label(x_axis_label)
-  const y_parsed = parse_axis_label(y_axis_label)
-  const freq_defaults = {
-    name: is_phonon ? `Frequency` : `Energy`,
-    unit: is_phonon ? units : `eV`,
-  }
-
-  const lines = is_horizontal
-    ? [
-        format_tooltip_line(
-          y_parsed.name || freq_defaults.name,
-          y_formatted,
-          y_parsed.unit || freq_defaults.unit,
-        ),
-        format_tooltip_line(x_parsed.name || `Density`, x_formatted),
-      ]
-    : [
-        format_tooltip_line(y_parsed.name || `Density`, y_formatted),
-        format_tooltip_line(
-          x_parsed.name || freq_defaults.name,
-          x_formatted,
-          x_parsed.unit || freq_defaults.unit,
-        ),
-      ]
-
-  return { title: num_series > 1 && label ? label : undefined, lines }
-}
-
-// Spin mode options for DOS visualization
-export const SPIN_MODES = [
-  { value: `mirror`, label: `↕`, title: `Mirror: spin-up above, spin-down below zero` },
-  { value: `overlay`, label: `≡`, title: `Overlay: both spins on same axis` },
-  { value: `up_only`, label: `↑`, title: `Show spin-up only` },
-  { value: `down_only`, label: `↓`, title: `Show spin-down only` },
-] as const satisfies readonly { value: types.SpinMode; label: string; title: string }[]
-
-// Normalization mode options
-export const NORMALIZATION_MODES = [
-  { value: null, label: `None` },
-  { value: `max`, label: `Max=1` },
-  { value: `sum`, label: `Sum=1` },
-  { value: `integral`, label: `∫=1` },
-] as const satisfies readonly { value: types.NormalizationMode; label: string }[]
-
-// Available frequency units for phonon DOS
-export const FREQUENCY_UNITS: types.FrequencyUnit[] = [`THz`, `eV`, `meV`, `cm-1`, `Ha`]
-
-// Default values for DOS controls
-export const DEFAULT_SPIN_MODE: types.SpinMode = `mirror`
-export const DEFAULT_SIGMA = 0
-export const DEFAULT_NORMALIZE: types.NormalizationMode = null
-export const DEFAULT_UNITS: types.FrequencyUnit = `THz`
-
-// Format sigma with adaptive precision: 0→"0", <0.01→exp, <1→3dp, else→2dp
-export function format_sigma(val: number): string {
-  if (val === 0) return `0`
-  if (val < 0.01) return val.toExponential(1)
-  return val.toFixed(val < 1 ? 3 : 2)
-}
-
-// Validate sigma_range: ensures min < max, returns [0, 1] if invalid
-export const validate_sigma_range = ([min, max]: [number, number]): [number, number] =>
-  Number.isFinite(min) && Number.isFinite(max) && min < max ? [min, max] : [0, 1]
-
-// Calculate slider step: 1/100th of range, or 0.01 fallback
-export function calculate_sigma_step(range: [number, number]): number {
-  const [min, max] = validate_sigma_range(range)
-  return (max - min) / 100 || 0.01
-}
-
-// === Band Tooltip Helpers ===
-
-// Per-point metadata for band tooltip display
-export interface BandPointMeta extends Record<string, unknown> {
-  band_idx: number
-  spin: `up` | `down`
-  is_acoustic: boolean | null
-  nb_bands: number
-  frac_coords: Vec3 | null
-  qpoint_label: string | null
-  band_width: number | null
-  slope: number | null
-}
-
-// Central difference for local slope (dω/dk or dE/dk).
-// Uses forward/backward difference at endpoints, central difference for interior points.
-export function compute_slope(x_vals: number[], y_vals: number[], idx: number): number | null {
-  const len = Math.min(x_vals.length, y_vals.length)
-  if (len < 2 || idx < 0 || idx >= len) return null
-  const lo = idx === 0 ? 0 : idx - 1
-  const hi = idx >= len - 1 ? len - 1 : idx + 1
-  const dx = x_vals[hi] - x_vals[lo]
-  return dx ? (y_vals[hi] - y_vals[lo]) / dx : null
-}
-
-// Find Gamma-point indices (q ≈ integer lattice point) in a band structure.
-// Returns indices of q-points whose fractional coordinates are all within 0.01 of integers.
-export function find_gamma_indices(bs: types.BaseBandStructure): number[] {
-  const indices: number[] = []
-  for (let q_idx = 0; q_idx < bs.qpoints.length; q_idx++) {
-    const coords = bs.qpoints[q_idx]?.frac_coords
-    if (coords?.every((coord) => Math.abs(coord - Math.round(coord)) < 0.01)) {
-      indices.push(q_idx)
-    }
-  }
-  return indices
-}
-
-// Threshold below which a band's frequency at Gamma is considered acoustic (THz).
-// Assumes bands are stored in THz (normalize_band_structure converts to THz).
-export const ACOUSTIC_FREQ_THRESHOLD = 0.5
-
-// Classify a band as acoustic based on near-zero frequency at Gamma points.
-// Returns true (acoustic), false (optical), or null (no Gamma points → can't determine).
-export function classify_acoustic(
-  bs: types.BaseBandStructure,
-  band_idx: number,
-  gamma_indices: number[],
-  threshold = ACOUSTIC_FREQ_THRESHOLD,
-): boolean | null {
-  if (gamma_indices.length === 0) return null
-  return gamma_indices.some(
-    (gamma_idx) => Math.abs(bs.bands[band_idx]?.[gamma_idx] ?? Infinity) < threshold,
-  )
-}
-
-// Build per-point metadata array for a band series in the tooltip.
-export function build_point_metadata(opts: {
-  x_vals: number[]
-  y_vals: number[]
-  band_idx: number
-  spin: `up` | `down`
-  is_acoustic: boolean | null
-  bs: types.BaseBandStructure
-  start_idx: number
-}): BandPointMeta[] {
-  const { x_vals, y_vals, band_idx, spin, is_acoustic, bs, start_idx } = opts
-  return x_vals.map((_, pt_idx) => {
-    const global_idx = start_idx + pt_idx
-    const qpoint = bs.qpoints[global_idx]
-    return {
-      band_idx,
-      spin,
-      is_acoustic,
-      nb_bands: bs.nb_bands,
-      frac_coords: qpoint?.frac_coords ?? null,
-      qpoint_label: qpoint?.label ?? null,
-      band_width: bs.band_widths?.[band_idx]?.[global_idx] ?? null,
-      slope: compute_slope(x_vals, y_vals, pt_idx),
-    }
-  })
-}