matterviz 0.4.0 → 0.4.2

package/dist/structure/atom-properties.d.ts

@@ -1,4 +1,5 @@
 import type { ColorScaleType, D3InterpolateName } from '../colors';
+import { type CoordinationData } from '../coordination/calc-coordination';
 import type { AtomColorMode } from '../settings';
 import type { AnyStructure, Site } from './';
 import type { BondingStrategy } from './bonding';
@@ -17,7 +18,7 @@ export interface AtomPropertyColors {
     unique_values?: (number | string)[];
 }
 type SymmetryDataWithOrigMap = MoyoDataset & {
-    orig_site_indices_by_std_idx?: number[][];
+    orig_site_indices_by_input_idx?: number[][];
 };
 export declare const get_d3_color_scales: () => string[];
 export declare function apply_color_scale(vals: number[], scale?: string, type?: ColorScaleType): {
@@ -29,6 +30,7 @@ export declare const apply_categorical_color_scale: (vals: string[], scale?: str
     unique_values: string[];
 };
 export declare const get_orig_site_idx: (site: Site | undefined, site_idx: number) => number;
+export declare function calc_structure_coordination(structure: AnyStructure, strategy?: BondingStrategy): CoordinationData;
 export declare function get_coordination_colors(structure: AnyStructure, strategy?: BondingStrategy, scale?: string, type?: ColorScaleType): AtomPropertyColors;
 export declare function get_wyckoff_colors(structure: AnyStructure, sym_data: SymmetryDataWithOrigMap | null, scale?: string): AtomPropertyColors;
 export declare function get_custom_colors(structure: AnyStructure, fn: (site: Site, idx: number) => number | string, scale?: string, type?: ColorScaleType): AtomPropertyColors;

package/dist/structure/atom-properties.js

@@ -1,21 +1,23 @@
 // Utility functions for computing atom properties and applying color scales
-import { calc_coordination_nums } from '../coordination';
+import { get_d3_interpolator } from '../colors';
+import { calc_coordination_nums, } from '../coordination/calc-coordination';
 import * as math from '../math';
-import { wrap_to_unit_cell } from './pbc';
+import { element_lookup, get_majority_element } from './bonding';
+import { wrap_frac_coord } from './pbc';
 import { rgb } from 'd3-color';
 import * as d3_sc from 'd3-scale-chromatic';
 const GRAY = `#808080`;
 const DEFAULT_COLOR_SCALE = `interpolateViridis`;
+// Cap on periodic image shells per axis when expanding for coordination. Guards
+// against image explosion in very thin / highly oblique cells (coordination is ~O(n²)).
+const MAX_IMAGE_SHELLS = 3;
+// Max bond distance each strategy can form, mirroring the defaults in bonding.ts
+// (electroneg_ratio.max_distance_ratio, solid_angle.max_distance). Used to size PBC
+// image expansion just tightly enough that coordination never misses a bonded neighbor.
+const ELECTRONEG_MAX_RATIO = 2;
+const SOLID_ANGLE_MAX_DIST = 5; // Å
 export const get_d3_color_scales = () => Object.keys(d3_sc).filter((key) => key.startsWith(`interpolate`));
-const get_interpolator = (scale) => {
-    const interp_fn = d3_sc[scale];
-    if (typeof interp_fn !== `function`) {
-        console.warn(`Unknown D3 scale: ${scale}, using ${DEFAULT_COLOR_SCALE}`);
-        return d3_sc.interpolateViridis;
-    }
-    return interp_fn;
-};
-const to_hex = (interp_fn, t) => rgb(interp_fn(t)).formatHex();
+const to_hex = (interp_fn, frac) => rgb(interp_fn(frac)).formatHex();
 const build_image_site = (site, frac_to_cart, offset, orig_idx) => {
     const img_abc = [
         site.abc[0] + offset[0],
@@ -29,14 +31,8 @@ const build_image_site = (site, frac_to_cart, offset, orig_idx) => {
         properties: { ...site.properties, orig_site_idx: orig_idx },
     };
 };
-const get_all_offsets = (pbc) => [-1, 0, 1]
-    .flatMap((dx) => [-1, 0, 1].flatMap((dy) => [-1, 0, 1].map((dz) => [dx, dy, dz])))
-    .filter(([dx, dy, dz]) => !(dx === 0 && dy === 0 && dz === 0) &&
-    (pbc[0] || dx === 0) &&
-    (pbc[1] || dy === 0) &&
-    (pbc[2] || dz === 0));
 const make_categorical = (vals, scale, sort_fn) => {
-    const interp_fn = get_interpolator(scale);
+    const interp_fn = get_d3_interpolator(scale);
     const uniq = sort_fn
         ? [...new Set(vals)].sort(sort_fn)
         : [...new Set(vals)].sort((val_a, val_b) => String(val_a).localeCompare(String(val_b)));
@@ -61,7 +57,7 @@ export function apply_color_scale(vals, scale = DEFAULT_COLOR_SCALE, type = `con
         const result = make_categorical(vals, scale, (val_a, val_b) => val_a - val_b);
         return { colors: result.colors, unique_values: result.unique_values };
     }
-    const interp_fn = get_interpolator(scale);
+    const interp_fn = get_d3_interpolator(scale);
     // Compute min/max in single pass to avoid spreading large arrays
     let [min, max] = [vals[0], vals[0]];
     for (const val of vals) {
@@ -82,46 +78,109 @@ export const get_orig_site_idx = (site, site_idx) => typeof site?.properties?.or
     : typeof site?.properties?.orig_site_idx === `number`
         ? site.properties.orig_site_idx
         : site_idx;
-// Expand structure with PBC images - use minimal expansion based on atom positions
-function expand_structure_for_pbc(structure) {
+// Expand a periodic structure with the neighbor images needed for correct
+// coordination. Each atom's `reach` (the largest bond `strategy` can form for it —
+// electroneg_ratio's (r + r_max)·ratio or solid_angle's flat cap) sizes how many whole
+// cells to image per periodic axis, measured over the perpendicular cell height (not
+// the lattice vector length, so oblique cells work), keeping only images within `reach`
+// of the [0,1] cell and capping at MAX_IMAGE_SHELLS/axis (warns + may undercount beyond
+// that — near-degenerate cells only). Smaller atoms image less; atoms with no covalent
+// radius form no bonds and get no images.
+function expand_structure_for_pbc(structure, strategy) {
     if (!(`lattice` in structure) || !structure.lattice || structure.sites.length === 0) {
         return structure;
     }
     const { sites, lattice } = structure;
-    const frac_to_cart = math.create_frac_to_cart(lattice.matrix);
     const pbc = lattice.pbc ?? [true, true, true];
-    const all_offsets = get_all_offsets(pbc);
-    // Small structures: expand all atoms
-    if (sites.length < 20 || !pbc.some(Boolean)) {
-        const image_sites = sites.flatMap((site, orig_idx) => all_offsets.map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx)));
-        return { ...structure, sites: [...sites, ...image_sites] };
-    }
-    // Large structures: only expand atoms near boundaries (within 5Å bond distance)
-    const cutoff = [5.0 / lattice.a, 5.0 / lattice.b, 5.0 / lattice.c];
-    const image_sites = sites.flatMap((site, orig_idx) => {
-        const norm = wrap_to_unit_cell(site.abc);
-        return all_offsets
-            .filter(([dx, dy, dz]) => (dx === 0 || (dx === -1 ? norm[0] <= cutoff[0] : norm[0] >= 1 - cutoff[0])) &&
-            (dy === 0 || (dy === -1 ? norm[1] <= cutoff[1] : norm[1] >= 1 - cutoff[1])) &&
-            (dz === 0 || (dz === -1 ? norm[2] <= cutoff[2] : norm[2] >= 1 - cutoff[2])))
-            .map((offset) => build_image_site(site, frac_to_cart, offset, orig_idx));
+    if (!pbc.some(Boolean))
+        return structure;
+    const frac_to_cart = math.create_frac_to_cart(lattice.matrix);
+    // Wrap into [0,1) along PERIODIC axes only so the near-cell filter and image
+    // building share one position (else boundary atoms image on the wrong side and lose
+    // neighbors). Vacuum axes keep their real coord — wrapping would fold apart atoms
+    // together and invent bonds.
+    const cell_sites = sites.map((site) => {
+        const abc = site.abc.map((coord, axis) => pbc[axis] ? wrap_frac_coord(coord) : coord);
+        return { ...site, abc, xyz: frac_to_cart(abc) };
     });
-    return { ...structure, sites: [...sites, ...image_sites] };
+    // Covalent radius per atom (0 = unknown → forms no bonds → needs no images)
+    const radii = cell_sites.map((site) => {
+        const elem = get_majority_element(site);
+        return (elem ? element_lookup.get(elem)?.covalent_radius : undefined) ?? 0;
+    });
+    let max_radius = 0;
+    for (const radius of radii)
+        if (radius > max_radius)
+            max_radius = radius;
+    const reach_of = (radius) => strategy === `solid_angle`
+        ? SOLID_ANGLE_MAX_DIST
+        : (radius + max_radius) * ELECTRONEG_MAX_RATIO;
+    const heights = math.cell_heights(lattice.matrix);
+    // Axes we image along: periodic and non-degenerate (finite height). Non-live axes
+    // (vacuum or degenerate) contribute no images — 0 shells + ∞ cutoff so their only
+    // copy (shift 0) always passes the near-cell filter. Loop-invariant, so hoisted out.
+    const live_axis = heights.map((height, axis) => pbc[axis] && Number.isFinite(height));
+    const image_near_cell = (frac, shift, axis_cutoff) => {
+        const shifted = frac + shift;
+        return shifted >= -axis_cutoff && shifted <= 1 + axis_cutoff;
+    };
+    let capped = false;
+    const image_sites = [];
+    for (const [orig_idx, site] of cell_sites.entries()) {
+        const radius = radii[orig_idx];
+        if (radius === 0)
+            continue; // no covalent radius → no bonds → no images
+        const reach = reach_of(radius);
+        // `cutoff` = fractional reach for the near-cell filter (keep an image shifted by `s`
+        // iff abc+s lands within `cutoff` of [0,1]); `n_shells` bounds the loop so no
+        // in-reach copy is missed.
+        const cutoff = heights.map((height, axis) => (live_axis[axis] ? reach / height : Infinity));
+        const n_shells = heights.map((height, axis) => {
+            if (!live_axis[axis])
+                return 0;
+            const shells = Math.floor(1 + reach / height);
+            if (shells > MAX_IMAGE_SHELLS)
+                capped = true;
+            return Math.min(MAX_IMAGE_SHELLS, shells);
+        });
+        const [frac_a, frac_b, frac_c] = site.abc; // periodic axes wrapped into [0, 1)
+        for (let dx = -n_shells[0]; dx <= n_shells[0]; dx++) {
+            if (!image_near_cell(frac_a, dx, cutoff[0]))
+                continue;
+            for (let dy = -n_shells[1]; dy <= n_shells[1]; dy++) {
+                if (!image_near_cell(frac_b, dy, cutoff[1]))
+                    continue;
+                for (let dz = -n_shells[2]; dz <= n_shells[2]; dz++) {
+                    if (dx === 0 && dy === 0 && dz === 0)
+                        continue;
+                    if (!image_near_cell(frac_c, dz, cutoff[2]))
+                        continue;
+                    image_sites.push(build_image_site(site, frac_to_cart, [dx, dy, dz], orig_idx));
+                }
+            }
+        }
+    }
+    if (capped) {
+        console.warn(`[coordination] cell is very thin or oblique relative to bond reach; capping ` +
+            `PBC images at ${MAX_IMAGE_SHELLS} shells/axis, coordination near cell ` +
+            `boundaries may be undercounted`);
+    }
+    return { ...structure, sites: [...cell_sites, ...image_sites] };
 }
-export function get_coordination_colors(structure, strategy = `electroneg_ratio`, scale = DEFAULT_COLOR_SCALE, type = `continuous`) {
-    const orig_site_count = structure.sites.length;
-    // Check if structure has periodic boundary conditions
+// PBC-aware coordination: expand periodic cells with image atoms (so boundary atoms get
+// full coordination), counting only original atoms as centers. Shared by the 3D viewer and
+// CoordinationBarPlot so both report identical numbers.
+export function calc_structure_coordination(structure, strategy = `electroneg_ratio`) {
     const has_lattice = `lattice` in structure && structure.lattice !== undefined;
     const pbc = has_lattice ? structure.lattice.pbc : undefined;
     const has_pbc = has_lattice && (pbc === undefined || pbc.some(Boolean));
-    // For PBC structures, expand with images from neighboring cells for accurate coordination
-    const coord_structure = has_pbc ? expand_structure_for_pbc(structure) : structure;
-    // Calculate coordination numbers on the (potentially expanded) structure
-    const all_coord_data = calc_coordination_nums(coord_structure, strategy);
-    // Extract coordination numbers only for the original sites (not image atoms)
-    const coord_nums = all_coord_data.sites
-        .slice(0, orig_site_count)
-        .map((site) => site.coordination_num);
+    // Image atoms still count as neighbors but aren't iterated as centers (big speedup)
+    const coord_structure = has_pbc ? expand_structure_for_pbc(structure, strategy) : structure;
+    return calc_coordination_nums(coord_structure, strategy, structure.sites.length);
+}
+export function get_coordination_colors(structure, strategy = `electroneg_ratio`, scale = DEFAULT_COLOR_SCALE, type = `continuous`) {
+    // sites is already limited to the original atoms (calc_coordination_nums center_count)
+    const coord_nums = calc_structure_coordination(structure, strategy).sites.map((site) => site.coordination_num);
     const { colors, unique_values } = apply_color_scale(coord_nums, scale, type);
     return build_prop_colors(coord_nums, colors, unique_values);
 }
@@ -134,12 +193,14 @@ export function get_wyckoff_colors(structure, sym_data, scale = DEFAULT_COLOR_SC
             unique_values: [`unknown`],
         };
     }
+    // moyo's wyckoffs array is indexed by INPUT cell sites (the merged moyo input cell),
+    // so map letters to original sites through orig_site_indices_by_input_idx
     const wyckoff_by_orig_idx = new Map();
-    const mapping_by_std_idx = sym_data.orig_site_indices_by_std_idx;
-    if (mapping_by_std_idx) {
-        for (let std_idx = 0; std_idx < sym_data.wyckoffs.length; std_idx += 1) {
-            const wyckoff = sym_data.wyckoffs[std_idx];
-            for (const orig_idx of mapping_by_std_idx[std_idx] ?? []) {
+    const mapping_by_input_idx = sym_data.orig_site_indices_by_input_idx;
+    if (mapping_by_input_idx) {
+        for (let input_idx = 0; input_idx < sym_data.wyckoffs.length; input_idx += 1) {
+            const wyckoff = sym_data.wyckoffs[input_idx];
+            for (const orig_idx of mapping_by_input_idx[input_idx] ?? []) {
                 if (!wyckoff_by_orig_idx.has(orig_idx))
                     wyckoff_by_orig_idx.set(orig_idx, wyckoff);
             }

package/dist/structure/bond-order-perception.js

@@ -1,7 +1,5 @@
-import { get_bond_key } from './bonding';
-const primary_element = (site) => {
-    return (site.species?.reduce((best_species, species) => (species.occu > best_species.occu ? species : best_species), site.species[0])?.element ?? ``);
-};
+import { get_bond_key, get_majority_element } from './bonding';
+const primary_element = (site) => get_majority_element(site) ?? ``;
 // xyz2mol atomic_valence. Valence combinations are re-sorted by total
 // valence sum so the least-saturated solution is tried first.
 const ATOMIC_VALENCE = {

package/dist/structure/bonding.d.ts

@@ -1,5 +1,10 @@
+import type { ElementSymbol } from '../element';
 import type { Vec3 } from '../math';
 import type { AnyStructure, BondOrder, BondPair, Site, StructureBond } from './';
+export declare const element_lookup: Map<"Ac" | "Ag" | "Al" | "Am" | "Ar" | "As" | "At" | "Au" | "B" | "Ba" | "Be" | "Bh" | "Bi" | "Bk" | "Br" | "C" | "Ca" | "Cd" | "Ce" | "Cf" | "Cl" | "Cm" | "Co" | "Cr" | "Cs" | "Cu" | "Db" | "Dy" | "Er" | "Es" | "Eu" | "F" | "Fe" | "Fm" | "Fr" | "Ga" | "Gd" | "Ge" | "H" | "He" | "Hf" | "Hg" | "Ho" | "Hs" | "I" | "In" | "Ir" | "K" | "Kr" | "La" | "Li" | "Lr" | "Lu" | "Md" | "Mg" | "Mn" | "Mo" | "Mt" | "N" | "Na" | "Nb" | "Nd" | "Ne" | "Ni" | "No" | "Np" | "O" | "Os" | "P" | "Pa" | "Pb" | "Pd" | "Pm" | "Po" | "Pr" | "Pt" | "Pu" | "Ra" | "Rb" | "Re" | "Rf" | "Rh" | "Rn" | "Ru" | "S" | "Sb" | "Sc" | "Se" | "Sg" | "Si" | "Sm" | "Sn" | "Sr" | "Ta" | "Tb" | "Tc" | "Te" | "Th" | "Ti" | "Tl" | "Tm" | "U" | "V" | "W" | "Xe" | "Y" | "Yb" | "Zn" | "Zr" | "Ds" | "Rg" | "Cn" | "Nh" | "Fl" | "Mc" | "Lv" | "Ts" | "Og", import("../element").ChemicalElement>;
+export declare const get_majority_element: (site: Site | undefined) => ElementSymbol | null;
+export declare const is_spectator_center: (element: string) => boolean;
+export declare function has_framework_potential(elements: Iterable<string>): boolean;
 export declare const normalize_structure_bond: (site_idx_1: number, site_idx_2: number, order: BondOrder, cell_shift?: Vec3) => StructureBond;
 export declare const get_bond_key: (idx_1: number, idx_2: number, cell_shift?: Vec3) => string;
 export declare function remap_bonds_after_deletion(bonds: readonly StructureBond[], deleted_indices: ReadonlySet<number>): StructureBond[];
@@ -36,12 +41,14 @@ export declare function apply_explicit_bond_metadata(structure: AnyStructure, bo
 export declare function scale_and_offset_bond_matrix(transform_matrix: Float32Array, offset: number, radius_scale: number): Float32Array;
 export declare function get_bond_render_matrices(bond: BondPair, bond_thickness: number): Float32Array[];
 export declare function compute_bond_transform(pos_1: Vec3, pos_2: Vec3): Float32Array;
+export declare const pack_cell_key: (x: number, y: number, z: number) => number;
 export declare const BONDING_STRATEGIES: {
     readonly electroneg_ratio: typeof electroneg_ratio;
     readonly solid_angle: typeof solid_angle;
 };
 export type BondingStrategy = keyof typeof BONDING_STRATEGIES;
 export type BondingAlgo = (typeof BONDING_STRATEGIES)[BondingStrategy];
+export declare function compute_bonds(structure: AnyStructure, strategy: BondingStrategy, options?: Record<string, unknown>): BondPair[];
 export declare function electroneg_ratio(structure: AnyStructure, { electronegativity_threshold, // Max electronegativity difference for bonding
 max_distance_ratio, // Max distance as multiple of sum of covalent radii
 min_bond_dist, // Minimum bond distance in Angstroms
@@ -49,7 +56,8 @@ metal_metal_penalty, // Strength penalty for metal-metal bonds
 metal_nonmetal_bonus, // Strength bonus for metal-nonmetal bonds
 similar_electronegativity_bonus, // Bonus for similar electronegativity
 same_species_penalty, // Penalty for bonds between same element
-strength_threshold, }?: {
+strength_threshold, // Minimum bond strength to include in results
+center_count, }?: {
     electronegativity_threshold?: number | undefined;
     max_distance_ratio?: number | undefined;
     min_bond_dist?: number | undefined;
@@ -58,12 +66,14 @@ strength_threshold, }?: {
     similar_electronegativity_bonus?: number | undefined;
     same_species_penalty?: number | undefined;
     strength_threshold?: number | undefined;
+    center_count?: number | undefined;
 }): BondPair[];
-export declare function solid_angle(structure: AnyStructure, { min_solid_angle, min_face_area, max_distance, min_bond_dist, strength_threshold, }?: {
+export declare function solid_angle(structure: AnyStructure, { min_solid_angle, min_face_area, max_distance, min_bond_dist, strength_threshold, center_count, }?: {
     min_solid_angle?: number | undefined;
     min_face_area?: number | undefined;
     max_distance?: number | undefined;
     min_bond_dist?: number | undefined;
     strength_threshold?: number | undefined;
+    center_count?: number | undefined;
 }): BondPair[];
 export {};