matterviz 0.3.2 → 0.3.4

package/dist/math.js

@@ -14,6 +14,7 @@ export const LOG_EPS = 1e-9;
 export const EPS = 1e-10;
 export const RAD_TO_DEG = 180 / Math.PI;
 export const DEG_TO_RAD = Math.PI / 180;
+const MAX_MIN_IMAGE_CANDIDATES = 100_000;
 export const to_degrees = (radians) => radians * RAD_TO_DEG;
 export const to_radians = (degrees) => degrees * DEG_TO_RAD;
 // Calculate all lattice parameters in a single efficient pass
@@ -44,21 +45,70 @@ export const euclidean_dist = (vec1, vec2) => {
     }
     return Math.hypot(...vec1.map((x, idx) => x - vec2[idx]));
 };
+const vec3_norm_sq = (vec) => vec[0] ** 2 + vec[1] ** 2 + vec[2] ** 2;
+// Exact minimum-image displacement for row-vector lattices.
+// Rounded fractional wrapping is only approximate for highly skewed cells, so
+// we use it as a starting guess and then search the small set of shifts that
+// can still beat that Cartesian radius.
+export function min_image_displacement(from, to, lattice_matrix, converters, pbc = [true, true, true]) {
+    const { cart_to_frac, frac_to_cart, reciprocal_axis_norms } = converters ?? create_lattice_converters(lattice_matrix);
+    const frac_from = cart_to_frac(from);
+    const frac_to = cart_to_frac(to);
+    const frac_diff = [
+        frac_to[0] - frac_from[0],
+        frac_to[1] - frac_from[1],
+        frac_to[2] - frac_from[2],
+    ];
+    const wrapped_frac_diff = [
+        pbc[0] ? frac_diff[0] - Math.round(frac_diff[0]) : frac_diff[0],
+        pbc[1] ? frac_diff[1] - Math.round(frac_diff[1]) : frac_diff[1],
+        pbc[2] ? frac_diff[2] - Math.round(frac_diff[2]) : frac_diff[2],
+    ];
+    let best_displacement = frac_to_cart(wrapped_frac_diff);
+    let best_dist_sq = vec3_norm_sq(best_displacement);
+    const search_radius = Math.sqrt(best_dist_sq) + EPS;
+    const candidate_shift_ranges = [0, 1, 2].map((axis_idx) => {
+        if (!pbc[axis_idx])
+            return [0, 0];
+        const axis_bound = reciprocal_axis_norms[axis_idx] * search_radius;
+        return [
+            Math.ceil(-frac_diff[axis_idx] - axis_bound),
+            Math.floor(-frac_diff[axis_idx] + axis_bound),
+        ];
+    });
+    let candidate_count = 1;
+    for (const [shift_min, shift_max] of candidate_shift_ranges) {
+        candidate_count *= shift_max - shift_min + 1;
+        if (candidate_count > MAX_MIN_IMAGE_CANDIDATES) {
+            throw new Error(`Minimum-image search would test >${MAX_MIN_IMAGE_CANDIDATES} candidates ` +
+                `for lattice ${JSON.stringify(lattice_matrix)}; reciprocal norms=` +
+                `${JSON.stringify(reciprocal_axis_norms)} ranges=${JSON.stringify(candidate_shift_ranges)}`);
+        }
+    }
+    const [[i_min, i_max], [j_min, j_max], [k_min, k_max]] = candidate_shift_ranges;
+    // Only test integer shifts that reciprocal-space bounds say could still win.
+    for (let ii = i_min; ii <= i_max; ii++) {
+        for (let jj = j_min; jj <= j_max; jj++) {
+            for (let kk = k_min; kk <= k_max; kk++) {
+                const candidate_frac_diff = [
+                    frac_diff[0] + ii,
+                    frac_diff[1] + jj,
+                    frac_diff[2] + kk,
+                ];
+                const candidate_displacement = frac_to_cart(candidate_frac_diff);
+                const candidate_dist_sq = vec3_norm_sq(candidate_displacement);
+                if (candidate_dist_sq < best_dist_sq) {
+                    best_dist_sq = candidate_dist_sq;
+                    best_displacement = candidate_displacement;
+                }
+            }
+        }
+    }
+    return best_displacement;
+}
 // Calculate the minimum distance between two points considering periodic boundary conditions.
-export function pbc_dist(pos1, // First position vector (Cartesian coordinates)
-pos2, // Second position vector (Cartesian coordinates)
-lattice_matrix, // 3x3 lattice matrix where each row is a lattice vector
-lattice_inv, // Optional pre-computed inverse matrix for optimization (since lattice is usually constant and repeatedly inverting matrix is expensive)
-pbc = [true, true, true]) {
-    const inv_matrix = lattice_inv ?? matrix_inverse_3x3(lattice_matrix);
-    // Convert Cartesian coordinates to fractional coordinates
-    const [fx1, fy1, fz1] = mat3x3_vec3_multiply(inv_matrix, pos1);
-    const [fx2, fy2, fz2] = mat3x3_vec3_multiply(inv_matrix, pos2);
-    // Apply minimum image convention only for periodic axes
-    const wrapped_frac_diff = [fx1 - fx2, fy1 - fy2, fz1 - fz2].map((diff, idx) => pbc[idx] ? diff - Math.round(diff) : diff);
-    // Convert back to Cartesian coordinates
-    const cart_diff = mat3x3_vec3_multiply(lattice_matrix, wrapped_frac_diff);
-    return Math.hypot(...cart_diff);
+export function pbc_dist(pos1, pos2, lattice_matrix, converters, pbc = [true, true, true]) {
+    return Math.hypot(...min_image_displacement(pos1, pos2, lattice_matrix, converters, pbc));
 }
 export function matrix_inverse_3x3(matrix) {
     const [[m11, m12, m13], [m21, m22, m23], [m31, m32, m33]] = matrix;
@@ -106,7 +156,7 @@ export function add(...vecs) {
             throw new Error(`All vectors must have the same length`);
         }
     }
-    const result = new Array(length).fill(0);
+    const result = Array.from({ length }).fill(0);
     for (const vec of vecs) {
         for (let idx = 0; idx < length; idx++) {
             result[idx] += vec[idx];
@@ -192,7 +242,11 @@ export function from_voigt(voigt) {
         throw new Error(`Expected 6-element Voigt vector, got ${voigt.length} elements`);
     }
     const [v1, v2, v3, v4, v5, v6] = voigt;
-    return [[v1, v6, v5], [v6, v2, v4], [v5, v4, v3]];
+    return [
+        [v1, v6, v5],
+        [v6, v2, v4],
+        [v5, v4, v3],
+    ];
 }
 // Convert flat 9-element array to 3x3 tensor (row-major order)
 export function vec9_to_mat3x3(flat_array) {
@@ -200,7 +254,11 @@ export function vec9_to_mat3x3(flat_array) {
         throw new Error(`Expected 9-element array, got ${flat_array.length} elements`);
     }
     const [a1, a2, a3, a4, a5, a6, a7, a8, a9] = flat_array;
-    return [[a1, a2, a3], [a4, a5, a6], [a7, a8, a9]];
+    return [
+        [a1, a2, a3],
+        [a4, a5, a6],
+        [a7, a8, a9],
+    ];
 }
 // Convert 3x3 tensor to flat 9-element array (row-major order)
 export function tensor_to_flat_array(tensor) {
@@ -216,6 +274,18 @@ export const transpose_3x3_matrix = (matrix) => [
     [matrix[0][1], matrix[1][1], matrix[2][1]],
     [matrix[0][2], matrix[1][2], matrix[2][2]],
 ];
+// Scale each row of a 3x3 matrix by the corresponding element of a Vec3.
+// Used to scale lattice vectors by supercell factors.
+export function scale_lattice_matrix(orig_matrix, scaling_factors) {
+    const [nx, ny, nz] = scaling_factors;
+    const [a, b, c] = orig_matrix;
+    return [
+        [a[0] * nx, a[1] * nx, a[2] * nx],
+        [b[0] * ny, b[1] * ny, b[2] * ny],
+        [c[0] * nz, c[1] * nz, c[2] * nz],
+    ];
+}
+const create_cart_to_frac_matrix = (lattice) => matrix_inverse_3x3(transpose_3x3_matrix(lattice));
 // Curried fractional→Cartesian converter (caches transposed matrix)
 export const create_frac_to_cart = (lattice) => {
     const transposed = transpose_3x3_matrix(lattice);
@@ -223,8 +293,16 @@ export const create_frac_to_cart = (lattice) => {
 };
 // Curried Cartesian→fractional converter (caches inverse transpose)
 export const create_cart_to_frac = (lattice) => {
-    const inv_transposed = matrix_inverse_3x3(transpose_3x3_matrix(lattice));
-    return (cart) => mat3x3_vec3_multiply(inv_transposed, cart);
+    const cart_to_frac_mat = create_cart_to_frac_matrix(lattice);
+    return (cart) => mat3x3_vec3_multiply(cart_to_frac_mat, cart);
+};
+export const create_lattice_converters = (lattice) => {
+    const cart_to_frac_mat = create_cart_to_frac_matrix(lattice);
+    return {
+        cart_to_frac: (cart) => mat3x3_vec3_multiply(cart_to_frac_mat, cart),
+        frac_to_cart: create_frac_to_cart(lattice),
+        reciprocal_axis_norms: cart_to_frac_mat.map((row) => Math.hypot(...row)),
+    };
 };
 // Convert unit cell parameters to lattice matrix (crystallographic convention)
 export function cell_to_lattice_matrix(a, b, c, alpha, beta, gamma) {
@@ -237,11 +315,7 @@ export function cell_to_lattice_matrix(a, b, c, alpha, beta, gamma) {
     const cos_gamma = Math.cos(gamma_rad);
     const sin_gamma = Math.sin(gamma_rad);
     // Calculate volume factor for triclinic system
-    const vol_factor = Math.sqrt(1 -
-        cos_alpha ** 2 -
-        cos_beta ** 2 -
-        cos_gamma ** 2 +
-        2 * cos_alpha * cos_beta * cos_gamma);
+    const vol_factor = Math.sqrt(1 - cos_alpha ** 2 - cos_beta ** 2 - cos_gamma ** 2 + 2 * cos_alpha * cos_beta * cos_gamma);
     // Standard crystallographic lattice vectors
     const c_x = c * cos_beta;
     const c_y = (c * (cos_alpha - cos_beta * cos_gamma)) / sin_gamma;
@@ -256,7 +330,8 @@ export function det_3x3(matrix) {
     // |A| = a(ei − fh) − b(di − fg) + c(dh − eg)
     // where matrix = [[a, b, c], [d, e, f], [g, h, i]]
     const [[m00, m01, m02], [m10, m11, m12], [m20, m21, m22]] = matrix;
-    return (m00 * (m11 * m22 - m12 * m21) - m01 * (m10 * m22 - m12 * m20) +
+    return (m00 * (m11 * m22 - m12 * m21) -
+        m01 * (m10 * m22 - m12 * m20) +
         m02 * (m10 * m21 - m11 * m20));
 }
 export function get_coefficient_of_variation(values) {
@@ -264,9 +339,7 @@ export function get_coefficient_of_variation(values) {
         return 0;
     const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
     const variance = values.reduce((sum, val) => sum + (val - mean) ** 2, 0) / values.length;
-    return Math.abs(mean) > 1e-10
-        ? Math.sqrt(variance) / Math.abs(mean)
-        : Math.sqrt(variance);
+    return Math.abs(mean) > 1e-10 ? Math.sqrt(variance) / Math.abs(mean) : Math.sqrt(variance);
 }
 // Compute 4x4 determinant (used for 4D barycentric coordinates)
 export function det_4x4(matrix) {
@@ -275,42 +348,38 @@ export function det_4x4(matrix) {
     const [b0, b1, b2, b3] = b_row;
     const [c0, c1, c2, c3] = c_row;
     const [d0, d1, d2, d3] = d_row;
-    return (a0 *
-        (b1 * (c2 * d3 - c3 * d2) - b2 * (c1 * d3 - c3 * d1) + b3 * (c1 * d2 - c2 * d1)) -
-        a1 *
-            (b0 * (c2 * d3 - c3 * d2) - b2 * (c0 * d3 - c3 * d0) + b3 * (c0 * d2 - c2 * d0)) +
-        a2 *
-            (b0 * (c1 * d3 - c3 * d1) - b1 * (c0 * d3 - c3 * d0) + b3 * (c0 * d1 - c1 * d0)) -
+    return (a0 * (b1 * (c2 * d3 - c3 * d2) - b2 * (c1 * d3 - c3 * d1) + b3 * (c1 * d2 - c2 * d1)) -
+        a1 * (b0 * (c2 * d3 - c3 * d2) - b2 * (c0 * d3 - c3 * d0) + b3 * (c0 * d2 - c2 * d0)) +
+        a2 * (b0 * (c1 * d3 - c3 * d1) - b1 * (c0 * d3 - c3 * d0) + b3 * (c0 * d1 - c1 * d0)) -
         a3 * (b0 * (c1 * d2 - c2 * d1) - b1 * (c0 * d2 - c2 * d0) + b2 * (c0 * d1 - c1 * d0)));
 }
 // Compute NxN determinant using LU decomposition with partial pivoting
 // More numerically stable than cofactor expansion for N > 4
 // Returns 0 for singular/near-singular matrices (pivot < EPS ≈ 1e-10)
 export function det_nxn(matrix) {
-    const n = matrix.length;
-    if (n === 0)
+    const mat_size = matrix.length;
+    if (mat_size === 0)
         return 1;
-    if (!matrix.every((row) => row.length === n)) {
+    if (!matrix.every((row) => row.length === mat_size)) {
         throw new Error(`det_nxn requires a square matrix`);
     }
     // Fast paths for small matrices
-    if (n === 1)
+    if (mat_size === 1)
         return matrix[0][0];
-    if (n === 2)
+    if (mat_size === 2)
         return matrix[0][0] * matrix[1][1] - matrix[0][1] * matrix[1][0];
-    if (n === 3)
+    if (mat_size === 3)
         return det_3x3(matrix);
-    if (n === 4)
+    if (mat_size === 4)
         return det_4x4(matrix);
     // LU decomposition with partial pivoting
     // Create a working copy to avoid mutating input
     const lu = matrix.map((row) => [...row]);
     let swaps = 0;
-    for (let col = 0; col < n; col++) {
+    for (let col = 0; col < mat_size; col++) {
         // Find pivot (largest absolute value in column)
-        let max_row = col;
-        let max_val = Math.abs(lu[col][col]);
-        for (let row = col + 1; row < n; row++) {
+        let [max_row, max_val] = [col, Math.abs(lu[col][col])];
+        for (let row = col + 1; row < mat_size; row++) {
             const val = Math.abs(lu[row][col]);
             if (val > max_val) {
                 max_val = val;
@@ -328,17 +397,17 @@ export function det_nxn(matrix) {
         }
         // Eliminate below pivot
         const pivot = lu[col][col];
-        for (let row = col + 1; row < n; row++) {
+        for (let row = col + 1; row < mat_size; row++) {
             const factor = lu[row][col] / pivot;
             lu[row][col] = 0;
-            for (let k = col + 1; k < n; k++) {
+            for (let k = col + 1; k < mat_size; k++) {
                 lu[row][k] -= factor * lu[col][k];
             }
         }
     }
     // Determinant is product of diagonal elements × (-1)^swaps
     let det = swaps % 2 === 0 ? 1 : -1;
-    for (let idx = 0; idx < n; idx++) {
+    for (let idx = 0; idx < mat_size; idx++) {
         det *= lu[idx][idx];
     }
     return det;
@@ -370,8 +439,12 @@ export const centered_frac = (val) => {
 };
 // Element-wise equality check for two optional Vec3s.
 // Returns true if both are the same reference, or both are defined with equal components.
-export const vecs_equal = (vec_a, vec_b) => vec_a === vec_b || (!!vec_a && !!vec_b &&
-    vec_a[0] === vec_b[0] && vec_a[1] === vec_b[1] && vec_a[2] === vec_b[2]);
+export const vecs_equal = (vec_a, vec_b) => vec_a === vec_b ||
+    (!!vec_a &&
+        !!vec_b &&
+        vec_a[0] === vec_b[0] &&
+        vec_a[1] === vec_b[1] &&
+        vec_a[2] === vec_b[2]);
 // Normalize a Vec3 to unit length, returns zero vector if input is zero
 export function normalize_vec3(vec, fallback) {
     const len = Math.hypot(vec[0], vec[1], vec[2]);
@@ -393,7 +466,7 @@ export function compute_in_plane_basis(normal) {
     ];
     const u_vec = normalize_vec3(u_raw, [0, 1, 0]);
     const v_vec = cross_3d(normal, u_vec);
-    return [u_vec, v_vec];
+    return [u_vec, v_vec]; // u, v basis vectors
 }
 // Check whether N 3D points all lie on the same plane within tolerance.
 // Fewer than 3 points are trivially coplanar.
@@ -539,8 +612,7 @@ export function merge_coplanar_triangles(positions, tolerance = 1e-4) {
         if (pa.degenerate || pb.degenerate)
             continue;
         // Check coplanarity: same canonical normal direction AND same plane distance
-        const normal_dot = pa.normal[0] * pb.normal[0] + pa.normal[1] * pb.normal[1] +
-            pa.normal[2] * pb.normal[2];
+        const normal_dot = pa.normal[0] * pb.normal[0] + pa.normal[1] * pb.normal[1] + pa.normal[2] * pb.normal[2];
         if (Math.abs(normal_dot) < 1 - tolerance)
             continue;
         if (Math.abs(pa.plane_d - pb.plane_d) > tolerance)
@@ -591,7 +663,7 @@ export function merge_coplanar_triangles(positions, tolerance = 1e-4) {
         }
         // Project to 2D using in-plane basis
         const [u_vec, v_vec] = compute_in_plane_basis(normal);
-        const pts_2d = unique_verts.map((vert) => [dot(u_vec, vert), dot(v_vec, vert)]);
+        const pts_2d = unique_verts.map((vertex) => [dot(u_vec, vertex), dot(v_vec, vertex)]);
         const hull = convex_hull_2d(pts_2d);
         if (hull.length < 3) {
             emit_original(members);
@@ -661,7 +733,7 @@ export function point_in_polygon(point_x, point_y, vertices) {
         const [x_i, y_i] = vertices[idx];
         const [x_j, y_j] = vertices[prev_idx];
         // Check if horizontal ray from point crosses this edge
-        if (y_i !== y_j && (y_i > point_y) !== (y_j > point_y)) {
+        if (y_i !== y_j && y_i > point_y !== y_j > point_y) {
             const x_intersect = ((x_j - x_i) * (point_y - y_i)) / (y_j - y_i) + x_i;
             if (point_x < x_intersect)
                 inside = !inside;
@@ -733,10 +805,7 @@ b) {
         const det = A[0][0] * A[1][1] - A[0][1] * A[1][0];
         if (Math.abs(det) < EPS)
             return null;
-        return [
-            (b[0] * A[1][1] - b[1] * A[0][1]) / det,
-            (A[0][0] * b[1] - A[1][0] * b[0]) / det,
-        ];
+        return [(b[0] * A[1][1] - b[1] * A[0][1]) / det, (A[0][0] * b[1] - A[1][0] * b[0]) / det];
     }
     // 3x3 fast path via matrix inverse
     if (n === 3) {
@@ -751,14 +820,11 @@ b) {
     const perm = Array.from({ length: n }, (_, idx) => idx);
     for (let col = 0; col < n; col++) {
         // Find pivot
-        let max_row = col;
-        let max_val = Math.abs(lu[col][col]);
+        let [max_row, max_val] = [col, Math.abs(lu[col][col])];
         for (let row = col + 1; row < n; row++) {
             const val = Math.abs(lu[row][col]);
-            if (val > max_val) {
-                max_val = val;
-                max_row = row;
-            }
+            if (val > max_val)
+                [max_val, max_row] = [val, row];
         }
         if (max_val < EPS)
             return null; // singular
@@ -787,7 +853,7 @@ b) {
         }
     }
     // Back substitution (Ux = y)
-    const x = new Array(n).fill(0);
+    const x = Array.from({ length: n }).fill(0);
     for (let row = n - 1; row >= 0; row--) {
         let sum = pb[row];
         for (let col = row + 1; col < n; col++) {
@@ -802,7 +868,7 @@ b) {
 export function convex_hull_2d(points) {
     if (points.length < 3)
         return [...points];
-    const sorted = [...points].sort((a, b) => (a[0] - b[0]) || (a[1] - b[1]));
+    const sorted = points.toSorted((a, b) => a[0] - b[0] || a[1] - b[1]);
     const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
     // Lower hull
     const lower = [];

package/dist/overlays/ContextMenu.svelte

@@ -1,47 +1,72 @@
-<script lang="ts">import Icon from '../Icon.svelte';
-let { sections, selected_values = {}, on_select, position, visible, on_close, menu_element, ...rest } = $props();
-// Calculate smart position that keeps menu in viewport
-function get_smart_position() {
-    if (!menu_element)
-        return position;
-    const rect = menu_element.getBoundingClientRect();
-    let { x, y } = position;
-    if (x + rect.width > window.innerWidth)
-        x = position.x - rect.width;
-    if (y + rect.height > window.innerHeight)
-        y = position.y - rect.height;
-    return { x: Math.max(0, x), y: Math.max(0, y) };
-}
-// Handle click outside to close
-function handle_click_outside(event) {
-    const target = event.target;
+<script lang="ts">
+  import Icon from '../Icon.svelte'
+  import type { IconName } from '../icons'
+  import type { HTMLAttributes } from 'svelte/elements'
+
+  interface MenuOption {
+    value: string
+    icon?: string
+    label?: string
+    disabled?: boolean
+  }
+  let {
+    sections,
+    selected_values = {},
+    on_select,
+    position,
+    visible,
+    on_close,
+    menu_element,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    sections: Readonly<{ title: string; options: readonly MenuOption[] }[]>
+    selected_values?: Record<string, string>
+    on_select?: (section_title: string, option: MenuOption) => void
+    position: { x: number; y: number }
+    visible: boolean
+    on_close?: () => void
+    menu_element?: HTMLDivElement
+  } = $props()
+
+  // Calculate smart position that keeps menu in viewport
+  function get_smart_position() {
+    if (!menu_element) return position
+    const rect = menu_element.getBoundingClientRect()
+    let { x, y } = position
+    if (x + rect.width > window.innerWidth) x = position.x - rect.width
+    if (y + rect.height > window.innerHeight) y = position.y - rect.height
+    return { x: Math.max(0, x), y: Math.max(0, y) }
+  }
+
+  // Handle click outside to close
+  function handle_click_outside(event: MouseEvent) {
+    const target = event.target
     if (target instanceof Element && visible) {
-        const menu = target.closest(`.context-menu`);
-        if (!menu)
-            on_close?.();
+      const menu = target.closest(`.context-menu`)
+      if (!menu) on_close?.()
     }
-}
-// Handle right-click outside to close
-function handle_right_click_outside(event) {
-    if (!visible)
-        return;
-    const target = event.target;
-    const menu = target instanceof Element ? target.closest(`.context-menu`) : null;
+  }
+
+  // Handle right-click outside to close
+  function handle_right_click_outside(event: MouseEvent) {
+    if (!visible) return
+    const target = event.target
+    const menu = target instanceof Element ? target.closest(`.context-menu`) : null
     if (!menu) {
-        event.preventDefault();
-        on_close?.();
+      event.preventDefault()
+      on_close?.()
     }
-}
-// Handle keyboard shortcuts
-function handle_keydown(event) {
-    if (event.key === `Escape` && visible)
-        on_close?.();
-}
-// Handle option selection
-function handle_option_click(section_title, option) {
-    if (!option.disabled)
-        on_select?.(section_title, option);
-}
+  }
+
+  // Handle keyboard shortcuts
+  function handle_keydown(event: KeyboardEvent) {
+    if (event.key === `Escape` && visible) on_close?.()
+  }
+
+  // Handle option selection
+  function handle_option_click(section_title: string, option: MenuOption) {
+    if (!option.disabled) on_select?.(section_title, option)
+  }
 </script>
 
 <svelte:document