matterviz 0.3.6 → 0.4.0

package/dist/fermi-surface/FermiSurfaceScene.svelte.d.ts

@@ -0,0 +1,50 @@
+import type { BrillouinZoneData } from '../brillouin';
+import type { Vec3 } from '../math';
+import type { CameraProjection } from '../settings';
+import * as extras from '@threlte/extras';
+import type { ComponentProps } from 'svelte';
+import type { Camera, Scene } from 'three';
+import type { ColorProperty, FermiHoverData, FermiSurfaceData, RepresentationMode } from './types';
+type $$ComponentProps = {
+    fermi_data?: FermiSurfaceData;
+    bz_data?: BrillouinZoneData;
+    camera_position?: Vec3 | undefined;
+    camera_projection?: CameraProjection;
+    color_property?: ColorProperty;
+    color_scale?: string;
+    representation?: RepresentationMode;
+    surface_opacity?: number;
+    selected_bands?: number[];
+    show_bz?: boolean;
+    bz_color?: string;
+    bz_opacity?: number;
+    bz_edge_color?: string;
+    bz_edge_width?: number;
+    show_vectors?: boolean;
+    tile_bz?: boolean;
+    clip_enabled?: boolean;
+    clip_axis?: `x` | `y` | `z`;
+    clip_position?: number;
+    clip_flip?: boolean;
+    vector_scale?: number;
+    rotation_damping?: number;
+    max_zoom?: number;
+    min_zoom?: number;
+    rotate_speed?: number;
+    zoom_speed?: number;
+    pan_speed?: number;
+    zoom_to_cursor?: boolean;
+    fov?: number;
+    initial_zoom?: number;
+    ambient_light?: number;
+    directional_light?: number;
+    gizmo?: boolean | ComponentProps<typeof extras.Gizmo>;
+    auto_rotate?: number;
+    camera_is_moving?: boolean;
+    scene?: Scene;
+    camera?: Camera;
+    hover_data?: FermiHoverData | null;
+};
+declare const FermiSurfaceScene: import("svelte").Component<$$ComponentProps, {}, "camera_position" | "camera_projection" | "camera" | "scene" | "camera_is_moving" | "surface_opacity" | "bz_data" | "hover_data" | "fermi_data">;
+type FermiSurfaceScene = ReturnType<typeof FermiSurfaceScene>;
+export default FermiSurfaceScene;

package/dist/fermi-surface/FermiSurfaceTooltip.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+  // Tooltip component for Fermi surface hover information
+  // Displays band index, spin, k-coordinates, and optional property values
+  import { format_num } from '../labels'
+  import { KCoords, TooltipContent } from '../tooltip'
+  import type { FermiHoverData, FermiTooltipProp } from './types'
+
+  let { hover_data, tooltip }: {
+    hover_data: FermiHoverData
+    tooltip?: FermiTooltipProp
+  } = $props()
+</script>
+
+<TooltipContent data={hover_data} snippet_arg={{ hover_data }} {tooltip}>
+  <div class="tooltip-content">
+    <div class="tooltip-title">
+      <strong>Band {hover_data.band_index}</strong>
+      {#if hover_data.spin}
+        <span class="spin-badge spin-{hover_data.spin}">{hover_data.spin}</span>
+      {/if}
+    </div>
+
+    <KCoords
+      cartesian={hover_data.position_cartesian}
+      fractional={hover_data.position_fractional}
+    />
+
+    {#if hover_data.property_value != null}
+      <div class="property-row">
+        {hover_data.property_name || `Property`}: {
+          format_num(hover_data.property_value, `.4~`)
+        }
+        <span class="nearest-note">(nearest)</span>
+      </div>
+    {/if}
+
+    {#if hover_data.is_tiled && hover_data.symmetry_index != null &&
+        hover_data.symmetry_index > 0}
+      <div class="tiling-info">
+        Symmetry copy #{hover_data.symmetry_index + 1}/48
+      </div>
+    {/if}
+  </div>
+</TooltipContent>
+
+<style>
+  .tooltip-content {
+    max-width: var(--tooltip-max-width, 250px);
+  }
+  .tooltip-title {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    margin-bottom: 4px;
+  }
+  .spin-badge {
+    font-size: 0.75em;
+    padding: 1px 4px;
+    border-radius: 3px;
+    font-weight: 500;
+  }
+  .spin-badge.spin-up {
+    background: #e41a1c;
+    color: white;
+  }
+  .spin-badge.spin-down {
+    background: #377eb8;
+    color: white;
+  }
+  .property-row {
+    margin-top: 4px;
+    font-size: 0.9em;
+  }
+  .nearest-note {
+    opacity: 0.6;
+    font-size: 0.85em;
+    margin-left: 3px;
+  }
+  .tiling-info {
+    margin-top: 4px;
+    font-size: 0.8em;
+    opacity: 0.7;
+    font-style: italic;
+  }
+</style>

package/dist/fermi-surface/FermiSurfaceTooltip.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { FermiHoverData, FermiTooltipProp } from './types';
+type $$ComponentProps = {
+    hover_data: FermiHoverData;
+    tooltip?: FermiTooltipProp;
+};
+declare const FermiSurfaceTooltip: import("svelte").Component<$$ComponentProps, {}, "">;
+type FermiSurfaceTooltip = ReturnType<typeof FermiSurfaceTooltip>;
+export default FermiSurfaceTooltip;

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

@@ -0,0 +1,5 @@
+import type { BandGridData, FermiSliceData, FermiSliceOptions, FermiSurfaceData, FermiSurfaceOptions, Isosurface } from './types';
+export declare function extract_fermi_surface(band_data: BandGridData, options?: FermiSurfaceOptions): FermiSurfaceData;
+export declare function compute_surface_area(surface: Isosurface): number;
+export declare function compute_fermi_slice(fermi_data: FermiSurfaceData, options?: FermiSliceOptions): FermiSliceData;
+export declare function detect_irreducible_bz(fermi_data: FermiSurfaceData): boolean;

package/dist/fermi-surface/compute.js

@@ -0,0 +1,538 @@
+// Fermi surface computation and analysis functions
+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';
+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
+function catmull_rom_coeffs(t) {
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const c1 = 0.5 * (-t + 2 * t2 - t3);
+    const c2 = 0.5 * (2 - 5 * t2 + 3 * t3);
+    const c3 = 0.5 * (t + 4 * t2 - 3 * t3);
+    const c4 = 0.5 * (-t2 + t3);
+    return [c1, c2, c3, c4];
+}
+// 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);
+    const iz = Math.floor(fz);
+    // Precompute Catmull-Rom coefficients
+    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);
+    // 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((v) => period > 0 ? ((v % 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];
+    const cy = [cy0, cy1, cy2, cy3];
+    const cz = [cz0, cz1, cz2, cz3];
+    for (let xi = 0; xi < 4; xi++) {
+        const row = grid[wx[xi]];
+        let y_sum = 0;
+        for (let yi = 0; yi < 4; yi++) {
+            const col = row[wy[yi]];
+            // Inline z interpolation
+            y_sum +=
+                cy[yi] *
+                    (cz[0] * col[wz[0]] + cz[1] * col[wz[1]] + cz[2] * col[wz[2]] + cz[3] * col[wz[3]]);
+        }
+        result += cx[xi] * y_sum;
+    }
+    return result;
+}
+// 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;
+    // 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((n) => n - endpoint);
+    const [new_nx, new_ny, new_nz] = [px, py, pz].map((p) => Math.round(p * 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++) {
+        const fx = fx_arr[ix];
+        const iy_arr = Array(new_ny);
+        for (let iy = 0; iy < new_ny; iy++) {
+            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], px, py, pz);
+            }
+            // Convert Float64Array back to regular array for compatibility
+            iy_arr[iy] = Array.from(iz_arr);
+        }
+        new_grid[ix] = iy_arr;
+    }
+    return new_grid;
+}
+// Extract Fermi surface from band grid data
+export function extract_fermi_surface(band_data, options = {}) {
+    const { mu = 0, wigner_seitz = true, compute_velocities = false, compute_dimensionality = false, selected_bands, interpolation_factor = 1, selected_spins, } = options;
+    const iso_value = band_data.fermi_energy + mu;
+    const isosurfaces = [];
+    let total_area = 0;
+    // Process each spin channel and band
+    for (let spin_idx = 0; spin_idx < band_data.n_spins; spin_idx++) {
+        const spin = band_data.n_spins === 2 ? (spin_idx === 0 ? `up` : `down`) : null;
+        // Skip if spin not selected
+        if (selected_spins && !selected_spins.includes(spin))
+            continue;
+        for (let band_idx = 0; band_idx < band_data.n_bands; band_idx++) {
+            // Skip if band not selected
+            if (selected_bands && !selected_bands.includes(band_idx))
+                continue;
+            const raw_energies = band_data.energies[spin_idx][band_idx];
+            // 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, periodic)
+                : raw_energies;
+            // Extract isosurface using marching cubes
+            const mc_result = marching_cubes(energies, iso_value, band_data.k_lattice, {
+                periodic,
+                interpolate: true,
+            });
+            if (mc_result.vertices.length === 0)
+                continue;
+            // Build isosurface
+            // Note: We don't clip to Wigner-Seitz BZ here because marching cubes output is in
+            // a centered parallelepiped cell. BZ symmetry tiling in renderer handles full BZ.
+            const isosurface = {
+                vertices: mc_result.vertices,
+                faces: mc_result.faces,
+                normals: mc_result.normals,
+                band_index: band_idx,
+                spin,
+            };
+            // Compute surface area
+            isosurface.area = compute_surface_area(isosurface);
+            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, periodic);
+                isosurface.avg_velocity =
+                    isosurface.properties.reduce((s, v) => s + v, 0) / isosurface.properties.length;
+            }
+            // Compute dimensionality if requested
+            if (compute_dimensionality) {
+                const { dimensionality, orientation } = analyze_surface_topology(isosurface, band_data.k_lattice);
+                isosurface.dimensionality = dimensionality;
+                isosurface.orientation = orientation;
+            }
+            isosurfaces.push(isosurface);
+        }
+    }
+    const metadata = {
+        n_bands: band_data.n_bands,
+        n_surfaces: isosurfaces.length,
+        total_area,
+        has_spin: band_data.n_spins === 2,
+        has_velocities: compute_velocities && band_data.velocities !== undefined,
+    };
+    return {
+        isosurfaces,
+        k_lattice: band_data.k_lattice,
+        fermi_energy: band_data.fermi_energy,
+        reciprocal_cell: wigner_seitz ? `wigner_seitz` : `parallelepiped`,
+        metadata,
+    };
+}
+// Check if Fermi level intersects a band (has values both above and below)
+function band_intersects_fermi(energies, iso_value) {
+    let has_below = false;
+    let has_above = false;
+    for (const plane of energies) {
+        for (const row of plane) {
+            for (const energy of row) {
+                if (energy < iso_value)
+                    has_below = true;
+                else if (energy > iso_value)
+                    has_above = true;
+                if (has_below && has_above)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// Compute surface area of an isosurface (assumes triangular faces from marching cubes)
+export function compute_surface_area(surface) {
+    let total_area = 0;
+    const verts = surface.vertices;
+    for (const face of surface.faces) {
+        if (face.length < 3)
+            continue;
+        const [v0x, v0y, v0z] = verts[face[0]];
+        const [v1x, v1y, v1z] = verts[face[1]];
+        const [v2x, v2y, v2z] = verts[face[2]];
+        // Inlined edge subtraction and cross product
+        const [e1x, e1y, e1z] = [v1x - v0x, v1y - v0y, v1z - v0z];
+        const [e2x, e2y, e2z] = [v2x - v0x, v2y - v0y, v2z - v0z];
+        const cx = e1y * e2z - e1z * e2y;
+        const cy = e1z * e2x - e1x * e2z;
+        const cz = e1x * e2y - e1y * e2x;
+        // Area is half the magnitude of cross product
+        total_area += Math.sqrt(cx * cx + cy * cy + cz * cz) * 0.5;
+    }
+    return total_area;
+}
+// Compute Fermi velocities at surface vertices
+function compute_fermi_velocities(surface, velocity_grid, k_lattice, k_grid, periodic = false) {
+    const [nx, ny, nz] = k_grid;
+    const velocities = [];
+    // 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) {
+        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
+    }
+    return velocities;
+}
+// Trilinear interpolation for Vec3 grid
+// Note: Assumes x, y, z are non-negative (e.g. from wrapped fractional coordinates)
+function trilinear_interpolate_vec3(grid, x, y, z) {
+    const nx = grid.length;
+    const ny = grid[0]?.length || 0;
+    const nz = grid[0]?.[0]?.length || 0;
+    // Guard against empty or malformed grids to prevent division by zero in modulo
+    if (nx === 0 || ny === 0 || nz === 0)
+        return [0, 0, 0];
+    // Use safe modulo pattern to handle negative values from floating-point edge cases
+    const x0 = safe_mod(Math.floor(x), nx);
+    const y0 = safe_mod(Math.floor(y), ny);
+    const z0 = safe_mod(Math.floor(z), nz);
+    const x1 = (x0 + 1) % nx;
+    const y1 = (y0 + 1) % ny;
+    const z1 = (z0 + 1) % nz;
+    const xd = x - Math.floor(x);
+    const yd = y - Math.floor(y);
+    const zd = z - Math.floor(z);
+    const c000 = grid[x0][y0][z0];
+    const c001 = grid[x0][y0][z1];
+    const c010 = grid[x0][y1][z0];
+    const c011 = grid[x0][y1][z1];
+    const c100 = grid[x1][y0][z0];
+    const c101 = grid[x1][y0][z1];
+    const c110 = grid[x1][y1][z0];
+    const c111 = grid[x1][y1][z1];
+    const c00 = math.lerp_vec3(c000, c100, xd);
+    const c01 = math.lerp_vec3(c001, c101, xd);
+    const c10 = math.lerp_vec3(c010, c110, xd);
+    const c11 = math.lerp_vec3(c011, c111, xd);
+    const c0 = math.lerp_vec3(c00, c10, yd);
+    const c1 = math.lerp_vec3(c01, c11, yd);
+    return math.lerp_vec3(c0, c1, zd);
+}
+// Analyze surface topology to determine dimensionality
+function analyze_surface_topology(surface, k_lattice) {
+    if (surface.vertices.length === 0) {
+        return { dimensionality: `3D`, orientation: null };
+    }
+    // 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];
+    for (let axis_idx = 0; axis_idx < 3; axis_idx++) {
+        const bz_size = bz_extent.max[axis_idx] - bz_extent.min[axis_idx];
+        const surface_size = surface_extent.max[axis_idx] - surface_extent.min[axis_idx];
+        // Consider spanning if surface covers significant fraction of BZ extent
+        spans[axis_idx] = surface_size > SPANNING_THRESHOLD * bz_size;
+    }
+    const n_spanning = spans.filter(Boolean).length;
+    if (n_spanning === 0) {
+        // Closed surface, no spanning directions
+        return { dimensionality: `3D`, orientation: null };
+    }
+    else if (n_spanning === 1) {
+        // 2D sheet spanning one direction
+        const axis_idx = spans.indexOf(true);
+        const orientation = [0, 0, 0];
+        orientation[axis_idx] = 1;
+        return { dimensionality: `2D`, orientation };
+    }
+    else if (n_spanning === 2) {
+        // 1D noodle-like (tube spanning 2 directions, bounded in 1)
+        const axis_idx = spans.indexOf(false);
+        const orientation = [0, 0, 0];
+        orientation[axis_idx] = 1;
+        return { dimensionality: `1D`, orientation };
+    }
+    // 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 = {}) {
+    const { miller_indices = [0, 0, 1], distance = 0 } = options;
+    // Validate miller indices are not all zero
+    if (miller_indices[0] === 0 && miller_indices[1] === 0 && miller_indices[2] === 0) {
+        throw new Error(`Invalid miller indices [0, 0, 0]: at least one index must be non-zero to define a plane`);
+    }
+    // Compute plane normal in Cartesian coordinates
+    const plane_normal = math.add(math.add(math.scale(fermi_data.k_lattice[0], miller_indices[0]), math.scale(fermi_data.k_lattice[1], miller_indices[1])), math.scale(fermi_data.k_lattice[2], miller_indices[2]));
+    const normal_len = Math.hypot(...plane_normal);
+    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_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
+    const isolines = [];
+    for (const surface of fermi_data.isosurfaces) {
+        const lines = slice_surface_with_plane(surface, unit_normal, distance, in_plane_u, in_plane_v);
+        isolines.push(...lines);
+    }
+    return {
+        isolines,
+        plane_normal: unit_normal,
+        plane_distance: distance,
+        k_lattice_2d: [in_plane_u, in_plane_v],
+        metadata: {
+            n_lines: isolines.length,
+            has_properties: isolines.some((line) => line.properties !== undefined),
+        },
+    };
+}
+// Helper to create edge key (sorted vertex indices)
+const make_edge_key = (v0_idx, v1_idx) => `${Math.min(v0_idx, v1_idx)},${Math.max(v0_idx, v1_idx)}`;
+// Compute intersection point on an edge
+function compute_edge_intersection(surface, vertex_distances, v0_idx, v1_idx) {
+    const d0 = vertex_distances[v0_idx];
+    const d1 = vertex_distances[v1_idx];
+    // Edge must cross the plane (opposite signs)
+    if (d0 * d1 >= 0)
+        return null;
+    const t = 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]),
+    ];
+    let property;
+    if (surface.properties) {
+        property =
+            surface.properties[v0_idx] +
+                t * (surface.properties[v1_idx] - surface.properties[v0_idx]);
+    }
+    return { point, property };
+}
+// Slice a surface with a plane to get isolines
+// Uses contour tracing to produce properly ordered line segments
+function slice_surface_with_plane(surface, plane_normal, plane_distance, in_plane_u, in_plane_v) {
+    if (surface.vertices.length === 0 || surface.faces.length === 0)
+        return [];
+    // Compute signed distance of each vertex to plane
+    const vertex_distances = surface.vertices.map((vert) => math.dot(vert, plane_normal) - plane_distance);
+    const face_segments = [];
+    const edge_to_faces = new Map(); // edge_key -> face indices
+    for (let face_idx = 0; face_idx < surface.faces.length; face_idx++) {
+        const face = surface.faces[face_idx];
+        if (face.length < 3)
+            continue;
+        // Find which edges of this face cross the plane
+        const crossing_edges = [];
+        for (let edge_idx = 0; edge_idx < face.length; edge_idx++) {
+            const v0_idx = face[edge_idx];
+            const v1_idx = face[(edge_idx + 1) % face.length];
+            const edge_key = make_edge_key(v0_idx, v1_idx);
+            const intersection = compute_edge_intersection(surface, vertex_distances, v0_idx, v1_idx);
+            if (intersection) {
+                crossing_edges.push({ edge_key, intersection });
+                // Register this face with the edge
+                const faces = edge_to_faces.get(edge_key) ?? [];
+                faces.push(face_idx);
+                edge_to_faces.set(edge_key, faces);
+            }
+        }
+        // A face intersected by a plane has exactly 2 crossing edges
+        if (crossing_edges.length === 2) {
+            face_segments.push({
+                face_idx,
+                edge_keys: [crossing_edges[0].edge_key, crossing_edges[1].edge_key],
+                points: [crossing_edges[0].intersection.point, crossing_edges[1].intersection.point],
+                properties: surface.properties
+                    ? [
+                        crossing_edges[0].intersection.property ?? 0,
+                        crossing_edges[1].intersection.property ?? 0,
+                    ]
+                    : undefined,
+            });
+        }
+    }
+    if (face_segments.length === 0)
+        return [];
+    // Build face_idx -> segment map for O(1) lookup
+    const face_to_segment = new Map();
+    for (const seg of face_segments) {
+        face_to_segment.set(seg.face_idx, seg);
+    }
+    // Precompute in-plane basis dot products for faster 2D projection
+    const [ux, uy, uz] = in_plane_u;
+    const [vx, vy, vz] = in_plane_v;
+    // Trace connected contours by following adjacent faces
+    const used_faces = new Set();
+    const isolines = [];
+    for (const start_segment of face_segments) {
+        if (used_faces.has(start_segment.face_idx))
+            continue;
+        // Start a new contour from this segment
+        // Use arrays that we'll reverse at the end instead of unshift (O(1) vs O(n))
+        const forward_points = [start_segment.points[1]];
+        const backward_points = [];
+        const forward_props = start_segment.properties
+            ? [start_segment.properties[1]]
+            : undefined;
+        const backward_props = start_segment.properties ? [] : undefined;
+        used_faces.add(start_segment.face_idx);
+        // Helper to trace in one direction
+        const trace_direction = (initial_edge, points, props) => {
+            let current_edge = initial_edge;
+            let found_next = true;
+            while (found_next) {
+                found_next = false;
+                const adjacent_faces = edge_to_faces.get(current_edge);
+                if (!adjacent_faces)
+                    break;
+                for (const adj_face_idx of adjacent_faces) {
+                    if (used_faces.has(adj_face_idx))
+                        continue;
+                    const adj_segment = face_to_segment.get(adj_face_idx);
+                    if (!adj_segment)
+                        continue;
+                    // Find which end connects to current_edge
+                    let next_point_idx;
+                    let next_edge;
+                    if (adj_segment.edge_keys[0] === current_edge) {
+                        next_point_idx = 1;
+                        next_edge = adj_segment.edge_keys[1];
+                    }
+                    else if (adj_segment.edge_keys[1] === current_edge) {
+                        next_point_idx = 0;
+                        next_edge = adj_segment.edge_keys[0];
+                    }
+                    else {
+                        continue;
+                    }
+                    points.push(adj_segment.points[next_point_idx]);
+                    if (props && adj_segment.properties) {
+                        props.push(adj_segment.properties[next_point_idx]);
+                    }
+                    used_faces.add(adj_face_idx);
+                    current_edge = next_edge;
+                    found_next = true;
+                    break;
+                }
+            }
+        };
+        // Trace forward and backward
+        trace_direction(start_segment.edge_keys[1], forward_points, forward_props);
+        trace_direction(start_segment.edge_keys[0], backward_points, backward_props);
+        // Combine: backward (reversed) + start_point[0] + forward
+        backward_points.reverse();
+        if (backward_props)
+            backward_props.reverse();
+        const contour_points = [
+            ...backward_points,
+            start_segment.points[0],
+            ...forward_points,
+        ];
+        const contour_props = backward_props && forward_props && start_segment.properties
+            ? [...backward_props, start_segment.properties[0], ...forward_props]
+            : undefined;
+        // Check if contour is closed
+        const first = contour_points[0];
+        const last = contour_points[contour_points.length - 1];
+        const is_closed = math.euclidean_dist(first, last) < CLOSED_CONTOUR_TOLERANCE;
+        // Project to 2D (inlined dot product for speed)
+        const points_2d = Array(contour_points.length);
+        for (let idx = 0; idx < contour_points.length; idx++) {
+            const point = contour_points[idx];
+            points_2d[idx] = [
+                point[0] * ux + point[1] * uy + point[2] * uz,
+                point[0] * vx + point[1] * vy + point[2] * vz,
+            ];
+        }
+        isolines.push({
+            points: contour_points,
+            points_2d,
+            properties: contour_props,
+            band_index: surface.band_index,
+            spin: surface.spin,
+            is_closed,
+        });
+    }
+    return isolines;
+}
+// Detect if Fermi surface data appears to cover only the irreducible BZ wedge.
+// For cubic Oh symmetry, this is the region where all vertices are in the first octant
+// (x >= 0, y >= 0, z >= 0) with some tolerance. Such data needs tiling to show the full BZ.
+export function detect_irreducible_bz(fermi_data) {
+    if (fermi_data.isosurfaces.length === 0)
+        return false;
+    // Check if all vertices are in the positive octant (with small tolerance for numerical error)
+    let all_positive = true;
+    let vertex_count = 0;
+    for (const surface of fermi_data.isosurfaces) {
+        for (const vertex of surface.vertices) {
+            vertex_count++;
+            if (vertex[0] < -IRREDUCIBLE_BZ_TOLERANCE ||
+                vertex[1] < -IRREDUCIBLE_BZ_TOLERANCE ||
+                vertex[2] < -IRREDUCIBLE_BZ_TOLERANCE) {
+                all_positive = false;
+                break;
+            }
+        }
+        if (!all_positive)
+            break;
+    }
+    // Only consider it irreducible if we have significant data and all positive
+    return all_positive && vertex_count > IRREDUCIBLE_BZ_MIN_VERTICES;
+}