matterviz 0.3.6 → 0.4.0

package/dist/brillouin/compute.js

@@ -0,0 +1,422 @@
+// Brillouin zone generation via convex hull
+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.
+// Returns fractional-coordinate rotations (W matrices from spglib convention).
+// These must be converted to Cartesian k-space before use in clipping.
+export function extract_point_group_from_operations(operations) {
+    const seen = new Set();
+    const unique_rotations = [];
+    for (const { rotation } of operations) {
+        const key = rotation.map((val) => val.toFixed(6)).join(`,`);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // moyo serializes rotations COLUMN-major; vec9_to_mat3x3 reads row-major → transpose to get W
+        const rot = math.transpose_3x3_matrix(math.vec9_to_mat3x3(Array.from(rotation)));
+        unique_rotations.push(rot);
+    }
+    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.
+export function fractional_to_cartesian_rotation(W, k_lattice) {
+    try {
+        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));
+    }
+    catch {
+        // Fallback to identity if inversion fails (shouldn't happen for valid rotations)
+        return [
+            [1, 0, 0],
+            [0, 1, 0],
+            [0, 0, 1],
+        ];
+    }
+}
+// Compute reciprocal lattice: k = inv(real).T * 2π
+export function reciprocal_lattice(real_lattice) {
+    const inv = math.matrix_inverse_3x3(real_lattice);
+    const transposed = math.transpose_3x3_matrix(inv);
+    return transposed.map((row) => math.scale(row, 2 * Math.PI));
+}
+// Generate k-space grid with size based on BZ order
+function generate_k_space_grid(k_lattice, order) {
+    const points = [];
+    // For order n, we need to include points up to ±n to capture all nearest neighbors
+    const range = Math.max(1, order);
+    for (let idx_i = -range; idx_i <= range; idx_i++) {
+        for (let idx_j = -range; idx_j <= range; idx_j++) {
+            for (let idx_k = -range; idx_k <= range; idx_k++) {
+                const point = math.add(math.scale(k_lattice[0], idx_i), math.scale(k_lattice[1], idx_j), math.scale(k_lattice[2], idx_k));
+                points.push(point);
+            }
+        }
+    }
+    return points;
+}
+// O(1) duplicate vertex detection using spatial hashing
+class VertexDeduplicator {
+    grid = new Map();
+    cell_size;
+    constructor(cell_size) {
+        this.cell_size = cell_size;
+    }
+    has_duplicate(vertex) {
+        const [base_x, base_y, base_z] = vertex.map((val) => Math.floor(val / this.cell_size));
+        for (let dx = -1; dx <= 1; dx++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dz = -1; dz <= 1; dz++) {
+                    const neighbors = this.grid.get(`${base_x + dx},${base_y + dy},${base_z + dz}`);
+                    if (neighbors?.some(([v1, v2, v3]) => Math.abs(v1 - vertex[0]) < TOL &&
+                        Math.abs(v2 - vertex[1]) < TOL &&
+                        Math.abs(v3 - vertex[2]) < TOL))
+                        return true;
+                }
+            }
+        }
+        return false;
+    }
+    add(vertex) {
+        const key = vertex.map((vert) => Math.floor(vert / this.cell_size)).join(`,`);
+        const cell = this.grid.get(key);
+        if (cell)
+            cell.push(vertex);
+        else
+            this.grid.set(key, [vertex]);
+    }
+}
+// Find intersection of three Bragg planes by solving N·v = d
+function intersect_planes(p1, p2, p3) {
+    try {
+        const matrix = [p1.normal, p2.normal, p3.normal];
+        const distances = [p1.dist, p2.dist, p3.dist];
+        return math.mat3x3_vec3_multiply(math.matrix_inverse_3x3(matrix), distances);
+    }
+    catch {
+        return null;
+    }
+}
+// Generate BZ vertices for nth-order zone via three-plane intersections
+export function generate_bz_vertices(k_lattice, order = 1, 
+// Maximum number of Bragg planes to consider for each BZ order.
+// Limits the number of three-plane intersections tested (O(n³) operation).
+// Higher values give more accurate zones but increase computation time significantly.
+// Default values: 26 (1st order), 80 (2nd order), 150 (3rd+ order)
+max_planes_by_order = { 1: 26, 2: 80, 3: 150 }) {
+    if (order > 3)
+        order = 3; // Performance limit
+    const k_points = generate_k_space_grid(k_lattice, order);
+    const center_idx = Math.floor(k_points.length / 2);
+    // Determine max planes for this order (default to highest value for orders > 3)
+    const max_planes = max_planes_by_order[order] ?? 150;
+    // Create Bragg planes (perpendicular bisectors of k-points)
+    const planes = k_points
+        .map((pt, idx) => {
+        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 };
+    })
+        .filter((plane) => plane !== null)
+        .sort((a, b) => a.dist_sq - b.dist_sq)
+        .slice(0, max_planes);
+    // Pre-compute plane data for fast access
+    const normals = planes.map((plane) => plane.normal);
+    const distances = planes.map((plane) => plane.dist);
+    const dedup = new VertexDeduplicator(TOL * 10);
+    const vertices = [];
+    // Test all three-plane intersections
+    for (let idx_i = 0; idx_i < planes.length; idx_i++) {
+        for (let idx_j = idx_i + 1; idx_j < planes.length; idx_j++) {
+            for (let idx_k = idx_j + 1; idx_k < planes.length; idx_k++) {
+                const vertex = intersect_planes(planes[idx_i], planes[idx_j], planes[idx_k]);
+                if (!vertex)
+                    continue;
+                // Count how many planes this vertex is beyond (with early termination)
+                let beyond_count = 0;
+                for (let p_idx = 0; p_idx < normals.length; p_idx++) {
+                    const dot = vertex[0] * normals[p_idx][0] +
+                        vertex[1] * normals[p_idx][1] +
+                        vertex[2] * normals[p_idx][2];
+                    if (dot > distances[p_idx] + TOL) {
+                        beyond_count++;
+                        if (beyond_count >= order)
+                            break;
+                    }
+                }
+                // Vertex belongs to nth BZ if it's beyond fewer than n planes
+                if (beyond_count < order && !dedup.has_duplicate(vertex)) {
+                    vertices.push(vertex);
+                    dedup.add(vertex);
+                }
+            }
+        }
+    }
+    return vertices;
+}
+// Compute polyhedron volume via divergence theorem (sum of signed tetrahedral volumes)
+function compute_hull_volume(vertices, faces) {
+    if (faces.length === 0)
+        return 0;
+    return Math.abs(faces.reduce((sum, face) => {
+        if (face.length < 3)
+            return sum;
+        const [v0, v1, v2] = face.slice(0, 3).map((idx) => vertices[idx]);
+        const area_normal = math.scale(math.cross_3d(math.subtract(v1, v0), math.subtract(v2, v0)), 0.5);
+        return sum + math.dot(v0, area_normal) / 3;
+    }, 0));
+}
+// Build convex hull from vertices and extract topology
+export function compute_convex_hull(vertices, edge_sharp_angle_deg = 5) {
+    if (vertices.length < 4) {
+        throw new Error(`Need ≥4 vertices for convex hull, got ${vertices.length}`);
+    }
+    const geometry = new ConvexGeometry(vertices.map((vertex) => new Vector3(...vertex)));
+    const pos = geometry.getAttribute(`position`);
+    const geometry_index = geometry.index;
+    // Deduplicate vertices from Three.js geometry
+    const unique_verts = [];
+    const vert_map = new Map();
+    for (let idx_vertex = 0; idx_vertex < pos.count; idx_vertex++) {
+        const vert = [pos.getX(idx_vertex), pos.getY(idx_vertex), pos.getZ(idx_vertex)];
+        const existing_idx = unique_verts.findIndex((unique_vert) => Math.abs(unique_vert[0] - vert[0]) < TOL &&
+            Math.abs(unique_vert[1] - vert[1]) < TOL &&
+            Math.abs(unique_vert[2] - vert[2]) < TOL);
+        vert_map.set(idx_vertex, existing_idx === -1 ? unique_verts.push(vert) - 1 : existing_idx);
+    }
+    // Build faces with deduplicated vertex indices
+    const faces = [];
+    const n_faces = geometry_index ? geometry_index.count / 3 : pos.count / 3;
+    for (let idx_face = 0; idx_face < n_faces; idx_face++) {
+        const tri = geometry_index
+            ? [
+                geometry_index.getX(idx_face * 3),
+                geometry_index.getX(idx_face * 3 + 1),
+                geometry_index.getX(idx_face * 3 + 2),
+            ]
+            : [idx_face * 3, idx_face * 3 + 1, idx_face * 3 + 2];
+        faces.push(tri.map((vertex_idx) => {
+            const mapped = vert_map.get(vertex_idx);
+            if (mapped === undefined)
+                throw new Error(`Vertex ${vertex_idx} not mapped`);
+            return mapped;
+        }));
+    }
+    // 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)));
+    });
+    const edge_to_faces = new Map();
+    faces.forEach((face, face_idx) => {
+        face.forEach((from_vertex_idx, idx) => {
+            const to_vertex_idx = face[(idx + 1) % face.length];
+            const key = from_vertex_idx < to_vertex_idx
+                ? `${from_vertex_idx},${to_vertex_idx}`
+                : `${to_vertex_idx},${from_vertex_idx}`;
+            const adj = edge_to_faces.get(key);
+            if (adj)
+                adj.push(face_idx);
+            else
+                edge_to_faces.set(key, [face_idx]);
+        });
+    });
+    // Extract edges: keep boundary edges or sharp angles
+    const cos_threshold = Math.cos((edge_sharp_angle_deg * Math.PI) / 180);
+    const edges = [];
+    for (const [key, adj] of edge_to_faces) {
+        const is_sharp = adj.length === 1 ||
+            (adj.length === 2 &&
+                math.dot(face_normals[adj[0]], face_normals[adj[1]]) < cos_threshold);
+        if (is_sharp)
+            edges.push(key.split(`,`).map(Number));
+    }
+    geometry.dispose();
+    return { vertices: unique_verts, faces, edges };
+}
+// Compute complete Brillouin zone with topology and volume
+export function compute_brillouin_zone(k_lattice, order = 1, edge_sharp_angle_deg = 5, // Angle threshold for edge extraction (default 5°, increase for fewer edges, decrease for more)
+max_planes_by_order = { 1: 26, 2: 80, 3: 150 }) {
+    const vertices = generate_bz_vertices(k_lattice, order, max_planes_by_order);
+    if (vertices.length < 4) {
+        throw new Error(`Insufficient vertices for BZ (got ${vertices.length}, need ≥4)`);
+    }
+    const hull = compute_convex_hull(vertices, edge_sharp_angle_deg);
+    return {
+        order,
+        vertices: hull.vertices,
+        faces: hull.faces,
+        edges: hull.edges.map(([i1, i2]) => [hull.vertices[i1], hull.vertices[i2]]),
+        k_lattice,
+        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
+];
+// Compute clipping planes from point group operations.
+// For each non-identity rotation, we define a plane that selects one representative
+// from each equivalence class.
+export function compute_ibz_clipping_planes(point_group_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;
+        }
+    }
+    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;
+    const signed_dists = vertices.map((vertex) => math.dot(vertex, normal) - dist);
+    // Keep vertices inside the half-space
+    const result = vertices.filter((_, idx) => signed_dists[idx] <= TOL);
+    // Build edge set from faces
+    const edge_set = new Set();
+    for (const face of faces) {
+        for (let idx = 0; idx < face.length; idx++) {
+            const i1 = face[idx];
+            const i2 = face[(idx + 1) % face.length];
+            edge_set.add(i1 < i2 ? `${i1},${i2}` : `${i2},${i1}`);
+        }
+    }
+    // Add intersection points where edges cross the plane
+    for (const key of edge_set) {
+        const [i1, i2] = key.split(`,`).map(Number);
+        const d1 = signed_dists[i1];
+        const d2 = signed_dists[i2];
+        // Edge crosses plane if exactly one endpoint is inside the half-space
+        const inside1 = d1 <= TOL;
+        const inside2 = d2 <= TOL;
+        if (inside1 !== inside2) {
+            const denom = d1 - d2;
+            // Skip if denominator too small (tighter than TOL for numerical stability)
+            if (Math.abs(denom) < 1e-12)
+                continue;
+            const t = d1 / denom;
+            // Only add intersection if it's not at an endpoint (which is already kept)
+            if (t > TOL && t < 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]),
+                ]);
+            }
+        }
+    }
+    return result;
+}
+// Try to build hull from vertices, returns null on failure
+function try_build_hull(vertices, edge_sharp_angle_deg) {
+    if (vertices.length < 4)
+        return null;
+    try {
+        return compute_convex_hull(vertices, edge_sharp_angle_deg);
+    }
+    catch {
+        return null;
+    }
+}
+// Compute the irreducible Brillouin zone by clipping the full BZ with symmetry planes
+export function compute_irreducible_bz(bz_data, point_group_ops, edge_sharp_angle_deg = 5) {
+    // Convert fractional rotations to Cartesian k-space rotations
+    // R_cart = Bᵀ · W^{-T} · B^{-T}, where B is k_lattice (reciprocal vectors as rows)
+    const cartesian_ops = point_group_ops.map((W) => fractional_to_cartesian_rotation(W, bz_data.k_lattice));
+    const clipping_planes = compute_ibz_clipping_planes(cartesian_ops);
+    if (clipping_planes.length === 0) {
+        // No symmetry (P1), IBZ = full BZ
+        return {
+            vertices: [...bz_data.vertices],
+            faces: [...bz_data.faces],
+            edges: [...bz_data.edges],
+            volume: bz_data.volume,
+        };
+    }
+    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;
+            }
+        }
+        // If both orientations failed, vertices unchanged - continue with best effort
+        if (!clipped_successfully) {
+            console.warn(`IBZ clipping: plane orientation failed, continuing with current geometry`);
+        }
+    }
+    const hull = try_build_hull(current_vertices, edge_sharp_angle_deg);
+    if (!hull)
+        return null;
+    return {
+        vertices: hull.vertices,
+        faces: hull.faces,
+        edges: hull.edges.map(([i1, i2]) => [hull.vertices[i1], hull.vertices[i2]]),
+        volume: compute_hull_volume(hull.vertices, hull.faces),
+    };
+}

package/dist/brillouin/index.d.ts

@@ -0,0 +1,8 @@
+export { default as BrillouinZone } from './BrillouinZone.svelte';
+export { default as BrillouinZoneControls } from './BrillouinZoneControls.svelte';
+export { default as BrillouinZoneExportPane } from './BrillouinZoneExportPane.svelte';
+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 type * from './types';

package/dist/brillouin/index.js

@@ -0,0 +1,7 @@
+export { default as BrillouinZone } from './BrillouinZone.svelte';
+export { default as BrillouinZoneControls } from './BrillouinZoneControls.svelte';
+export { default as BrillouinZoneExportPane } from './BrillouinZoneExportPane.svelte';
+export { default as BrillouinZoneInfoPane } from './BrillouinZoneInfoPane.svelte';
+export { default as BrillouinZoneScene } from './BrillouinZoneScene.svelte';
+export { default as BrillouinZoneTooltip } from './BrillouinZoneTooltip.svelte';
+export * from './compute';

package/dist/brillouin/types.d.ts

@@ -0,0 +1,43 @@
+import type { Matrix3x3, Point2D, Vec3 } from '../math';
+import type { Crystal } from '../structure';
+import type { TooltipConfig, TooltipProp } from '../tooltip';
+export type BZHoverData = {
+    position_cartesian: Vec3;
+    position_fractional: Vec3 | null;
+    screen_position: Point2D;
+    is_ibz: boolean;
+    bz_order: number;
+    bz_volume: number;
+    ibz_volume: number | null;
+    symmetry_multiplicity: number | null;
+};
+export type BZTooltipConfig = TooltipConfig<BZHoverData>;
+export type BZTooltipProp = TooltipProp<BZHoverData, [{
+    hover_data: BZHoverData;
+}]>;
+type BZMeshData = {
+    vertices: Vec3[];
+    faces: number[][];
+    edges: Vec3[][];
+};
+export type IrreducibleBZData = BZMeshData & {
+    volume: number;
+};
+export type BrillouinZoneData = BZMeshData & {
+    order: number;
+    k_lattice: Matrix3x3;
+    volume: number;
+};
+export type BrillouinZoneProps = {
+    structure: Crystal;
+    bz_order?: number;
+    surface_color?: string;
+    surface_opacity?: number;
+    edge_color?: string;
+    edge_width?: number;
+    show_vectors?: boolean;
+};
+export type ConvexHullData = Pick<BZMeshData, `vertices` | `faces`> & {
+    edges: [number, number][];
+};
+export {};

package/dist/brillouin/types.js

@@ -0,0 +1 @@
+export {};