matterviz 0.3.6 → 0.3.7

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

@@ -0,0 +1,384 @@
+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 ?? ``);
+};
+// xyz2mol atomic_valence. Valence combinations are re-sorted by total
+// valence sum so the least-saturated solution is tried first.
+const ATOMIC_VALENCE = {
+    H: [1],
+    B: [3, 4],
+    C: [4],
+    N: [3, 4],
+    O: [2, 1, 3],
+    F: [1],
+    Si: [4],
+    P: [5, 3],
+    S: [6, 3, 2],
+    Cl: [1],
+    Se: [6, 3, 2],
+    Br: [1],
+    Te: [6, 3, 2],
+    I: [1],
+};
+// xyz2mol atomic_valence_electrons (group valence-electron count).
+const VALENCE_ELECTRONS = {
+    H: 1,
+    B: 3,
+    C: 4,
+    N: 5,
+    O: 6,
+    F: 7,
+    Si: 4,
+    P: 5,
+    S: 6,
+    Cl: 7,
+    Se: 6,
+    Br: 7,
+    Te: 6,
+    I: 7,
+};
+// xyz2mol get_atomic_charge: formal charge from the atom's actual bond
+// valence. H/B use (group-1-like) special forms; hypervalent P(V) and
+// S(VI) are treated as neutral; everything else is group - 8 + valence.
+function formal_charge(symbol, bond_valence) {
+    if (symbol === `H`)
+        return 1 - bond_valence;
+    if (symbol === `B`)
+        return 3 - bond_valence;
+    if (symbol === `P` && bond_valence === 5)
+        return 0;
+    if (symbol === `S` && bond_valence === 6)
+        return 0;
+    return VALENCE_ELECTRONS[symbol] - 8 + bond_valence;
+}
+const is_main_group = (symbol) => symbol in ATOMIC_VALENCE;
+// Cap per-fragment valence enumeration (3^k for catenated S/Se/Te/P chains).
+const MAX_VALENCE_COMBOS = 4096;
+function split_fragments(n_atoms, edges) {
+    const adjacency = Array.from({ length: n_atoms }, () => []);
+    for (const [atom_idx_1, atom_idx_2] of edges) {
+        if (adjacency[atom_idx_1] === undefined || adjacency[atom_idx_2] === undefined) {
+            throw new Error(`Invalid edge ${atom_idx_1}-${atom_idx_2} for ${n_atoms} atoms`);
+        }
+        adjacency[atom_idx_1].push(atom_idx_2);
+        adjacency[atom_idx_2].push(atom_idx_1);
+    }
+    const seen = new Set();
+    const fragments = [];
+    for (let start = 0; start < n_atoms; start++) {
+        if (seen.has(start))
+            continue;
+        const stack = [start];
+        const frag = [];
+        seen.add(start);
+        while (stack.length) {
+            const node = stack.pop();
+            if (node === undefined)
+                break;
+            frag.push(node);
+            for (const nb of adjacency[node]) {
+                if (!seen.has(nb)) {
+                    seen.add(nb);
+                    stack.push(nb);
+                }
+            }
+        }
+        fragments.push(frag);
+    }
+    return fragments;
+}
+// Enumerate one target valence per atom, all combinations, lowest total
+// valence-sum first (xyz2mol prefers the least-saturated solution).
+function* valence_combinations(valence_lists) {
+    const combos = [];
+    const rec = (pos, acc) => {
+        if (pos === valence_lists.length) {
+            combos.push({
+                sum: acc.reduce((sum, valence) => sum + valence, 0),
+                pick: [...acc],
+            });
+            return;
+        }
+        for (const valence of valence_lists[pos])
+            rec(pos + 1, [...acc, valence]);
+    };
+    rec(0, []);
+    combos.sort((left_combo, right_combo) => left_combo.sum - right_combo.sum);
+    for (const combo of combos)
+        yield combo.pick;
+}
+const atom_valence = (atom, edges, orders) => edges.reduce((sum, edge, edge_idx) => sum + (edge.from === atom || edge.to === atom ? orders[edge_idx] : 0), 0);
+// Greedily raise bond orders toward each atom's target valence; succeeds
+// only if every atom's used valence ends exactly at its target.
+function assign_bond_orders(edges, target_valence) {
+    const orders = Array.from({ length: edges.length }, () => 1);
+    const used = (atom) => atom_valence(atom, edges, orders);
+    let progressed = true;
+    while (progressed) {
+        progressed = false;
+        let best = -1;
+        let best_deficit = 0;
+        edges.forEach((edge, edge_idx) => {
+            const deficit_1 = target_valence[edge.from] - used(edge.from);
+            const deficit_2 = target_valence[edge.to] - used(edge.to);
+            const shared_deficit = Math.min(deficit_1, deficit_2);
+            if (shared_deficit > best_deficit && orders[edge_idx] < 3) {
+                best_deficit = shared_deficit;
+                best = edge_idx;
+            }
+        });
+        if (best >= 0) {
+            orders[best] += 1;
+            progressed = true;
+        }
+    }
+    for (let atom_idx = 0; atom_idx < target_valence.length; atom_idx++) {
+        if (used(atom_idx) !== target_valence[atom_idx])
+            return null;
+    }
+    return orders;
+}
+// Spanning-tree cycle basis, deduplicated by sorted vertex set.
+function find_rings(n_atoms, edges) {
+    const adjacency = Array.from({ length: n_atoms }, () => new Set());
+    for (const [atom_idx_1, atom_idx_2] of edges) {
+        if (adjacency[atom_idx_1] === undefined || adjacency[atom_idx_2] === undefined) {
+            throw new Error(`Invalid edge ${atom_idx_1}-${atom_idx_2} for ${n_atoms} atoms`);
+        }
+        adjacency[atom_idx_1].add(atom_idx_2);
+        adjacency[atom_idx_2].add(atom_idx_1);
+    }
+    const parent = Array.from({ length: n_atoms }, () => -1);
+    const seen = new Set();
+    const rings = [];
+    const path_to_ancestor = (start_idx, ancestor_idx) => {
+        const path = [];
+        for (let path_atom_idx = start_idx; path_atom_idx !== ancestor_idx; path_atom_idx = parent[path_atom_idx]) {
+            path.push(path_atom_idx);
+        }
+        return path;
+    };
+    for (let start_idx = 0; start_idx < n_atoms; start_idx++) {
+        if (seen.has(start_idx))
+            continue;
+        const queue = [start_idx];
+        let queue_idx = 0;
+        seen.add(start_idx);
+        parent[start_idx] = -1;
+        while (queue_idx < queue.length) {
+            const current_atom_idx = queue[queue_idx++];
+            for (const neighbor_idx of adjacency[current_atom_idx]) {
+                if (!seen.has(neighbor_idx)) {
+                    seen.add(neighbor_idx);
+                    parent[neighbor_idx] = current_atom_idx;
+                    queue.push(neighbor_idx);
+                }
+                else if (parent[current_atom_idx] !== neighbor_idx) {
+                    const current_ancestors = new Set();
+                    for (let ancestor_idx = current_atom_idx; ancestor_idx !== -1; ancestor_idx = parent[ancestor_idx]) {
+                        current_ancestors.add(ancestor_idx);
+                    }
+                    for (let ancestor_idx = neighbor_idx; ancestor_idx !== -1; ancestor_idx = parent[ancestor_idx]) {
+                        if (current_ancestors.has(ancestor_idx)) {
+                            const ring = [
+                                ancestor_idx,
+                                ...path_to_ancestor(current_atom_idx, ancestor_idx),
+                                ...path_to_ancestor(neighbor_idx, ancestor_idx).toReversed(),
+                            ];
+                            if (ring.length >= 3)
+                                rings.push(ring);
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const uniq = new Map();
+    for (const ring of rings) {
+        const key = [...ring].sort((left_idx, right_idx) => left_idx - right_idx).join(`,`);
+        if (!uniq.has(key))
+            uniq.set(key, ring);
+    }
+    return [...uniq.values()];
+}
+const order_to_bond_order = (order) => order >= 3 ? 3 : order === 2 ? 2 : 1;
+// Conservative planarity check: degenerate first-3-atom planes are non-planar.
+function ring_is_planar(ring, sites) {
+    if (ring.length < 3)
+        return false;
+    const points = ring.map((atom_idx) => sites[atom_idx].xyz);
+    const v1 = [
+        points[1][0] - points[0][0],
+        points[1][1] - points[0][1],
+        points[1][2] - points[0][2],
+    ];
+    const v2 = [
+        points[2][0] - points[0][0],
+        points[2][1] - points[0][1],
+        points[2][2] - points[0][2],
+    ];
+    const nx = v1[1] * v2[2] - v1[2] * v2[1];
+    const ny = v1[2] * v2[0] - v1[0] * v2[2];
+    const nz = v1[0] * v2[1] - v1[1] * v2[0];
+    const len = Math.hypot(nx, ny, nz);
+    if (len < 1e-6)
+        return false;
+    return points.every((point) => {
+        const dev = Math.abs((point[0] - points[0][0]) * nx +
+            (point[1] - points[0][1]) * ny +
+            (point[2] - points[0][2]) * nz) / len;
+        return dev < 0.3;
+    });
+}
+// Elements that can sit in an aromatic ring contributing a p-orbital to
+// the conjugated π system (C, N, O, S). Other ring members disqualify.
+const SP2_OK = new Set([`C`, `N`, `O`, `S`]);
+// xyz2mol AC->BO core (neutral, main-group). Processes each connected
+// fragment independently; fragments containing a non-main-group atom or
+// with no valence-consistent assignment fall back to single + not perceived.
+export function perceive_bond_orders(sites, bonds, opts = {}) {
+    const max_atoms = opts.max_atoms ?? 5000;
+    if (sites.length > max_atoms) {
+        return bonds.map((bond) => ({ ...bond, bond_order: 1, perceived: false }));
+    }
+    const edges = [];
+    const result = new Map();
+    for (const bond of bonds) {
+        result.set(bond, { ...bond, bond_order: 1, perceived: false });
+        if (bond.site_idx_1 < 0 ||
+            bond.site_idx_2 < 0 ||
+            bond.site_idx_1 >= sites.length ||
+            bond.site_idx_2 >= sites.length)
+            continue;
+        edges.push({
+            from: bond.site_idx_1,
+            to: bond.site_idx_2,
+            bond,
+        });
+    }
+    const frags = split_fragments(sites.length, edges.map((edge) => [edge.from, edge.to]));
+    let ring_id = 0;
+    for (const frag of frags) {
+        const atom_set = new Set(frag);
+        const frag_edges = edges.filter((edge) => atom_set.has(edge.from));
+        const symbols = frag.map((atom_idx) => primary_element(sites[atom_idx]));
+        if (!symbols.every(is_main_group))
+            continue;
+        const idx_of = Array.from({ length: sites.length }, () => -1);
+        frag.forEach((site_idx, local_idx) => {
+            idx_of[site_idx] = local_idx;
+        });
+        const local_edges = frag_edges.map((edge) => ({
+            from: idx_of[edge.from],
+            to: idx_of[edge.to],
+            bond: edge.bond,
+        }));
+        const valence_lists = symbols.map((symbol) => ATOMIC_VALENCE[symbol]);
+        const combo_count = valence_lists.reduce((product, valence_list) => product * valence_list.length, 1);
+        if (combo_count > MAX_VALENCE_COMBOS)
+            continue;
+        let solved = null;
+        const want_charge = opts.total_charge ?? 0;
+        for (const target of valence_combinations(valence_lists)) {
+            const candidate = assign_bond_orders(local_edges, target);
+            if (!candidate)
+                continue;
+            let sum_fc = 0;
+            for (let local_atom_idx = 0; local_atom_idx < frag.length; local_atom_idx++) {
+                sum_fc += formal_charge(symbols[local_atom_idx], atom_valence(local_atom_idx, local_edges, candidate));
+            }
+            if (sum_fc === want_charge) {
+                solved = candidate;
+                break;
+            }
+        }
+        if (!solved)
+            continue;
+        local_edges.forEach((edge, edge_idx) => {
+            const order = order_to_bond_order(solved[edge_idx]);
+            result.set(edge.bond, { ...edge.bond, bond_order: order, perceived: true });
+        });
+        // Hückel aromatic post-pass, retaining Kekulé orders for display toggles.
+        const rings = find_rings(frag.length, local_edges.map((edge) => [edge.from, edge.to]));
+        for (const ring of rings) {
+            const global_ring = ring.map((local_atom_idx) => frag[local_atom_idx]);
+            const has_only_sp2_ring_atoms = global_ring.every((global_atom_idx) => SP2_OK.has(primary_element(sites[global_atom_idx])));
+            if (!has_only_sp2_ring_atoms)
+                continue;
+            if (!ring_is_planar(global_ring, sites))
+                continue;
+            const ring_set = new Set(ring);
+            const edge_is_in_ring = (edge) => ring_set.has(edge.from) && ring_set.has(edge.to);
+            const has_ring_multiple = new Set();
+            local_edges.forEach((edge, edge_idx) => {
+                if (edge_is_in_ring(edge) && solved[edge_idx] > 1) {
+                    has_ring_multiple.add(edge.from);
+                    has_ring_multiple.add(edge.to);
+                }
+            });
+            const has_any_multiple_bond = (atom_idx) => local_edges.some((edge, edge_idx) => {
+                if (edge.from !== atom_idx && edge.to !== atom_idx)
+                    return false;
+                return solved[edge_idx] > 1;
+            });
+            const has_non_ring_neighbor = (atom_idx) => local_edges.some((edge) => {
+                if (edge.from !== atom_idx && edge.to !== atom_idx)
+                    return false;
+                const neighbor_idx = edge.from === atom_idx ? edge.to : edge.from;
+                return !ring_set.has(neighbor_idx);
+            });
+            const pi_by_atom = ring.map((atom_idx) => {
+                const element = primary_element(sites[frag[atom_idx]]);
+                if (has_ring_multiple.has(atom_idx))
+                    return 1;
+                if (element === `N` || element === `O` || element === `S`)
+                    return 2;
+                if (element === `C`)
+                    return Number(has_any_multiple_bond(atom_idx) || !has_non_ring_neighbor(atom_idx));
+                return 0;
+            });
+            const pi = pi_by_atom.reduce((sum, val) => sum + val, 0);
+            if (pi_by_atom.every((val) => val > 0) && pi >= 2 && (pi - 2) % 4 === 0) {
+                const this_ring = ring_id++;
+                local_edges.forEach((edge) => {
+                    if (edge_is_in_ring(edge)) {
+                        const prev = result.get(edge.bond);
+                        if (prev === undefined)
+                            throw new Error(`Missing perceived bond`);
+                        result.set(edge.bond, {
+                            ...prev,
+                            bond_order: `aromatic`,
+                            aromatic_ring: this_ring,
+                            kekule_order: prev.kekule_order ?? (prev.bond_order === 1 ? 1 : 2),
+                            perceived: true,
+                        });
+                    }
+                });
+            }
+        }
+    }
+    return bonds.map((bond) => {
+        const perceived = result.get(bond);
+        if (perceived === undefined)
+            throw new Error(`Missing perceived bond`);
+        return perceived;
+    });
+}
+// Final display order: explicit bonds win, then Kekulé mode, then perception.
+export function compose_perceived_bonds(perceived, explicit_bonds, aromatic_display) {
+    const explicit_orders = new Map(explicit_bonds.map((bond) => [
+        get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift),
+        bond.order,
+    ]));
+    return perceived.map((bond) => {
+        const explicit = explicit_orders.get(get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift));
+        if (explicit !== undefined)
+            return { ...bond, bond_order: explicit };
+        if (aromatic_display === `kekule` &&
+            bond.bond_order === `aromatic` &&
+            bond.kekule_order !== undefined)
+            return { ...bond, bond_order: bond.kekule_order };
+        return bond;
+    });
+}

package/dist/structure/bonding.d.ts

@@ -0,0 +1,68 @@
+import type { Vec3 } from '../math';
+import type { AnyStructure, BondOrder, BondPair, Site, StructureBond } from './';
+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 type BondEditState = {
+    added_bonds: StructureBond[];
+    removed_bonds: StructureBond[];
+    bond_order_overrides: StructureBond[];
+};
+export type BondEditAction = `added` | `already-visible` | `deleted-added` | `deleted-calculated` | `not-visible` | `ordered-added` | `ordered-calculated` | `restored`;
+export type BondEditResult = {
+    action: BondEditAction;
+    changed: boolean;
+    state: BondEditState;
+};
+export type BondKeyTarget = Pick<StructureBond, `site_idx_1` | `site_idx_2` | `cell_shift`>;
+type BondOrderTarget = BondKeyTarget & {
+    bond_order?: BondOrder;
+    order?: BondOrder;
+};
+export declare const BOND_ORDER_OPTIONS: {
+    order: BondOrder;
+    label: string;
+}[];
+export declare const canonicalize_bond_target: (bond: BondKeyTarget, sites: Site[] | undefined) => BondKeyTarget;
+export declare function has_visible_bond(edit_state: BondEditState, bond: BondKeyTarget, calculated_bonds: BondOrderTarget[]): boolean;
+export declare function add_or_restore_bond(edit_state: BondEditState, bond: BondKeyTarget, calculated_bonds: BondOrderTarget[], order: BondOrder): BondEditResult;
+export declare function delete_bond(edit_state: BondEditState, bond: BondKeyTarget, calculated_bonds: BondOrderTarget[]): BondEditResult;
+export declare function set_bond_order(edit_state: BondEditState, bond: BondKeyTarget, calculated_bonds: BondOrderTarget[], order: BondOrder): BondEditResult;
+export declare const merge_bond_edits: (base_bonds: StructureBond[], added: StructureBond[], removed: StructureBond[], overrides: StructureBond[]) => StructureBond[];
+export declare function normalize_bond_order(order: unknown): BondOrder | null;
+export declare function structure_bond_to_bond_pair(structure: AnyStructure, bond: StructureBond): BondPair;
+export declare function get_explicit_bond_metadata(structure: AnyStructure): StructureBond[];
+export declare function apply_explicit_bond_metadata(structure: AnyStructure, bonds: BondPair[]): BondPair[];
+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 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 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
+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, }?: {
+    electronegativity_threshold?: number | undefined;
+    max_distance_ratio?: number | undefined;
+    min_bond_dist?: number | undefined;
+    metal_metal_penalty?: number | undefined;
+    metal_nonmetal_bonus?: number | undefined;
+    similar_electronegativity_bonus?: number | undefined;
+    same_species_penalty?: number | undefined;
+    strength_threshold?: number | undefined;
+}): BondPair[];
+export declare function solid_angle(structure: AnyStructure, { min_solid_angle, min_face_area, max_distance, min_bond_dist, strength_threshold, }?: {
+    min_solid_angle?: number | undefined;
+    min_face_area?: number | undefined;
+    max_distance?: number | undefined;
+    min_bond_dist?: number | undefined;
+    strength_threshold?: number | undefined;
+}): BondPair[];
+export {};