matterviz 0.3.6 → 0.4.0

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

@@ -1,183 +0,0 @@
-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

@@ -1,164 +0,0 @@
-// 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

@@ -1,226 +0,0 @@
-// 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

@@ -1,11 +0,0 @@
-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
-}