matterviz 0.3.5 → 0.3.6

package/dist/src/lib/structure/partial-occupancy.ts

@@ -0,0 +1,183 @@
+import type { Vec3 } from '$lib/math'
+import type { Site } from '$lib/structure'
+
+export const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 1e-3
+const OCCUPANCY_EPS = 1e-6
+const MIN_PHI_LENGTH = 1e-4
+const MERGE_DISTANCE_TOLERANCE = 1e-8
+const CAP_ARC_START = Math.PI / 2
+
+export type RenderSite = {
+  site_idx: number
+  site: Site
+  is_image_atom: boolean
+  source_site_indices: number[]
+}
+
+export type SliceGeometry = {
+  element: string
+  occupancy: number
+  start_phi: number
+  end_phi: number
+  phi_length: number
+  render_start_cap: boolean
+  render_end_cap: boolean
+}
+
+export type CapArcConfig = {
+  start_cap_arc_start: number
+  end_cap_arc_start: number
+  arc_length: number
+}
+
+const is_image_atom = (site: Site): boolean =>
+  typeof site.properties?.orig_site_idx === `number`
+const make_render_site = (
+  sites: Site[],
+  site_idx: number,
+  source_site_indices: number[],
+  site_override?: Site,
+): RenderSite => ({
+  site_idx,
+  site: site_override ?? sites[site_idx],
+  is_image_atom: source_site_indices.some((source_site_idx) =>
+    is_image_atom(sites[source_site_idx]),
+  ),
+  source_site_indices,
+})
+const sq_dist = (xyz_1: Vec3, xyz_2: Vec3): number =>
+  (xyz_1[0] - xyz_2[0]) ** 2 + (xyz_1[1] - xyz_2[1]) ** 2 + (xyz_1[2] - xyz_2[2]) ** 2
+
+const is_split_partial_site = (site: Site, hidden_elements: ReadonlySet<string>): boolean => {
+  const visible_species = site.species.filter(({ element }) => !hidden_elements.has(element))
+  const total_visible_occupancy = visible_species.reduce(
+    (occupancy_sum, { occu }) => occupancy_sum + occu,
+    0,
+  )
+  return visible_species.length === 1 && total_visible_occupancy < 1 - OCCUPANCY_EPS
+}
+
+const group_split_partial_indices = (
+  sites: Site[],
+  hidden_elements: ReadonlySet<string>,
+): {
+  non_grouped_site_indices: number[]
+  grouped_site_indices: number[][]
+} => {
+  const grouped_centers: Vec3[] = []
+  const grouped_site_indices: number[][] = []
+  const non_grouped_site_indices: number[] = []
+  for (const [site_idx, site] of sites.entries()) {
+    if (!is_split_partial_site(site, hidden_elements)) {
+      non_grouped_site_indices.push(site_idx)
+      continue
+    }
+
+    const matched_group_idx = grouped_centers.findIndex(
+      (center_xyz) => sq_dist(center_xyz, site.xyz) <= MERGE_DISTANCE_TOLERANCE ** 2,
+    )
+    if (matched_group_idx === -1) {
+      grouped_centers.push(site.xyz)
+      grouped_site_indices.push([site_idx])
+      continue
+    }
+    grouped_site_indices[matched_group_idx].push(site_idx)
+  }
+  return { non_grouped_site_indices, grouped_site_indices }
+}
+
+const build_render_sites = (
+  sites: Site[],
+  non_grouped_site_indices: number[],
+  grouped_site_indices: number[][],
+): RenderSite[] => {
+  const render_sites: RenderSite[] = non_grouped_site_indices.map((site_idx) =>
+    make_render_site(sites, site_idx, [site_idx]),
+  )
+
+  for (const grouped_indices of grouped_site_indices) {
+    if (grouped_indices.length === 1) {
+      const site_idx = grouped_indices[0]
+      render_sites.push(make_render_site(sites, site_idx, [site_idx]))
+      continue
+    }
+
+    const representative_site_idx = grouped_indices[0]
+    const representative_site = sites[representative_site_idx]
+    const merged_species = grouped_indices.flatMap(
+      (grouped_site_idx) => sites[grouped_site_idx].species,
+    )
+    render_sites.push(
+      make_render_site(sites, representative_site_idx, [...grouped_indices], {
+        ...representative_site,
+        species: merged_species,
+      }),
+    )
+  }
+
+  return render_sites
+}
+
+export const PARTIAL_OCCUPANCY_CAP_ARC: CapArcConfig = {
+  start_cap_arc_start: CAP_ARC_START,
+  end_cap_arc_start: CAP_ARC_START,
+  arc_length: Math.PI,
+}
+
+export const merge_split_partial_sites = (
+  sites: Site[],
+  hidden_elements: ReadonlySet<string> = new Set(),
+): RenderSite[] => {
+  const grouped_indices = group_split_partial_indices(sites, hidden_elements)
+  return build_render_sites(
+    sites,
+    grouped_indices.non_grouped_site_indices,
+    grouped_indices.grouped_site_indices,
+  )
+}
+
+export const compute_slice_geometry = (
+  visible_species: Site[`species`],
+  slice_gap_rad: number = PARTIAL_OCCUPANCY_SLICE_GAP_RAD,
+): SliceGeometry[] => {
+  if (visible_species.length === 0) return []
+  const total_visible_occupancy = visible_species.reduce(
+    (occupancy_sum, { occu }) => occupancy_sum + occu,
+    0,
+  )
+  // Preserve total angular coverage at one full turn for invalid overfull inputs.
+  const occupancy_scale_factor =
+    total_visible_occupancy > 1 + OCCUPANCY_EPS ? 1 / total_visible_occupancy : 1
+  const normalized_species = visible_species.map(({ element, occu }) => ({
+    element,
+    occu: occu * occupancy_scale_factor,
+  }))
+  const normalized_total_occupancy = normalized_species.reduce(
+    (occupancy_sum, { occu }) => occupancy_sum + occu,
+    0,
+  )
+  const has_vacancy_gap = normalized_total_occupancy < 1 - OCCUPANCY_EPS
+  const last_visible_species_idx = normalized_species.length - 1
+  let start_angle = 0
+  return normalized_species.map(({ element, occu }, species_idx) => {
+    const start_phi_raw = 2 * Math.PI * start_angle
+    const end_phi_raw = 2 * Math.PI * (start_angle += occu)
+    // Keep neighboring wedges from sharing the exact same plane (z-fighting).
+    const phi_span_raw = Math.max(0, end_phi_raw - start_phi_raw)
+    const max_safe_gap = Math.max(0, phi_span_raw - MIN_PHI_LENGTH)
+    const desired_gap =
+      visible_species.length > 1 ? Math.min(slice_gap_rad, phi_span_raw * 0.25) : 0
+    const phi_gap = Math.min(desired_gap, max_safe_gap)
+    const start_phi = start_phi_raw + phi_gap / 2
+    const end_phi = end_phi_raw - phi_gap / 2
+    return {
+      element,
+      occupancy: occu,
+      start_phi,
+      end_phi,
+      phi_length: Math.max(MIN_PHI_LENGTH, end_phi - start_phi),
+      render_start_cap: has_vacancy_gap && species_idx === 0,
+      render_end_cap: has_vacancy_gap && species_idx === last_visible_species_idx,
+    }
+  })
+}

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

@@ -0,0 +1,164 @@
+// Periodic boundary conditions utilities
+import type { Vec3 } from '$lib/math'
+import * as math from '$lib/math'
+import type { ParsedStructure } from './parse'
+
+export type Pbc = readonly [boolean, boolean, boolean]
+
+// Wrap a single fractional coordinate to [0, 1), clamping near-1 values to 0
+// and rounding to 15 digits to suppress floating-point noise.
+export const wrap_frac_coord = (coord: number): number => {
+  const wrapped = coord - Math.floor(coord)
+  if (wrapped >= 1 - 1e-10) return 0
+  return Number(wrapped.toFixed(15))
+}
+
+// Wrap fractional coordinates to [0, 1) range for periodicity.
+export const wrap_to_unit_cell = (frac: Vec3): Vec3 => [
+  wrap_frac_coord(frac[0]),
+  wrap_frac_coord(frac[1]),
+  wrap_frac_coord(frac[2]),
+]
+
+export function find_image_atoms(
+  structure: ParsedStructure,
+  { tolerance }: { tolerance?: number } = {},
+): [number, Vec3, Vec3][] {
+  // Find image atoms for PBC. Returns [atom_idx, image_xyz, image_abc] tuples.
+  // Skips image generation for trajectory data with scattered atoms.
+  if (!structure.lattice || !structure.sites || structure.sites.length === 0) return []
+
+  // Skip trajectory data (>10% atoms outside cell)
+  const atoms_outside_cell = structure.sites.filter(({ abc }) =>
+    abc.some((coord) => coord < -0.1 || coord > 1.1),
+  )
+  // Skip image generation for trajectory data (>10% atoms outside cell)
+  if (atoms_outside_cell.length > structure.sites.length * 0.1) {
+    return []
+  }
+
+  // Check if this is a supercell to correctly identify external boundaries correctly
+  const image_sites: [number, Vec3, Vec3][] = []
+  const lattice_vecs = structure.lattice.matrix
+
+  // Scale zero-displacement threshold by lattice length scale to avoid hard-coded magic numbers
+  const lattice_norm = Math.max(
+    Math.hypot(...lattice_vecs[0]),
+    Math.hypot(...lattice_vecs[1]),
+    Math.hypot(...lattice_vecs[2]),
+  )
+  // Threshold to filter out floating-point-identical (zero-displacement) images; rarely triggers but guards against edge cases
+  const displacement_eps_sq = (1e-10 * lattice_norm) ** 2
+
+  // Tolerances determine which atoms are near cell boundaries and need image generation
+  // Use provided tolerance or default to physical tolerance of 0.5 Angstroms converted to fractional
+  // This prevents excessive image generation for large unit cells (e.g. MOFs) where 0.05 fractional is huge
+  const PHYSICAL_TOLERANCE = 0.5 // Angstroms
+  const tolerances = [0, 1, 2].map((dim) => {
+    if (tolerance !== undefined) return tolerance
+    const vec_len = Math.hypot(...lattice_vecs[dim])
+    // zero-length lattice vector should not occur in valid structures,
+    // but fall back to 0.05 fractional tolerance if it does
+    return vec_len > 0 ? PHYSICAL_TOLERANCE / vec_len : 0.05
+  })
+
+  for (const [idx, site] of structure.sites.entries()) {
+    // Find edge dimensions and translation directions
+    const edge_dims: { dim: number; direction: number }[] = []
+
+    // Find boundary dimensions
+    for (let dim = 0; dim < 3; dim++) {
+      const coord = site.abc[dim]
+      const dim_tolerance = tolerances[dim]
+      if (Math.abs(coord) < dim_tolerance) edge_dims.push({ dim, direction: 1 })
+      if (Math.abs(coord - 1) < dim_tolerance) edge_dims.push({ dim, direction: -1 })
+    }
+
+    // Generate all translation combinations
+    for (let mask = 1; mask < 1 << edge_dims.length; mask++) {
+      // Track selected translation per dimension. If both +1 and -1 are selected for a dim,
+      // the net shift is zero and we skip because it yields no image.
+      const selected_shift: Vec3 = [0, 0, 0]
+      for (let bit = 0; bit < edge_dims.length; bit++) {
+        if (mask & (1 << bit)) {
+          const { dim, direction } = edge_dims[bit]
+          selected_shift[dim] += direction
+        }
+      }
+
+      // Early skip if no net shift across any dimension
+      if (selected_shift.every((val) => val === 0)) continue
+
+      // Build fractional coordinates by applying the integer translation
+      // This ensures the image is a true periodic copy (preserving bond lengths)
+      // rather than clamping it to the cell face.
+      const img_abc: Vec3 = [
+        site.abc[0] + selected_shift[0],
+        site.abc[1] + selected_shift[1],
+        site.abc[2] + selected_shift[2],
+      ]
+
+      // If no dimension actually shifted, continue
+      if (
+        img_abc[0] === site.abc[0] &&
+        img_abc[1] === site.abc[1] &&
+        img_abc[2] === site.abc[2]
+      )
+        continue
+
+      // Compute xyz from img_abc to ensure consistency
+      const img_xyz = math.add(
+        math.scale(lattice_vecs[0], img_abc[0]),
+        math.scale(lattice_vecs[1], img_abc[1]),
+        math.scale(lattice_vecs[2], img_abc[2]),
+      )
+
+      // Skip zero-displacement images (should not happen, guards against FP edge cases)
+      const displacement = math.subtract(img_xyz, site.xyz)
+      const displacement_len_sq = displacement.reduce((sum, val) => sum + val * val, 0)
+      if (displacement_len_sq < displacement_eps_sq) continue
+
+      image_sites.push([idx, img_xyz, img_abc])
+    }
+  }
+
+  return image_sites
+}
+
+// Return structure with image atoms added
+export function get_pbc_image_sites(
+  ...args: Parameters<typeof find_image_atoms>
+): ParsedStructure {
+  const structure = args[0]
+
+  if (!structure || !structure.sites || structure.sites.length === 0) {
+    return structure
+  }
+
+  // Check for trajectory data
+  const atoms_outside_cell = structure.sites.filter((site) =>
+    site.abc.some((coord) => coord < -0.1 || coord > 1.1),
+  )
+
+  // Return trajectory data unchanged
+  if (atoms_outside_cell.length > structure.sites.length * 0.1) {
+    return structure
+  }
+
+  // Add image atoms to regular crystal structures
+  const image_sites = find_image_atoms(...args)
+  const imaged_struct = { ...structure, sites: [...structure.sites] }
+
+  // Add image atoms as new sites using provided (xyz, abc) from find_image_atoms
+  for (const [site_idx, img_xyz, img_abc] of image_sites) {
+    const orig_site = structure.sites[site_idx]
+    imaged_struct.sites.push({
+      ...orig_site,
+      abc: img_abc,
+      xyz: img_xyz,
+      properties: { ...orig_site.properties, orig_site_idx: site_idx },
+    })
+  }
+
+  return imaged_struct
+}

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

@@ -0,0 +1,226 @@
+// Supercell generation utilities for Crystal
+import type { Vec3 } from '$lib/math'
+import * as math from '$lib/math'
+import { scale_lattice_matrix } from '$lib/math'
+import type { Crystal, Site, StructureBond } from './index'
+import { wrap_frac_coord } from './pbc'
+import { normalize_structure_bond } from './bonding'
+
+type SupercellType = Crystal & {
+  supercell_scaling?: Vec3
+}
+
+const mod = (value: number, divisor: number): number => ((value % divisor) + divisor) % divisor
+
+const replicate_bonds_for_supercell = (
+  bonds: StructureBond[],
+  n_sites: number,
+  scaling_factors: Vec3,
+): StructureBond[] => {
+  const [scale_x, scale_y, scale_z] = scaling_factors
+  const replicated: StructureBond[] = []
+  const site_offset = ([cell_x, cell_y, cell_z]: Vec3): number =>
+    (cell_z * scale_x * scale_y + cell_y * scale_x + cell_x) * n_sites
+  for (const [source_cell_idx, source_cell] of generate_lattice_points(
+    scaling_factors,
+  ).entries()) {
+    const source_offset = source_cell_idx * n_sites
+    for (const { site_idx_1, site_idx_2, order, cell_shift = [0, 0, 0] } of bonds) {
+      const target_raw: Vec3 = [
+        source_cell[0] + cell_shift[0],
+        source_cell[1] + cell_shift[1],
+        source_cell[2] + cell_shift[2],
+      ]
+      const target_cell: Vec3 = [
+        mod(target_raw[0], scale_x),
+        mod(target_raw[1], scale_y),
+        mod(target_raw[2], scale_z),
+      ]
+      const supercell_shift = target_raw.map((val, idx) =>
+        Math.floor(val / scaling_factors[idx]),
+      ) as Vec3
+      const target_offset = site_offset(target_cell)
+      replicated.push(
+        normalize_structure_bond(
+          site_idx_1 + source_offset,
+          site_idx_2 + target_offset,
+          order,
+          supercell_shift,
+        ),
+      )
+    }
+  }
+  return replicated
+}
+
+// Parse supercell scaling input from various formats. Can be "2x2x2", "2", [2,2,2], or a single number.
+// Returns [x, y, z] scaling factors.
+export function parse_supercell_scaling(scaling: string | number | Vec3): Vec3 {
+  if (typeof scaling === `number`) {
+    if (scaling <= 0 || !Number.isInteger(scaling)) {
+      throw new Error(`Supercell scaling must be a positive integer, got: ${scaling}`)
+    }
+    return [scaling, scaling, scaling]
+  }
+  if (Array.isArray(scaling) && scaling.length === 3) {
+    if (scaling.some((val) => !Number.isInteger(val) || val <= 0)) {
+      throw new Error(`All supercell scaling factors must be positive integers: ${scaling}`)
+    }
+    return scaling
+  }
+  if (typeof scaling === `string`) {
+    // Parse "2x2x2" format
+    const parts = scaling
+      .trim()
+      .toLowerCase()
+      .split(/[x×,\s]+/)
+      .filter((part) => part.length > 0)
+
+    if (parts.length === 1 || parts.length === 3) {
+      // Check that all parts are strictly digits to avoid scientific notation/hex/etc per tests
+      if (parts.every((part) => /^\d+$/.test(part))) {
+        const values = parts.map(Number)
+        if (values.every((val) => val > 0)) {
+          return (parts.length === 1 ? [values[0], values[0], values[0]] : values) as Vec3
+        }
+      }
+    }
+  }
+  throw new Error(`Invalid supercell scaling: ${scaling}`)
+}
+
+// Generate all lattice points for a supercell. Takes [scale_x, scale_y, scale_z] scaling factors
+// and returns array of fractional coordinates for lattice points
+export function generate_lattice_points(scaling_factors: Vec3): Vec3[] {
+  const [scale_x, scale_y, scale_z] = scaling_factors
+  const count = scale_x * scale_y * scale_z
+  const points: Vec3[] = Array(count)
+
+  let write_idx = 0
+  // Generate in x, y, z order to match expected test results
+  for (let kk = 0; kk < scale_z; kk++) {
+    for (let jj = 0; jj < scale_y; jj++) {
+      for (let ii = 0; ii < scale_x; ii++) {
+        points[write_idx++] = [ii, jj, kk]
+      }
+    }
+  }
+
+  return points
+}
+
+// Re-export from $lib/math for backward compatibility
+export { scale_lattice_matrix }
+
+// Create a supercell from a Crystal
+// Takes original structure, scaling factors, and whether to fold coordinates back to unit cell (default: true)
+// Returns new supercell structure
+export function make_supercell(
+  structure: Crystal,
+  scaling: string | number | Vec3,
+  to_unit_cell: boolean = true,
+): Crystal {
+  if (!structure.lattice) {
+    throw new Error(`Cannot create supercell: structure has no lattice`)
+  }
+
+  const supercell_scaling = parse_supercell_scaling(scaling)
+  const [scale_x, scale_y, scale_z] = supercell_scaling
+  const total_cells = scale_x * scale_y * scale_z
+
+  // Short circuit for 1x1x1 (no actual supercell needed)
+  if (scale_x === 1 && scale_y === 1 && scale_z === 1) {
+    return { ...structure, supercell_scaling } as SupercellType
+  }
+
+  const orig_matrix = structure.lattice.matrix
+  // Create new scaled lattice
+  const new_lattice_matrix = scale_lattice_matrix(orig_matrix, supercell_scaling)
+  const lattice_params = math.calc_lattice_params(new_lattice_matrix)
+
+  const new_lattice = {
+    ...structure.lattice,
+    matrix: new_lattice_matrix,
+    ...lattice_params,
+  }
+
+  // Pre-allocate sites array
+  const n_sites = structure.sites.length
+  const new_sites: Site[] = Array(n_sites * total_cells)
+
+  // Destructure lattice vectors for fast inline arithmetic (avoid function calls in hot loop)
+  const [[ax, ay, az], [bx, by, bz], [cx, cy, cz]] = orig_matrix
+  const [sx, sy, sz] = supercell_scaling
+
+  let write_idx = 0
+  const sites = structure.sites
+
+  // Loop order: k, j, i to match typical pymatgen/standard ordering
+  for (let kk = 0; kk < scale_z; kk++) {
+    for (let jj = 0; jj < scale_y; jj++) {
+      for (let ii = 0; ii < scale_x; ii++) {
+        const label_suffix = total_cells > 1 ? `_${ii}${jj}${kk}` : ``
+
+        // Translation = ii * vec_a + jj * vec_b + kk * vec_c (inlined for performance)
+        const tx = ii * ax + jj * bx + kk * cx
+        const ty = ii * ay + jj * by + kk * cy
+        const tz = ii * az + jj * bz + kk * cz
+
+        for (let site_idx = 0; site_idx < n_sites; site_idx++) {
+          const site = sites[site_idx]
+
+          // new_abc = (old_abc + [ii, jj, kk]) / supercell_scaling
+          let new_a = (site.abc[0] + ii) / sx
+          let new_b = (site.abc[1] + jj) / sy
+          let new_c = (site.abc[2] + kk) / sz
+
+          if (to_unit_cell) {
+            new_a = wrap_frac_coord(new_a)
+            new_b = wrap_frac_coord(new_b)
+            new_c = wrap_frac_coord(new_c)
+          }
+
+          new_sites[write_idx++] = {
+            species: site.species,
+            xyz: [site.xyz[0] + tx, site.xyz[1] + ty, site.xyz[2] + tz],
+            abc: [new_a, new_b, new_c],
+            label: label_suffix ? `${site.label}${label_suffix}` : site.label,
+            properties: { ...site.properties, orig_unit_cell_idx: site_idx },
+          }
+        }
+      }
+    }
+  }
+
+  const properties =
+    structure.properties?.bonds === undefined
+      ? structure.properties
+      : {
+          ...structure.properties,
+          bonds: replicate_bonds_for_supercell(
+            structure.properties.bonds,
+            n_sites,
+            supercell_scaling,
+          ),
+        }
+
+  return {
+    ...structure,
+    lattice: new_lattice,
+    sites: new_sites,
+    properties,
+    charge: structure.charge ? structure.charge * total_cells : structure.charge,
+    supercell_scaling,
+  } as SupercellType
+}
+
+// Validate supercell input string
+// Takes user input string and returns true if valid, false otherwise
+export function is_valid_supercell_input(input: string): boolean {
+  try {
+    parse_supercell_scaling(input)
+    return true
+  } catch {
+    return false
+  }
+}

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

@@ -0,0 +1,11 @@
+import type { Crystal } from './index'
+
+export function is_crystal(obj: unknown): obj is Crystal {
+  if (obj === null || typeof obj !== `object`) return false
+  const structure_obj = obj as { sites?: unknown; lattice?: unknown }
+  const sites = structure_obj.sites
+  const lattice = structure_obj.lattice
+  const has_sites = Array.isArray(sites) && sites.length > 0
+  const has_lattice = lattice !== undefined && lattice !== null && typeof lattice === `object`
+  return has_sites && has_lattice
+}