matterviz 0.3.6 → 0.4.0

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

@@ -0,0 +1,25 @@
+import type { Site } from './';
+export declare const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 0.001;
+export type RenderSite = {
+    site_idx: number;
+    site: Site;
+    is_image_atom: boolean;
+    source_site_indices: number[];
+};
+export type SliceGeometry = {
+    element: string;
+    occupancy: number;
+    start_phi: number;
+    end_phi: number;
+    phi_length: number;
+    render_start_cap: boolean;
+    render_end_cap: boolean;
+};
+export type CapArcConfig = {
+    start_cap_arc_start: number;
+    end_cap_arc_start: number;
+    arc_length: number;
+};
+export declare const PARTIAL_OCCUPANCY_CAP_ARC: CapArcConfig;
+export declare const merge_split_partial_sites: (sites: Site[], hidden_elements?: ReadonlySet<string>) => RenderSite[];
+export declare const compute_slice_geometry: (visible_species: Site[`species`], slice_gap_rad?: number) => SliceGeometry[];

package/dist/structure/partial-occupancy.js

@@ -0,0 +1,99 @@
+export 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;
+const CAP_ARC_START = Math.PI / 2;
+const is_image_atom = (site) => typeof site.properties?.orig_site_idx === `number`;
+const make_render_site = (sites, site_idx, source_site_indices, site_override) => ({
+    site_idx,
+    site: site_override ?? sites[site_idx],
+    is_image_atom: source_site_indices.some((source_site_idx) => is_image_atom(sites[source_site_idx])),
+    source_site_indices,
+});
+const sq_dist = (xyz_1, xyz_2) => (xyz_1[0] - xyz_2[0]) ** 2 + (xyz_1[1] - xyz_2[1]) ** 2 + (xyz_1[2] - xyz_2[2]) ** 2;
+const is_split_partial_site = (site, hidden_elements) => {
+    const visible_species = site.species.filter(({ element }) => !hidden_elements.has(element));
+    const total_visible_occupancy = visible_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
+    return visible_species.length === 1 && total_visible_occupancy < 1 - OCCUPANCY_EPS;
+};
+const group_split_partial_indices = (sites, hidden_elements) => {
+    const grouped_centers = [];
+    const grouped_site_indices = [];
+    const non_grouped_site_indices = [];
+    for (const [site_idx, site] of sites.entries()) {
+        if (!is_split_partial_site(site, hidden_elements)) {
+            non_grouped_site_indices.push(site_idx);
+            continue;
+        }
+        const matched_group_idx = grouped_centers.findIndex((center_xyz) => sq_dist(center_xyz, site.xyz) <= MERGE_DISTANCE_TOLERANCE ** 2);
+        if (matched_group_idx === -1) {
+            grouped_centers.push(site.xyz);
+            grouped_site_indices.push([site_idx]);
+            continue;
+        }
+        grouped_site_indices[matched_group_idx].push(site_idx);
+    }
+    return { non_grouped_site_indices, grouped_site_indices };
+};
+const build_render_sites = (sites, non_grouped_site_indices, grouped_site_indices) => {
+    const render_sites = non_grouped_site_indices.map((site_idx) => make_render_site(sites, site_idx, [site_idx]));
+    for (const grouped_indices of grouped_site_indices) {
+        if (grouped_indices.length === 1) {
+            const site_idx = grouped_indices[0];
+            render_sites.push(make_render_site(sites, site_idx, [site_idx]));
+            continue;
+        }
+        const representative_site_idx = grouped_indices[0];
+        const representative_site = sites[representative_site_idx];
+        const merged_species = grouped_indices.flatMap((grouped_site_idx) => sites[grouped_site_idx].species);
+        render_sites.push(make_render_site(sites, representative_site_idx, [...grouped_indices], {
+            ...representative_site,
+            species: merged_species,
+        }));
+    }
+    return render_sites;
+};
+export const PARTIAL_OCCUPANCY_CAP_ARC = {
+    start_cap_arc_start: CAP_ARC_START,
+    end_cap_arc_start: CAP_ARC_START,
+    arc_length: Math.PI,
+};
+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);
+};
+export const compute_slice_geometry = (visible_species, slice_gap_rad = PARTIAL_OCCUPANCY_SLICE_GAP_RAD) => {
+    if (visible_species.length === 0)
+        return [];
+    const total_visible_occupancy = visible_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
+    // Preserve total angular coverage at one full turn for invalid overfull inputs.
+    const occupancy_scale_factor = total_visible_occupancy > 1 + OCCUPANCY_EPS ? 1 / total_visible_occupancy : 1;
+    const normalized_species = visible_species.map(({ element, occu }) => ({
+        element,
+        occu: occu * occupancy_scale_factor,
+    }));
+    const normalized_total_occupancy = normalized_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
+    const has_vacancy_gap = normalized_total_occupancy < 1 - OCCUPANCY_EPS;
+    const last_visible_species_idx = normalized_species.length - 1;
+    let start_angle = 0;
+    return normalized_species.map(({ element, occu }, species_idx) => {
+        const start_phi_raw = 2 * Math.PI * start_angle;
+        const end_phi_raw = 2 * Math.PI * (start_angle += occu);
+        // Keep neighboring wedges from sharing the exact same plane (z-fighting).
+        const phi_span_raw = Math.max(0, end_phi_raw - start_phi_raw);
+        const max_safe_gap = Math.max(0, phi_span_raw - MIN_PHI_LENGTH);
+        const desired_gap = visible_species.length > 1 ? Math.min(slice_gap_rad, phi_span_raw * 0.25) : 0;
+        const phi_gap = Math.min(desired_gap, max_safe_gap);
+        const start_phi = start_phi_raw + phi_gap / 2;
+        const end_phi = end_phi_raw - phi_gap / 2;
+        return {
+            element,
+            occupancy: occu,
+            start_phi,
+            end_phi,
+            phi_length: Math.max(MIN_PHI_LENGTH, end_phi - start_phi),
+            render_start_cap: has_vacancy_gap && species_idx === 0,
+            render_end_cap: has_vacancy_gap && species_idx === last_visible_species_idx,
+        };
+    });
+};

package/dist/structure/pbc.d.ts

@@ -0,0 +1,9 @@
+import type { Vec3 } from '../math';
+import type { ParsedStructure } from './parse';
+export type Pbc = readonly [boolean, boolean, boolean];
+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][];
+export declare function get_pbc_image_sites(...args: Parameters<typeof find_image_atoms>): ParsedStructure;

package/dist/structure/pbc.js

@@ -0,0 +1,127 @@
+import * as math from '../math';
+// Wrap a single fractional coordinate to [0, 1), clamping near-1 values to 0
+// and rounding to 15 digits to suppress floating-point noise.
+export const wrap_frac_coord = (coord) => {
+    const wrapped = coord - Math.floor(coord);
+    if (wrapped >= 1 - 1e-10)
+        return 0;
+    return Number(wrapped.toFixed(15));
+};
+// Wrap fractional coordinates to [0, 1) range for periodicity.
+export const wrap_to_unit_cell = (frac) => [
+    wrap_frac_coord(frac[0]),
+    wrap_frac_coord(frac[1]),
+    wrap_frac_coord(frac[2]),
+];
+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.
+    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) {
+        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 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];
+    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;
+            const coord = site.abc[dim];
+            const dim_tolerance = tolerances[dim];
+            if (Math.abs(coord) < dim_tolerance)
+                edge_dims.push({ dim, direction: 1 });
+            if (Math.abs(coord - 1) < dim_tolerance)
+                edge_dims.push({ dim, direction: -1 });
+        }
+        // Generate all translation combinations
+        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)) {
+                    const { dim, direction } = edge_dims[bit];
+                    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 img_abc = [
+                site.abc[0] + selected_shift[0],
+                site.abc[1] + selected_shift[1],
+                site.abc[2] + 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])
+                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 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)
+                continue;
+            image_sites.push([idx, img_xyz, img_abc]);
+        }
+    }
+    return image_sites;
+}
+// Return structure with image atoms added
+export function get_pbc_image_sites(...args) {
+    const structure = args[0];
+    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) {
+        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) {
+        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 },
+        });
+    }
+    return imaged_struct;
+}

package/dist/structure/supercell.d.ts

@@ -0,0 +1,8 @@
+import type { Vec3 } from '../math';
+import { scale_lattice_matrix } from '../math';
+import type { Crystal } from './index';
+export declare function parse_supercell_scaling(scaling: string | number | Vec3): Vec3;
+export declare function generate_lattice_points(scaling_factors: Vec3): Vec3[];
+export { scale_lattice_matrix };
+export declare function make_supercell(structure: Crystal, scaling: string | number | Vec3, to_unit_cell?: boolean): Crystal;
+export declare function is_valid_supercell_input(input: string): boolean;

package/dist/structure/supercell.js

@@ -0,0 +1,170 @@
+import * as math from '../math';
+import { scale_lattice_matrix } from '../math';
+import { wrap_frac_coord } from './pbc';
+import { normalize_structure_bond } from './bonding';
+const mod = (value, divisor) => ((value % divisor) + divisor) % divisor;
+const replicate_bonds_for_supercell = (bonds, n_sites, scaling_factors) => {
+    const [scale_x, scale_y, scale_z] = scaling_factors;
+    const replicated = [];
+    const site_offset = ([cell_x, cell_y, cell_z]) => (cell_z * scale_x * scale_y + cell_y * scale_x + cell_x) * n_sites;
+    for (const [source_cell_idx, source_cell] of generate_lattice_points(scaling_factors).entries()) {
+        const source_offset = source_cell_idx * n_sites;
+        for (const { site_idx_1, site_idx_2, order, cell_shift = [0, 0, 0] } of bonds) {
+            const target_raw = [
+                source_cell[0] + cell_shift[0],
+                source_cell[1] + cell_shift[1],
+                source_cell[2] + cell_shift[2],
+            ];
+            const target_cell = [
+                mod(target_raw[0], scale_x),
+                mod(target_raw[1], scale_y),
+                mod(target_raw[2], scale_z),
+            ];
+            const supercell_shift = target_raw.map((val, idx) => Math.floor(val / scaling_factors[idx]));
+            const target_offset = site_offset(target_cell);
+            replicated.push(normalize_structure_bond(site_idx_1 + source_offset, site_idx_2 + target_offset, order, supercell_shift));
+        }
+    }
+    return replicated;
+};
+// Parse supercell scaling input from various formats. Can be "2x2x2", "2", [2,2,2], or a single number.
+// Returns [x, y, z] scaling factors.
+export function parse_supercell_scaling(scaling) {
+    if (typeof scaling === `number`) {
+        if (scaling <= 0 || !Number.isInteger(scaling)) {
+            throw new Error(`Supercell scaling must be a positive integer, got: ${scaling}`);
+        }
+        return [scaling, scaling, scaling];
+    }
+    if (Array.isArray(scaling) && scaling.length === 3) {
+        if (scaling.some((val) => !Number.isInteger(val) || val <= 0)) {
+            throw new Error(`All supercell scaling factors must be positive integers: ${scaling}`);
+        }
+        return scaling;
+    }
+    if (typeof scaling === `string`) {
+        // Parse "2x2x2" format
+        const parts = scaling
+            .trim()
+            .toLowerCase()
+            .split(/[x×,\s]+/)
+            .filter((part) => part.length > 0);
+        if (parts.length === 1 || parts.length === 3) {
+            // Check that all parts are strictly digits to avoid scientific notation/hex/etc per tests
+            if (parts.every((part) => /^\d+$/.test(part))) {
+                const values = parts.map(Number);
+                if (values.every((val) => val > 0)) {
+                    return (parts.length === 1 ? [values[0], values[0], values[0]] : values);
+                }
+            }
+        }
+    }
+    throw new Error(`Invalid supercell scaling: ${scaling}`);
+}
+// Generate all lattice points for a supercell. Takes [scale_x, scale_y, scale_z] scaling factors
+// and returns array of fractional coordinates for lattice points
+export function generate_lattice_points(scaling_factors) {
+    const [scale_x, scale_y, scale_z] = scaling_factors;
+    const count = scale_x * scale_y * scale_z;
+    const points = Array(count);
+    let write_idx = 0;
+    // Generate in x, y, z order to match expected test results
+    for (let kk = 0; kk < scale_z; kk++) {
+        for (let jj = 0; jj < scale_y; jj++) {
+            for (let ii = 0; ii < scale_x; ii++) {
+                points[write_idx++] = [ii, jj, kk];
+            }
+        }
+    }
+    return points;
+}
+// Re-export from $lib/math for backward compatibility
+export { scale_lattice_matrix };
+// Create a supercell from a Crystal
+// Takes original structure, scaling factors, and whether to fold coordinates back to unit cell (default: true)
+// Returns new supercell structure
+export function make_supercell(structure, scaling, to_unit_cell = true) {
+    if (!structure.lattice) {
+        throw new Error(`Cannot create supercell: structure has no lattice`);
+    }
+    const supercell_scaling = parse_supercell_scaling(scaling);
+    const [scale_x, scale_y, scale_z] = supercell_scaling;
+    const total_cells = scale_x * scale_y * scale_z;
+    // Short circuit for 1x1x1 (no actual supercell needed)
+    if (scale_x === 1 && scale_y === 1 && scale_z === 1) {
+        return { ...structure, supercell_scaling };
+    }
+    const orig_matrix = structure.lattice.matrix;
+    // Create new scaled lattice
+    const new_lattice_matrix = scale_lattice_matrix(orig_matrix, supercell_scaling);
+    const lattice_params = math.calc_lattice_params(new_lattice_matrix);
+    const new_lattice = {
+        ...structure.lattice,
+        matrix: new_lattice_matrix,
+        ...lattice_params,
+    };
+    // Pre-allocate sites array
+    const n_sites = structure.sites.length;
+    const new_sites = Array(n_sites * total_cells);
+    // Destructure lattice vectors for fast inline arithmetic (avoid function calls in hot loop)
+    const [[ax, ay, az], [bx, by, bz], [cx, cy, cz]] = orig_matrix;
+    const [sx, sy, sz] = supercell_scaling;
+    let write_idx = 0;
+    const sites = structure.sites;
+    // Loop order: k, j, i to match typical pymatgen/standard ordering
+    for (let kk = 0; kk < scale_z; kk++) {
+        for (let jj = 0; jj < scale_y; jj++) {
+            for (let ii = 0; ii < scale_x; ii++) {
+                const label_suffix = total_cells > 1 ? `_${ii}${jj}${kk}` : ``;
+                // Translation = ii * vec_a + jj * vec_b + kk * vec_c (inlined for performance)
+                const tx = ii * ax + jj * bx + kk * cx;
+                const ty = ii * ay + jj * by + kk * cy;
+                const tz = ii * az + jj * bz + kk * cz;
+                for (let site_idx = 0; site_idx < n_sites; site_idx++) {
+                    const site = sites[site_idx];
+                    // new_abc = (old_abc + [ii, jj, kk]) / supercell_scaling
+                    let new_a = (site.abc[0] + ii) / sx;
+                    let new_b = (site.abc[1] + jj) / sy;
+                    let new_c = (site.abc[2] + kk) / sz;
+                    if (to_unit_cell) {
+                        new_a = wrap_frac_coord(new_a);
+                        new_b = wrap_frac_coord(new_b);
+                        new_c = wrap_frac_coord(new_c);
+                    }
+                    new_sites[write_idx++] = {
+                        species: site.species,
+                        xyz: [site.xyz[0] + tx, site.xyz[1] + ty, site.xyz[2] + tz],
+                        abc: [new_a, new_b, new_c],
+                        label: label_suffix ? `${site.label}${label_suffix}` : site.label,
+                        properties: { ...site.properties, orig_unit_cell_idx: site_idx },
+                    };
+                }
+            }
+        }
+    }
+    const properties = structure.properties?.bonds === undefined
+        ? structure.properties
+        : {
+            ...structure.properties,
+            bonds: replicate_bonds_for_supercell(structure.properties.bonds, n_sites, supercell_scaling),
+        };
+    return {
+        ...structure,
+        lattice: new_lattice,
+        sites: new_sites,
+        properties,
+        charge: structure.charge ? structure.charge * total_cells : structure.charge,
+        supercell_scaling,
+    };
+}
+// Validate supercell input string
+// Takes user input string and returns true if valid, false otherwise
+export function is_valid_supercell_input(input) {
+    try {
+        parse_supercell_scaling(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/structure/validation.d.ts

@@ -0,0 +1,2 @@
+import type { Crystal } from './index';
+export declare function is_crystal(obj: unknown): obj is Crystal;

package/dist/structure/validation.js

@@ -0,0 +1,10 @@
+export function is_crystal(obj) {
+    if (obj === null || typeof obj !== `object`)
+        return false;
+    const structure_obj = obj;
+    const sites = structure_obj.sites;
+    const lattice = structure_obj.lattice;
+    const has_sites = Array.isArray(sites) && sites.length > 0;
+    const has_lattice = lattice !== undefined && lattice !== null && typeof lattice === `object`;
+    return has_sites && has_lattice;
+}