matterviz 0.3.7 → 0.4.1

package/dist/fermi-surface/compute.js

@@ -2,7 +2,7 @@
 import * as math from '../math';
 import { EPS } from '../math';
 import { CLOSED_CONTOUR_TOLERANCE, IRREDUCIBLE_BZ_MIN_VERTICES, IRREDUCIBLE_BZ_TOLERANCE, SPANNING_THRESHOLD, } from './constants';
-import { marching_cubes } from './marching-cubes';
+import { marching_cubes } from '../marching-cubes';
 const safe_mod = (val, dim) => ((val % dim) + dim) % dim;
 // Precompute Catmull-Rom coefficients for a given t value
 // Returns [c0, c1, c2, c3] where result = c0*p0 + c1*p1 + c2*p2 + c3*p3
@@ -15,8 +15,10 @@ function catmull_rom_coeffs(t) {
     const c4 = 0.5 * (-t2 + t3);
     return [c1, c2, c3, c4];
 }
-// Tricubic interpolation with cached wrap indices and precomputed coefficients
-function tricubic_interpolate(grid, fx, fy, fz, nx, ny, nz) {
+// Tricubic interpolation with cached wrap indices and precomputed coefficients.
+// px/py/pz are the wrap periods (unique points per axis): n for periodic grids,
+// n−1 for endpoint-inclusive grids whose last point duplicates the first.
+function tricubic_interpolate(grid, fx, fy, fz, px, py, pz) {
     // Get integer and fractional parts
     const ix = Math.floor(fx);
     const iy = Math.floor(fy);
@@ -25,13 +27,10 @@ function tricubic_interpolate(grid, fx, fy, fz, nx, ny, nz) {
     const [cx0, cx1, cx2, cx3] = catmull_rom_coeffs(fx - ix);
     const [cy0, cy1, cy2, cy3] = catmull_rom_coeffs(fy - iy);
     const [cz0, cz1, cz2, cz3] = catmull_rom_coeffs(fz - iz);
-    // Precompute wrapped indices (avoid modulo in inner loop)
-    const wrap_x = (v) => ((v % nx) + nx) % nx;
-    const wrap_y = (v) => ((v % ny) + ny) % ny;
-    const wrap_z = (v) => ((v % nz) + nz) % nz;
-    const wx = [wrap_x(ix - 1), wrap_x(ix), wrap_x(ix + 1), wrap_x(ix + 2)];
-    const wy = [wrap_y(iy - 1), wrap_y(iy), wrap_y(iy + 1), wrap_y(iy + 2)];
-    const wz = [wrap_z(iz - 1), wrap_z(iz), wrap_z(iz + 1), wrap_z(iz + 2)];
+    // Wrapped stencil indices (modulo hoisted out of the inner loop); a zero period
+    // (single-point axis) has no neighbours, so collapse the stencil onto index 0
+    const stencil = (idx, period) => [idx - 1, idx, idx + 1, idx + 2].map((stencil_idx) => period > 0 ? ((stencil_idx % period) + period) % period : 0);
+    const [wx, wy, wz] = [stencil(ix, px), stencil(iy, py), stencil(iz, pz)];
     // Interpolate along z, then y, then x (fully inlined)
     let result = 0;
     const cx = [cx0, cx1, cx2, cx3];
@@ -51,26 +50,29 @@ function tricubic_interpolate(grid, fx, fy, fz, nx, ny, nz) {
     }
     return result;
 }
-// Upsample a 3D grid using tricubic interpolation for smoother surfaces
-function upsample_grid(grid, factor) {
+// Upsample a 3D grid with tricubic interpolation, preserving the grid convention:
+// endpoint-inclusive (BXSF, point i ↔ frac i/(n−1)) vs periodic (FRMSF, i ↔ i/n).
+// Mixing conventions rescales the surface and distorts the zone boundary.
+function upsample_grid(grid, factor, periodic = false) {
     if (factor <= 1)
         return grid;
-    const nx = grid.length;
-    const ny = grid[0]?.length || 0;
-    const nz = grid[0]?.[0]?.length || 0;
-    const new_nx = Math.round(nx * factor);
-    const new_ny = Math.round(ny * factor);
-    const new_nz = Math.round(nz * factor);
-    // Precompute fractional coordinates for each axis
-    const fx_arr = new Float64Array(new_nx);
-    const fy_arr = new Float64Array(new_ny);
-    const fz_arr = new Float64Array(new_nz);
-    for (let ix = 0; ix < new_nx; ix++)
-        fx_arr[ix] = (ix / new_nx) * nx;
-    for (let iy = 0; iy < new_ny; iy++)
-        fy_arr[iy] = (iy / new_ny) * ny;
-    for (let iz = 0; iz < new_nz; iz++)
-        fz_arr[iz] = (iz / new_nz) * nz;
+    // Endpoint-inclusive grids carry one duplicated boundary sample per axis; the wrap
+    // period (count of unique points) doubles as the resampling span numerator
+    const endpoint = periodic ? 0 : 1;
+    const dims = [grid.length, grid[0]?.length || 0, grid[0]?.[0]?.length || 0];
+    const [px, py, pz] = dims.map((dim) => dim - endpoint);
+    const [new_nx, new_ny, new_nz] = [px, py, pz].map((period) => Math.round(period * factor) + endpoint);
+    // Map new index → source coordinate; a single-point axis (span 0) pins its lone
+    // output to source 0 to avoid 0/0 = NaN
+    const src_coords = (new_n, period) => {
+        const span = new_n - endpoint;
+        return Float64Array.from({ length: new_n }, (_, idx) => span > 0 ? (idx / span) * period : 0);
+    };
+    const [fx_arr, fy_arr, fz_arr] = [
+        [new_nx, px],
+        [new_ny, py],
+        [new_nz, pz],
+    ].map(([new_n, period]) => src_coords(new_n, period));
     // Preallocate output grid
     const new_grid = Array(new_nx);
     for (let ix = 0; ix < new_nx; ix++) {
@@ -80,7 +82,7 @@ function upsample_grid(grid, factor) {
             const fy = fy_arr[iy];
             const iz_arr = new Float64Array(new_nz);
             for (let iz = 0; iz < new_nz; iz++) {
-                iz_arr[iz] = tricubic_interpolate(grid, fx, fy, fz_arr[iz], nx, ny, nz);
+                iz_arr[iz] = tricubic_interpolate(grid, fx, fy, fz_arr[iz], px, py, pz);
             }
             // Convert Float64Array back to regular array for compatibility
             iy_arr[iy] = Array.from(iz_arr);
@@ -109,15 +111,16 @@ export function extract_fermi_surface(band_data, options = {}) {
             // Check if Fermi level intersects this band
             if (!band_intersects_fermi(raw_energies, iso_value))
                 continue;
+            // BXSF grids are endpoint-inclusive (store both equivalent k=0 and k=1 → false);
+            // FRMSF grids store k=i/n without the duplicated endpoint (→ true)
+            const periodic = band_data.periodic ?? false;
             // Apply interpolation for smoother surfaces
             const energies = interpolation_factor > 1
-                ? upsample_grid(raw_energies, interpolation_factor)
+                ? upsample_grid(raw_energies, interpolation_factor, periodic)
                 : raw_energies;
             // Extract isosurface using marching cubes
-            // Use periodic: false because BXSF grids include both endpoints (k=0 and k=1)
-            // which are equivalent due to BZ periodicity. This matches scikit-image behavior.
             const mc_result = marching_cubes(energies, iso_value, band_data.k_lattice, {
-                periodic: false,
+                periodic,
                 interpolate: true,
             });
             if (mc_result.vertices.length === 0)
@@ -137,13 +140,14 @@ export function extract_fermi_surface(band_data, options = {}) {
             total_area += isosurface.area;
             // Compute Fermi velocities if requested
             if (compute_velocities && band_data.velocities) {
-                isosurface.properties = compute_fermi_velocities(isosurface, band_data.velocities[spin_idx][band_idx], band_data.k_lattice, band_data.k_grid);
+                isosurface.properties = compute_fermi_velocities(isosurface, band_data.velocities[spin_idx][band_idx], band_data.k_lattice, band_data.k_grid, periodic);
                 isosurface.avg_velocity =
-                    isosurface.properties.reduce((s, v) => s + v, 0) / isosurface.properties.length;
+                    isosurface.properties.reduce((sum, velocity) => sum + velocity, 0) /
+                        isosurface.properties.length;
             }
             // Compute dimensionality if requested
             if (compute_dimensionality) {
-                const { dimensionality, orientation } = analyze_surface_topology(isosurface, null);
+                const { dimensionality, orientation } = analyze_surface_topology(isosurface, band_data.k_lattice);
                 isosurface.dimensionality = dimensionality;
                 isosurface.orientation = orientation;
             }
@@ -205,24 +209,22 @@ export function compute_surface_area(surface) {
     return total_area;
 }
 // Compute Fermi velocities at surface vertices
-function compute_fermi_velocities(surface, velocity_grid, k_lattice, k_grid) {
+function compute_fermi_velocities(surface, velocity_grid, k_lattice, k_grid, periodic = false) {
     const [nx, ny, nz] = k_grid;
     const velocities = [];
-    // Inverse of k_lattice for Cartesian to fractional conversion
-    const k_inv = math.matrix_inverse_3x3(k_lattice);
+    // Invert the marching-cubes transform cart = k_latticeᵀ·(frac − 0.5): frac =
+    // (k_latticeᵀ)⁻¹·cart + 0.5. Omitting the transpose samples wrong k-points for
+    // non-symmetric lattices; skipping the +0.5 is off by half a reciprocal cell.
+    const k_inv = math.matrix_inverse_3x3(math.transpose_3x3_matrix(k_lattice));
+    // Grid point i sits at frac i/(n−1) (endpoint-inclusive BXSF) or i/n (periodic)
+    const [sx, sy, sz] = periodic ? [nx, ny, nz] : [nx - 1, ny - 1, nz - 1];
+    // Clamp guards float jitter at the cell boundary
+    const clamp01 = (val) => Math.min(Math.max(val, 0), 1);
     for (const vertex of surface.vertices) {
-        // Convert Cartesian to fractional coordinates
-        const frac = math.mat3x3_vec3_multiply(k_inv, vertex);
-        // Wrap to [0, 1)
-        const wrapped = [
-            ((frac[0] % 1) + 1) % 1,
-            ((frac[1] % 1) + 1) % 1,
-            ((frac[2] % 1) + 1) % 1,
-        ];
-        // Grid indices (with interpolation)
-        const gx = wrapped[0] * nx;
-        const gy = wrapped[1] * ny;
-        const gz = wrapped[2] * nz;
+        const frac = math.mat3x3_vec3_multiply(k_inv, vertex); // centered, in [-0.5, 0.5]
+        const gx = clamp01(frac[0] + 0.5) * sx;
+        const gy = clamp01(frac[1] + 0.5) * sy;
+        const gz = clamp01(frac[2] + 0.5) * sz;
         // Trilinear interpolation of velocity
         const velocity = trilinear_interpolate_vec3(velocity_grid, gx, gy, gz);
         velocities.push(Math.hypot(...velocity)); // magnitude
@@ -265,14 +267,15 @@ function trilinear_interpolate_vec3(grid, x, y, z) {
     return math.lerp_vec3(c0, c1, zd);
 }
 // Analyze surface topology to determine dimensionality
-function analyze_surface_topology(surface, bz_data) {
+function analyze_surface_topology(surface, k_lattice) {
     if (surface.vertices.length === 0) {
         return { dimensionality: `3D`, orientation: null };
     }
-    // Check if surface spans the full BZ in each direction
-    const bz_extent = bz_data
-        ? math.compute_bounding_box(bz_data.vertices)
-        : { min: [-1, -1, -1], max: [1, 1, 1] };
+    // Vertices live in the centered parallelepiped k_latticeᵀ·[-0.5, 0.5]³, whose bounding
+    // box along Cartesian axis j has half-extent 0.5·Σᵢ|k_lattice[i][j]| (a hardcoded box
+    // would make dimensionality depend on the absolute lattice scale)
+    const half_extent = [0, 1, 2].map((axis_idx) => 0.5 * k_lattice.reduce((sum, row) => sum + Math.abs(row[axis_idx]), 0));
+    const bz_extent = { min: half_extent.map((ext) => -ext), max: half_extent };
     const surface_extent = math.compute_bounding_box(surface.vertices);
     // Check spanning in each direction
     const spans = [false, false, false];
@@ -301,10 +304,8 @@ function analyze_surface_topology(surface, bz_data) {
         orientation[axis_idx] = 1;
         return { dimensionality: `1D`, orientation };
     }
-    else {
-        // Spans all 3 directions - complex warped network
-        return { dimensionality: `quasi-2D`, orientation: null };
-    }
+    // Spans all 3 directions - complex warped network
+    return { dimensionality: `quasi-2D`, orientation: null };
 }
 // Compute 2D Fermi slice along a specified plane
 export function compute_fermi_slice(fermi_data, options = {}) {
@@ -319,7 +320,7 @@ export function compute_fermi_slice(fermi_data, options = {}) {
     if (normal_len < EPS) {
         throw new Error(`Degenerate plane normal: k_lattice vectors produce a zero-length normal for miller indices [${miller_indices.join(`, `)}]`);
     }
-    const unit_normal = math.normalize_vec3(plane_normal);
+    const unit_normal = math.normalize_vec(plane_normal);
     // Compute in-plane basis vectors
     const [in_plane_u, in_plane_v] = math.compute_in_plane_basis(unit_normal);
     // Slice each isosurface
@@ -348,19 +349,19 @@ function compute_edge_intersection(surface, vertex_distances, v0_idx, v1_idx) {
     // Edge must cross the plane (opposite signs)
     if (d0 * d1 >= 0)
         return null;
-    const t = d0 / (d0 - d1);
+    const frac = d0 / (d0 - d1);
     const v0 = surface.vertices[v0_idx];
     const v1 = surface.vertices[v1_idx];
     const point = [
-        v0[0] + t * (v1[0] - v0[0]),
-        v0[1] + t * (v1[1] - v0[1]),
-        v0[2] + t * (v1[2] - v0[2]),
+        v0[0] + frac * (v1[0] - v0[0]),
+        v0[1] + frac * (v1[1] - v0[1]),
+        v0[2] + frac * (v1[2] - v0[2]),
     ];
     let property;
     if (surface.properties) {
         property =
             surface.properties[v0_idx] +
-                t * (surface.properties[v1_idx] - surface.properties[v0_idx]);
+                frac * (surface.properties[v1_idx] - surface.properties[v0_idx]);
     }
     return { point, property };
 }

package/dist/fermi-surface/export.js

@@ -1,15 +1,5 @@
-// Helper to trigger file download
-function download_file(content, filename, mime_type) {
-    const blob = new Blob([content], { type: mime_type });
-    const url = URL.createObjectURL(blob);
-    const link = document.createElement(`a`);
-    link.href = url;
-    link.download = filename;
-    document.body.appendChild(link);
-    link.click();
-    document.body.removeChild(link);
-    URL.revokeObjectURL(url);
-}
+import { download } from '../io/fetch';
+import { to_error } from '../utils';
 // Export scene to STL format (good for 3D printing)
 export async function export_to_stl(scene, filename) {
     const { STLExporter } = await import(`three/addons/exporters/STLExporter.js`);
@@ -17,14 +7,14 @@ export async function export_to_stl(scene, filename) {
     const result = exporter.parse(scene, { binary: true });
     // Binary STL returns DataView, convert to ArrayBuffer for Blob
     const buffer = result instanceof DataView ? result.buffer : result;
-    download_file(buffer, `${filename}.stl`, `application/octet-stream`);
+    download(buffer, `${filename}.stl`, `application/octet-stream`);
 }
 // Export scene to OBJ format (widely compatible)
 export async function export_to_obj(scene, filename) {
     const { OBJExporter } = await import(`three/addons/exporters/OBJExporter.js`);
     const exporter = new OBJExporter();
     const result = exporter.parse(scene);
-    download_file(result, `${filename}.obj`, `text/plain`);
+    download(result, `${filename}.obj`, `text/plain`);
 }
 // Export scene to GLTF format (modern web/AR standard)
 export async function export_to_gltf(scene, filename) {
@@ -33,9 +23,9 @@ export async function export_to_gltf(scene, filename) {
     return new Promise((resolve, reject) => {
         exporter.parse(scene, (gltf) => {
             const output = JSON.stringify(gltf, null, 2);
-            download_file(output, `${filename}.gltf`, `application/json`);
+            download(output, `${filename}.gltf`, `application/json`);
             resolve();
-        }, (error) => reject(error), { binary: false });
+        }, (error) => reject(to_error(error)), { binary: false });
     });
 }
 // Main export function that dispatches to the appropriate format

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

@@ -6,7 +6,6 @@ export { default as FermiSurfaceTooltip } from './FermiSurfaceTooltip.svelte';
 export * from './compute';
 export * from './constants';
 export * from './export';
-export * from './marching-cubes';
 export * from './parse';
 export * from './symmetry';
 export * from './types';

package/dist/fermi-surface/index.js

@@ -7,7 +7,6 @@ export { default as FermiSurfaceTooltip } from './FermiSurfaceTooltip.svelte';
 export * from './compute';
 export * from './constants';
 export * from './export';
-export * from './marching-cubes';
 export * from './parse';
 export * from './symmetry';
 export * from './types';

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

@@ -1,2 +1,2 @@
 import type { BandGridData, FermiSurfaceData } from './types';
-export declare function parse_fermi_file(content: string, filename?: string): BandGridData | FermiSurfaceData | null;
+export declare function parse_fermi_file(content: string, filename?: string): BandGridData | FermiSurfaceData;

package/dist/fermi-surface/parse.js

@@ -1,8 +1,10 @@
+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((part) => +part);
+const parse_floats = (line) => parse_number_tokens(line).map(Number);
 // Parse whitespace-separated integers from a line
 const parse_ints = (line) => parse_number_tokens(line).map((part) => parseInt(part, 10));
 // Parse BXSF (Band-XSF) format used by XCrySDen, Quantum ESPRESSO, etc.
@@ -219,18 +221,14 @@ function parse_frmsf(content) {
         fermi_energy: 0, // FRMSF typically expects Fermi level at 0
         n_bands,
         n_spins,
+        periodic: true, // FRMSF stores k=i/n with no duplicated endpoint (unlike BXSF)
     };
 }
 // 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))
@@ -245,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
@@ -286,29 +292,34 @@ 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,
             fermi_energy: bs.fermi_energy ?? bs.efermi ?? 0,
-            n_bands: bs.n_bands || bs.nbands || bs.energies[0]?.length || 0,
-            n_spins: bs.n_spins || bs.nspins || bs.energies.length || 1,
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- numeric fallback chain (0 falls through)
+            n_bands: (bs.n_bands ?? bs.nbands) || bs.energies[0]?.length || 0,
+            // 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
@@ -384,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({
@@ -424,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 lower_name = filename?.toLowerCase() ?? ``;
+    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`;
@@ -48,6 +48,7 @@ export interface BandGridData {
     n_bands: number;
     n_spins: number;
     origin?: Vec3;
+    periodic?: boolean;
 }
 export interface FermiSliceData {
     isolines: Isoline[];
@@ -61,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;