matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,291 @@
+import type { CompositionType } from '$lib/composition'
+import { ATOMIC_WEIGHTS } from '$lib/composition/parse'
+import type { ElementSymbol } from '$lib/element'
+import { element_data } from '$lib/element'
+import type { Vec3 } from '$lib/math'
+import * as math from '$lib/math'
+import type { ComponentProps } from 'svelte'
+import type LatticeComponent from './Lattice.svelte'
+import type { Pbc } from './pbc'
+import type StructureSceneComponent from './StructureScene.svelte'
+
+export { default as Arrow } from './Arrow.svelte'
+export * from './atom-properties'
+export { default as AtomLegend } from './AtomLegend.svelte'
+export { default as Bond } from './Bond.svelte'
+export * as bonding_strategies from './bonding'
+export { default as CanvasTooltip } from './CanvasTooltip.svelte'
+export { default as Cylinder } from './Cylinder.svelte'
+export { default as Lattice } from './Lattice.svelte'
+export * from './pbc'
+export { default as Structure } from './Structure.svelte'
+export { default as StructureControls } from './StructureControls.svelte'
+export { default as StructureExportPane } from './StructureExportPane.svelte'
+export { default as StructureInfoPane } from './StructureInfoPane.svelte'
+export { default as StructureScene } from './StructureScene.svelte'
+export * from './supercell'
+
+export type MeasureMode = `distance` | `angle` | `edit-bonds` | `edit-atoms`
+export type BondEditMode = `add` | `delete`
+
+export type Species = {
+  element: ElementSymbol
+  occu: number
+  oxidation_state: number
+}
+export type Site = {
+  species: Species[]
+  abc: Vec3
+  xyz: Vec3
+  label: string
+  properties: Record<string, unknown>
+}
+
+export const LATTICE_PARAM_KEYS = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`] as const
+export type LatticeParams = { [key in (typeof LATTICE_PARAM_KEYS)[number]]: number }
+
+export type LatticeType = {
+  matrix: math.Matrix3x3
+  pbc: Pbc
+  volume: number
+} & LatticeParams
+
+export type Molecule = {
+  sites: Site[]
+  charge?: number
+  id?: string
+  properties?: StructureProperties
+}
+export type Crystal = Molecule & { lattice: LatticeType }
+export type AnyStructure = Crystal | Molecule
+
+export type BondOrder = 1 | 1.5 | 2 | 3 | `aromatic`
+
+export type StructureBond = {
+  site_idx_1: number
+  site_idx_2: number
+  order: BondOrder
+  // Integer lattice-vector offset applied to site_idx_2 relative to site_idx_1.
+  cell_shift?: Vec3
+}
+
+export type StructureProperties = Record<string, unknown> & { bonds?: StructureBond[] }
+
+// Bond pair with position vectors, site indices, bond length, strength score,
+// optional explicit bond order, and transformation matrix.
+export type BondPair = {
+  pos_1: Vec3
+  pos_2: Vec3
+  site_idx_1: number
+  site_idx_2: number
+  bond_length: number
+  strength: number
+  bond_order?: BondOrder
+  cell_shift?: Vec3
+  transform_matrix: Float32Array
+}
+
+export type { PerceivedBond, PerceptionOptions } from '$lib/structure/bond-order-perception'
+export {
+  compose_perceived_bonds,
+  perceive_bond_orders,
+} from '$lib/structure/bond-order-perception'
+
+export function get_element_counts(structure: AnyStructure) {
+  const elements: CompositionType = {}
+  for (const site of structure.sites) {
+    for (const species of site.species) {
+      const { element: elem, occu } = species
+      elements[elem] = (elements[elem] ?? 0) + occu
+    }
+  }
+  return elements
+}
+
+export function format_chemical_formula(
+  structure: AnyStructure,
+  sort_fn: (symbols: ElementSymbol[]) => ElementSymbol[],
+): string {
+  // concatenate elements in a structure followed by their amount
+  const elements = get_element_counts(structure)
+  const formula = []
+  for (const element of sort_fn(Object.keys(elements) as ElementSymbol[])) {
+    const amount = elements[element] ?? 0
+    if (amount === 1) formula.push(element)
+    else formula.push(`${element}<sub>${amount}</sub>`)
+  }
+  return formula.join(` `)
+}
+
+export function format_formula_by_electronegativity(structure: AnyStructure): string {
+  // concatenate elements in a structure followed by their amount sorted by electronegativity
+  return format_chemical_formula(structure, (symbols) =>
+    symbols.sort((el1, el2) => {
+      const elec_neg1 = element_data.find((el) => el.symbol === el1)?.electronegativity ?? 0
+      const elec_neg2 = element_data.find((el) => el.symbol === el2)?.electronegativity ?? 0
+      // Sort by electronegativity (ascending), then alphabetically for ties
+      if (elec_neg1 !== elec_neg2) return elec_neg1 - elec_neg2
+      return el1.localeCompare(el2)
+    }),
+  )
+}
+
+// Atomic radii in Angstroms (used for relative sizing, not absolute rendering scale)
+export const atomic_radii: CompositionType = Object.fromEntries(
+  element_data.map((el) => [el.symbol, el.atomic_radius ?? 1]),
+)
+
+// unified atomic mass units (u) per cubic angstrom (Å^3)
+// to grams per cubic centimeter (g/cm^3)
+const AMU_PER_A3_TO_G_PER_CM3 = 1.66053907
+
+export function get_density(structure: Crystal): number {
+  // calculate the density of a Crystal in g/cm³
+  const elements = get_element_counts(structure)
+  let mass = 0
+  for (const [element, amount] of Object.entries(elements)) {
+    const weight = ATOMIC_WEIGHTS.get(element as ElementSymbol)
+    if (weight !== undefined) mass += amount * weight
+  }
+  return (AMU_PER_A3_TO_G_PER_CM3 * mass) / structure.lattice.volume
+}
+
+export function get_center_of_mass(structure: AnyStructure): Vec3 {
+  let center: Vec3 = [0, 0, 0]
+  let total_weight = 0
+
+  for (const site of structure.sites) {
+    // Handle disordered sites by summing contributions from all species
+    for (const species of site.species) {
+      const atomic_weight = ATOMIC_WEIGHTS.get(species.element) ?? 1
+      const weight = atomic_weight * species.occu
+
+      const scaled_pos = math.scale(site.xyz, weight)
+      center = math.add(center, scaled_pos)
+
+      total_weight += weight
+    }
+  }
+
+  return math.scale(center, 1 / total_weight)
+}
+
+// Recognized prefixes for per-site vector data (force, magnetic moment, spin).
+// Both singular and plural forms are accepted. Keys matching exactly or starting
+// with one of these followed by `_` (e.g. `force_DFT`) are treated as vectors.
+export const VECTOR_KEY_PREFIXES = [
+  `force`,
+  `forces`,
+  `magmom`,
+  `magmoms`,
+  `spin`,
+  `spins`,
+] as const
+
+export function is_vector_key(key: string): boolean {
+  return VECTOR_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}_`))
+}
+
+// Default color palette for distinguishing multiple vector layers
+export const VECTOR_PALETTE = [
+  `#e74c3c`,
+  `#3498db`,
+  `#2ecc71`,
+  `#f39c12`,
+  `#9b59b6`,
+  `#1abc9c`,
+] as const
+
+// Single key → null color (semantic coloring); multiple keys → palette colors.
+export const default_vector_configs = (keys: string[]) =>
+  Object.fromEntries(
+    keys.map((key, idx) => [
+      key,
+      {
+        visible: true,
+        color: keys.length > 1 ? VECTOR_PALETTE[idx % VECTOR_PALETTE.length] : null,
+        scale: null,
+      },
+    ]),
+  )
+
+function try_parse_vec3(val: unknown): Vec3 | null {
+  if (
+    Array.isArray(val) &&
+    val.length === 3 &&
+    val.every((elem) => typeof elem === `number` && isFinite(elem))
+  )
+    return val as Vec3
+  if (typeof val === `number` && isFinite(val)) return [0, 0, val]
+  return null
+}
+
+// Priority index for ordering: bare names first in VECTOR_KEY_PREFIXES order,
+// then prefixed keys in the same prefix order, alphabetically within each prefix group.
+function vector_key_sort_order(key: string): [number, number, string] {
+  for (const [prefix_idx, prefix] of VECTOR_KEY_PREFIXES.entries()) {
+    if (key === prefix) return [prefix_idx, 0, ``]
+    if (key.startsWith(`${prefix}_`)) return [prefix_idx, 1, key]
+  }
+  return [VECTOR_KEY_PREFIXES.length, 0, key]
+}
+
+function compare_vector_keys(left: string, right: string): number {
+  const ord_l = vector_key_sort_order(left)
+  const ord_r = vector_key_sort_order(right)
+  return ord_l[0] - ord_r[0] || ord_l[1] - ord_r[1] || ord_l[2].localeCompare(ord_r[2])
+}
+
+// Extract ALL vector properties from a site (not just the first match).
+// Returns entries for every key that is_vector_key() and has a valid 3D vector value.
+// Ordered by VECTOR_KEY_PREFIXES priority, then alphabetically for prefixed keys.
+export function get_all_site_vectors(site: Site): { vec: Vec3; key: string }[] {
+  const props = site.properties
+  if (!props) return []
+  const results: { vec: Vec3; key: string }[] = []
+  for (const key of Object.keys(props)) {
+    if (!is_vector_key(key)) continue
+    const vec = try_parse_vec3(props[key])
+    if (vec) results.push({ vec, key })
+  }
+  return results.sort((left, right) => compare_vector_keys(left.key, right.key))
+}
+
+// Collect the union of all vector property keys across all sites in a structure,
+// preserving VECTOR_KEY_PREFIXES priority order.
+export function get_structure_vector_keys(structure: AnyStructure): string[] {
+  const seen = new Set<string>()
+  for (const site of structure.sites) {
+    for (const { key } of get_all_site_vectors(site)) seen.add(key)
+  }
+  return [...seen].sort(compare_vector_keys)
+}
+
+export interface StructureHandlerData {
+  structure?: AnyStructure
+  filename?: string
+  file_size?: number
+  total_atoms?: number
+  error_msg?: string
+  fullscreen?: boolean
+  camera_position?: Vec3
+  camera_target?: Vec3
+  camera_has_moved?: boolean
+  color_scheme?: string
+  performance_mode?: `quality` | `speed`
+  scene_props?: ComponentProps<typeof StructureSceneComponent>
+  lattice_props?: ComponentProps<typeof LatticeComponent>
+}
+
+export interface BondInstance {
+  matrix: Float32Array
+  color_start: string
+  color_end: string
+}
+
+export interface BondGroupWithGradients {
+  thickness: number
+  instances: BondInstance[]
+  ambient_light?: number
+  directional_light?: number
+}

package/dist/src/lib/structure/label-placement.ts

@@ -0,0 +1,130 @@
+import type { Vec3 } from '$lib/math'
+import * as math from '$lib/math'
+import type { Camera, Object3D } from 'three'
+import { Vector3 } from 'three'
+
+export const LABEL_OFFSET_EPS = 1e-9
+type LabelOffsetSource = Vec3 | (() => Vec3)
+
+const LABEL_OFFSET_DIRECTIONS: Vec3[] = [
+  [0, -1, 0],
+  [1, 0, 0],
+  [-1, 0, 0],
+  [1, 1, 0],
+  [-1, 1, 0],
+  [1, -1, 0],
+  [-1, -1, 0],
+  [0, 0, 1],
+  [0, 0, -1],
+]
+
+const label_direction_score = (
+  direction: Vec3,
+  bond_directions: Vec3[],
+  preferred_direction: Vec3,
+): number => {
+  let max_bond_alignment = 0
+  for (const bond_direction of bond_directions) {
+    max_bond_alignment = Math.max(
+      max_bond_alignment,
+      Math.max(0, math.dot(direction, bond_direction)),
+    )
+  }
+  const preferred_bonus = Math.max(0, math.dot(direction, preferred_direction)) * 0.05
+  const screen_plane_bonus = Math.abs(direction[2]) < LABEL_OFFSET_EPS ? 0.02 : 0
+  return -max_bond_alignment + preferred_bonus + screen_plane_bonus
+}
+
+export const choose_site_label_offset = (bond_directions: Vec3[], base_offset: Vec3): Vec3 => {
+  const offset_length = Math.hypot(...base_offset)
+  if (offset_length < LABEL_OFFSET_EPS || bond_directions.length === 0) {
+    return base_offset
+  }
+
+  const preferred_direction = math.normalize_vec3(base_offset, [0, 1, 0])
+  const repulsion_direction = math.normalize_vec3(
+    bond_directions.reduce<Vec3>(
+      (offset_sum, bond_direction) => math.subtract(offset_sum, bond_direction),
+      [0, 0, 0],
+    ),
+    preferred_direction,
+  )
+  let best_direction = preferred_direction
+  let best_score = -Infinity
+
+  for (const candidate_direction of [
+    preferred_direction,
+    repulsion_direction,
+    ...LABEL_OFFSET_DIRECTIONS,
+  ]) {
+    const direction = math.normalize_vec3(candidate_direction, preferred_direction)
+    const score = label_direction_score(direction, bond_directions, preferred_direction)
+    if (score <= best_score + LABEL_OFFSET_EPS) continue
+    best_score = score
+    best_direction = direction
+  }
+  return math.scale(best_direction, offset_length)
+}
+
+const project_to_screen = (
+  position: Vec3,
+  label_camera: Camera,
+  size: { width: number; height: number },
+): [number, number] => {
+  const projected = new Vector3(...position).project(label_camera)
+  return [
+    (projected.x * size.width) / 2 + size.width / 2,
+    (-projected.y * size.height) / 2 + size.height / 2,
+  ]
+}
+
+export const label_screen_position = (
+  atom_position: Vec3,
+  label_offset: Vec3,
+  visual_radius: number,
+  label_screen_margin: number,
+  label_camera: Camera,
+  size: { width: number; height: number },
+): [number, number] => {
+  const atom_screen = project_to_screen(atom_position, label_camera, size)
+  const offset_screen = project_to_screen(
+    math.add(atom_position, label_offset),
+    label_camera,
+    size,
+  )
+  const offset_x = offset_screen[0] - atom_screen[0]
+  const offset_y = offset_screen[1] - atom_screen[1]
+  const offset_length = Math.hypot(offset_x, offset_y)
+  const direction_x = offset_length > LABEL_OFFSET_EPS ? offset_x / offset_length : 0
+  const direction_y =
+    offset_length > LABEL_OFFSET_EPS ? offset_y / offset_length : label_offset[1] >= 0 ? -1 : 1
+  const radius_direction = math.normalize_vec3(label_offset, [0, 1, 0])
+  const radius_edge = math.add(atom_position, math.scale(radius_direction, visual_radius))
+  const radius_screen = project_to_screen(radius_edge, label_camera, size)
+  const atom_screen_radius = Math.hypot(
+    radius_screen[0] - atom_screen[0],
+    radius_screen[1] - atom_screen[1],
+  )
+  const screen_gap = atom_screen_radius + label_screen_margin
+
+  return [atom_screen[0] + direction_x * screen_gap, atom_screen[1] + direction_y * screen_gap]
+}
+
+export const make_label_position_calculator =
+  (
+    _atom_position: Vec3,
+    label_offset: LabelOffsetSource,
+    visual_radius: number,
+    label_screen_margin: number,
+  ) =>
+  (object: Object3D, label_camera: Camera, size: { width: number; height: number }) => {
+    const world_position = object.getWorldPosition(new Vector3())
+    return label_screen_position(
+      [world_position.x, world_position.y, world_position.z],
+      typeof label_offset === `function` ? label_offset() : label_offset,
+      visual_radius,
+      label_screen_margin,
+      label_camera,
+      size,
+    )
+  }

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

@@ -0,0 +1,45 @@
+// functions for measuring distances and angles between structure sites
+
+import type { LatticeConverters, Matrix3x3, Vec3 } from '$lib/math'
+import { min_image_displacement, subtract } from '$lib/math'
+
+export type AngleMode = `degrees` | `radians`
+
+export const MAX_SELECTED_SITES = 8
+
+// Calculate minimum image displacement between two points under PBC
+// If lattice_matrix is null/undefined, returns Euclidean displacement
+export function displacement_pbc(
+  from: Vec3,
+  to: Vec3,
+  lattice_matrix: Matrix3x3 | null | undefined,
+  converters?: LatticeConverters,
+): Vec3 {
+  if (!lattice_matrix) return subtract(to, from)
+  return min_image_displacement(from, to, lattice_matrix, converters)
+}
+
+export function distance_pbc(a: Vec3, b: Vec3, lattice_matrix: Matrix3x3): number {
+  const [dx, dy, dz] = displacement_pbc(a, b, lattice_matrix)
+  return Math.hypot(dx, dy, dz)
+}
+
+export function angle_between_vectors(v1: Vec3, v2: Vec3, mode: AngleMode = `degrees`) {
+  const n1 = Math.hypot(v1[0], v1[1], v1[2])
+  const n2 = Math.hypot(v2[0], v2[1], v2[2])
+  if (n1 === 0 || n2 === 0) return 0
+
+  // Dot product of vectors
+  const dot = v1[0] * v2[0] + v1[1] * v2[1] + v1[2] * v2[2]
+
+  // Normalize dot product to get cosine
+  const cos_angle = dot / (n1 * n2)
+
+  // Clamp to [-1, 1] to avoid numerical errors with acos
+  const clamped = Math.max(-1, Math.min(1, cos_angle))
+
+  // Compute angle using arccos
+  const ang = Math.acos(clamped)
+
+  return mode === `degrees` ? (ang * 180) / Math.PI : ang
+}