matterviz 0.3.6 → 0.4.0

package/dist/src/lib/structure/bonding.ts

@@ -1,944 +0,0 @@
-// Bonding algorithms for structure visualization
-
-import { element_data } from '$lib/element'
-import type { Vec3 } from '$lib/math'
-import * as math from '$lib/math'
-import type { AnyStructure, BondOrder, BondPair, Site, StructureBond } from '$lib/structure'
-
-type SpatialGrid = Map<string, number[]>
-
-const element_lookup = new Map(element_data.map((el) => [el.symbol, el]))
-const covalent_radii: Map<string, number> = new Map(
-  element_data.flatMap((el) =>
-    el.covalent_radius === null ? [] : [[el.symbol, el.covalent_radius]],
-  ),
-)
-
-const is_zero_cell_shift = (cell_shift: Vec3 | undefined): boolean =>
-  cell_shift === undefined || cell_shift.every((val) => val === 0)
-
-const format_cell_shift = (cell_shift: Vec3 | undefined): string => {
-  if (cell_shift === undefined || is_zero_cell_shift(cell_shift)) return ``
-  return `@${cell_shift.join(`,`)}`
-}
-
-const negate_cell_shift = (cell_shift: Vec3): Vec3 => [
-  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: Vec3): Vec3 => {
-  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: number,
-  site_idx_2: number,
-  cell_shift?: Vec3,
-): Pick<StructureBond, `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: number,
-  site_idx_2: number,
-  order: BondOrder,
-  cell_shift?: Vec3,
-): StructureBond => {
-  const bond = normalize_bond_endpoints(site_idx_1, site_idx_2, cell_shift)
-  return { ...bond, order }
-}
-
-export const get_bond_key = (idx_1: number, idx_2: number, cell_shift?: Vec3): string => {
-  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,
-  )}`
-}
-
-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 const BOND_ORDER_OPTIONS: { order: BondOrder; label: string }[] = [
-  { 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[] | undefined, site_idx: number): Vec3 => {
-  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[] | undefined, site_idx: number): number => {
-  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: BondKeyTarget,
-  sites: Site[] | undefined,
-): BondKeyTarget => {
-  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: Vec3 = [
-    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: BondKeyTarget): string =>
-  get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift)
-
-const matches_bond_key = (bond: BondKeyTarget, key: string): boolean =>
-  bond_key_for(bond) === key
-
-const replace_bond = (bonds: StructureBond[], next_bond: StructureBond): StructureBond[] => {
-  const key = bond_key_for(next_bond)
-  return [...bonds.filter((bond) => !matches_bond_key(bond, key)), next_bond]
-}
-
-const remove_bond_key = (bonds: StructureBond[], key: string): StructureBond[] =>
-  bonds.filter((bond) => !matches_bond_key(bond, key))
-
-const includes_bond_key = (bonds: BondKeyTarget[], key: string): boolean =>
-  bonds.some((bond) => matches_bond_key(bond, key))
-
-const get_bond_order = (bond: BondOrderTarget | undefined): BondOrder =>
-  bond?.bond_order ?? bond?.order ?? 1
-
-const find_bond_by_key = <BondType extends BondKeyTarget>(
-  bonds: BondType[],
-  key: string,
-): BondType | undefined => bonds.find((bond) => matches_bond_key(bond, key))
-
-const make_bond_record = (bond: BondKeyTarget, order: BondOrder): StructureBond =>
-  normalize_structure_bond(bond.site_idx_1, bond.site_idx_2, order, bond.cell_shift)
-
-export function has_visible_bond(
-  edit_state: BondEditState,
-  bond: BondKeyTarget,
-  calculated_bonds: BondOrderTarget[],
-): boolean {
-  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: BondEditState,
-  bond: BondKeyTarget,
-  calculated_bonds: BondOrderTarget[],
-  order: BondOrder,
-): BondEditResult {
-  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: BondEditState,
-  bond: BondKeyTarget,
-  calculated_bonds: BondOrderTarget[],
-): BondEditResult {
-  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: BondEditState,
-  bond: BondKeyTarget,
-  calculated_bonds: BondOrderTarget[],
-  order: BondOrder,
-): BondEditResult {
-  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: StructureBond[],
-  added: StructureBond[],
-  removed: StructureBond[],
-  overrides: StructureBond[],
-): StructureBond[] => {
-  const key_for = (bond: StructureBond): string =>
-    get_bond_key(bond.site_idx_1, bond.site_idx_2, bond.cell_shift)
-  const normalize_record = (bond: StructureBond): StructureBond =>
-    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: unknown): value is Record<string, unknown> =>
-  typeof value === `object` && value !== null
-
-export function normalize_bond_order(order: unknown): BondOrder | null {
-  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: unknown): Vec3 | undefined | null {
-  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: AnyStructure, cell_shift: Vec3 | undefined): Vec3 {
-  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: AnyStructure,
-  bond: StructureBond,
-): BondPair {
-  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: AnyStructure): StructureBond[] {
-  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<string, StructureBond>()
-  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: AnyStructure,
-  bonds: BondPair[],
-): BondPair[] {
-  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: Float32Array,
-  offset: number,
-  radius_scale: number,
-): Float32Array {
-  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: Vec3 = [
-    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: BondPair,
-  bond_thickness: number,
-): Float32Array[] {
-  const order = bond.bond_order ?? 1
-  const gap = bond_thickness * 1.8
-  const offsets_and_scales: [number, number][] =
-    order === 2
-      ? [
-          [-gap / 2, 0.65],
-          [gap / 2, 0.65],
-        ]
-      : order === 3
-        ? [
-            [-gap, 0.55],
-            [0, 0.55],
-            [gap, 0.55],
-          ]
-        : order === 1.5 || order === `aromatic`
-          ? [
-              [-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) =>
-  (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: Site, fallback: number): number {
-  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: Vec3, pos_2: Vec3): Float32Array {
-  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: Site[], cell_size: number): SpatialGrid {
-  const grid: SpatialGrid = 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: Vec3, grid: SpatialGrid, cell_size: number): number[] {
-  const [cx, cy, cz] = [
-    Math.floor(pos[0] / cell_size),
-    Math.floor(pos[1] / cell_size),
-    Math.floor(pos[2] / cell_size),
-  ]
-  const neighbors: number[] = []
-  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: Site[], cutoff: number) {
-  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: Vec3,
-  sites: Site[],
-  spatial: ReturnType<typeof setup_spatial_grid>,
-): number[] =>
-  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 } as const
-export type BondingStrategy = keyof typeof BONDING_STRATEGIES
-export type BondingAlgo = (typeof BONDING_STRATEGIES)[BondingStrategy]
-
-// 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: AnyStructure,
-  {
-    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
-  } = {},
-): BondPair[] {
-  const { sites } = structure
-  if (sites.length < 2) return []
-
-  const bonds: BondPair[] = []
-  const min_dist_sq = min_bond_dist ** 2
-  const closest = new Map<number, number>()
-
-  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)
-
-  // Two-pass approach to ensure symmetry between original and image atoms:
-  // 1. Collect all potential bonds and determine closest neighbor distance for each unique atom (orig_idx)
-  // 2. Filter bonds based on penalties using the fully populated closest distances
-
-  interface PotentialBond {
-    site_idx_1: number
-    site_idx_2: number
-    dist: number
-    expected_dist: number
-    base_strength: number
-    orig_idx_a: number
-    orig_idx_b: number
-  }
-
-  const potential_bonds: PotentialBond[] = []
-
-  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: AnyStructure,
-  {
-    min_solid_angle = 0.01,
-    min_face_area = 0.05,
-    max_distance = 5.0,
-    min_bond_dist = 0.4,
-    strength_threshold = 0.05,
-  } = {},
-): BondPair[] {
-  const { sites } = structure
-  if (sites.length < 2) return []
-
-  const bonds: BondPair[] = []
-  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)
-}