matterviz 0.3.6 → 0.4.0

package/dist/src/lib/structure/bond-order-perception.ts

@@ -1,447 +0,0 @@
-// Bond-order perception adapted from jensengroup/xyz2mol (MIT,
-// Kim & Kim, Bull. Korean Chem. Soc. 2015, 36, 1769). Clean-room TS port.
-import type { BondOrder, BondPair, Site, StructureBond } from '$lib/structure'
-import { get_bond_key } from './bonding'
-
-export type PerceptionOptions = { total_charge?: number; max_atoms?: number }
-
-export type PerceivedBond = BondPair & {
-  bond_order: BondOrder
-  perceived: boolean
-  aromatic_ring?: number
-  kekule_order?: BondOrder
-}
-
-const primary_element = (site: Site): string => {
-  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: Record<string, number[]> = {
-  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: Record<string, number> = {
-  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: string, bond_valence: number): number {
-  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: string): boolean => 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: number, edges: [number, number][]): number[][] {
-  const adjacency = Array.from({ length: n_atoms }, () => [] as number[])
-  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<number>()
-  const fragments: number[][] = []
-  for (let start = 0; start < n_atoms; start++) {
-    if (seen.has(start)) continue
-    const stack = [start]
-    const frag: number[] = []
-    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
-}
-
-type Edge = { from: number; to: number; bond: BondPair }
-
-// Enumerate one target valence per atom, all combinations, lowest total
-// valence-sum first (xyz2mol prefers the least-saturated solution).
-function* valence_combinations(valence_lists: number[][]): Generator<number[]> {
-  const combos: { sum: number; pick: number[] }[] = []
-  const rec = (pos: number, acc: number[]) => {
-    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: number, edges: Edge[], orders: number[]): number =>
-  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: Edge[], target_valence: number[]): number[] | null {
-  const orders = Array.from({ length: edges.length }, () => 1)
-  const used = (atom: number) => 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: number, edges: [number, number][]): number[][] {
-  const adjacency = Array.from({ length: n_atoms }, () => new Set<number>())
-  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<number>()
-  const rings: number[][] = []
-  const path_to_ancestor = (start_idx: number, ancestor_idx: number): number[] => {
-    const path: number[] = []
-    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<number>()
-          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<string, number[]>()
-  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: number): BondOrder =>
-  order >= 3 ? 3 : order === 2 ? 2 : 1
-
-// Conservative planarity check: degenerate first-3-atom planes are non-planar.
-function ring_is_planar(ring: number[], sites: Site[]): boolean {
-  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: Site[],
-  bonds: BondPair[],
-  opts: PerceptionOptions = {},
-): PerceivedBond[] {
-  const max_atoms = opts.max_atoms ?? 5000
-  if (sites.length > max_atoms) {
-    return bonds.map((bond) => ({ ...bond, bond_order: 1, perceived: false }))
-  }
-  const edges: Edge[] = []
-  const result = new Map<BondPair, PerceivedBond>()
-  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] as [number, number]),
-  )
-  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: Edge[] = 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: number[] | null = 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] as [number, number]),
-    )
-    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: Edge): boolean =>
-        ring_set.has(edge.from) && ring_set.has(edge.to)
-      const has_ring_multiple = new Set<number>()
-      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: number): boolean =>
-        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: number): boolean =>
-        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: PerceivedBond[],
-  explicit_bonds: StructureBond[],
-  aromatic_display: `aromatic` | `kekule`,
-): PerceivedBond[] {
-  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
-  })
-}