matterviz 0.4.0 → 0.4.1

package/dist/fermi-surface/parse.js

@@ -1,5 +1,7 @@
+import * as math from '../math';
+import { is_plain_object } from '../utils';
 import * as constants from './constants';
-import { compute_vertex_normals } from './marching-cubes';
+import { compute_vertex_normals } from '../marching-cubes';
 const parse_number_tokens = (line) => line.split(/\s+/).filter(Boolean);
 // Parse whitespace-separated floats from a line (optimized with unary +)
 const parse_floats = (line) => parse_number_tokens(line).map(Number);
@@ -224,14 +226,9 @@ function parse_frmsf(content) {
 }
 // Validate that an object has the required Isosurface shape
 function is_valid_isosurface(obj) {
-    if (!obj || typeof obj !== `object`)
+    if (!is_plain_object(obj))
         return false;
-    const isosurface_obj = obj;
-    const vertices = isosurface_obj.vertices;
-    const faces = isosurface_obj.faces;
-    const normals = isosurface_obj.normals;
-    const band_index = isosurface_obj.band_index;
-    const spin = isosurface_obj.spin;
+    const { vertices, faces, normals, band_index, spin } = obj;
     if (!Array.isArray(vertices) || vertices.length === 0)
         return false;
     if (!Array.isArray(faces))
@@ -246,27 +243,35 @@ function is_valid_isosurface(obj) {
 }
 // Validate FermiSurfaceData shape
 function is_valid_fermi_surface_data(obj) {
-    if (!obj || typeof obj !== `object`)
+    if (!is_plain_object(obj))
         return false;
-    const data = obj;
     // Check required fields
-    if (!Array.isArray(data.isosurfaces))
+    if (!Array.isArray(obj.isosurfaces))
         return false;
-    if (!Array.isArray(data.k_lattice) || data.k_lattice.length !== 3)
+    if (!math.is_square_matrix(obj.k_lattice, 3))
         return false;
-    if (typeof data.fermi_energy !== `number`)
+    if (typeof obj.fermi_energy !== `number`)
         return false;
-    if (data.reciprocal_cell !== `wigner_seitz` && data.reciprocal_cell !== `parallelepiped`) {
+    if (obj.reciprocal_cell !== `wigner_seitz` && obj.reciprocal_cell !== `parallelepiped`) {
         return false;
     }
-    if (!data.metadata || typeof data.metadata !== `object`)
+    if (!obj.metadata || typeof obj.metadata !== `object`)
         return false;
     // Validate each isosurface
-    for (const iso of data.isosurfaces) {
-        if (!is_valid_isosurface(iso))
-            return false;
-    }
-    return true;
+    return obj.isosurfaces.every(is_valid_isosurface);
+}
+// Validate BandGridData shape: non-empty energies grid, 3 k-grid dims, 3x3 k-lattice
+function is_valid_band_grid_data(obj) {
+    if (!is_plain_object(obj))
+        return false;
+    const { energies, k_grid, k_lattice } = obj;
+    if (!Array.isArray(energies) || energies.length === 0)
+        return false;
+    if (!Array.isArray(k_grid) ||
+        k_grid.length !== 3 ||
+        !k_grid.every((dim) => Number.isInteger(dim) && dim > 0))
+        return false;
+    return math.is_square_matrix(k_lattice, 3);
 }
 // Parse Matterviz/IFermi JSON format for Fermi surface data
 // Throws on invalid input; returns parsed data on success
@@ -287,22 +292,21 @@ function parse_fermi_json(content) {
     }
     // Check if it's BandGridData (raw grid data)
     if (data.energies && data.k_grid && data.k_lattice) {
-        // Minimal validation of required fields
-        if (!Array.isArray(data.energies) ||
-            !Array.isArray(data.k_grid) ||
-            data.k_grid.length !== 3 ||
-            !Array.isArray(data.k_lattice) ||
-            data.k_lattice.length !== 3)
-            throw new Error(`Invalid BandGridData JSON: malformed required fields`);
+        if (!is_valid_band_grid_data(data)) {
+            throw new Error(`Invalid BandGridData JSON: expected non-empty 'energies' grid, 3 'k_grid' dims, and 3x3 'k_lattice'`);
+        }
         return data;
     }
     // Try to extract from nested structure (e.g. IFermi output)
     if (data.fermi_surface) {
+        if (!is_valid_fermi_surface_data(data.fermi_surface)) {
+            throw new Error(`Invalid nested 'fermi_surface' JSON: expected isosurfaces array, 3x3 k_lattice, numeric fermi_energy, reciprocal_cell, and metadata`);
+        }
         return data.fermi_surface;
     }
     if (data.band_structure?.energies || data.bands?.energies) {
         const bs = data.band_structure ?? data.bands;
-        return {
+        const grid_data = {
             energies: bs.energies,
             k_grid: bs.k_grid ?? bs.kgrid,
             k_lattice: bs.k_lattice ?? bs.reciprocal_lattice,
@@ -312,6 +316,10 @@ function parse_fermi_json(content) {
             // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- numeric fallback chain (0 falls through)
             n_spins: (bs.n_spins ?? bs.nspins) || bs.energies.length || 1,
         };
+        if (!is_valid_band_grid_data(grid_data)) {
+            throw new Error(`Invalid band_structure JSON: expected non-empty 'energies' grid, 3 'k_grid' dims, and 3x3 'k_lattice'`);
+        }
+        return grid_data;
     }
     // Check for pymatgen BandStructure format (k-path, not k-grid)
     // These files cannot be used for Fermi surface visualization directly
@@ -387,14 +395,8 @@ function parse_ifermi_surface(data) {
                 for (let fan_idx = 1; fan_idx < face.length - 1; fan_idx++) {
                     const v1 = vertices[face[fan_idx]];
                     const v2 = vertices[face[fan_idx + 1]];
-                    const e1 = [v1[0] - v0[0], v1[1] - v0[1], v1[2] - v0[2]];
-                    const e2 = [v2[0] - v0[0], v2[1] - v0[1], v2[2] - v0[2]];
-                    const cross = [
-                        e1[1] * e2[2] - e1[2] * e2[1],
-                        e1[2] * e2[0] - e1[0] * e2[2],
-                        e1[0] * e2[1] - e1[1] * e2[0],
-                    ];
-                    area += 0.5 * Math.hypot(cross[0], cross[1], cross[2]);
+                    const cross = math.cross_3d(math.subtract(v1, v0), math.subtract(v2, v0));
+                    area += 0.5 * Math.hypot(...cross);
                 }
             }
             isosurfaces.push({
@@ -427,68 +429,55 @@ function parse_ifermi_surface(data) {
         },
     };
 }
-// Auto-detect file format and parse accordingly
+// Auto-detect file format and parse; throws an Error aggregating per-format failure reasons when nothing parses
 export function parse_fermi_file(content, filename) {
     const lower_name = filename?.toLowerCase() ?? ``;
-    // Detect by filename extension
-    if (lower_name.endsWith(`.bxsf`) || lower_name.endsWith(`.bxsf.gz`)) {
+    const errors = [];
+    const attempt = (format, parse) => {
         try {
-            return parse_bxsf(content);
+            return parse();
         }
         catch (error) {
-            console.error(`BXSF parse error:`, error);
+            errors.push(`${format}: ${error instanceof Error ? error.message : String(error)}`);
+            console.error(`${format} parse error:`, error);
             return null;
         }
+    };
+    const fail = () => {
+        const detail = errors.length ? `: ${errors.join(`; `)}` : `: unrecognized format`;
+        throw new Error(`Failed to parse Fermi surface file${filename ? ` '${filename}'` : ``}${detail}`);
+    };
+    // Detect by filename extension (authoritative: parse failure throws immediately)
+    if (lower_name.endsWith(`.bxsf`) || lower_name.endsWith(`.bxsf.gz`)) {
+        return attempt(`BXSF`, () => parse_bxsf(content)) ?? fail();
     }
     if (lower_name.endsWith(`.frmsf`) || lower_name.endsWith(`.frmsf.gz`)) {
-        try {
-            return parse_frmsf(content);
-        }
-        catch (error) {
-            console.error(`FRMSF parse error:`, error);
-            return null;
-        }
+        return attempt(`FRMSF`, () => parse_frmsf(content)) ?? fail();
     }
     if (lower_name.endsWith(`.json`) || lower_name.endsWith(`.json.gz`)) {
-        try {
-            return parse_fermi_json(content);
-        }
-        catch (error) {
-            console.error(`JSON parse error:`, error);
-            return null;
-        }
+        return attempt(`JSON`, () => parse_fermi_json(content)) ?? fail();
     }
     // Try auto-detection based on content
     const trimmed = content.trim();
     // BXSF format detection
     if (trimmed.includes(`BEGIN_BLOCK_BANDGRID_3D`) || trimmed.includes(`BEGIN_BANDGRID_3D`)) {
-        try {
-            return parse_bxsf(content);
-        }
-        catch (error) {
-            console.error(`BXSF auto-detect parse error:`, error);
-        }
+        const result = attempt(`BXSF`, () => parse_bxsf(content));
+        if (result)
+            return result;
     }
     // JSON format detection
     if (trimmed.startsWith(`{`) || trimmed.startsWith(`[`)) {
-        try {
-            return parse_fermi_json(content);
-        }
-        catch (error) {
-            console.error(`JSON auto-detect parse error:`, error);
-        }
+        const result = attempt(`JSON`, () => parse_fermi_json(content));
+        if (result)
+            return result;
     }
     // FRMSF format detection (starts with grid dimensions)
     const first_line = trimmed.split(/\r?\n/)[0];
     const first_tokens = first_line.split(/\s+/).filter(Boolean);
     if (first_tokens.length === 3 && first_tokens.every((token) => /^\d+$/.test(token))) {
-        try {
-            return parse_frmsf(content);
-        }
-        catch (error) {
-            console.error(`FRMSF auto-detect parse error:`, error);
-        }
+        const result = attempt(`FRMSF`, () => parse_frmsf(content));
+        if (result)
+            return result;
     }
-    console.warn(`Could not detect Fermi surface file format for: ${filename}`);
-    return null;
+    return fail();
 }

package/dist/fermi-surface/types.d.ts

@@ -1,4 +1,4 @@
-import type { Matrix3x3, Point2D, Vec3 } from '../math';
+import type { Matrix3x3, Point2D, Vec2, Vec3 } from '../math';
 import type { TooltipConfig, TooltipProp } from '../tooltip';
 export type SpinChannel = `up` | `down` | null;
 export type RepresentationMode = `solid` | `wireframe` | `transparent`;
@@ -62,7 +62,7 @@ export interface FermiSliceData {
 }
 export interface Isoline {
     points: Vec3[];
-    points_2d: [number, number][];
+    points_2d: Vec2[];
     properties?: number[];
     band_index: number;
     spin: SpinChannel;

package/dist/heatmap-matrix/HeatmapMatrix.svelte

@@ -1,11 +1,11 @@
 <script lang="ts">
   import type { D3InterpolateName } from '../colors'
-  import { is_color, pick_contrast_color } from '../colors'
+  import { get_d3_interpolator, is_color, pick_contrast_color } from '../colors'
   import { format_num } from '../labels'
+  import type { Vec2 } from '../math'
   import type { AxisConfig } from '../plot'
   import ColorBar from '../plot/core/components/ColorBar.svelte'
-  import { make_change_detector } from '../utils'
-  import * as d3_sc from 'd3-scale-chromatic'
+  import { quickselect } from '../plot/box/quantile'
   import { type ComponentProps, onDestroy, onMount, type Snippet } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
   import { SvelteMap, SvelteSet } from 'svelte/reactivity'
@@ -127,7 +127,7 @@
     ) => number | null
     normalize?: NormalizeMode
     domain_mode?: DomainMode
-    quantile_clip?: [number, number]
+    quantile_clip?: Vec2
     show_legend?: boolean
     legend_position?: LegendPosition
     legend_label?: string
@@ -146,8 +146,8 @@
     oncontextmenu?: (cell: CellContext, event: MouseEvent) => void
     enable_brush?: boolean
     onbrush?: (payload: {
-      x_range: [number, number]
-      y_range: [number, number]
+      x_range: Vec2
+      y_range: Vec2
       cells: CellContext[]
     }) => void
     tile_size?: string
@@ -213,7 +213,6 @@
   // === Value resolution ===
   let x_keys = $derived(x_items.map((item) => item.key ?? item.label))
   let y_keys = $derived(y_items.map((item) => item.key ?? item.label))
-  let interaction_axis_signature = $derived(JSON.stringify([x_keys, y_keys]))
   let highlight_x_key_set = $derived(new SvelteSet(highlight_x_keys))
   let highlight_y_key_set = $derived(new SvelteSet(highlight_y_keys))
   let search_query_norm = $derived(search_query.trim().toLowerCase())
@@ -290,11 +289,23 @@
 
     const col_has_data = Array(x_items.length).fill(false)
     const row_has_data = Array(y_items.length).fill(false)
+    // Early-exit: skip cells whose row+col are already non-empty, stop once all resolved (dense matrices touch ~n+m cells, not n*m)
+    let unknown_cols = x_items.length
+    let unknown_rows = y_items.length
     for (let y_idx = 0; y_idx < y_items.length; y_idx++) {
+      if (unknown_cols === 0 && unknown_rows === 0) break
       for (let x_idx = 0; x_idx < x_items.length; x_idx++) {
-        if (get_value(x_idx, y_idx) !== null) {
+        if (row_has_data[y_idx] && col_has_data[x_idx]) continue
+        // ignore cells hidden by symmetric rendering so emptiness reflects only visible cells
+        if (is_hidden_cell(x_idx, y_idx)) continue
+        if (get_value(x_idx, y_idx) === null) continue
+        if (!col_has_data[x_idx]) {
           col_has_data[x_idx] = true
+          unknown_cols--
+        }
+        if (!row_has_data[y_idx]) {
           row_has_data[y_idx] = true
+          unknown_rows--
         }
       }
     }
@@ -313,11 +324,9 @@
   })
 
   // === Color computation ===
-  let color_scale_fn = $derived.by(() => {
-    if (typeof color_scale === `function`) return color_scale
-    const named_scale = d3_sc[color_scale]
-    return typeof named_scale === `function` ? named_scale : d3_sc.interpolateViridis
-  })
+  let color_scale_fn = $derived(
+    typeof color_scale === `function` ? color_scale : get_d3_interpolator(color_scale),
+  )
 
   function get_transformed_value(x_idx: number, y_idx: number): number | null {
     const raw_value = get_value(x_idx, y_idx)
@@ -333,53 +342,53 @@
     return transformed_value
   }
 
-  function get_quantile(sorted_values: number[], quantile: number): number {
-    if (sorted_values.length === 0) return 0
+  // Interpolated quantile via quickselect (O(n) avg vs full sort); reorders `scratch_values` in place so callers must pass a copy they own
+  function get_quantile(scratch_values: number[], quantile: number): number {
+    if (scratch_values.length === 0) return 0
     const clipped_quantile = Math.max(0, Math.min(1, quantile))
-    const float_idx = (sorted_values.length - 1) * clipped_quantile
+    const float_idx = (scratch_values.length - 1) * clipped_quantile
     const low_idx = Math.floor(float_idx)
     const high_idx = Math.ceil(float_idx)
-    if (low_idx === high_idx) return sorted_values[low_idx]
+    const low_val = quickselect(scratch_values, low_idx)
+    if (low_idx === high_idx) return low_val
+    const high_val = quickselect(scratch_values, high_idx)
     const low_weight = high_idx - float_idx
     const high_weight = float_idx - low_idx
-    return sorted_values[low_idx] * low_weight + sorted_values[high_idx] * high_weight
+    return low_val * low_weight + high_val * high_weight
   }
 
-  let valid_numeric_values = $derived.by(() => {
+  // Single pass collecting transformed values + min/max (avoids spreading large arrays into
+  // Math.min/max). min_pos is the log-mode lower bound when domain min <= 0 (the old
+  // Number.MIN_VALUE floor gave log_min ~ -744, squashing all colors to the top)
+  let { valid_numeric_values, auto_min, auto_max, min_pos } = $derived.by(() => {
     const numeric_values: number[] = []
+    let [min, max, pos] = [Infinity, -Infinity, Infinity]
     for (let y_idx = 0; y_idx < y_items.length; y_idx++) {
       for (let x_idx = 0; x_idx < x_items.length; x_idx++) {
         if (is_hidden_cell(x_idx, y_idx)) continue
         const value = get_transformed_value(x_idx, y_idx)
         if (value === null) continue
         numeric_values.push(value)
+        if (value < min) min = value
+        if (value > max) max = value
+        if (value > 0 && value < pos) pos = value
       }
     }
-    return numeric_values
-  })
-
-  // Single-pass min/max to avoid spreading large arrays into Math.min/max. min_pos is
-  // the log-mode lower bound when the domain min is <= 0 (the old Number.MIN_VALUE
-  // floor gave log_min ~ -744, squashing all colors to the top)
-  let [auto_min, auto_max, min_pos] = $derived.by(() => {
-    let [min, max, pos] = [Infinity, -Infinity, Infinity]
-    for (const value of valid_numeric_values) {
-      if (value < min) min = value
-      if (value > max) max = value
-      if (value > 0 && value < pos) pos = value
+    return {
+      valid_numeric_values: numeric_values,
+      auto_min: min <= max ? min : 0,
+      auto_max: min <= max ? max : 1,
+      min_pos: Number.isFinite(pos) ? pos : null,
     }
-    const min_pos_val = Number.isFinite(pos) ? pos : null
-    return min <= max ? [min, max, min_pos_val] as const : [0, 1, min_pos_val] as const
   })
 
+  // Lazy derived: only evaluated while domain_mode === 'robust' reads it
   let [robust_min, robust_max] = $derived.by(() => {
     if (valid_numeric_values.length === 0) return [0, 1] as const
-    const sorted_values = valid_numeric_values.toSorted((value_a, value_b) =>
-      value_a - value_b
-    )
+    const scratch = [...valid_numeric_values]
     const [q_low, q_high] = quantile_clip
-    const clipped_min = get_quantile(sorted_values, q_low)
-    const clipped_max = get_quantile(sorted_values, q_high)
+    const clipped_min = get_quantile(scratch, q_low)
+    const clipped_max = get_quantile(scratch, q_high)
     return clipped_min <= clipped_max
       ? [clipped_min, clipped_max] as const
       : [clipped_max, clipped_min] as const
@@ -1089,9 +1098,15 @@
 
   // Tooltip state: only used for custom tooltip snippets (function tooltips)
   let tooltip_cell: CellContext | null = $state(null)
-  const axis_changed = make_change_detector()
+  // Reset interactions when axis keys change; element-wise compare beats JSON.stringify-ing every key on each x_items/y_items update
+  const keys_equal = (keys_a: string[], keys_b: string[]): boolean =>
+    keys_a.length === keys_b.length && keys_a.every((key, idx) => key === keys_b[idx])
+  let prev_axis_keys: { x: string[]; y: string[] } | null = null
   $effect(() => {
-    if (!axis_changed(interaction_axis_signature)) return
+    const changed = prev_axis_keys !== null &&
+      !(keys_equal(x_keys, prev_axis_keys.x) && keys_equal(y_keys, prev_axis_keys.y))
+    prev_axis_keys = { x: x_keys, y: y_keys }
+    if (!changed) return
     cancel_raf(active_cell_raf)
     // Cancel delayed clicks before old cell coordinates can fire on new axes.
     clear_pending_click()

package/dist/heatmap-matrix/HeatmapMatrix.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { D3InterpolateName } from '../colors';
+import type { Vec2 } from '../math';
 import type { AxisConfig } from '../plot';
 import { type ComponentProps, type Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
@@ -29,7 +30,7 @@ type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, `onclick` | `ondblc
     }) => number | null;
     normalize?: NormalizeMode;
     domain_mode?: DomainMode;
-    quantile_clip?: [number, number];
+    quantile_clip?: Vec2;
     show_legend?: boolean;
     legend_position?: LegendPosition;
     legend_label?: string;
@@ -51,8 +52,8 @@ type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, `onclick` | `ondblc
     oncontextmenu?: (cell: CellContext, event: MouseEvent) => void;
     enable_brush?: boolean;
     onbrush?: (payload: {
-        x_range: [number, number];
-        y_range: [number, number];
+        x_range: Vec2;
+        y_range: Vec2;
         cells: CellContext[];
     }) => void;
     tile_size?: string;

package/dist/heatmap-matrix/HeatmapMatrixControls.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import type { PaneProps, PaneToggleProps } from '../overlays'
   import DraggablePane from '../overlays/DraggablePane.svelte'
   import type { ComponentProps, Snippet } from 'svelte'
   import {
@@ -46,8 +47,8 @@
     export_formats?: HeatmapExportFormat[]
     onexport?: (format: HeatmapExportFormat) => void
     show_pane?: boolean
-    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`]
-    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`]
+    pane_props?: PaneProps
+    toggle_props?: PaneToggleProps
     children?: Snippet<[{ controls_open: boolean }]>
   } = $props()
 

package/dist/heatmap-matrix/HeatmapMatrixControls.svelte.d.ts

@@ -1,5 +1,5 @@
-import DraggablePane from '../overlays/DraggablePane.svelte';
-import type { ComponentProps, Snippet } from 'svelte';
+import type { PaneProps, PaneToggleProps } from '../overlays';
+import type { Snippet } from 'svelte';
 import type { ElementAxisOrderingKey, DomainMode, HeatmapExportFormat, LegendPosition, NormalizeMode, SymmetricMode } from './index';
 type $$ComponentProps = {
     ordering?: ElementAxisOrderingKey;
@@ -19,12 +19,12 @@ type $$ComponentProps = {
     export_formats?: HeatmapExportFormat[];
     onexport?: (format: HeatmapExportFormat) => void;
     show_pane?: boolean;
-    pane_props?: ComponentProps<typeof DraggablePane>[`pane_props`];
-    toggle_props?: ComponentProps<typeof DraggablePane>[`toggle_props`];
+    pane_props?: PaneProps;
+    toggle_props?: PaneToggleProps;
     children?: Snippet<[{
         controls_open: boolean;
     }]>;
 };
-declare const HeatmapMatrixControls: import("svelte").Component<$$ComponentProps, {}, "normalize" | "theme" | "show_legend" | "controls_open" | "show_values" | "ordering" | "toggle_visible" | "domain_mode" | "legend_position" | "search_query" | "symmetric" | "show_row_summaries" | "show_col_summaries">;
+declare const HeatmapMatrixControls: import("svelte").Component<$$ComponentProps, {}, "normalize" | "show_values" | "show_legend" | "controls_open" | "ordering" | "theme" | "toggle_visible" | "domain_mode" | "legend_position" | "search_query" | "symmetric" | "show_row_summaries" | "show_col_summaries">;
 type HeatmapMatrixControls = ReturnType<typeof HeatmapMatrixControls>;
 export default HeatmapMatrixControls;

package/dist/heatmap-matrix/index.d.ts

@@ -1,4 +1,5 @@
 import type { ChemicalElement, ElementSymbol } from '../element';
+import type { Vec2 } from '../math';
 import type { Snippet } from 'svelte';
 export { COLOR_OVERRIDE_KEY_SEPARATOR, make_color_override_key } from './shared';
 export type AxisItem<T = Record<string, unknown>> = {
@@ -41,8 +42,8 @@ export type HeatmapSelection = {
 };
 export type HeatmapExportFormat = `csv` | `json`;
 export type HeatmapBrushPayload = {
-    x_range: [number, number];
-    y_range: [number, number];
+    x_range: Vec2;
+    y_range: Vec2;
     cells: CellContext[];
 };
 export declare const ELEMENT_ORDERINGS: ElementAxisOrderingKey[];

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export * from './phase-diagram';
 export * from './plot';
 export * from './rdf';
 export * from './sanitize';
+export * from './scene';
 export * from './settings';
 export * from './spectral';
 export * from './structure';

package/dist/index.js

@@ -27,6 +27,7 @@ export * from './phase-diagram';
 export * from './plot';
 export * from './rdf';
 export * from './sanitize';
+export * from './scene';
 export * from './settings';
 export * from './spectral';
 export * from './structure';