matterviz 0.3.5 → 0.3.7

package/dist/structure/StructureScene.svelte.d.ts

@@ -3,7 +3,7 @@ import type { ElementSymbol } from '../element';
 import type { IsosurfaceSettings, VolumetricData } from '../isosurface/types';
 import type { Vec3 } from '../math';
 import type { CameraProjection, ShowBonds, VectorColorMode, VectorLayerConfig } from '../settings';
-import type { AnyStructure, MeasureMode, Site, StructureBond } from './';
+import type { AnyStructure, BondEditMode, BondOrder, MeasureMode, Site, StructureBond } from './';
 import { Lattice } from './';
 import type { AtomColorConfig } from './atom-properties';
 import type { MoyoDataset } from '@spglib/moyo-wasm';
@@ -78,6 +78,8 @@ type $$ComponentProps = {
     removed_bonds?: StructureBond[];
     bond_order_overrides?: StructureBond[];
     bond_edits_enabled?: boolean;
+    bond_edit_mode?: BondEditMode;
+    bond_edit_order?: BondOrder;
     selection_highlight_color?: string;
     active_sites?: number[];
     active_highlight_color?: string;
@@ -95,6 +97,7 @@ type $$ComponentProps = {
     sym_data?: MoyoDataset | null;
     on_sites_moved?: (scene_indices: number[], delta: Vec3) => void;
     on_operation_start?: () => void;
+    on_bond_edit_start?: () => void;
     on_add_atom?: (xyz: Vec3, element: ElementSymbol) => void;
     add_atom_mode?: boolean;
     add_element?: ElementSymbol;
@@ -103,6 +106,6 @@ type $$ComponentProps = {
     volumetric_data?: VolumetricData;
     isosurface_settings?: IsosurfaceSettings;
 };
-declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "vector_configs" | "camera" | "scene" | "orbit_controls" | "site_radius_overrides" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "selected_sites" | "measured_sites" | "added_bonds" | "removed_bonds" | "bond_order_overrides" | "active_sites" | "rotation_target_ref" | "initial_computed_zoom" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "add_atom_mode" | "add_element" | "dragging_atoms">;
+declare const StructureScene: import("svelte").Component<$$ComponentProps, {}, "cursor" | "site_label_offset" | "vector_configs" | "camera" | "scene" | "orbit_controls" | "site_radius_overrides" | "hovered_idx" | "hovered_site" | "camera_is_moving" | "selected_sites" | "measured_sites" | "added_bonds" | "removed_bonds" | "bond_order_overrides" | "bond_edit_mode" | "active_sites" | "rotation_target_ref" | "initial_computed_zoom" | "hidden_elements" | "hidden_prop_vals" | "element_radius_overrides" | "add_atom_mode" | "add_element" | "dragging_atoms">;
 type StructureScene = ReturnType<typeof StructureScene>;
 export default StructureScene;

package/dist/structure/atom-properties.js

@@ -126,11 +126,11 @@ export function get_coordination_colors(structure, strategy = `electroneg_ratio`
     return build_prop_colors(coord_nums, colors, unique_values);
 }
 export function get_wyckoff_colors(structure, sym_data, scale = DEFAULT_COLOR_SCALE) {
-    const n = structure.sites.length;
+    const n_sites = structure.sites.length;
     if (!sym_data?.wyckoffs || sym_data.wyckoffs.length === 0) {
         return {
-            colors: Array(n).fill(GRAY),
-            values: Array(n).fill(`unknown`),
+            colors: Array(n_sites).fill(GRAY),
+            values: Array(n_sites).fill(`unknown`),
             unique_values: [`unknown`],
         };
     }
@@ -155,7 +155,7 @@ export function get_wyckoff_colors(structure, sym_data, scale = DEFAULT_COLOR_SC
         }
         if (sym_idx >= sym_data.wyckoffs.length) {
             console.error(`[get_wyckoff_colors] Site ${idx} (maps to ${sym_idx}) has no Wyckoff data. ` +
-                `Structure has ${n} sites but symmetry data only has ${sym_data.wyckoffs.length}.`);
+                `Structure has ${n_sites} sites but symmetry data only has ${sym_data.wyckoffs.length}.`);
             return `unknown`;
         }
         const wyckoff = sym_data.wyckoffs[sym_idx];

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

@@ -1,6 +1,6 @@
 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 ?? ``);
+    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.
@@ -51,19 +51,17 @@ function formal_charge(symbol, bond_valence) {
         return 0;
     return VALENCE_ELECTRONS[symbol] - 8 + bond_valence;
 }
-function is_main_group(symbol) {
-    return symbol in ATOMIC_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 [a, b] of edges) {
-        if (adjacency[a] === undefined || adjacency[b] === undefined) {
-            throw new Error(`Invalid edge ${a}-${b} for ${n_atoms} 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[a].push(b);
-        adjacency[b].push(a);
+        adjacency[atom_idx_1].push(atom_idx_2);
+        adjacency[atom_idx_2].push(atom_idx_1);
     }
     const seen = new Set();
     const fragments = [];
@@ -95,18 +93,21 @@ 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] });
+            combos.push({
+                sum: acc.reduce((sum, valence) => sum + valence, 0),
+                pick: [...acc],
+            });
             return;
         }
-        for (const v of valence_lists[pos])
-            rec(pos + 1, [...acc, v]);
+        for (const valence of valence_lists[pos])
+            rec(pos + 1, [...acc, valence]);
     };
     rec(0, []);
-    combos.sort((a, b) => a.sum - b.sum);
-    for (const c of combos)
-        yield c.pick;
+    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.i === atom || edge.j === atom ? orders[edge_idx] : 0), 0);
+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) {
@@ -117,13 +118,13 @@ function assign_bond_orders(edges, target_valence) {
         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;
+        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) {
@@ -138,46 +139,52 @@ function assign_bond_orders(edges, target_valence) {
     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`);
+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[a].add(b);
-        adjacency[b].add(a);
+        adjacency[atom_idx_1].add(atom_idx_2);
+        adjacency[atom_idx_2].add(atom_idx_1);
     }
-    const parent = Array.from({ length: n }, () => -1);
+    const parent = Array.from({ length: n_atoms }, () => -1);
     const seen = new Set();
     const rings = [];
-    for (let s = 0; s < n; s++) {
-        if (seen.has(s))
+    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 = [s];
+        const queue = [start_idx];
         let queue_idx = 0;
-        seen.add(s);
-        parent[s] = -1;
+        seen.add(start_idx);
+        parent[start_idx] = -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);
+            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[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()];
+                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;
@@ -188,31 +195,39 @@ function find_rings(n, edges) {
         }
     }
     const uniq = new Map();
-    for (const r of rings) {
-        const key = [...r].sort((x, y) => x - y).join(`,`);
+    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, r);
+            uniq.set(key, ring);
     }
     return [...uniq.values()];
 }
-function order_to_bond_order(o) {
-    return o >= 3 ? 3 : o === 2 ? 2 : 1;
-}
+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 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 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 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 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;
     });
 }
@@ -225,7 +240,7 @@ const SP2_OK = new Set([`C`, `N`, `O`, `S`]);
 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 }));
+        return bonds.map((bond) => ({ ...bond, bond_order: 1, perceived: false }));
     }
     const edges = [];
     const result = new Map();
@@ -237,30 +252,30 @@ export function perceive_bond_orders(sites, bonds, opts = {}) {
             bond.site_idx_2 >= sites.length)
             continue;
         edges.push({
-            i: bond.site_idx_1,
-            j: bond.site_idx_2,
-            ref: bond,
+            from: bond.site_idx_1,
+            to: bond.site_idx_2,
+            bond,
         });
     }
-    const frags = split_fragments(sites.length, edges.map((e) => [e.i, e.j]));
+    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((e) => atom_set.has(e.i));
-        const symbols = frag.map((a) => primary_element(sites[a]));
+        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((e) => ({
-            i: idx_of[e.i],
-            j: idx_of[e.j],
-            ref: e.ref,
+        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((s) => ATOMIC_VALENCE[s]);
-        const combo_count = valence_lists.reduce((p, l) => p * l.length, 1);
+        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;
@@ -270,8 +285,8 @@ export function perceive_bond_orders(sites, bonds, opts = {}) {
             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));
+            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;
@@ -280,35 +295,37 @@ export function perceive_bond_orders(sites, bonds, opts = {}) {
         }
         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 });
+        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((e) => [e.i, e.j]));
+        const rings = find_rings(frag.length, local_edges.map((edge) => [edge.from, edge.to]));
         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]))))
+            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((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);
+            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.i !== atom_idx && edge.j !== atom_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.i !== atom_idx && edge.j !== atom_idx)
+                if (edge.from !== atom_idx && edge.to !== atom_idx)
                     return false;
-                const neighbor_idx = edge.i === atom_idx ? edge.j : edge.i;
+                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) => {
@@ -324,12 +341,12 @@ export function perceive_bond_orders(sites, bonds, opts = {}) {
             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);
+                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(e.ref, {
+                        result.set(edge.bond, {
                             ...prev,
                             bond_order: `aromatic`,
                             aromatic_ring: this_ring,

package/dist/structure/bonding.d.ts

@@ -1,7 +1,32 @@
 import type { Vec3 } from '../math';
-import type { AnyStructure, BondOrder, BondPair, StructureBond } from './';
+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;
@@ -40,3 +65,4 @@ export declare function solid_angle(structure: AnyStructure, { min_solid_angle,
     min_bond_dist?: number | undefined;
     strength_threshold?: number | undefined;
 }): BondPair[];
+export {};