matterviz 0.4.0 → 0.4.1

package/dist/structure/partial-occupancy.d.ts

@@ -1,5 +1,4 @@
 import type { Site } from './';
-export declare const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 0.001;
 export type RenderSite = {
     site_idx: number;
     site: Site;

package/dist/structure/partial-occupancy.js

@@ -1,4 +1,4 @@
-export const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 1e-3;
+const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 1e-3;
 const OCCUPANCY_EPS = 1e-6;
 const MIN_PHI_LENGTH = 1e-4;
 const MERGE_DISTANCE_TOLERANCE = 1e-8;

package/dist/structure/pbc.d.ts

@@ -5,5 +5,5 @@ export declare const wrap_frac_coord: (coord: number) => number;
 export declare const wrap_to_unit_cell: (frac: Vec3) => Vec3;
 export declare function find_image_atoms(structure: ParsedStructure, { tolerance }?: {
     tolerance?: number;
-}): [number, Vec3, Vec3][];
+}): [number, Vec3, Vec3, boolean?][];
 export declare function get_pbc_image_sites(...args: Parameters<typeof find_image_atoms>): ParsedStructure;

package/dist/structure/pbc.js

@@ -1,6 +1,21 @@
 import * as math from '../math';
+import { element_lookup, get_majority_element } from './bonding';
+// Distance slack added to the covalent-radii sum when deciding whether a
+// candidate image atom bonds to a base atom (VESTA-like bond search criterion)
+const BOND_SLACK = 0.4; // Å
+// Below this separation two sites are overlapping copies, not a bond (matches
+// the min_bond_dist default in bonding.ts)
+const MIN_BOND_DIST = 0.4; // Å
 // Wrap a single fractional coordinate to [0, 1), clamping near-1 values to 0
 // and rounding to 15 digits to suppress floating-point noise.
+// NOTE on epsilon: this is the tightest of three intentionally different wrap
+// helpers. Coordinates here come almost straight from file parsing, so float
+// error is tiny and a 1e-10 snap + toFixed(15) preserves maximal precision.
+// Compare wrap_frac @1e-9 [[src/lib/symmetry/index.ts:80]] (post moyo
+// standardization + matrix transforms) and wrap_point @1e-8
+// [[src/lib/symmetry/symmetry-elements.ts:214]] (feeds symmetry-element dedup
+// keys). Do not unify: loosening this epsilon changes snapping near cell
+// boundaries for parsed structures.
 export const wrap_frac_coord = (coord) => {
     const wrapped = coord - Math.floor(coord);
     if (wrapped >= 1 - 1e-10)
@@ -13,17 +28,23 @@ export const wrap_to_unit_cell = (frac) => [
     wrap_frac_coord(frac[1]),
     wrap_frac_coord(frac[2]),
 ];
+// Trajectory-like data: >10% of atoms far outside the unit cell. Image-atom
+// generation is skipped for such structures.
+const is_scattered_trajectory = (sites) => {
+    const atoms_outside_cell = sites.filter(({ abc }) => abc.some((coord) => coord < -0.1 || coord > 1.1));
+    return atoms_outside_cell.length > sites.length * 0.1;
+};
+// Cartesian position of fractional coords abc in the given lattice (rows = lattice vectors)
+const frac_to_cart_pos = (abc, lattice_vecs) => math.add(math.scale(lattice_vecs[0], abc[0]), math.scale(lattice_vecs[1], abc[1]), math.scale(lattice_vecs[2], abc[2]));
 export function find_image_atoms(structure, { tolerance } = {}) {
-    // Find image atoms for PBC. Returns [atom_idx, image_xyz, image_abc] tuples.
+    // Find image atoms for PBC. Returns [atom_idx, image_xyz, image_abc, is_completion?]
+    // tuples; is_completion marks phase-2 images that exist only to complete bonds /
+    // coordination polyhedra at cell faces (renderers may hide them when neither shows).
     // Skips image generation for trajectory data with scattered atoms.
     if (!structure.lattice || !structure.sites || structure.sites.length === 0)
         return [];
-    // Skip trajectory data (>10% atoms outside cell)
-    const atoms_outside_cell = structure.sites.filter(({ abc }) => abc.some((coord) => coord < -0.1 || coord > 1.1));
-    // Skip image generation for trajectory data (>10% atoms outside cell)
-    if (atoms_outside_cell.length > structure.sites.length * 0.1) {
+    if (is_scattered_trajectory(structure.sites))
         return [];
-    }
     // Check if this is a supercell to correctly identify external boundaries correctly
     const image_sites = [];
     const lattice_vecs = structure.lattice.matrix;
@@ -87,7 +108,7 @@ export function find_image_atoms(structure, { tolerance } = {}) {
                 img_abc[2] === site.abc[2])
                 continue;
             // Compute xyz from img_abc to ensure consistency
-            const img_xyz = math.add(math.scale(lattice_vecs[0], img_abc[0]), math.scale(lattice_vecs[1], img_abc[1]), math.scale(lattice_vecs[2], img_abc[2]));
+            const img_xyz = frac_to_cart_pos(img_abc, lattice_vecs);
             // Skip zero-displacement images (should not happen, guards against FP edge cases)
             const displacement = math.subtract(img_xyz, site.xyz);
             const displacement_len_sq = displacement.reduce((sum, val) => sum + val * val, 0);
@@ -96,6 +117,156 @@ export function find_image_atoms(structure, { tolerance } = {}) {
             image_sites.push([idx, img_xyz, img_abc]);
         }
     }
+    // Phase 2: polyhedra-completing images (VESTA boundary-mode-like). The face
+    // tolerance above only catches atoms within ~0.5 Å of a boundary, but bonds
+    // reach a covalent-radii sum further: an anion just beyond a cell face may be
+    // needed to complete the coordination shell of a cation near that face, so
+    // bonds and coordination polyhedra at cell edges come out truncated without it.
+    // Phase 2 adds ONLY such anion images: a candidate must qualify as a polyhedron
+    // vertex (a non-metal/metalloid - same condition as is_anion_vertex in
+    // polyhedra.ts) and be strictly more electronegative than the anchor atom it
+    // bonds to. Everything else - elemental metals, intermetallics (incl. multi
+    // metal ones like Al-Fe-Ni where EN differs but no polyhedra exist), equal-EN
+    // covalent networks, cation copies - gets no phase-2 images, so the default
+    // render stays minimal and grows uniformly from all cell surfaces (the phase-1
+    // boundary copies above are the only non-anion atoms outside the cell).
+    const site_radii = [];
+    const site_en = [];
+    const site_is_metal = [];
+    let max_radius = 0;
+    // Minimum electronegativity among potential anchors: a candidate can only ever
+    // complete some cation's shell if it's strictly more electronegative than this
+    let min_anchor_en = Infinity;
+    for (const site of structure.sites) {
+        const elem = get_majority_element(site);
+        const data = elem === null ? undefined : element_lookup.get(elem);
+        const radius = data?.covalent_radius ?? null;
+        const en = data?.electronegativity ?? null;
+        site_radii.push(radius);
+        site_en.push(en);
+        site_is_metal.push(data?.metal === true);
+        if (radius !== null && radius > max_radius)
+            max_radius = radius;
+        if (radius !== null && en !== null && en < min_anchor_en)
+            min_anchor_en = en;
+    }
+    const max_bond_dist = 2 * max_radius + BOND_SLACK;
+    if (max_bond_dist > BOND_SLACK && min_anchor_en < Infinity) {
+        // Perpendicular cell heights: |frac| * height lower-bounds the Cartesian
+        // distance along each axis (valid for oblique cells)
+        const volume = Math.abs(math.dot(lattice_vecs[0], math.cross_3d(lattice_vecs[1], lattice_vecs[2])));
+        // height = volume / opposite-face area. A zero-volume (degenerate) cell has two
+        // parallel lattice vectors and ill-defined heights; treat every axis as
+        // infinitely tall so the pad logic below adds no images (pad -> 0) instead of
+        // dividing by zero. When volume > 0 the vectors are linearly independent, so no
+        // pairwise cross product can be zero.
+        const heights = volume === 0
+            ? [Infinity, Infinity, Infinity]
+            : [
+                volume / Math.hypot(...math.cross_3d(lattice_vecs[1], lattice_vecs[2])),
+                volume / Math.hypot(...math.cross_3d(lattice_vecs[0], lattice_vecs[2])),
+                volume / Math.hypot(...math.cross_3d(lattice_vecs[0], lattice_vecs[1])),
+            ];
+        // Anchor set for the bond test: base atoms plus the phase-1 boundary images
+        // (corner/edge/face copies). Anchoring on those too matches VESTA - every
+        // displayed boundary cation gets its shell completed (e.g. all 8 corner
+        // octahedra in rutile, not just the one at the origin).
+        const anchor_positions = structure.sites.map((site) => site.xyz);
+        const anchor_radii = [...site_radii];
+        const anchor_en = [...site_en];
+        for (const [src_idx, img_xyz] of image_sites) {
+            anchor_positions.push(img_xyz);
+            anchor_radii.push(site_radii[src_idx]);
+            anchor_en.push(site_en[src_idx]);
+        }
+        // Spatial grid over anchors for the bond check
+        const grid = new Map();
+        const grid_key = (pos) => pos.map((coord) => Math.floor(coord / max_bond_dist)).join(`,`);
+        for (const [idx, pos] of anchor_positions.entries()) {
+            const key = grid_key(pos);
+            const cell = grid.get(key);
+            if (cell)
+                cell.push(idx);
+            else
+                grid.set(key, [idx]);
+        }
+        // True when the candidate (an anion image) bonds a strictly less
+        // electronegative anchor, i.e. completes some cation's coordination shell
+        const completes_cation_shell = (pos, radius, en) => {
+            const [cx, cy, cz] = pos.map((coord) => Math.floor(coord / max_bond_dist));
+            for (let dx = -1; dx <= 1; dx++) {
+                for (let dy = -1; dy <= 1; dy++) {
+                    for (let dz = -1; dz <= 1; dz++) {
+                        for (const anchor_idx of grid.get(`${cx + dx},${cy + dy},${cz + dz}`) ?? []) {
+                            const anchor_radius = anchor_radii[anchor_idx];
+                            const anchor_electroneg = anchor_en[anchor_idx];
+                            if (anchor_radius === null)
+                                continue;
+                            if (anchor_electroneg === null || en <= anchor_electroneg)
+                                continue;
+                            const dist = math.euclidean_dist(pos, anchor_positions[anchor_idx]);
+                            if (dist > MIN_BOND_DIST && dist <= radius + anchor_radius + BOND_SLACK) {
+                                return true;
+                            }
+                        }
+                    }
+                }
+            }
+            return false;
+        };
+        // Dedupe against phase-1 images via (site, integer shift) keys
+        const seen_images = new Set(image_sites.map(([idx, _xyz, img_abc]) => `${idx}|${img_abc
+            .map((coord, axis) => Math.round(coord - structure.sites[idx].abc[axis]))
+            .join(`,`)}`));
+        for (const [idx, site] of structure.sites.entries()) {
+            const radius = site_radii[idx];
+            const en = site_en[idx];
+            // Skip candidates that could never be a polyhedron vertex: metals (e.g.
+            // Fe/Ni in Al-Fe-Ni intermetallics, despite their higher EN) and anything
+            // not strictly more electronegative than at least one anchor (covers all
+            // sites of elemental/equal-EN structures and all cations)
+            if (radius === null || en === null || en <= min_anchor_en)
+                continue;
+            if (site_is_metal[idx])
+                continue;
+            // Per-axis shifts that could land a copy of this atom within bonding reach
+            // of the cell: {0} plus +1/-1 when the atom is within max_bond_dist of the
+            // respective boundary
+            const axis_shifts = [0, 1, 2].map((axis) => {
+                if (!pbc[axis])
+                    return [0];
+                // + face tolerance: anchors (phase-1 images) can sit slightly outside the cell
+                const pad = (max_bond_dist + PHYSICAL_TOLERANCE) / heights[axis];
+                const shifts = [0];
+                if (site.abc[axis] < pad)
+                    shifts.push(1);
+                if (site.abc[axis] > 1 - pad)
+                    shifts.push(-1);
+                return shifts;
+            });
+            for (const shift_a of axis_shifts[0]) {
+                for (const shift_b of axis_shifts[1]) {
+                    for (const shift_c of axis_shifts[2]) {
+                        if (shift_a === 0 && shift_b === 0 && shift_c === 0)
+                            continue;
+                        const key = `${idx}|${shift_a},${shift_b},${shift_c}`;
+                        if (seen_images.has(key))
+                            continue;
+                        const img_abc = [
+                            site.abc[0] + shift_a,
+                            site.abc[1] + shift_b,
+                            site.abc[2] + shift_c,
+                        ];
+                        const img_xyz = frac_to_cart_pos(img_abc, lattice_vecs);
+                        if (!completes_cation_shell(img_xyz, radius, en))
+                            continue;
+                        seen_images.add(key);
+                        image_sites.push([idx, img_xyz, img_abc, true]);
+                    }
+                }
+            }
+        }
+    }
     return image_sites;
 }
 // Return structure with image atoms added
@@ -104,23 +275,25 @@ export function get_pbc_image_sites(...args) {
     if (!structure || !structure.sites || structure.sites.length === 0) {
         return structure;
     }
-    // Check for trajectory data
-    const atoms_outside_cell = structure.sites.filter((site) => site.abc.some((coord) => coord < -0.1 || coord > 1.1));
     // Return trajectory data unchanged
-    if (atoms_outside_cell.length > structure.sites.length * 0.1) {
+    if (is_scattered_trajectory(structure.sites))
         return structure;
-    }
     // Add image atoms to regular crystal structures
     const image_sites = find_image_atoms(...args);
     const imaged_struct = { ...structure, sites: [...structure.sites] };
     // Add image atoms as new sites using provided (xyz, abc) from find_image_atoms
-    for (const [site_idx, img_xyz, img_abc] of image_sites) {
+    for (const [site_idx, img_xyz, img_abc, is_completion] of image_sites) {
         const orig_site = structure.sites[site_idx];
         imaged_struct.sites.push({
             ...orig_site,
             abc: img_abc,
             xyz: img_xyz,
-            properties: { ...orig_site.properties, orig_site_idx: site_idx },
+            properties: {
+                ...orig_site.properties,
+                orig_site_idx: site_idx,
+                // phase-2 images only complete bonds/polyhedra - hidden when neither renders
+                ...(is_completion ? { completion_image: true } : {}),
+            },
         });
     }
     return imaged_struct;

package/dist/structure/polyhedra.d.ts

@@ -0,0 +1,41 @@
+import type { ElementSymbol } from '../element';
+import type { Vec3 } from '../math';
+import type { AnyStructure, BondPair } from './';
+export type PolyhedraColorMode = `vertex` | `center` | `uniform`;
+export interface PolyhedraOptions {
+    min_neighbors?: number;
+    max_neighbors?: number;
+    excluded_center_elements?: readonly string[];
+    included_center_elements?: readonly string[];
+    electronegativity_margin?: number;
+    distance_factor?: number;
+    weak_bond_norm?: number;
+    volume_eps?: number;
+}
+export interface ConvexHullResult {
+    vertices: Vec3[];
+    input_idxs: number[];
+    faces: [number, number, number][];
+    volume: number;
+}
+export interface Polyhedron {
+    center_site_idx: number;
+    center_orig_idx: number;
+    center_element: ElementSymbol;
+    vertices: Vec3[];
+    vertex_site_idxs: number[];
+    faces: [number, number, number][];
+    volume: number;
+}
+export interface MergedPolyhedraBuffers {
+    positions: Float32Array;
+    colors: Float32Array;
+    edge_positions: Float32Array;
+    triangle_count: number;
+    edge_count: number;
+}
+export declare function convex_hull_3d(points: readonly Vec3[], eps_scale?: number): ConvexHullResult;
+export declare function build_adjacency(bonds: readonly BondPair[]): Map<number, Set<number>>;
+export declare const is_spectator_center: (element: string) => boolean;
+export declare function compute_polyhedra(structure: AnyStructure, bonds: readonly BondPair[], options?: PolyhedraOptions): Polyhedron[];
+export declare function merge_polyhedra_buffers(polyhedra: readonly Polyhedron[], get_vertex_color: (poly: Polyhedron, vertex_idx: number) => string, coplanar_tol?: number): MergedPolyhedraBuffers;