matterviz 0.3.6 → 0.3.7

package/dist/spectral/helpers.js

@@ -0,0 +1,1032 @@
+// Helper utilities for band structure and DOS data processing
+import { SUBSCRIPT_MAP } from '../labels';
+import { centered_frac, euclidean_dist } from '../math';
+const is_subscript_key = (key) => 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) => 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, b, tol = 0.001) => {
+    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, range, label) => ({
+    ...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, dos_range, shared_range, current_synced, dos_enabled = true) {
+    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) {
+    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) => (is_subscript_key(digit) ? SUBSCRIPT_MAP[digit] : digit))
+            .join(``));
+}
+// Create segment key from start and end labels
+export const get_segment_key = (start_label, end_label) => `${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, segments) => {
+    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, x_start, x_end) {
+    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, label) {
+    const defaults = { opacity: 0.3, max_width: 6, scale: 1 };
+    const config_record = ribbon_config;
+    // 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, branches = []) {
+    const ticks_x_pos = [];
+    const tick_labels = [];
+    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, unit = `THz`) {
+    const conversion_factors = {
+        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, freqs_or_energies, mode) {
+    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();
+// FNV-1a hash for number arrays (fast, good distribution, O(n))
+function fnv1a_hash(arr) {
+    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, densities, sigma) {
+    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, densities, sigma) {
+    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, densities, sigma) {
+    // 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() {
+    smearing_cache.clear();
+}
+// Type guards for pymatgen qpoint formats
+const is_vec3 = (val) => Array.isArray(val) && val.length >= 3 && val.slice(0, 3).every(Number.isFinite);
+const is_kpoint = (val) => !!val && typeof val === `object` && `frac_coords` in val && is_vec3(val.frac_coords);
+const is_pymatgen_format = (obj) => {
+    // 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, labels_dict) => {
+    const frac_coords = is_vec3(qpt)
+        ? [qpt[0], qpt[1], qpt[2]]
+        : 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(data) {
+    if (Array.isArray(data))
+        return { up: data, down: null };
+    if (data && typeof data === `object`) {
+        const record = data;
+        let spin_up = null;
+        let spin_down = 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) {
+    // Support both qpoints (phonon) and kpoints (electronic)
+    const raw_qpts = (pmg.qpoints ?? pmg.kpoints);
+    // 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(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;
+        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;
+    const lattice_rec = pmg.lattice_rec;
+    // Determine unit: cm-1 if frequencies_cm present, else check explicit unit or default to THz
+    const unit = pmg.unit?.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 !== 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;
+    let branches = [];
+    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) => {
+        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) {
+    if (!bs || typeof bs !== `object`)
+        return null;
+    const band_struct = bs;
+    // 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;
+    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;
+}
+// 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, options = {}) {
+    const { auto_convert_units = true } = options;
+    if (!dos || typeof dos !== `object`)
+        return null;
+    const dos_obj = dos;
+    // 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(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 ?? 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);
+        let final_frequencies = frequencies;
+        if (auto_convert_units && max_freq > 100) {
+            // Likely in cm⁻¹, convert to THz
+            final_frequencies = frequencies.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 ??
+            (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, recip_lattice_matrix, options = {}) {
+    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) => {
+        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, target) {
+    const { distance } = band_struct;
+    if (!distance?.length)
+        return null;
+    return distance.reduce((closest, dist, idx) => 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, rescaled_x, x_positions) {
+    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],
+        ]) {
+            const dist = Math.abs(rescaled_x - x_pos);
+            if (dist < min_dist) {
+                min_dist = dist;
+                closest_idx = idx;
+            }
+        }
+    }
+    return closest_idx;
+}
+// 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, pdos_type, filter_keys) {
+    if (!dos || typeof dos !== `object`)
+        return null;
+    const dos_obj = dos;
+    // Get the appropriate projected DOS dict
+    const pdos_dict = pdos_type === `atom`
+        ? dos_obj.atom_dos
+        : dos_obj.spd_dos;
+    if (!pdos_dict || typeof pdos_dict !== `object`)
+        return null;
+    const result = {};
+    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(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 = (dos, shift) => ({
+    ...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) {
+    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, y_values, width_values, x_scale_fn, y_scale_fn, max_width_px, scale = 1) {
+    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 = [];
+    const lower_points = [];
+    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) {
+    if (!data || typeof data !== `object`)
+        return undefined;
+    const obj = data;
+    // 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.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) {
+    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) {
+    if (!bs || typeof bs !== `object`)
+        return false;
+    const obj = bs;
+    // 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, doses, padding_factor = 0.02) {
+    let [min_val, max_val, is_phonon] = [Infinity, -Infinity, false];
+    const all_freqs = [];
+    // 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).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
+            ? [normalize_dos(doses)]
+            : Object.values(doses).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) {
+    const match = /^(.+?)\s*\(([^)]+)\)$/.exec(label);
+    return match ? { name: match[1], unit: match[2] } : { name: label };
+}
+const format_tooltip_line = (name, value, unit) => `${name}: ${value}${unit ? ` ${unit}` : ``}`;
+// Format DOS tooltip content from axis labels and values
+export function format_dos_tooltip(x_formatted, y_formatted, label, is_horizontal, is_phonon, units, x_axis_label, y_axis_label, num_series) {
+    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` },
+];
+// 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` },
+];
+// Available frequency units for phonon DOS
+export const FREQUENCY_UNITS = [`THz`, `eV`, `meV`, `cm-1`, `Ha`];
+// Default values for DOS controls
+export const DEFAULT_SPIN_MODE = `mirror`;
+export const DEFAULT_SIGMA = 0;
+export const DEFAULT_NORMALIZE = null;
+export const DEFAULT_UNITS = `THz`;
+// Format sigma with adaptive precision: 0→"0", <0.01→exp, <1→3dp, else→2dp
+export function format_sigma(val) {
+    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.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) {
+    const [min, max] = validate_sigma_range(range);
+    return (max - min) / 100 || 0.01;
+}
+// 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, y_vals, idx) {
+    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) {
+    const indices = [];
+    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, band_idx, gamma_indices, threshold = ACOUSTIC_FREQ_THRESHOLD) {
+    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) {
+    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),
+        };
+    });
+}