matterviz 0.1.12 → 0.1.13

package/dist/bands/Dos.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">import { plot_colors } from '../colors';
+import ScatterPlot from '../plot/ScatterPlot.svelte';
+import { apply_gaussian_smearing, convert_frequencies, normalize_densities, normalize_dos, } from './helpers';
+let { doses, stack = false, sigma = 0, units = `THz`, normalize = null, orientation = `vertical`, show_legend = true, x_axis = {}, y_axis = {}, ...rest } = $props();
+// Normalize input to dict format
+let doses_dict = $derived.by(() => {
+    if (!doses)
+        return {};
+    if (`densities` in doses && (`frequencies` in doses || `energies` in doses)) {
+        // Single DOS
+        const normalized = normalize_dos(doses);
+        return normalized ? { '': normalized } : {};
+    }
+    // Already a dict - normalize each DOS
+    const result = {};
+    for (const [key, dos] of Object.entries(doses)) {
+        const normalized = normalize_dos(dos);
+        if (normalized)
+            result[key] = normalized;
+    }
+    return result;
+});
+// Determine if this is phonon or electronic DOS using discriminated union
+let is_phonon = $derived.by(() => {
+    const first_dos = Object.values(doses_dict)[0];
+    return first_dos?.type === `phonon`;
+});
+// Convert DOS data to scatter plot series
+// Performance: Only recalculates when doses_dict, units, sigma, or normalize changes
+let series_data = $derived.by(() => {
+    if (Object.keys(doses_dict).length === 0)
+        return []; // Early return for empty data
+    const all_series = [];
+    const dos_entries = Object.entries(doses_dict);
+    let cumulative_densities = null;
+    for (let dos_idx = 0; dos_idx < dos_entries.length; dos_idx++) {
+        const [label, dos] = dos_entries[dos_idx];
+        const color = plot_colors[dos_idx % plot_colors.length];
+        // Get frequencies or energies using discriminated union type narrowing
+        let x_values = dos.type === `phonon` ? dos.frequencies : dos.energies;
+        // Convert units if needed
+        if (dos.type === `phonon` && units !== `THz`) {
+            x_values = convert_frequencies(x_values, units);
+        }
+        // Apply Gaussian smearing if requested (expensive for large datasets)
+        let densities = sigma > 0
+            ? apply_gaussian_smearing(x_values, dos.densities, sigma)
+            : [...dos.densities];
+        // Normalize densities
+        densities = normalize_densities(densities, x_values, normalize);
+        // For stacked plots, accumulate densities
+        if (stack && cumulative_densities) {
+            if (cumulative_densities.length !== densities.length) {
+                console.warn(`DOS stacking: length mismatch (cumulative=${cumulative_densities.length}, current=${densities.length})`);
+            }
+            densities = densities.map((d, idx) => d + (cumulative_densities?.[idx] ?? 0));
+        }
+        // Store cumulative for next iteration if stacking
+        if (stack)
+            cumulative_densities = densities;
+        // Determine x and y based on orientation
+        const series = orientation === `horizontal`
+            ? {
+                x: densities,
+                y: x_values,
+                markers: `line`,
+                label: label || `DOS ${dos_idx + 1}`,
+                line_style: {
+                    stroke: color,
+                    stroke_width: 1.5,
+                },
+                point_style: {
+                    fill: stack ? color : undefined,
+                },
+            }
+            : {
+                x: x_values,
+                y: densities,
+                markers: `line`,
+                label: label || `DOS ${dos_idx + 1}`,
+                line_style: {
+                    stroke: color,
+                    stroke_width: 1.5,
+                },
+                point_style: {
+                    fill: stack ? color : undefined,
+                },
+            };
+        all_series.push(series);
+    }
+    return all_series;
+});
+// Calculate axis ranges
+let x_range = $derived.by(() => {
+    if (!series_data.length)
+        return undefined;
+    const all_x = series_data.flatMap((s) => s.x);
+    return [Math.min(...all_x), Math.max(...all_x)];
+});
+let y_range = $derived.by(() => {
+    if (!series_data.length)
+        return undefined;
+    const all_y = series_data.flatMap((s) => s.y);
+    return [Math.min(...all_y), Math.max(...all_y)];
+});
+// Get axis labels based on orientation
+let x_label = $derived(orientation === `horizontal`
+    ? `Density of States`
+    : is_phonon
+        ? `Frequency (${units})`
+        : `Energy (eV)`);
+let y_label = $derived(orientation === `horizontal`
+    ? is_phonon ? `Frequency (${units})` : `Energy (eV)`
+    : `Density of States`);
+</script>
+
+<ScatterPlot
+  series={series_data}
+  x_axis={{ label: x_label, format: `.2f`, range: x_range, ...x_axis }}
+  y_axis={{ label: y_label, format: `.2f`, range: y_range, ...y_axis }}
+  display={{ x_grid: true, y_grid: true, x_zero_line: true, y_zero_line: true }}
+  legend={show_legend ? {} : null}
+  {...rest}
+/>

package/dist/bands/Dos.svelte.d.ts

@@ -0,0 +1,18 @@
+import ScatterPlot from '../plot/ScatterPlot.svelte';
+import type { AxisConfig } from '../plot/types';
+import type { ComponentProps } from 'svelte';
+import type { Dos, FrequencyUnit, NormalizationMode } from './types';
+type $$ComponentProps = ComponentProps<typeof ScatterPlot> & {
+    doses: Dos | Record<string, Dos>;
+    x_axis?: AxisConfig;
+    y_axis?: AxisConfig;
+    stack?: boolean;
+    sigma?: number;
+    units?: FrequencyUnit;
+    normalize?: NormalizationMode;
+    orientation?: `vertical` | `horizontal`;
+    show_legend?: boolean;
+};
+declare const Dos: import("svelte").Component<$$ComponentProps, {}, "">;
+type Dos = ReturnType<typeof Dos>;
+export default Dos;

package/dist/bands/helpers.d.ts

@@ -0,0 +1,11 @@
+import type { BaseBandStructure, Dos, FrequencyUnit, NormalizationMode } from './types';
+export declare const N_ACOUSTIC_MODES = 3;
+export declare function pretty_sym_point(symbol: string): string;
+export declare const get_segment_key: (start_label?: string, end_label?: string) => string;
+export declare const get_ordered_segments: (band_struct: BaseBandStructure | null, segments: Set<string>) => string[];
+export declare function get_band_xaxis_ticks(band_struct: BaseBandStructure, branches?: string[] | Set<string>): [number[], string[]];
+export declare function convert_frequencies(frequencies: number[], unit?: FrequencyUnit): number[];
+export declare function normalize_densities(densities: number[], freqs_or_energies: number[], mode: NormalizationMode): number[];
+export declare function apply_gaussian_smearing(freqs_or_energies: number[], densities: number[], sigma: number): number[];
+export declare function normalize_band_structure(bs: unknown): BaseBandStructure | null;
+export declare function normalize_dos(dos: unknown): Dos | null;

package/dist/bands/helpers.js

@@ -0,0 +1,195 @@
+// Helper utilities for band structure and DOS data processing
+import { subscript_map } from '../labels';
+// 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
+// Band structure constants
+export const N_ACOUSTIC_MODES = 3; // Number of acoustic modes in typical 3D crystals
+// Convert symmetry point symbols to pretty-printed versions.
+// Handles Greek letters 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 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) => 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((br) => get_segment_key(band_struct.qpoints[br.start_index]?.label ?? undefined, band_struct.qpoints[br.end_index]?.label ?? undefined));
+    const remaining = Array.from(segments).filter((seg) => !ordered.includes(seg));
+    return [...ordered, ...remaining];
+};
+// 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((b) => b.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((f) => f * 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((d) => d / max_val);
+    }
+    else if (mode === `sum`) {
+        const sum = normalized.reduce((acc, d) => acc + d, 0);
+        if (sum === 0)
+            return normalized;
+        return normalized.map((d) => d / 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((d) => d / (sum * bin_width));
+    }
+    return normalized;
+}
+// Apply Gaussian smearing to DOS densities.
+// Uses truncated Gaussian (±4σ) for O(n·w) complexity instead of O(n²).
+export function apply_gaussian_smearing(freqs_or_energies, densities, sigma) {
+    const original_sum = densities.reduce((acc, d) => acc + d, 0);
+    if (sigma <= 0 || original_sum === 0)
+        return densities;
+    const smeared = new 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 = original_sum / smeared_sum;
+    return smeared.map((d) => d * normalization);
+}
+export function normalize_band_structure(bs) {
+    if (!bs || typeof bs !== `object`)
+        return null;
+    const band_struct = bs;
+    // Check required fields exist and are arrays
+    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((br) => typeof br.start_index !== `number` ||
+            typeof br.end_index !== `number` ||
+            br.start_index < 0 ||
+            br.end_index >= n_qpts ||
+            br.start_index > br.end_index))
+        return null;
+    return band_struct;
+}
+// Validate and normalize a DOS object.
+export function normalize_dos(dos) {
+    if (!dos || typeof dos !== `object`)
+        return null;
+    const { densities, frequencies, energies, spin_polarized } = dos;
+    if (!Array.isArray(densities))
+        return null;
+    // Phonon DOS: has frequencies
+    if (Array.isArray(frequencies)) {
+        if (frequencies.length !== densities.length)
+            return null;
+        return { type: `phonon`, frequencies, densities };
+    }
+    // Electronic DOS: has energies
+    if (Array.isArray(energies)) {
+        if (energies.length !== densities.length)
+            return null;
+        return {
+            type: `electronic`,
+            energies,
+            densities,
+            spin_polarized: spin_polarized,
+        };
+    }
+    return null;
+}

package/dist/bands/index.d.ts

@@ -0,0 +1,5 @@
+export { default as Bands } from './Bands.svelte';
+export { default as Dos } from './Dos.svelte';
+export { default as BandsAndDos } from './BandsAndDos.svelte';
+export * from './types';
+export * from './helpers';

package/dist/bands/index.js

@@ -0,0 +1,6 @@
+// Band structure and density of states visualization components
+export { default as Bands } from './Bands.svelte';
+export { default as Dos } from './Dos.svelte';
+export { default as BandsAndDos } from './BandsAndDos.svelte';
+export * from './types';
+export * from './helpers';

package/dist/bands/types.d.ts

@@ -0,0 +1,54 @@
+export type BandStructureType = `phonon` | `electronic`;
+export type PathMode = `union` | `intersection` | `strict`;
+export type FrequencyUnit = `THz` | `eV` | `meV` | `Ha` | `cm-1`;
+export type NormalizationMode = `max` | `sum` | `integral` | null;
+export interface QPoint {
+    label: string | null;
+    frac_coords: [number, number, number];
+    distance?: number;
+}
+export interface Branch {
+    start_index: number;
+    end_index: number;
+    name: string;
+}
+export interface BaseBandStructure {
+    lattice_rec: {
+        matrix: number[][];
+    };
+    qpoints: QPoint[];
+    branches: Branch[];
+    labels_dict: Record<string, [number, number, number]>;
+    distance: number[];
+    nb_bands: number;
+    bands: number[][];
+}
+export interface PhononBandStructure extends BaseBandStructure {
+    has_imaginary_modes?: boolean;
+    has_nac?: boolean;
+}
+export interface ElectronicBandStructure extends BaseBandStructure {
+    is_spin_polarized: boolean;
+    efermi?: number;
+    is_metal?: boolean;
+    band_gap?: {
+        energy: number;
+        direct: boolean;
+    };
+}
+export interface PhononDos {
+    type: `phonon`;
+    frequencies: number[];
+    densities: number[];
+}
+export interface ElectronicDos {
+    type: `electronic`;
+    energies: number[];
+    densities: number[];
+    spin_polarized?: boolean;
+}
+export type Dos = PhononDos | ElectronicDos;
+export type LineKwargs = Record<string, unknown> | {
+    acoustic?: Record<string, unknown>;
+    optical?: Record<string, unknown>;
+} | ((frequencies: number[], band_idx: number) => Record<string, unknown>);

package/dist/bands/types.js

@@ -0,0 +1,2 @@
+// TypeScript type definitions for band structures and density of states
+export {};