matterviz 0.3.6 → 0.4.0

package/dist/structure/bonding.js

@@ -0,0 +1,724 @@
+// Bonding algorithms for structure visualization
+import { element_data } from '../element';
+import * as math from '../math';
+const element_lookup = new Map(element_data.map((el) => [el.symbol, el]));
+const covalent_radii = new Map(element_data.flatMap((el) => el.covalent_radius === null ? [] : [[el.symbol, el.covalent_radius]]));
+const is_zero_cell_shift = (cell_shift) => cell_shift === undefined || cell_shift.every((val) => val === 0);
+const format_cell_shift = (cell_shift) => {
+    if (cell_shift === undefined || is_zero_cell_shift(cell_shift))
+        return ``;
+    return `@${cell_shift.join(`,`)}`;
+};
+const negate_cell_shift = (cell_shift) => [
+    cell_shift[0] === 0 ? 0 : -cell_shift[0],
+    cell_shift[1] === 0 ? 0 : -cell_shift[1],
+    cell_shift[2] === 0 ? 0 : -cell_shift[2],
+];
+const canonical_self_bond_shift = (cell_shift) => {
+    const first_non_zero = cell_shift.find((val) => val !== 0);
+    return first_non_zero !== undefined && first_non_zero < 0
+        ? negate_cell_shift(cell_shift)
+        : cell_shift;
+};
+const normalize_bond_endpoints = (site_idx_1, site_idx_2, cell_shift) => {
+    if (site_idx_1 === site_idx_2) {
+        const ordered = { site_idx_1, site_idx_2 };
+        if (cell_shift === undefined || is_zero_cell_shift(cell_shift))
+            return ordered;
+        return { ...ordered, cell_shift: canonical_self_bond_shift(cell_shift) };
+    }
+    const ordered = site_idx_1 < site_idx_2
+        ? { site_idx_1, site_idx_2 }
+        : { site_idx_1: site_idx_2, site_idx_2: site_idx_1 };
+    if (cell_shift === undefined || is_zero_cell_shift(cell_shift))
+        return ordered;
+    return {
+        ...ordered,
+        cell_shift: site_idx_1 < site_idx_2 ? cell_shift : negate_cell_shift(cell_shift),
+    };
+};
+export const normalize_structure_bond = (site_idx_1, site_idx_2, order, cell_shift) => {
+    const bond = normalize_bond_endpoints(site_idx_1, site_idx_2, cell_shift);
+    return { ...bond, order };
+};
+export const get_bond_key = (idx_1, idx_2, cell_shift) => {
+    const normalized = normalize_bond_endpoints(idx_1, idx_2, cell_shift);
+    return `${normalized.site_idx_1}-${normalized.site_idx_2}${format_cell_shift(normalized.cell_shift)}`;
+};
+// Remap explicit bond metadata after site deletion: drop bonds touching deleted
+// sites and shift each surviving index down by the number of deleted indices below it.
+export function remap_bonds_after_deletion(bonds, deleted_indices) {
+    // Sort the deleted indices once; shift each surviving index down by the count of deleted
+    // indices below it via binary search (O(log m) per lookup vs re-filtering the set each call).
+    const sorted = [...deleted_indices].sort((idx_a, idx_b) => idx_a - idx_b);
+    const shift = (idx) => {
+        let [lo, hi] = [0, sorted.length];
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (sorted[mid] < idx)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return idx - lo; // lo == count of deleted indices < idx
+    };
+    return bonds
+        .filter((bond) => !deleted_indices.has(bond.site_idx_1) && !deleted_indices.has(bond.site_idx_2))
+        .map((bond) => ({
+        ...bond,
+        site_idx_1: shift(bond.site_idx_1),
+        site_idx_2: shift(bond.site_idx_2),
+    }));
+}
+export const BOND_ORDER_OPTIONS = [
+    { order: 1, label: `Single` },
+    { order: 1.5, label: `1.5` },
+    { order: 2, label: `Double` },
+    { order: 3, label: `Triple` },
+    { order: `aromatic`, label: `Aromatic` },
+];
+const site_image_shift = (sites, site_idx) => {
+    const site = sites?.[site_idx];
+    const orig_site_idx = site?.properties?.orig_site_idx;
+    if (typeof orig_site_idx !== `number`)
+        return [0, 0, 0];
+    const orig_site = sites?.[orig_site_idx];
+    if (!site?.abc || !orig_site?.abc)
+        return [0, 0, 0];
+    return [
+        Math.round(site.abc[0] - orig_site.abc[0]),
+        Math.round(site.abc[1] - orig_site.abc[1]),
+        Math.round(site.abc[2] - orig_site.abc[2]),
+    ];
+};
+const original_site_idx = (sites, site_idx) => {
+    const orig_site_idx = sites?.[site_idx]?.properties?.orig_site_idx;
+    return typeof orig_site_idx === `number` ? orig_site_idx : site_idx;
+};
+export const canonicalize_bond_target = (bond, sites) => {
+    const shift_1 = site_image_shift(sites, bond.site_idx_1);
+    const shift_2 = site_image_shift(sites, bond.site_idx_2);
+    const base_shift = bond.cell_shift ?? [0, 0, 0];
+    const cell_shift = [
+        base_shift[0] + shift_2[0] - shift_1[0],
+        base_shift[1] + shift_2[1] - shift_1[1],
+        base_shift[2] + shift_2[2] - shift_1[2],
+    ];
+    return normalize_bond_endpoints(original_site_idx(sites, bond.site_idx_1), original_site_idx(sites, bond.site_idx_2), cell_shift);
+};
+const bond_key_for = (bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift);
+const matches_bond_key = (bond, key) => bond_key_for(bond) === key;
+const replace_bond = (bonds, next_bond) => {
+    const key = bond_key_for(next_bond);
+    return [...bonds.filter((bond) => !matches_bond_key(bond, key)), next_bond];
+};
+const remove_bond_key = (bonds, key) => bonds.filter((bond) => !matches_bond_key(bond, key));
+const includes_bond_key = (bonds, key) => bonds.some((bond) => matches_bond_key(bond, key));
+const get_bond_order = (bond) => bond?.bond_order ?? bond?.order ?? 1;
+const find_bond_by_key = (bonds, key) => bonds.find((bond) => matches_bond_key(bond, key));
+const make_bond_record = (bond, order) => normalize_structure_bond(bond.site_idx_1, bond.site_idx_2, order, bond.cell_shift);
+export function has_visible_bond(edit_state, bond, calculated_bonds) {
+    const key = bond_key_for(bond);
+    if (includes_bond_key(edit_state.removed_bonds, key)) {
+        return false;
+    }
+    if (includes_bond_key(edit_state.added_bonds, key))
+        return true;
+    return includes_bond_key(calculated_bonds, key);
+}
+export function add_or_restore_bond(edit_state, bond, calculated_bonds, order) {
+    const record = make_bond_record(bond, order);
+    const key = bond_key_for(record);
+    const removed_bond = find_bond_by_key(edit_state.removed_bonds, key);
+    if (removed_bond) {
+        return {
+            action: `restored`,
+            changed: true,
+            state: {
+                ...edit_state,
+                added_bonds: remove_bond_key(edit_state.added_bonds, key),
+                removed_bonds: remove_bond_key(edit_state.removed_bonds, key),
+                bond_order_overrides: removed_bond.order === order
+                    ? remove_bond_key(edit_state.bond_order_overrides, key)
+                    : replace_bond(edit_state.bond_order_overrides, record),
+            },
+        };
+    }
+    if (has_visible_bond(edit_state, record, calculated_bonds)) {
+        return { action: `already-visible`, changed: false, state: edit_state };
+    }
+    return {
+        action: `added`,
+        changed: true,
+        state: {
+            ...edit_state,
+            added_bonds: replace_bond(edit_state.added_bonds, record),
+            bond_order_overrides: remove_bond_key(edit_state.bond_order_overrides, key),
+        },
+    };
+}
+export function delete_bond(edit_state, bond, calculated_bonds) {
+    const record = make_bond_record(bond, 1);
+    const key = bond_key_for(record);
+    if (includes_bond_key(edit_state.added_bonds, key)) {
+        return {
+            action: `deleted-added`,
+            changed: true,
+            state: {
+                ...edit_state,
+                added_bonds: remove_bond_key(edit_state.added_bonds, key),
+                bond_order_overrides: remove_bond_key(edit_state.bond_order_overrides, key),
+            },
+        };
+    }
+    const calculated = find_bond_by_key(calculated_bonds, key);
+    if (!calculated || includes_bond_key(edit_state.removed_bonds, key)) {
+        return { action: `not-visible`, changed: false, state: edit_state };
+    }
+    return {
+        action: `deleted-calculated`,
+        changed: true,
+        state: {
+            ...edit_state,
+            removed_bonds: replace_bond(edit_state.removed_bonds, {
+                ...record,
+                order: get_bond_order(calculated),
+            }),
+            bond_order_overrides: remove_bond_key(edit_state.bond_order_overrides, key),
+        },
+    };
+}
+export function set_bond_order(edit_state, bond, calculated_bonds, order) {
+    const record = make_bond_record(bond, order);
+    const key = bond_key_for(record);
+    const calculated = find_bond_by_key(calculated_bonds, key);
+    if (calculated) {
+        const visible_order = get_bond_order(calculated);
+        const has_existing_edit = includes_bond_key(edit_state.added_bonds, key) ||
+            includes_bond_key(edit_state.removed_bonds, key) ||
+            includes_bond_key(edit_state.bond_order_overrides, key);
+        const next_overrides = order === visible_order
+            ? remove_bond_key(edit_state.bond_order_overrides, key)
+            : replace_bond(edit_state.bond_order_overrides, record);
+        const next_state = {
+            added_bonds: remove_bond_key(edit_state.added_bonds, key),
+            removed_bonds: remove_bond_key(edit_state.removed_bonds, key),
+            bond_order_overrides: next_overrides,
+        };
+        return {
+            action: `ordered-calculated`,
+            changed: has_existing_edit || order !== visible_order,
+            state: next_state,
+        };
+    }
+    return {
+        action: `ordered-added`,
+        changed: true,
+        state: {
+            ...edit_state,
+            added_bonds: replace_bond(edit_state.added_bonds, record),
+            bond_order_overrides: remove_bond_key(edit_state.bond_order_overrides, key),
+        },
+    };
+}
+export const merge_bond_edits = (base_bonds, added, removed, overrides) => {
+    const key_for = (bond) => get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift);
+    const normalize_record = (bond) => normalize_structure_bond(bond.site_idx_1, bond.site_idx_2, bond.order, bond.cell_shift);
+    const removed_keys = new Set(removed.map(key_for));
+    const merged = new Map(base_bonds
+        .filter((bond) => !removed_keys.has(key_for(bond)))
+        .map((bond) => [key_for(bond), normalize_record(bond)]));
+    // Apply additions before overrides so user-set bond orders win even if
+    // callers accidentally pass overlapping edit lists.
+    for (const bond of added) {
+        if (!removed_keys.has(key_for(bond)))
+            merged.set(key_for(bond), normalize_record(bond));
+    }
+    for (const bond of overrides) {
+        if (!removed_keys.has(key_for(bond)))
+            merged.set(key_for(bond), normalize_record(bond));
+    }
+    return [...merged.values()];
+};
+const is_record = (value) => typeof value === `object` && value !== null;
+export function normalize_bond_order(order) {
+    if (order === `aromatic`)
+        return order;
+    if (order === 1 || order === 1.5 || order === 2 || order === 3)
+        return order;
+    return null;
+}
+function normalize_cell_shift(cell_shift) {
+    if (cell_shift === undefined)
+        return undefined;
+    if (!Array.isArray(cell_shift) || cell_shift.length !== 3)
+        return null;
+    return cell_shift.some((val) => typeof val !== `number` || !Number.isInteger(val))
+        ? null
+        : [cell_shift[0], cell_shift[1], cell_shift[2]];
+}
+function lattice_translation(structure, cell_shift) {
+    if (cell_shift === undefined || is_zero_cell_shift(cell_shift))
+        return [0, 0, 0];
+    if (!(`lattice` in structure)) {
+        throw new Error(`Explicit bond cell_shift requires a crystal lattice`);
+    }
+    const [shift_a, shift_b, shift_c] = cell_shift;
+    const [vec_a, vec_b, vec_c] = structure.lattice.matrix;
+    return math.add(math.scale(vec_a, shift_a), math.scale(vec_b, shift_b), math.scale(vec_c, shift_c));
+}
+export function structure_bond_to_bond_pair(structure, bond) {
+    const { site_idx_1, site_idx_2, order, cell_shift } = bond;
+    const site_1 = structure.sites[site_idx_1];
+    const site_2 = structure.sites[site_idx_2];
+    if (!site_1 || !site_2) {
+        throw new Error(`Cannot create bond pair for invalid site indices ${site_idx_1}, ${site_idx_2}`);
+    }
+    const pos_1 = site_1.xyz;
+    const pos_2 = math.add(site_2.xyz, lattice_translation(structure, cell_shift));
+    return {
+        pos_1,
+        pos_2,
+        site_idx_1,
+        site_idx_2,
+        bond_length: math.euclidean_dist(pos_1, pos_2),
+        strength: 1,
+        bond_order: order,
+        cell_shift,
+        transform_matrix: compute_bond_transform(pos_1, pos_2),
+    };
+}
+export function get_explicit_bond_metadata(structure) {
+    const raw_bonds = structure.properties?.bonds;
+    if (raw_bonds === undefined)
+        return [];
+    if (!Array.isArray(raw_bonds)) {
+        console.warn(`Ignoring structure.properties.bonds because it is not an array`);
+        return [];
+    }
+    const explicit_bonds = new Map();
+    for (const [entry_idx, raw_bond] of raw_bonds.entries()) {
+        if (!is_record(raw_bond)) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: expected object`);
+            continue;
+        }
+        const { order } = raw_bond;
+        const site_idx_1 = raw_bond.site_idx_1;
+        const site_idx_2 = raw_bond.site_idx_2;
+        if (typeof site_idx_1 !== `number` ||
+            typeof site_idx_2 !== `number` ||
+            !Number.isInteger(site_idx_1) ||
+            !Number.isInteger(site_idx_2)) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: site indices must be integers`);
+            continue;
+        }
+        if (site_idx_1 < 0 ||
+            site_idx_2 < 0 ||
+            site_idx_1 >= structure.sites.length ||
+            site_idx_2 >= structure.sites.length) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: site indices ${site_idx_1}, ${site_idx_2} are out of range for ${structure.sites.length} sites`);
+            continue;
+        }
+        const bond_order = normalize_bond_order(order);
+        if (bond_order === null) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: unsupported order ${String(order)}`);
+            continue;
+        }
+        const cell_shift = normalize_cell_shift(raw_bond.cell_shift);
+        if (cell_shift === null) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: cell_shift must be three integers`);
+            continue;
+        }
+        if (site_idx_1 === site_idx_2 && is_zero_cell_shift(cell_shift)) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: endpoints match`);
+            continue;
+        }
+        if (cell_shift !== undefined &&
+            !is_zero_cell_shift(cell_shift) &&
+            !(`lattice` in structure)) {
+            console.warn(`Ignoring invalid explicit bond at index ${entry_idx}: cell_shift requires a crystal lattice`);
+            continue;
+        }
+        const key = get_bond_key(site_idx_1, site_idx_2, cell_shift);
+        if (explicit_bonds.has(key)) {
+            console.warn(`Duplicate explicit bond definition at index ${entry_idx} for site indices ${site_idx_1}, ${site_idx_2} with order ${bond_order}; will overwrite the previous entry`);
+        }
+        explicit_bonds.set(key, normalize_structure_bond(site_idx_1, site_idx_2, bond_order, cell_shift));
+    }
+    return [...explicit_bonds.values()];
+}
+export function apply_explicit_bond_metadata(structure, bonds) {
+    const explicit_bonds = get_explicit_bond_metadata(structure);
+    if (explicit_bonds.length === 0)
+        return bonds;
+    const explicit_by_key = new Map(explicit_bonds.map((bond) => [
+        get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift),
+        bond,
+    ]));
+    const merged = bonds.map((bond) => {
+        const key = get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift);
+        const explicit = explicit_by_key.get(key);
+        if (!explicit)
+            return bond;
+        explicit_by_key.delete(key);
+        return { ...bond, bond_order: explicit.order };
+    });
+    for (const explicit_bond of explicit_by_key.values()) {
+        merged.push(structure_bond_to_bond_pair(structure, explicit_bond));
+    }
+    return merged;
+}
+export function scale_and_offset_bond_matrix(transform_matrix, offset, radius_scale) {
+    const matrix = new Float32Array(transform_matrix);
+    // Column-major 4x4 layout: 0-2 are the right vector, 8-10 are the forward
+    // vector. Scale orientation columns for cylinder radius, not translation.
+    for (const matrix_idx of [0, 1, 2, 8, 9, 10]) {
+        matrix[matrix_idx] *= radius_scale;
+    }
+    const right_len = Math.hypot(matrix[0], matrix[1], matrix[2]) || 1;
+    const offset_dir = [
+        matrix[0] / right_len,
+        matrix[1] / right_len,
+        matrix[2] / right_len,
+    ];
+    matrix[12] += offset_dir[0] * offset;
+    matrix[13] += offset_dir[1] * offset;
+    matrix[14] += offset_dir[2] * offset;
+    return matrix;
+}
+export function get_bond_render_matrices(bond, bond_thickness) {
+    const order = bond.bond_order ?? 1;
+    const gap = bond_thickness * 1.8;
+    // Parallel cylinder [offset, radius_scale] pairs per bond order; empty → a single
+    // full-width bond (handled by the fallback below)
+    let offsets_and_scales = [];
+    if (order === 2)
+        offsets_and_scales = [
+            [-gap / 2, 0.65],
+            [gap / 2, 0.65],
+        ];
+    else if (order === 3)
+        offsets_and_scales = [
+            [-gap, 0.55],
+            [0, 0.55],
+            [gap, 0.55],
+        ];
+    else if (order === 1.5 || order === `aromatic`) {
+        offsets_and_scales = [
+            [-gap / 2, 0.75],
+            [gap / 2, 0.4],
+        ];
+    }
+    return offsets_and_scales.length === 0
+        ? [bond.transform_matrix]
+        : offsets_and_scales.map(([offset, radius_scale]) => scale_and_offset_bond_matrix(bond.transform_matrix, offset, radius_scale));
+}
+// Get the species with highest occupancy from a site.
+const get_majority_species = (site) => (site.species ?? []).reduce((max_species, species) => (species.occu > max_species.occu ? species : max_species), site.species?.[0] ?? { element: ``, occu: -1 });
+// Helper to extract numeric index from site properties
+function get_orig_idx(site, fallback) {
+    const props = site.properties;
+    if (!props)
+        return fallback;
+    const raw = props.orig_unit_cell_idx ?? props.orig_site_idx;
+    if (raw === undefined)
+        return fallback;
+    const num = Number(raw);
+    return Number.isFinite(num) ? num : fallback;
+}
+// Compute 4x4 transformation matrix for bond cylinder between two positions.
+// Uses Y-up, right-handed coordinate system convention for Three.js compatibility.
+export function compute_bond_transform(pos_1, pos_2) {
+    const [dx, dy, dz] = math.subtract(pos_2, pos_1);
+    const height = Math.hypot(dx, dy, dz);
+    if (height < 1e-10) {
+        return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+    }
+    const [dir_x, dir_y, dir_z] = [dx / height, dy / height, dz / height];
+    let [m00, m01, m02, m10, m11, m12, m20, m21, m22] = [0, 0, 0, 0, 0, 0, 0, 0, 0];
+    // Special case: bond pointing straight up (+Y)
+    if (Math.abs(dir_y - 1.0) < 1e-10) {
+        ;
+        [m00, m01, m02, m10, m11, m12, m20, m21, m22] = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+    }
+    else if (Math.abs(dir_y + 1.0) < 1e-10) {
+        // Special case: bond pointing straight down (-Y)
+        ;
+        [m00, m01, m02, m10, m11, m12, m20, m21, m22] = [1, 0, 0, 0, -1, 0, 0, 0, 1];
+    }
+    else {
+        // General case: construct orthonormal basis (right, dir, up)
+        // Right vector: perpendicular to dir in XZ plane
+        const [rx, rz] = [-dir_z, dir_x];
+        const r_len = Math.hypot(rx, rz);
+        const [right_x, right_z] = [rx / r_len, rz / r_len];
+        // Up vector: cross product of dir and right
+        const [up_x, up_y, up_z] = [
+            dir_y * right_z,
+            dir_z * right_x - dir_x * right_z,
+            -dir_y * right_x,
+        ];
+        [m00, m01, m02, m10, m11, m12, m20, m21, m22] = [
+            right_x,
+            dir_x,
+            up_x,
+            0,
+            dir_y,
+            up_y,
+            right_z,
+            dir_z,
+            up_z,
+        ];
+    }
+    // Position at midpoint between the two atoms
+    const [px, py, pz] = [
+        (pos_1[0] + pos_2[0]) / 2,
+        (pos_1[1] + pos_2[1]) / 2,
+        (pos_1[2] + pos_2[2]) / 2,
+    ];
+    return new Float32Array([
+        // Return flattened column-major 4x4 matrix for Three.js
+        m00,
+        m10,
+        m20,
+        0,
+        m01 * height,
+        m11 * height,
+        m21 * height,
+        0,
+        m02,
+        m12,
+        m22,
+        0,
+        px,
+        py,
+        pz,
+        1,
+    ]);
+}
+// Build spatial grid by dividing 3D space into cubic cells.
+function build_spatial_grid(sites, cell_size) {
+    const grid = new Map();
+    for (let idx = 0; idx < sites.length; idx++) {
+        const [x, y, z] = sites[idx].xyz.map((coord) => Math.floor(coord / cell_size));
+        const key = `${x},${y},${z}`;
+        const cell = grid.get(key);
+        if (cell)
+            cell.push(idx);
+        else
+            grid.set(key, [idx]);
+    }
+    return grid;
+}
+// Get all site indices in 3x3x3 cube of cells around position.
+function get_neighbors_from_grid(pos, grid, cell_size) {
+    const [cx, cy, cz] = [
+        Math.floor(pos[0] / cell_size),
+        Math.floor(pos[1] / cell_size),
+        Math.floor(pos[2] / cell_size),
+    ];
+    const neighbors = [];
+    for (let dx = -1; dx <= 1; dx++) {
+        for (let dy = -1; dy <= 1; dy++) {
+            for (let dz = -1; dz <= 1; dz++) {
+                const cell = grid.get(`${cx + dx},${cy + dy},${cz + dz}`);
+                if (cell)
+                    neighbors.push(...cell);
+            }
+        }
+    }
+    return neighbors;
+}
+// Setup spatial decomposition for structures with >50 atoms.
+function setup_spatial_grid(sites, cutoff) {
+    const use_grid = sites.length > 50;
+    return use_grid ? { grid: build_spatial_grid(sites, cutoff), cell_size: cutoff } : null;
+}
+// Get candidate neighbor indices using spatial grid or all sites.
+const get_candidates = (pos, sites, spatial) => spatial
+    ? get_neighbors_from_grid(pos, spatial.grid, spatial.cell_size)
+    : Array.from({ length: sites.length }, (_, idx) => idx);
+export const BONDING_STRATEGIES = { electroneg_ratio, solid_angle };
+// Electronegativity-based bonding with chemical preferences.
+// This algorithm considers electronegativity differences between atoms, metal/nonmetal
+// properties, and distance to determine bond strength. Bonds are only created if the
+// computed strength exceeds the strength_threshold parameter (default: 0.3).
+export function electroneg_ratio(structure, { electronegativity_threshold = 1.7, // Max electronegativity difference for bonding
+max_distance_ratio = 2.0, // Max distance as multiple of sum of covalent radii
+min_bond_dist = 0.4, // Minimum bond distance in Angstroms
+metal_metal_penalty = 0.7, // Strength penalty for metal-metal bonds
+metal_nonmetal_bonus = 1.5, // Strength bonus for metal-nonmetal bonds
+similar_electronegativity_bonus = 1.2, // Bonus for similar electronegativity
+same_species_penalty = 0.5, // Penalty for bonds between same element
+strength_threshold = 0.3, // Minimum bond strength to include in results
+ } = {}) {
+    const { sites } = structure;
+    if (sites.length < 2)
+        return [];
+    const bonds = [];
+    const min_dist_sq = min_bond_dist ** 2;
+    const closest = new Map();
+    const props = sites.map((site) => {
+        const majority = get_majority_species(site);
+        const elem = majority.element;
+        const data = element_lookup.get(elem);
+        return {
+            element: elem,
+            electroneg: data?.electronegativity ?? 2.0,
+            is_metal: data?.metal ?? false,
+            is_nonmetal: data?.nonmetal ?? false,
+            radius: elem ? covalent_radii.get(elem) : undefined,
+        };
+    });
+    let max_radius = 0;
+    for (const radius of covalent_radii.values()) {
+        if (radius > max_radius)
+            max_radius = radius;
+    }
+    const max_cutoff = max_radius * 2 * max_distance_ratio;
+    const spatial = setup_spatial_grid(sites, max_cutoff);
+    const potential_bonds = [];
+    for (let idx_a = 0; idx_a < sites.length - 1; idx_a++) {
+        const [x1, y1, z1] = sites[idx_a].xyz;
+        const props_a = props[idx_a];
+        for (const idx_b of get_candidates(sites[idx_a].xyz, sites, spatial)) {
+            if (idx_b <= idx_a)
+                continue;
+            const [x2, y2, z2] = sites[idx_b].xyz;
+            const props_b = props[idx_b];
+            const [dx, dy, dz] = [x2 - x1, y2 - y1, z2 - z1];
+            const dist_sq = dx * dx + dy * dy + dz * dz;
+            const dist = Math.sqrt(dist_sq);
+            if (dist_sq < min_dist_sq || !props_a.radius || !props_b.radius)
+                continue;
+            const expected = props_a.radius + props_b.radius;
+            if (dist > expected * max_distance_ratio)
+                continue;
+            const electroneg_diff = Math.abs(props_a.electroneg - props_b.electroneg);
+            const electroneg_balance = electroneg_diff / (props_a.electroneg + props_b.electroneg);
+            let bond_strength = 1.0;
+            if (props_a.is_metal && props_b.is_metal) {
+                bond_strength *= metal_metal_penalty;
+            }
+            else if ((props_a.is_metal && props_b.is_nonmetal) ||
+                (props_a.is_nonmetal && props_b.is_metal)) {
+                bond_strength *= metal_nonmetal_bonus;
+                if (electroneg_diff > electronegativity_threshold)
+                    bond_strength *= 1.3;
+            }
+            else if (electroneg_diff < 0.5) {
+                bond_strength *= similar_electronegativity_bonus;
+            }
+            const dist_weight = Math.exp(-((dist / expected - 1) ** 2) / 0.18);
+            const electroneg_weight = 1.0 - 0.3 * electroneg_balance;
+            let strength = bond_strength * dist_weight * electroneg_weight;
+            if (props_a.element === props_b.element)
+                strength *= same_species_penalty;
+            // If raw strength is already too low, we can skip early
+            // (penalty will only reduce it further)
+            if (strength <= strength_threshold)
+                continue;
+            // Use helper logic to handle both supercell and image atoms with robust normalization
+            const orig_idx_a = get_orig_idx(sites[idx_a], idx_a);
+            const orig_idx_b = get_orig_idx(sites[idx_b], idx_b);
+            // Update closest known normalized distance (dist / expected) for original atoms
+            // Normalized distance handles atoms of different sizes better than raw distance
+            // (e.g. C-H is short but C-C is longer; we don't want C-H to penalize C-C just because H is small)
+            const norm_dist = dist / expected;
+            const closest_dist_a = closest.get(orig_idx_a) ?? Infinity;
+            if (norm_dist < closest_dist_a)
+                closest.set(orig_idx_a, norm_dist);
+            const closest_dist_b = closest.get(orig_idx_b) ?? Infinity;
+            if (norm_dist < closest_dist_b)
+                closest.set(orig_idx_b, norm_dist);
+            potential_bonds.push({
+                site_idx_1: idx_a,
+                site_idx_2: idx_b,
+                dist,
+                expected_dist: expected,
+                base_strength: strength,
+                orig_idx_a,
+                orig_idx_b,
+            });
+        }
+    }
+    // Second pass: Apply penalties and filter
+    for (const bond of potential_bonds) {
+        const { site_idx_1, site_idx_2, dist, expected_dist, base_strength, orig_idx_a, orig_idx_b, } = bond;
+        const closest_dist_a = closest.get(orig_idx_a) ?? Infinity;
+        const closest_dist_b = closest.get(orig_idx_b) ?? Infinity;
+        const norm_dist = dist / expected_dist;
+        let strength = base_strength;
+        // Apply penalty if this bond is much longer (relative to radii) than the closest known bond
+        if (norm_dist > closest_dist_a) {
+            strength *= Math.exp(-(norm_dist / closest_dist_a - 1) / 0.5);
+        }
+        if (orig_idx_b !== orig_idx_a && norm_dist > closest_dist_b) {
+            strength *= Math.exp(-(norm_dist / closest_dist_b - 1) / 0.5);
+        }
+        if (strength > strength_threshold) {
+            bonds.push({
+                pos_1: sites[site_idx_1].xyz,
+                pos_2: sites[site_idx_2].xyz,
+                site_idx_1,
+                site_idx_2,
+                bond_length: dist,
+                strength,
+                transform_matrix: compute_bond_transform(sites[site_idx_1].xyz, sites[site_idx_2].xyz),
+            });
+        }
+    }
+    return apply_explicit_bond_metadata(structure, bonds);
+}
+// Solid angle-based bonding using geometric proximity heuristics.
+// Inspired by Voronoi tessellation without having to actually compute Voronoi cells.
+// This algorithm computes bond strength based on the solid angle subtended by atoms
+// and their distance penalty. Bonds are only created if the computed strength exceeds
+// the strength_threshold parameter.
+export function solid_angle(structure, { min_solid_angle = 0.01, min_face_area = 0.05, max_distance = 5.0, min_bond_dist = 0.4, strength_threshold = 0.05, } = {}) {
+    const { sites } = structure;
+    if (sites.length < 2)
+        return [];
+    const bonds = [];
+    const min_dist_sq = min_bond_dist ** 2;
+    const max_dist_sq = max_distance ** 2;
+    const spatial = setup_spatial_grid(sites, max_distance);
+    for (let idx_a = 0; idx_a < sites.length - 1; idx_a++) {
+        const [x1, y1, z1] = sites[idx_a].xyz;
+        const majority_a = get_majority_species(sites[idx_a]);
+        const radius_a = majority_a.element ? covalent_radii.get(majority_a.element) : undefined;
+        for (const idx_b of get_candidates(sites[idx_a].xyz, sites, spatial)) {
+            if (idx_b <= idx_a)
+                continue;
+            const [x2, y2, z2] = sites[idx_b].xyz;
+            const majority_b = get_majority_species(sites[idx_b]);
+            const radius_b = majority_b.element ? covalent_radii.get(majority_b.element) : undefined;
+            const [dx, dy, dz] = [x2 - x1, y2 - y1, z2 - z1];
+            const dist_sq = dx * dx + dy * dy + dz * dz;
+            const dist = Math.sqrt(dist_sq);
+            if (dist_sq < min_dist_sq || dist_sq > max_dist_sq || !radius_a || !radius_b) {
+                continue;
+            }
+            const avg_radius = (radius_a + radius_b) / 2.0;
+            const face_area = Math.PI * avg_radius * avg_radius;
+            const bond_solid_angle = face_area / dist_sq;
+            if (bond_solid_angle < min_solid_angle || face_area < min_face_area)
+                continue;
+            const dist_penalty = Math.exp(-((dist / (radius_a + radius_b) - 1) ** 2) / 0.4);
+            const angle_strength = Math.min(bond_solid_angle / (4.0 * Math.PI), 1.0);
+            const strength = angle_strength * dist_penalty;
+            if (strength > strength_threshold) {
+                bonds.push({
+                    pos_1: sites[idx_a].xyz,
+                    pos_2: sites[idx_b].xyz,
+                    site_idx_1: idx_a,
+                    site_idx_2: idx_b,
+                    bond_length: dist,
+                    strength,
+                    transform_matrix: compute_bond_transform(sites[idx_a].xyz, sites[idx_b].xyz),
+                });
+            }
+        }
+    }
+    return apply_explicit_bond_metadata(structure, bonds);
+}