matterviz 0.3.5 → 0.3.6

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

@@ -1,367 +0,0 @@
-import { get_bond_key } from './bonding';
-const primary_element = (site) => {
-    return (site.species?.reduce((a, b) => (b.occu > a.occu ? b : a), 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;
-}
-function is_main_group(symbol) {
-    return 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 [a, b] of edges) {
-        if (adjacency[a] === undefined || adjacency[b] === undefined) {
-            throw new Error(`Invalid edge ${a}-${b} for ${n_atoms} atoms`);
-        }
-        adjacency[a].push(b);
-        adjacency[b].push(a);
-    }
-    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((s, v) => s + v, 0), pick: [...acc] });
-            return;
-        }
-        for (const v of valence_lists[pos])
-            rec(pos + 1, [...acc, v]);
-    };
-    rec(0, []);
-    combos.sort((a, b) => a.sum - b.sum);
-    for (const c of combos)
-        yield c.pick;
-}
-const atom_valence = (atom, edges, orders) => edges.reduce((sum, edge, edge_idx) => sum + (edge.i === atom || edge.j === 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((e, ei) => {
-            const da = target_valence[e.i] - used(e.i);
-            const db = target_valence[e.j] - used(e.j);
-            const d = Math.min(da, db);
-            if (d > best_deficit && orders[ei] < 3) {
-                best_deficit = d;
-                best = ei;
-            }
-        });
-        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, edges) {
-    const adjacency = Array.from({ length: n }, () => new Set());
-    for (const [a, b] of edges) {
-        if (adjacency[a] === undefined || adjacency[b] === undefined) {
-            throw new Error(`Invalid edge ${a}-${b} for ${n} atoms`);
-        }
-        adjacency[a].add(b);
-        adjacency[b].add(a);
-    }
-    const parent = Array.from({ length: n }, () => -1);
-    const seen = new Set();
-    const rings = [];
-    for (let s = 0; s < n; s++) {
-        if (seen.has(s))
-            continue;
-        const queue = [s];
-        let queue_idx = 0;
-        seen.add(s);
-        parent[s] = -1;
-        while (queue_idx < queue.length) {
-            const u = queue[queue_idx++];
-            for (const v of adjacency[u]) {
-                if (!seen.has(v)) {
-                    seen.add(v);
-                    parent[v] = u;
-                    queue.push(v);
-                }
-                else if (parent[u] !== v) {
-                    const path_u = [];
-                    const path_v = [];
-                    const anc_u = new Set();
-                    for (let x = u; x !== -1; x = parent[x])
-                        anc_u.add(x);
-                    for (let x = v; x !== -1; x = parent[x]) {
-                        if (anc_u.has(x)) {
-                            for (let y = u; y !== x; y = parent[y])
-                                path_u.push(y);
-                            for (let y = v; y !== x; y = parent[y])
-                                path_v.push(y);
-                            const ring = [x, ...path_u, ...path_v.toReversed()];
-                            if (ring.length >= 3)
-                                rings.push(ring);
-                            break;
-                        }
-                    }
-                }
-            }
-        }
-    }
-    const uniq = new Map();
-    for (const r of rings) {
-        const key = [...r].sort((x, y) => x - y).join(`,`);
-        if (!uniq.has(key))
-            uniq.set(key, r);
-    }
-    return [...uniq.values()];
-}
-function order_to_bond_order(o) {
-    return o >= 3 ? 3 : o === 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 p = ring.map((a) => sites[a].xyz);
-    const v1 = [p[1][0] - p[0][0], p[1][1] - p[0][1], p[1][2] - p[0][2]];
-    const v2 = [p[2][0] - p[0][0], p[2][1] - p[0][1], p[2][2] - p[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 p.every((q) => {
-        const dev = Math.abs((q[0] - p[0][0]) * nx + (q[1] - p[0][1]) * ny + (q[2] - p[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((b) => ({ ...b, 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({
-            i: bond.site_idx_1,
-            j: bond.site_idx_2,
-            ref: bond,
-        });
-    }
-    const frags = split_fragments(sites.length, edges.map((e) => [e.i, e.j]));
-    let ring_id = 0;
-    for (const frag of frags) {
-        const atom_set = new Set(frag);
-        const frag_edges = edges.filter((e) => atom_set.has(e.i));
-        const symbols = frag.map((a) => primary_element(sites[a]));
-        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((e) => ({
-            i: idx_of[e.i],
-            j: idx_of[e.j],
-            ref: e.ref,
-        }));
-        const valence_lists = symbols.map((s) => ATOMIC_VALENCE[s]);
-        const combo_count = valence_lists.reduce((p, l) => p * l.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 k = 0; k < frag.length; k++) {
-                sum_fc += formal_charge(symbols[k], atom_valence(k, local_edges, candidate));
-            }
-            if (sum_fc === want_charge) {
-                solved = candidate;
-                break;
-            }
-        }
-        if (!solved)
-            continue;
-        local_edges.forEach((e, ei) => {
-            const ord = order_to_bond_order(solved[ei]);
-            result.set(e.ref, { ...e.ref, bond_order: ord, perceived: true });
-        });
-        // Hückel aromatic post-pass, retaining Kekulé orders for display toggles.
-        const rings = find_rings(frag.length, local_edges.map((e) => [e.i, e.j]));
-        for (const ring of rings) {
-            const global_ring = ring.map((k) => frag[k]);
-            if (!global_ring.every((g) => SP2_OK.has(primary_element(sites[g]))))
-                continue;
-            if (!ring_is_planar(global_ring, sites))
-                continue;
-            const ring_set = new Set(ring);
-            const has_ring_multiple = new Set();
-            local_edges.forEach((e, ei) => {
-                if (ring_set.has(e.i) && ring_set.has(e.j) && solved[ei] > 1) {
-                    has_ring_multiple.add(e.i);
-                    has_ring_multiple.add(e.j);
-                }
-            });
-            const has_any_multiple_bond = (atom_idx) => local_edges.some((edge, edge_idx) => {
-                if (edge.i !== atom_idx && edge.j !== atom_idx)
-                    return false;
-                return solved[edge_idx] > 1;
-            });
-            const has_non_ring_neighbor = (atom_idx) => local_edges.some((edge) => {
-                if (edge.i !== atom_idx && edge.j !== atom_idx)
-                    return false;
-                const neighbor_idx = edge.i === atom_idx ? edge.j : edge.i;
-                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((e) => {
-                    if (ring_set.has(e.i) && ring_set.has(e.j)) {
-                        const prev = result.get(e.ref);
-                        if (prev === undefined)
-                            throw new Error(`Missing perceived bond`);
-                        result.set(e.ref, {
-                            ...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

@@ -1,42 +0,0 @@
-import type { Vec3 } from '../math';
-import type { AnyStructure, BondOrder, BondPair, 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 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[];