matterviz 0.4.0 → 0.4.1

package/dist/brillouin/compute.js

@@ -3,10 +3,6 @@ import * as math from '../math';
 import { Vector3 } from 'three';
 import { ConvexGeometry } from 'three/examples/jsm/geometries/ConvexGeometry.js';
 const TOL = 1e-8;
-const normalize = (vec) => {
-    const mag = Math.hypot(...vec);
-    return mag < 1e-10 ? [0, 0, 0] : [vec[0] / mag, vec[1] / mag, vec[2] / mag];
-};
 // Check if rotation matrix is identity
 const is_identity_rotation = (rot) => rot.every((row, idx) => row.every((val, jdx) => Math.abs(val - (idx === jdx ? 1 : 0)) < TOL));
 // Extract unique point group rotation matrices from space group operations.
@@ -26,20 +22,6 @@ export function extract_point_group_from_operations(operations) {
     }
     return unique_rotations;
 }
-// Multiply two 3x3 matrices: C = A · B
-function mat3x3_multiply(A, B) {
-    const result = [
-        [0, 0, 0],
-        [0, 0, 0],
-        [0, 0, 0],
-    ];
-    for (let row = 0; row < 3; row++) {
-        for (let col = 0; col < 3; col++) {
-            result[row][col] = A[row][0] * B[0][col] + A[row][1] * B[1][col] + A[row][2] * B[2][col];
-        }
-    }
-    return result;
-}
 // Convert fractional rotation W to Cartesian k-space rotation. k_lattice stores reciprocal
 // vectors as ROWS (k_cart = Bᵀ·q) and reciprocal fractional rotation is q' = W^{-T}·q, so
 // R_cart = Bᵀ·W^{-T}·B^{-T}. For non-orthogonal lattices W^{-1} ≠ Wᵀ, so the transpose matters.
@@ -48,7 +30,7 @@ export function fractional_to_cartesian_rotation(W, k_lattice) {
         const B_T = math.transpose_3x3_matrix(k_lattice);
         const W_inv_T = math.transpose_3x3_matrix(math.matrix_inverse_3x3(W));
         // R_cart = Bᵀ · W^{-T} · B^{-T}
-        return mat3x3_multiply(mat3x3_multiply(B_T, W_inv_T), math.matrix_inverse_3x3(B_T));
+        return math.dot(math.dot(B_T, W_inv_T), math.matrix_inverse_3x3(B_T));
     }
     catch {
         // Fallback to identity if inversion fails (shouldn't happen for valid rotations)
@@ -141,7 +123,11 @@ max_planes_by_order = { 1: 26, 2: 80, 3: 150 }) {
         if (idx === center_idx)
             return null;
         const dist_sq = pt[0] ** 2 + pt[1] ** 2 + pt[2] ** 2;
-        return { normal: normalize(pt), dist: Math.sqrt(dist_sq) / 2, dist_sq };
+        return {
+            normal: math.normalize_vec(pt, [0, 0, 0]),
+            dist: Math.sqrt(dist_sq) / 2,
+            dist_sq,
+        };
     })
         .filter((plane) => plane !== null)
         .sort((a, b) => a.dist_sq - b.dist_sq)
@@ -231,7 +217,7 @@ export function compute_convex_hull(vertices, edge_sharp_angle_deg = 5) {
     // Compute face normals and build edge-to-face adjacency
     const face_normals = faces.map((face) => {
         const [v0, v1, v2] = face.slice(0, 3).map((vertex_idx) => unique_verts[vertex_idx]);
-        return normalize(math.cross_3d(math.subtract(v1, v0), math.subtract(v2, v0)));
+        return math.normalize_vec(math.cross_3d(math.subtract(v1, v0), math.subtract(v2, v0)), [0, 0, 0]);
     });
     const edge_to_faces = new Map();
     faces.forEach((face, face_idx) => {
@@ -277,51 +263,72 @@ max_planes_by_order = { 1: 26, 2: 80, 3: 150 }) {
         volume: compute_hull_volume(hull.vertices, hull.faces),
     };
 }
-// Test points for IBZ plane detection. These are chosen to:
-// 1. Avoid common rotation axes (2-fold, 3-fold, 4-fold, 6-fold)
-// 2. Span different directions to catch all symmetry operations
-// 3. Include a generic point [1,2,3] that lies on no special axis
-const IBZ_TEST_POINTS = [
-    [1, 0, 0],
-    [0, 1, 0],
-    [0, 0, 1], // basis vectors (avoid 4-fold axes)
-    [1, 1, 0],
-    [1, 0, 1],
-    [0, 1, 1], // face diagonals (avoid 2-fold axes)
-    [1, 1, 1], // body diagonal (avoid 3-fold axis)
-    [1, 2, 3], // generic point on no special axis
+// Generic reference directions for the Dirichlet-domain construction. Irrational-ish
+// component ratios keep them off every rotation axis and mirror plane of crystallographic
+// point groups in practice; the later directions are fallbacks in case a pathological
+// Cartesian orientation pins the first onto a symmetry element.
+export const IBZ_REFERENCE_DIRECTIONS = [
+    [1, Math.SQRT2 / 3, Math.E / 7],
+    [Math.PI / 5, 1, Math.SQRT1_2 / 4],
+    [Math.E / 9, Math.LN2, 1],
 ];
-// Compute clipping planes from point group operations.
-// For each non-identity rotation, we define a plane that selects one representative
-// from each equivalence class.
+// A reference direction is valid for the Dirichlet construction iff it has a trivial
+// stabilizer: no non-identity operation fixes it (R·t ≠ t for every R). Such a direction
+// always exists because the fixed-point sets (rotation axes, mirror planes) have measure
+// zero. Try the curated generic directions first, then deterministic pseudo-random ones,
+// and throw in the (mathematically unreachable) case where none qualify — rather than
+// silently using a non-generic direction, which would drop that operation's clipping
+// plane and inflate the IBZ volume above V_BZ/|G|.
+export function find_ibz_reference_direction(non_identity_ops) {
+    const has_trivial_stabilizer = (dir) => non_identity_ops.every((rot) => Math.hypot(...math.subtract(math.mat3x3_vec3_multiply(rot, dir), dir)) > TOL);
+    const curated = IBZ_REFERENCE_DIRECTIONS.find(has_trivial_stabilizer);
+    if (curated)
+        return curated;
+    // Park-Miller minstd PRNG (safe-integer arithmetic) keeps the rare fallback
+    // reproducible across runs while sampling generic directions
+    let seed = 16807;
+    const next_component = () => {
+        seed = (seed * 16807) % 2147483647;
+        return (seed / 2147483647) * 2 - 1;
+    };
+    for (let attempt = 0; attempt < 128; attempt++) {
+        const dir = [next_component(), next_component(), next_component()];
+        if (Math.hypot(...dir) > 0.1 && has_trivial_stabilizer(dir))
+            return dir;
+    }
+    throw new Error(`IBZ construction: no generic reference direction found for ${non_identity_ops.length} symmetry operations`);
+}
+// Compute clipping planes from point group operations via the Dirichlet (Voronoi)
+// fundamental-domain construction: pick ONE generic direction t with trivial stabilizer,
+// then for every non-identity operation R keep the half-space x·t ≥ x·(R·t), i.e.
+// (R·t − t)·x ≤ 0. Intersecting all half-spaces with the BZ yields an irreducible wedge
+// of exactly volume(BZ)/|G|. (Using a different reference point per operation — or
+// flipping individual planes — does NOT yield a fundamental domain in general.)
 export function compute_ibz_clipping_planes(point_group_ops) {
+    const non_identity_ops = point_group_ops.filter((rot) => !is_identity_rotation(rot));
+    if (non_identity_ops.length === 0)
+        return [];
+    const ref_dir = find_ibz_reference_direction(non_identity_ops);
     const planes = [];
     const seen_normals = new Set();
-    for (const rot of point_group_ops) {
-        if (is_identity_rotation(rot))
-            continue;
-        for (const test_pt of IBZ_TEST_POINTS) {
-            const rotated = math.mat3x3_vec3_multiply(rot, test_pt);
-            const diff = math.subtract(rotated, test_pt);
-            if (Math.hypot(...diff) < TOL)
-                continue; // point on rotation axis
-            const plane_normal = normalize(diff);
-            const key = plane_normal.map((val) => Math.round(val * 1000)).join(`,`);
-            const neg_key = plane_normal.map((val) => Math.round(-val * 1000)).join(`,`);
-            if (!seen_normals.has(key) && !seen_normals.has(neg_key)) {
-                seen_normals.add(key);
-                planes.push({ normal: plane_normal, dist: 0 });
-            }
-            break;
+    for (const rot of non_identity_ops) {
+        const rotated = math.mat3x3_vec3_multiply(rot, ref_dir);
+        const diff = math.subtract(rotated, ref_dir);
+        // ref_dir has a trivial stabilizer, so every op must move it; a zero diff would
+        // silently drop a plane and inflate the IBZ — surface it instead
+        if (Math.hypot(...diff) < TOL) {
+            throw new Error(`IBZ construction: reference direction unexpectedly fixed by an operation`);
+        }
+        const plane_normal = math.normalize_vec(diff, [0, 0, 0]);
+        // NOTE: do NOT merge antiparallel normals — n and −n select opposite half-spaces
+        const key = plane_normal.map((val) => Math.round(val * 1e6)).join(`,`);
+        if (!seen_normals.has(key)) {
+            seen_normals.add(key);
+            planes.push({ normal: plane_normal, dist: 0 });
         }
     }
     return planes;
 }
-// Flip a clipping plane to the opposite half-space
-const flip_plane = (plane) => ({
-    normal: math.scale(plane.normal, -1),
-    dist: -plane.dist,
-});
 // Clip polyhedron vertices by a half-space, adding intersection points where edges cross
 function clip_polyhedron_by_plane(vertices, faces, plane) {
     const { normal, dist } = plane;
@@ -350,14 +357,14 @@ function clip_polyhedron_by_plane(vertices, faces, plane) {
             // Skip if denominator too small (tighter than TOL for numerical stability)
             if (Math.abs(denom) < 1e-12)
                 continue;
-            const t = d1 / denom;
+            const frac = d1 / denom;
             // Only add intersection if it's not at an endpoint (which is already kept)
-            if (t > TOL && t < 1 - TOL) {
+            if (frac > TOL && frac < 1 - TOL) {
                 const [v1, v2] = [vertices[i1], vertices[i2]];
                 result.push([
-                    v1[0] + t * (v2[0] - v1[0]),
-                    v1[1] + t * (v2[1] - v1[1]),
-                    v1[2] + t * (v2[2] - v1[2]),
+                    v1[0] + frac * (v2[0] - v1[0]),
+                    v1[1] + frac * (v2[1] - v1[1]),
+                    v1[2] + frac * (v2[2] - v1[2]),
                 ]);
             }
         }
@@ -393,21 +400,17 @@ export function compute_irreducible_bz(bz_data, point_group_ops, edge_sharp_angl
     let current_vertices = [...bz_data.vertices];
     let current_faces = [...bz_data.faces];
     for (const plane of clipping_planes) {
-        // Try clipping with plane, then flipped plane if needed
-        let clipped_successfully = false;
-        for (const try_plane of [plane, flip_plane(plane)]) {
-            const clipped = clip_polyhedron_by_plane(current_vertices, current_faces, try_plane);
-            const hull = try_build_hull(clipped, edge_sharp_angle_deg);
-            if (hull) {
-                current_vertices = hull.vertices;
-                current_faces = hull.faces;
-                clipped_successfully = true;
-                break;
-            }
+        // Planes from the Dirichlet construction are consistently oriented (the kept side
+        // n·x ≤ 0 always contains the reference direction) so clip directly — flipping a
+        // plane would select the wrong half-space and break the fundamental-domain property
+        const clipped = clip_polyhedron_by_plane(current_vertices, current_faces, plane);
+        const hull = try_build_hull(clipped, edge_sharp_angle_deg);
+        if (hull) {
+            current_vertices = hull.vertices;
+            current_faces = hull.faces;
         }
-        // If both orientations failed, vertices unchanged - continue with best effort
-        if (!clipped_successfully) {
-            console.warn(`IBZ clipping: plane orientation failed, continuing with current geometry`);
+        else {
+            console.warn(`IBZ clipping: degenerate clip result, skipping plane`);
         }
     }
     const hull = try_build_hull(current_vertices, edge_sharp_angle_deg);

package/dist/brillouin/geometry.d.ts

@@ -0,0 +1,8 @@
+import type { Matrix3x3, Vec3 } from '../math';
+import { BufferGeometry } from 'three';
+export declare function polyhedron_geometry(vertices: Vec3[], faces: number[][]): BufferGeometry | null;
+export declare function k_lattice_inverse(k_lattice: Matrix3x3 | undefined): Matrix3x3 | null;
+export declare const cartesian_to_fractional: (k_lattice_inv: Matrix3x3 | null, cart: Vec3) => Vec3 | null;
+export declare const polyhedron_centroid: (vertices: Vec3[] | undefined) => Vec3;
+export declare const k_space_size: (k_lattice: Matrix3x3 | undefined) => number;
+export declare const default_camera_position: (size: number) => Vec3;

package/dist/brillouin/geometry.js

@@ -0,0 +1,57 @@
+import * as math from '../math';
+import { BufferAttribute, BufferGeometry } from 'three';
+// Build a renderable mesh from polyhedron vertices + polygonal faces via fan triangulation with flat per-face normals. Assumes convex faces (true for BZ/IBZ polyhedra); non-convex faces would triangulate incorrectly. Shared by BrillouinZoneScene (BZ + IBZ meshes) and FermiSurfaceScene (BZ overlay). Caller owns disposal.
+export function polyhedron_geometry(vertices, faces) {
+    if (faces.length === 0)
+        return null;
+    const positions = [];
+    const normals = [];
+    for (const face of faces) {
+        if (face.length < 3)
+            continue;
+        for (let face_idx = 1; face_idx < face.length - 1; face_idx++) {
+            const indices = [face[0], face[face_idx], face[face_idx + 1]];
+            if (indices.some((idx) => idx < 0 || idx >= vertices.length))
+                continue;
+            const [vertex_a, vertex_b, vertex_c] = indices.map((idx) => vertices[idx]);
+            positions.push(...vertex_a, ...vertex_b, ...vertex_c);
+            const edge_ab = math.subtract(vertex_b, vertex_a);
+            const edge_ac = math.subtract(vertex_c, vertex_a);
+            const face_normal = math.cross_3d(edge_ab, edge_ac);
+            const normal_length = Math.hypot(...face_normal);
+            const unit_normal = normal_length > 1e-10 ? face_normal.map((coord) => coord / normal_length) : [0, 0, 0];
+            normals.push(...unit_normal, ...unit_normal, ...unit_normal);
+        }
+    }
+    // All faces degenerate or out-of-range -> no triangles, so return null instead of an empty geometry
+    if (positions.length === 0)
+        return null;
+    const geometry = new BufferGeometry();
+    geometry.setAttribute(`position`, new BufferAttribute(new Float32Array(positions), 3));
+    geometry.setAttribute(`normal`, new BufferAttribute(new Float32Array(normals), 3));
+    geometry.computeBoundingSphere();
+    return geometry;
+}
+// Inverse of the reciprocal lattice for Cartesian -> fractional conversion; null if the lattice is missing or singular
+export function k_lattice_inverse(k_lattice) {
+    if (!k_lattice)
+        return null;
+    try {
+        return math.matrix_inverse_3x3(k_lattice);
+    }
+    catch {
+        return null;
+    }
+}
+// Convert Cartesian k-coordinates to fractional (reciprocal lattice units); null if the (pre-computed) lattice inverse is unavailable
+export const cartesian_to_fractional = (k_lattice_inv, cart) => k_lattice_inv && math.mat3x3_vec3_multiply(k_lattice_inv, cart);
+// Centroid of polyhedron vertices, used as orbit/rotation target by BZ + Fermi scenes
+export const polyhedron_centroid = (vertices) => vertices?.length
+    ? math.scale(vertices.reduce((acc, vert) => math.add(acc, vert), [0, 0, 0]), 1 / vertices.length)
+    : [0, 0, 0];
+// Mean reciprocal-lattice vector magnitude: characteristic scene size for camera placement
+// and arrow scaling. Fallback 10 (upper end of typical |b_i| ~ 2pi/a in 1/A) keeps the
+// camera at a sensible distance while no data is loaded.
+export const k_space_size = (k_lattice) => k_lattice ? k_lattice.reduce((sum, vec) => sum + Math.hypot(...vec), 0) / 3 : 10;
+// Default camera position scaled to the scene size
+export const default_camera_position = (size) => [10, 3, 8].map((coord) => coord * Math.max(1, size));

package/dist/brillouin/index.d.ts

@@ -5,4 +5,6 @@ export { default as BrillouinZoneInfoPane } from './BrillouinZoneInfoPane.svelte
 export { default as BrillouinZoneScene } from './BrillouinZoneScene.svelte';
 export { default as BrillouinZoneTooltip } from './BrillouinZoneTooltip.svelte';
 export * from './compute';
+export * from './geometry';
+export { default as ReciprocalVectors } from './ReciprocalVectors.svelte';
 export type * from './types';

package/dist/brillouin/index.js

@@ -5,3 +5,5 @@ export { default as BrillouinZoneInfoPane } from './BrillouinZoneInfoPane.svelte
 export { default as BrillouinZoneScene } from './BrillouinZoneScene.svelte';
 export { default as BrillouinZoneTooltip } from './BrillouinZoneTooltip.svelte';
 export * from './compute';
+export * from './geometry';
+export { default as ReciprocalVectors } from './ReciprocalVectors.svelte';

package/dist/brillouin/types.d.ts

@@ -1,4 +1,4 @@
-import type { Matrix3x3, Point2D, Vec3 } from '../math';
+import type { Matrix3x3, Point2D, Vec2, Vec3 } from '../math';
 import type { Crystal } from '../structure';
 import type { TooltipConfig, TooltipProp } from '../tooltip';
 export type BZHoverData = {
@@ -38,6 +38,6 @@ export type BrillouinZoneProps = {
     show_vectors?: boolean;
 };
 export type ConvexHullData = Pick<BZMeshData, `vertices` | `faces`> & {
-    edges: [number, number][];
+    edges: Vec2[];
 };
 export {};

package/dist/chempot-diagram/ChemPotDiagram.svelte.d.ts

@@ -8,6 +8,6 @@ type $$ComponentProps = {
     temperature?: number;
     hover_info?: ChemPotHoverInfo | null;
 };
-declare const ChemPotDiagram: import("svelte").Component<$$ComponentProps, {}, "temperature" | "height" | "width" | "hover_info">;
+declare const ChemPotDiagram: import("svelte").Component<$$ComponentProps, {}, "height" | "width" | "temperature" | "hover_info">;
 type ChemPotDiagram = ReturnType<typeof ChemPotDiagram>;
 export default ChemPotDiagram;