matterviz 0.4.0 → 0.4.2

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;
@@ -60,7 +60,8 @@ export const PARTIAL_OCCUPANCY_CAP_ARC = {
 };
 export const merge_split_partial_sites = (sites, hidden_elements = new Set()) => {
     const grouped_indices = group_split_partial_indices(sites, hidden_elements);
-    return build_render_sites(sites, grouped_indices.non_grouped_site_indices, grouped_indices.grouped_site_indices);
+    const { non_grouped_site_indices, grouped_site_indices } = grouped_indices;
+    return build_render_sites(sites, non_grouped_site_indices, grouped_site_indices);
 };
 export const compute_slice_geometry = (visible_species, slice_gap_rad = PARTIAL_OCCUPANCY_SLICE_GAP_RAD) => {
     if (visible_species.length === 0)
@@ -72,7 +73,8 @@ export const compute_slice_geometry = (visible_species, slice_gap_rad = PARTIAL_
         element,
         occu: occu * occupancy_scale_factor,
     }));
-    const normalized_total_occupancy = normalized_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
+    // Sum of scaled occupancies equals total * scale (avoids a second O(n) pass)
+    const normalized_total_occupancy = total_visible_occupancy * occupancy_scale_factor;
     const has_vacancy_gap = normalized_total_occupancy < 1 - OCCUPANCY_EPS;
     const last_visible_species_idx = normalized_species.length - 1;
     let start_angle = 0;

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, has_framework_potential, is_spectator_center, pack_cell_key, } 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,42 +28,36 @@ 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;
+};
 export function find_image_atoms(structure, { tolerance } = {}) {
-    // Find image atoms for PBC. Returns [atom_idx, image_xyz, image_abc] tuples.
-    // Skips image generation for trajectory data with scattered atoms.
+    // Find image atoms for PBC. Returns [atom_idx, image_xyz, image_abc, is_completion?]
+    // tuples; is_completion marks phase-2 images that only complete bonds / coordination
+    // polyhedra at cell faces (renderers may hide them). Skips scattered trajectories.
     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;
-    // Scale zero-displacement threshold by lattice length scale to avoid hard-coded magic numbers
-    const lattice_norm = Math.max(Math.hypot(...lattice_vecs[0]), Math.hypot(...lattice_vecs[1]), Math.hypot(...lattice_vecs[2]));
-    // Threshold to filter out floating-point-identical (zero-displacement) images; rarely triggers but guards against edge cases
+    const frac_to_cart = math.create_frac_to_cart(lattice_vecs);
+    const vec_lens = lattice_vecs.map((vec) => Math.hypot(...vec));
+    // Scale zero-displacement threshold by lattice length scale to avoid magic numbers
+    const lattice_norm = Math.max(...vec_lens);
     const displacement_eps_sq = (1e-10 * lattice_norm) ** 2;
-    // Tolerances determine which atoms are near cell boundaries and need image generation
-    // Use provided tolerance or default to physical tolerance of 0.5 Angstroms converted to fractional
-    // This prevents excessive image generation for large unit cells (e.g. MOFs) where 0.05 fractional is huge
-    const PHYSICAL_TOLERANCE = 0.5; // Angstroms
-    const tolerances = [0, 1, 2].map((dim) => {
-        if (tolerance !== undefined)
-            return tolerance;
-        const vec_len = Math.hypot(...lattice_vecs[dim]);
-        // zero-length lattice vector should not occur in valid structures,
-        // but fall back to 0.05 fractional tolerance if it does
-        return vec_len > 0 ? PHYSICAL_TOLERANCE / vec_len : 0.05;
-    });
-    // Respect per-axis periodicity: no images across non-periodic (vacuum) directions
-    const pbc = structure.lattice.pbc ?? [true, true, true];
+    // Boundary tolerance: physical 0.5 Å as fractional per-axis, so large cells (MOFs)
+    // don't over-generate (a flat 0.05 fractional would be huge there)
+    const PHYSICAL_TOLERANCE = 0.5; // Å
+    const tolerances = vec_lens.map((vec_len) => tolerance ?? (vec_len > 0 ? PHYSICAL_TOLERANCE / vec_len : 0.05));
+    const pbc = structure.lattice.pbc ?? [true, true, true]; // no images across vacuum
+    // Phase 1: true periodic copies of atoms within `tolerance` of a cell face (bond
+    // lengths preserved, rather than clamping the copy to the cell face)
     for (const [idx, site] of structure.sites.entries()) {
-        // Find edge dimensions and translation directions
         const edge_dims = [];
-        // Find boundary dimensions
         for (let dim = 0; dim < 3; dim++) {
             if (!pbc[dim])
                 continue;
@@ -59,10 +68,9 @@ export function find_image_atoms(structure, { tolerance } = {}) {
             if (Math.abs(coord - 1) < dim_tolerance)
                 edge_dims.push({ dim, direction: -1 });
         }
-        // Generate all translation combinations
+        // Generate all translation combinations; if both +1 and -1 are selected for a dim the
+        // net shift is zero and we skip (yields no image).
         for (let mask = 1; mask < 1 << edge_dims.length; mask++) {
-            // Track selected translation per dimension. If both +1 and -1 are selected for a dim,
-            // the net shift is zero and we skip because it yields no image.
             const selected_shift = [0, 0, 0];
             for (let bit = 0; bit < edge_dims.length; bit++) {
                 if (mask & (1 << bit)) {
@@ -70,25 +78,18 @@ export function find_image_atoms(structure, { tolerance } = {}) {
                     selected_shift[dim] += direction;
                 }
             }
-            // Early skip if no net shift across any dimension
             if (selected_shift.every((val) => val === 0))
                 continue;
-            // Build fractional coordinates by applying the integer translation
-            // This ensures the image is a true periodic copy (preserving bond lengths)
-            // rather than clamping it to the cell face.
+            const [s_a, s_b, s_c] = site.abc;
             const img_abc = [
-                site.abc[0] + selected_shift[0],
-                site.abc[1] + selected_shift[1],
-                site.abc[2] + selected_shift[2],
+                s_a + selected_shift[0],
+                s_b + selected_shift[1],
+                s_c + selected_shift[2],
             ];
-            // If no dimension actually shifted, continue
-            if (img_abc[0] === site.abc[0] &&
-                img_abc[1] === site.abc[1] &&
-                img_abc[2] === site.abc[2])
+            if (img_abc[0] === s_a && img_abc[1] === s_b && img_abc[2] === s_c)
                 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]));
-            // Skip zero-displacement images (should not happen, guards against FP edge cases)
+            const img_xyz = frac_to_cart(img_abc);
+            // Skip zero-displacement images (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);
             if (displacement_len_sq < displacement_eps_sq)
@@ -96,6 +97,157 @@ export function find_image_atoms(structure, { tolerance } = {}) {
             image_sites.push([idx, img_xyz, img_abc]);
         }
     }
+    // Per-site element data for the phase-2 completion pass. present_elements is the tiny
+    // composition (so has_framework_potential doesn't re-scan every site in big supercells).
+    const site_elements = [];
+    const site_radii = [];
+    const site_en = [];
+    const site_is_metal = [];
+    const present_elements = new Set();
+    let max_radius = 0;
+    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;
+        site_elements.push(elem);
+        if (elem !== null)
+            present_elements.add(elem);
+        site_radii.push(radius);
+        site_en.push(data?.electronegativity ?? null);
+        site_is_metal.push(data?.metal === true);
+        if (radius !== null && radius > max_radius)
+            max_radius = radius;
+    }
+    // Skip spectator A-site cations (Li/Na, heavy alkaline earths) when a framework cation
+    // is present: they render no polyhedron, so completing their shells floats coordination
+    // groups (e.g. a PO4 around a corner Li) beyond the cell. Purely ionic binaries (NaCl)
+    // keep theirs. Note: a spectator force-included as a polyhedra center (compute_polyhedra's
+    // included_center_elements) is still skipped here, so its boundary polyhedra truncate at
+    // cell faces - accepted to keep image generation independent of render-only settings.
+    const skip_spectators = has_framework_potential(present_elements);
+    const site_skipped = site_elements.map((elem) => skip_spectators && elem !== null && is_spectator_center(elem));
+    // Phase 2: anion images that complete coordination polyhedra / bonds at cell faces.
+    // Phase 1's ~0.5 Å face tolerance misses anions just beyond a face that still bond a
+    // cation near it, truncating boundary polyhedra. We add ONLY such images: a candidate
+    // must be a polyhedron vertex (non-metal/metalloid, like is_anion_vertex in polyhedra.ts)
+    // AND strictly more electronegative than the anchor it bonds. Metals, intermetallics,
+    // equal-EN networks and cation copies get none, keeping renders minimal.
+    // Min anchor EN: a candidate only completes a cation's shell if more electronegative
+    // than it. Over non-skipped anchors only, so skipped spectators can't loosen the filter.
+    let min_anchor_en = Infinity;
+    for (let idx = 0; idx < structure.sites.length; idx++) {
+        if (site_skipped[idx])
+            continue;
+        const en = site_en[idx];
+        if (site_radii[idx] !== 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) {
+        // Per-axis fractional bond reach via perpendicular cell heights (correct for oblique
+        // cells; 0 for degenerate cells → no images). The + face tolerance covers phase-1
+        // anchors sitting slightly outside the cell.
+        const pad_per_axis = math.frac_cutoff_per_axis(lattice_vecs, max_bond_dist + PHYSICAL_TOLERANCE);
+        // Bond-test anchors = base atoms + phase-1 boundary images, so every displayed
+        // boundary cation gets its shell completed (VESTA-like; e.g. all 8 rutile corners).
+        const anchor_positions = structure.sites.map((site) => site.xyz);
+        const anchor_radii = [...site_radii];
+        const anchor_en = [...site_en];
+        const anchor_skipped = [...site_skipped];
+        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]);
+            anchor_skipped.push(site_skipped[src_idx]);
+        }
+        // Spatial grid over anchors for the bond check (integer-packed keys: this
+        // grid is probed 27x per candidate image in the loop below)
+        const grid = new Map();
+        for (const [idx, pos] of anchor_positions.entries()) {
+            const key = pack_cell_key(Math.floor(pos[0] / max_bond_dist), Math.floor(pos[1] / max_bond_dist), Math.floor(pos[2] / max_bond_dist));
+            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(pack_cell_key(cx + dx, cy + dy, cz + dz)) ??
+                            []) {
+                            if (anchor_skipped[anchor_idx])
+                                continue;
+                            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) and anything not strictly more electronegative than at
+            // least one anchor (covers 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 boundary
+            const axis_shifts = [0, 1, 2].map((axis) => {
+                if (!pbc[axis])
+                    return [0];
+                const pad = pad_per_axis[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(img_abc);
+                        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 +256,24 @@ 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,40 @@
+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 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;