matterviz 0.4.0 → 0.4.2

package/dist/spectral/helpers.js

@@ -1,6 +1,7 @@
 // Helper utilities for band structure and DOS data processing
 import { SUBSCRIPT_MAP } from '../labels';
-import { euclidean_dist } from '../math';
+import { is_plain_object } from '../utils';
+import { euclidean_dist, is_square_matrix } 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) &&
@@ -91,7 +92,7 @@ export function pretty_sym_point(symbol) {
         .replaceAll(/\\?DELTA/gi, `Δ`)
         .replaceAll(/\\?SIGMA/gi, `Σ`)
         .replaceAll(/\\?LAMBDA/gi, `Λ`)
-        .replaceAll(/(\p{L})(\d+)/gu, (_, letter, num) => letter +
+        .replaceAll(/(?<letter>\p{L})(?<num>\d+)/gu, (_, letter, num) => letter +
         num
             .split(``)
             .map((digit) => (is_subscript_key(digit) ? SUBSCRIPT_MAP[digit] : digit))
@@ -194,33 +195,24 @@ export function convert_frequencies(frequencies, unit = `THz`) {
 }
 // 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);
+        const max_val = Math.max(...densities);
+        return max_val === 0 ? densities : densities.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);
+    if (mode === `sum`) {
+        const sum = densities.reduce((acc, dens) => acc + dens, 0);
+        return sum === 0 ? densities : densities.map((dens) => dens / sum);
     }
-    else if (mode === `integral`) {
+    if (mode === `integral`) {
         if (freqs_or_energies.length < 2)
-            return normalized;
+            return densities;
         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));
+        const sum = densities.reduce((acc, dens) => acc + dens, 0);
+        if (bin_width === 0 || sum === 0)
+            return densities;
+        return densities.map((dens) => dens / (sum * bin_width));
     }
-    return normalized;
+    return densities;
 }
 // Simple LRU cache for Gaussian smearing results
 // Key: hash of (frequencies, densities, sigma), Value: smeared densities
@@ -250,26 +242,24 @@ function generate_smearing_cache_key(freqs_or_energies, densities, sigma) {
 }
 // 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);
+    const orig_sum = densities.reduce((acc, dens) => acc + dens, 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%)
+    const cutoff = 4 * sigma; // Truncate Gaussian at ±4σ (contribution < 0.01%)
+    const inv_two_sigma_sq = 1 / (2 * sigma ** 2);
     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);
+            const delta = energy - freqs_or_energies[jdx];
             // Skip points beyond truncation width
-            if (delta > cutoff)
+            if (Math.abs(delta) > cutoff)
                 continue;
-            const gaussian = Math.exp(-((energy - e_j) ** 2) / (2 * sigma ** 2));
-            smeared[idx] += densities[jdx] * gaussian;
+            smeared[idx] += densities[jdx] * Math.exp(-(delta ** 2) * inv_two_sigma_sq);
         }
     }
     // Normalize to preserve integral
-    const smeared_sum = smeared.reduce((acc, d) => acc + d, 0);
+    const smeared_sum = smeared.reduce((acc, dens) => acc + dens, 0);
     if (smeared_sum === 0)
         return densities;
     const normalization = orig_sum / smeared_sum;
@@ -491,10 +481,9 @@ function convert_pymatgen_band_structure(pmg) {
         },
     };
 }
-export function normalize_band_structure(bs) {
-    if (!bs || typeof bs !== `object`)
+export function normalize_band_structure(band_struct) {
+    if (!is_plain_object(band_struct))
         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);
@@ -516,27 +505,42 @@ export function normalize_band_structure(bs) {
             branch.end_index >= n_qpts ||
             branch.start_index > branch.end_index))
         return null;
-    return band_struct;
+    // Fill required defaults (recip_lattice/labels_dict/nb_bands) not covered above so the cast below is sound
+    const recip_lattice = band_struct.recip_lattice;
+    const normalized = {
+        ...band_struct,
+        nb_bands: typeof band_struct.nb_bands === `number` ? band_struct.nb_bands : bands.length,
+        labels_dict: band_struct.labels_dict ?? {},
+        recip_lattice: is_square_matrix(recip_lattice?.matrix, 3)
+            ? recip_lattice
+            : {
+                matrix: [
+                    [1, 0, 0],
+                    [0, 1, 0],
+                    [0, 0, 1],
+                ],
+            },
+    };
+    return normalized;
 }
 // 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`)
+    if (!is_plain_object(dos))
         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;
+    const is_pymatgen = typeof dos[`@class`] === `string` || typeof dos[`@module`] === `string`;
+    const { frequencies, energies, spin_polarized } = dos;
     // 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);
+    const spin_channels = extract_spin_channels(dos.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;
+    const spin_down_densities = spin_channels.down ?? dos.spin_down_densities ?? null;
     if (!Array.isArray(densities))
         return null;
     // Phonon DOS: has frequencies
@@ -743,13 +747,12 @@ export function find_qpoint_at_rescaled_x(band_struct, rescaled_x, x_positions)
 // 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`)
+    if (!is_plain_object(dos))
         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;
+        ? dos.atom_dos
+        : dos.spd_dos;
     if (!pdos_dict || typeof pdos_dict !== `object`)
         return null;
     const result = {};
@@ -852,21 +855,15 @@ export function generate_ribbon_path(x_values, y_values, width_values, x_scale_f
 // 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`)
+    if (!is_plain_object(data))
         return undefined;
-    const obj = data;
     // Direct efermi field on the object
-    if (`efermi` in obj && typeof obj.efermi === `number`)
-        return obj.efermi;
+    if (typeof data.efermi === `number`)
+        return data.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;
+    const first_val = Object.values(data)[0];
+    if (is_plain_object(first_val) && typeof first_val.efermi === `number`) {
+        return first_val.efermi;
     }
     return undefined;
 }
@@ -886,18 +883,16 @@ export function negative_fraction(values) {
 // 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`)
+    if (!is_plain_object(bs))
         return false;
-    const obj = bs;
     // Electronic band structures have efermi field
-    if (`efermi` in obj && typeof obj.efermi === `number`)
+    if (typeof bs.efermi === `number`)
         return true;
     // Pymatgen electronic format uses kpoints (not qpoints)
-    if (`kpoints` in obj && Array.isArray(obj.kpoints) && obj.kpoints.length > 0) {
+    if (Array.isArray(bs.kpoints) && bs.kpoints.length > 0)
         return true;
-    }
     // Pymatgen @class: BandStructure* but not Phonon*
-    const raw_class = obj[`@class`];
+    const raw_class = bs[`@class`];
     const py_class_name = typeof raw_class === `string` ? raw_class : ``;
     if (py_class_name.startsWith(`BandStructure`) && !py_class_name.includes(`Phonon`)) {
         return true;
@@ -952,7 +947,7 @@ export function compute_frequency_range(band_structs, doses, padding_factor = 0.
             }
         }
     }
-    const dos_list = doses
+    const dos_list = doses && typeof doses === `object`
         ? `densities` in doses
             ? [normalize_dos(doses)]
             : Object.values(doses).map((dos) => normalize_dos(dos))
@@ -975,18 +970,19 @@ export function compute_frequency_range(band_structs, doses, padding_factor = 0.
     }
     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)
+    // clamp phonon noise to 0
+    if (is_phonon &&
+        min_val < 0 &&
+        negative_fraction(all_freqs) < IMAGINARY_MODE_NOISE_THRESHOLD) {
         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);
+    const match = /^(?<name>.+?)\s*\((?<unit>[^)]+)\)$/.exec(label);
     return match ? { name: match[1], unit: match[2] } : { name: label };
 }
 const format_tooltip_line = (name, value, unit) => `${name}: ${value}${unit ? ` ${unit}` : ``}`;

package/dist/state.svelte.d.ts

@@ -1,6 +1,5 @@
 import type { ChemicalElement, ElementCategory } from './element/types';
 import { DEFAULT_CATEGORY_COLORS, default_element_colors } from './colors';
-import type { Tooltip } from './plot';
 import { type ThemeMode, type ThemeType } from './theme';
 export declare const selected: {
     category: ElementCategory | null;
@@ -12,12 +11,6 @@ export declare const colors: {
     category: typeof DEFAULT_CATEGORY_COLORS;
     element: typeof default_element_colors;
 };
-export declare const tooltip: Tooltip;
-export declare const periodic_table_state: {
-    show_bonding_info: boolean;
-    show_oxidation_state: boolean;
-    highlighted_elements: string[];
-};
 export declare const theme_state: {
     mode: ThemeMode;
     system_mode: ThemeType;

package/dist/state.svelte.js

@@ -1,6 +1,6 @@
 import { AUTO_THEME, COLOR_THEMES, THEME_TYPE } from './theme/index';
 import { DEFAULT_CATEGORY_COLORS, default_element_colors } from './colors';
-import { is_valid_theme_mode } from './theme';
+import { get_theme_preference } from './theme';
 export const selected = $state({
     category: null,
     element: null,
@@ -11,29 +11,10 @@ export const colors = $state({
     category: { ...DEFAULT_CATEGORY_COLORS },
     element: { ...default_element_colors },
 });
-export const tooltip = $state({ show: false, x: 0, y: 0, title: ``, items: [] });
-export const periodic_table_state = $state({
-    show_bonding_info: false,
-    show_oxidation_state: false,
-    highlighted_elements: [],
-});
-// Theme state with safe initialization
-let initial_theme_mode = AUTO_THEME;
-let initial_system_mode = COLOR_THEMES.light;
-// Safe theme initialization for test environments
-try {
-    if (typeof window !== `undefined` && globalThis.localStorage) {
-        const saved_theme = localStorage.getItem(`matterviz-theme`) ?? ``;
-        initial_theme_mode = is_valid_theme_mode(saved_theme) ? saved_theme : AUTO_THEME;
-    }
-    else {
-        initial_theme_mode = AUTO_THEME;
-        initial_system_mode = COLOR_THEMES.light;
-    }
-}
-catch {
-    // Fallback for test environments or when localStorage is not available
-}
+// Theme state with safe initialization (get_theme_preference handles SSR +
+// missing/invalid localStorage, falling back to AUTO_THEME)
+const initial_theme_mode = get_theme_preference();
+const initial_system_mode = COLOR_THEMES.light;
 export const theme_state = $state({
     mode: initial_theme_mode,
     system_mode: initial_system_mode,

package/dist/structure/Arrow.svelte

@@ -4,7 +4,7 @@
   import { DEFAULTS } from '../settings'
   import { T } from '@threlte/core'
   import type { ComponentProps } from 'svelte'
-  import { Euler, Quaternion, Vector3 } from 'three'
+  import { rotation_from_direction } from './geometry'
 
   let {
     position,
@@ -26,37 +26,22 @@
   } = $props()
 
   const mag = $derived(Math.hypot(...vector))
-  const dir = $derived(
-    mag > math.EPS ? math.scale(vector, 1 / mag) : ([0, 1, 0] as Vec3),
-  )
+  const dir = $derived(mag > math.EPS ? math.scale(vector, 1 / mag) : ([0, 1, 0] as Vec3))
   const vec_len = $derived(mag * scale)
 
   const head_len = $derived(
     arrow_head_length < 0 ? vec_len * -arrow_head_length : arrow_head_length,
   )
   const shaft_len = $derived(Math.max(0, vec_len - head_len * 0.5))
-  const shaft_r = $derived(
-    shaft_radius < 0 ? shaft_len * -shaft_radius : shaft_radius,
-  )
+  const shaft_r = $derived(shaft_radius < 0 ? shaft_len * -shaft_radius : shaft_radius)
   const head_r = $derived(
     arrow_head_radius < 0 ? shaft_len * -arrow_head_radius : arrow_head_radius,
   )
 
-  const shaft_pos = $derived(
-    math.add(position, math.scale(dir, shaft_len * 0.5)) as Vec3,
-  )
-  const head_pos = $derived(
-    math.add(position, math.scale(dir, shaft_len + head_len * 0.5)) as Vec3,
-  )
+  const shaft_pos = $derived(math.add(position, math.scale(dir, shaft_len * 0.5)))
+  const head_pos = $derived(math.add(position, math.scale(dir, shaft_len + head_len * 0.5)))
 
-  const rotation = $derived.by((): Vec3 => {
-    if (mag < math.EPS) return [0, 0, 0]
-    const quat = new Quaternion().setFromUnitVectors(
-      new Vector3(0, 1, 0),
-      new Vector3(...dir),
-    )
-    return new Euler().setFromQuaternion(quat).toArray().slice(0, 3) as Vec3
-  })
+  const rotation = $derived(rotation_from_direction(vector))
 </script>
 
 {#if shaft_len > 0.01}

package/dist/structure/ArrowInstances.svelte

@@ -0,0 +1,160 @@
+<script lang="ts">
+  // Instanced arrows (shaft cylinders + head cones) for per-site vector layers
+  // (forces, magnetic moments, ...). Replaces one <Arrow> component per site
+  // (2 meshes + 2 geometries + 2 materials each) with 2 draw calls per layer.
+  // Sizing math mirrors Arrow.svelte so the two render identically.
+  import type { Vec3 } from '../math'
+  import { EPS } from '../math'
+  import { T, useThrelte } from '@threlte/core'
+  import { untrack } from 'svelte'
+  import type { BufferGeometry } from 'three'
+  import {
+    Color,
+    ConeGeometry,
+    CylinderGeometry,
+    InstancedMesh,
+    Matrix4,
+    MeshStandardMaterial,
+    Quaternion,
+    Vector3,
+  } from 'three'
+
+  type ArrowInstance = {
+    position: Vec3
+    vector: Vec3
+    scale: number
+    color: string
+  }
+
+  let {
+    arrows,
+    shaft_radius,
+    arrow_head_radius,
+    arrow_head_length,
+  }: {
+    arrows: ArrowInstance[]
+    shaft_radius: number // negative = relative to shaft length
+    arrow_head_radius: number // negative = relative to shaft length
+    arrow_head_length: number // negative = relative to arrow length
+  } = $props()
+
+  const { invalidate } = useThrelte()
+
+  // Unit primitives scaled per instance: cylinder radius/length via (x=r, y=len, z=r)
+  const shaft_geometry = new CylinderGeometry(1, 1, 1, 12)
+  const head_geometry = new ConeGeometry(1, 1, 12)
+  const shaft_material = new MeshStandardMaterial()
+  const head_material = new MeshStandardMaterial()
+  $effect(() => () => {
+    shaft_geometry.dispose()
+    head_geometry.dispose()
+    shaft_material.dispose()
+    head_material.dispose()
+  })
+
+  const make_mesh = (
+    geometry: BufferGeometry,
+    material: MeshStandardMaterial,
+    count: number,
+  ): InstancedMesh => {
+    const mesh = new InstancedMesh(geometry, material, count)
+    mesh.frustumCulled = false
+    mesh.raycast = () => undefined // arrows are display-only
+    mesh.userData.per_instance_color = true
+    return mesh
+  }
+
+  // Recreate meshes only when the arrow count changes (fixed buffer capacity)
+  let shaft_mesh = $state.raw<InstancedMesh | null>(null)
+  let head_mesh = $state.raw<InstancedMesh | null>(null)
+  $effect(() => {
+    const count = arrows.length
+    const prev = untrack(() => shaft_mesh)
+    if (prev && prev.count === count) return
+    prev?.dispose()
+    untrack(() => head_mesh)?.dispose()
+    if (count === 0) {
+      shaft_mesh = null
+      head_mesh = null
+      return
+    }
+    shaft_mesh = make_mesh(shaft_geometry, shaft_material, count)
+    head_mesh = make_mesh(head_geometry, head_material, count)
+  })
+  // Unmount-only cleanup (a cleanup on the effect above would dispose meshes
+  // on every re-run, including runs that keep them; cleanups run untracked)
+  $effect(() => () => {
+    shaft_mesh?.dispose()
+    head_mesh?.dispose()
+  })
+
+  const up_axis = new Vector3(0, 1, 0)
+  const scratch_dir = new Vector3()
+  const scratch_quat = new Quaternion()
+  const scratch_pos = new Vector3()
+  const scratch_scale = new Vector3()
+  const scratch_matrix = new Matrix4()
+  const scratch_color = new Color()
+
+  $effect(() => {
+    const shafts = shaft_mesh
+    const heads = head_mesh
+    if (!shafts || !heads) return
+    const limit = Math.min(arrows.length, shafts.count)
+    for (let idx = 0; idx < limit; idx++) {
+      const { position, vector, scale, color } = arrows[idx]
+      const mag = Math.hypot(vector[0], vector[1], vector[2])
+      if (mag > EPS) {
+        scratch_dir.set(vector[0] / mag, vector[1] / mag, vector[2] / mag)
+        scratch_quat.setFromUnitVectors(up_axis, scratch_dir)
+      } else {
+        scratch_dir.set(0, 1, 0)
+        scratch_quat.identity()
+      }
+      const vec_len = mag * scale
+      const head_len = arrow_head_length < 0 ? vec_len * -arrow_head_length : arrow_head_length
+      const shaft_len = Math.max(0, vec_len - head_len * 0.5)
+      const shaft_r = shaft_radius < 0 ? shaft_len * -shaft_radius : shaft_radius
+      const head_r = arrow_head_radius < 0 ? shaft_len * -arrow_head_radius : arrow_head_radius
+
+      // Shafts shorter than Arrow.svelte's 0.01 render threshold collapse to zero scale
+      const draw_shaft = shaft_len > 0.01
+      scratch_pos.set(
+        position[0] + scratch_dir.x * shaft_len * 0.5,
+        position[1] + scratch_dir.y * shaft_len * 0.5,
+        position[2] + scratch_dir.z * shaft_len * 0.5,
+      )
+      scratch_scale.set(
+        draw_shaft ? shaft_r : 0,
+        draw_shaft ? shaft_len : 0,
+        draw_shaft ? shaft_r : 0,
+      )
+      shafts.setMatrixAt(idx, scratch_matrix.compose(scratch_pos, scratch_quat, scratch_scale))
+
+      const head_offset = shaft_len + head_len * 0.5
+      scratch_pos.set(
+        position[0] + scratch_dir.x * head_offset,
+        position[1] + scratch_dir.y * head_offset,
+        position[2] + scratch_dir.z * head_offset,
+      )
+      scratch_scale.set(head_r, head_len, head_r)
+      heads.setMatrixAt(idx, scratch_matrix.compose(scratch_pos, scratch_quat, scratch_scale))
+
+      scratch_color.set(color)
+      shafts.setColorAt(idx, scratch_color)
+      heads.setColorAt(idx, scratch_color)
+    }
+    for (const mesh of [shafts, heads]) {
+      mesh.instanceMatrix.needsUpdate = true
+      if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true
+    }
+    invalidate()
+  })
+</script>
+
+{#if shaft_mesh}
+  <T is={shaft_mesh} />
+{/if}
+{#if head_mesh}
+  <T is={head_mesh} />
+{/if}

package/dist/structure/ArrowInstances.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Vec3 } from '../math';
+type ArrowInstance = {
+    position: Vec3;
+    vector: Vec3;
+    scale: number;
+    color: string;
+};
+type $$ComponentProps = {
+    arrows: ArrowInstance[];
+    shaft_radius: number;
+    arrow_head_radius: number;
+    arrow_head_length: number;
+};
+declare const ArrowInstances: import("svelte").Component<$$ComponentProps, {}, "">;
+type ArrowInstances = ReturnType<typeof ArrowInstances>;
+export default ArrowInstances;