matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,1705 @@
+import type { OptimadeStructure } from '$lib/api/optimade'
+import {
+  COMPRESSION_EXTENSIONS_REGEX,
+  CONFIG_DIRS_REGEX,
+  STRUCT_KEYWORDS_REGEX,
+  STRUCT_KEYWORDS_STRICT_REGEX,
+  STRUCTURE_EXTENSIONS_REGEX,
+  TRAJ_KEYWORDS_REGEX,
+  VASP_FILES_REGEX,
+  XYZ_EXTXYZ_REGEX,
+} from '$lib/constants'
+import type { ElementSymbol } from '$lib/element'
+import { ELEM_SYMBOLS } from '$lib/labels'
+import type { Vec3 } from '$lib/math'
+import * as math from '$lib/math'
+import type { AnyStructure, Crystal, Site, StructureProperties } from '$lib/structure'
+import type { Pbc } from '$lib/structure/pbc'
+import { wrap_to_unit_cell } from '$lib/structure/pbc'
+import { normalize_scientific_notation } from '$lib/utils'
+import { load as yaml_load } from 'js-yaml'
+
+export interface ParsedStructure {
+  sites: Site[]
+  properties?: StructureProperties
+  lattice?: {
+    matrix: math.Matrix3x3
+    a: number
+    b: number
+    c: number
+    alpha: number
+    beta: number
+    gamma: number
+    volume: number
+    pbc?: Pbc
+  }
+}
+
+const cif_coords_key = (coords: Vec3): string =>
+  `${coords[0].toFixed(6)},${coords[1].toFixed(6)},${coords[2].toFixed(6)}`
+const cif_site_key = (element: string, abc: Vec3, label: string): string =>
+  `${element}|${label}|${cif_coords_key(abc)}`
+const clone_structure_properties = (properties: StructureProperties): StructureProperties =>
+  structuredClone(properties)
+const FALLBACK_ELEMENTS = [`H`, `He`, `Li`, `Be`, `B`, `C`, `N`, `O`, `F`, `Ne`] as const
+const is_known_element_symbol = (symbol: string): symbol is ElementSymbol =>
+  (ELEM_SYMBOLS as readonly string[]).includes(symbol)
+const vec3_from_values = (values: readonly unknown[] | undefined, context: string): Vec3 => {
+  if (values?.length !== 3) {
+    throw new Error(`Invalid ${context}: expected 3 coordinates, got ${values?.length ?? 0}`)
+  }
+  const coords = math.finite_vec3_from_values(values)
+  if (coords) return coords
+  for (let idx = 0; idx < 3; idx++) {
+    const value = values[idx]
+    if (typeof value !== `number` || !Number.isFinite(value)) {
+      throw new TypeError(
+        `Invalid ${context}: coordinate ${idx} must be finite, got ${String(value)}`,
+      )
+    }
+  }
+  throw new Error(`Invalid ${context}: expected 3 finite coordinates`)
+}
+
+export interface PhonopyCell {
+  lattice: number[][]
+  points: {
+    symbol: string
+    coordinates: number[]
+    mass: number
+    reduced_to?: number
+  }[]
+  reciprocal_lattice?: number[][]
+}
+
+export interface PhonopyData {
+  phono3py?: {
+    version: string
+    [key: string]: unknown
+  }
+  phonopy?: {
+    version: string
+    [key: string]: unknown
+  }
+  space_group?: {
+    type: string
+    number: number
+    Hall_symbol: string
+  }
+  primitive_cell?: PhonopyCell
+  unit_cell?: PhonopyCell
+  supercell?: PhonopyCell
+  phonon_primitive_cell?: PhonopyCell
+  phonon_supercell?: PhonopyCell
+  phonon_displacements?: unknown[] // Ignored for performance
+  [key: string]: unknown
+}
+
+// Parse a coordinate value that might be in various scientific notation formats
+function parse_coordinate(str: string): number {
+  const normalized = normalize_scientific_notation(str.trim())
+  const value = parseFloat(normalized)
+  if (isNaN(value)) throw new Error(`Invalid coordinate value: ${str}`)
+  return value
+}
+
+// Parse coordinates from a line, handling malformed formatting
+function parse_coordinate_line(line: string): number[] {
+  let tokens = line.trim().split(/\s+/)
+
+  // Handle malformed coordinates like "1.0-2.0-3.0" (missing spaces)
+  if (tokens.length < 3) {
+    // Insert a space only for subtraction between numbers, not exponent signs (e/E)
+    const sanitized = line
+      .trim()
+      // Add space when '-' follows a digit and precedes a digit or dot
+      .replace(/(\d)-(?=[\d.])/g, `$1 -`)
+      // Revert accidental spaces after exponent markers
+      .replace(/([eE])\s-\s/g, `$1-`)
+    tokens = sanitized.split(/\s+/)
+  }
+
+  if (tokens.length < 3) throw new Error(`Insufficient coordinates in line: ${line}`)
+
+  return tokens.slice(0, 3).map(parse_coordinate)
+}
+
+// Validate element symbol and provide fallback
+function validate_element_symbol(symbol: string, index: number): ElementSymbol {
+  // Clean symbol (remove suffixes like _pv, /hash)
+  const clean_symbol = symbol.split(/[_/]/)[0]
+
+  if (is_known_element_symbol(clean_symbol)) return clean_symbol
+
+  // Fallback to default elements by atomic number
+  const fallback = FALLBACK_ELEMENTS[index % FALLBACK_ELEMENTS.length] ?? `H`
+  console.warn(`Invalid element symbol '${symbol}', using fallback '${fallback}'`)
+  return fallback
+}
+
+const try_create_cart_to_frac = (
+  lattice_matrix: math.Matrix3x3,
+): ((v: Vec3) => Vec3) | null => {
+  try {
+    return math.create_cart_to_frac(lattice_matrix)
+  } catch {
+    return null
+  }
+}
+
+const approximate_cart_to_frac = (xyz: Vec3, axis_lengths: Vec3): Vec3 => [
+  Math.abs(axis_lengths[0]) > math.EPS ? xyz[0] / axis_lengths[0] : 0,
+  Math.abs(axis_lengths[1]) > math.EPS ? xyz[1] / axis_lengths[1] : 0,
+  Math.abs(axis_lengths[2]) > math.EPS ? xyz[2] / axis_lengths[2] : 0,
+]
+
+// Parse VASP POSCAR file format
+export function parse_poscar(content: string): ParsedStructure | null {
+  try {
+    const lines = content.replace(/^\s+/, ``).split(/\r?\n/)
+
+    if (lines.length < 8) {
+      console.error(`POSCAR file too short`)
+      return null
+    }
+
+    // Parse scaling factor (line 2)
+    let scale_factor = parseFloat(lines[1])
+    if (isNaN(scale_factor)) {
+      console.error(`Invalid scaling factor in POSCAR`)
+      return null
+    }
+
+    // Parse lattice vectors (lines 3-5)
+    const parse_vector = (line: string, line_num: number): Vec3 => {
+      const coords = line.trim().split(/\s+/).map(parse_coordinate)
+      return vec3_from_values(coords, `lattice vector on line ${line_num}`)
+    }
+
+    const lattice_vecs: math.Matrix3x3 = [
+      parse_vector(lines[2], 3),
+      parse_vector(lines[3], 4),
+      parse_vector(lines[4], 5),
+    ]
+
+    // Handle negative scale factor (volume-based scaling)
+    if (scale_factor < 0) {
+      const volume = Math.abs(math.det_3x3(lattice_vecs))
+      scale_factor = Math.pow(-scale_factor / volume, 1 / 3)
+    }
+
+    // Scale lattice vectors
+    const scaled_lattice: math.Matrix3x3 = [
+      math.scale(lattice_vecs[0], scale_factor),
+      math.scale(lattice_vecs[1], scale_factor),
+      math.scale(lattice_vecs[2], scale_factor),
+    ]
+
+    // Parse element symbols and atom counts (may span multiple lines)
+    let line_index = 5
+    let element_symbols: string[] = []
+    let atom_counts: number[] = []
+
+    // Detect if this is VASP 5+ format (has element symbols)
+    // Try to parse the first token as a number - if it succeeds, it's VASP 4 format
+    const first_token = lines[line_index].trim().split(/\s+/)[0]
+    const first_token_as_number = parseInt(first_token)
+    const has_element_symbols = isNaN(first_token_as_number)
+
+    if (has_element_symbols) {
+      // VASP 5+ format - parse element symbols (may span multiple lines)
+      let symbol_lines = 1
+
+      // Look ahead to find where numbers start (atom counts)
+      for (let lookahead_idx = 1; lookahead_idx < 10; lookahead_idx++) {
+        if (line_index + lookahead_idx >= lines.length) break
+        const next_line_first_token = lines[line_index + lookahead_idx].trim().split(/\s+/)[0]
+        const next_token_as_number = parseInt(next_line_first_token)
+        if (!isNaN(next_token_as_number)) {
+          symbol_lines = lookahead_idx
+          break
+        }
+      }
+
+      // Collect all element symbols from the symbol lines
+      for (let symbol_line_idx = 0; symbol_line_idx < symbol_lines; symbol_line_idx++) {
+        if (line_index + symbol_line_idx < lines.length) {
+          element_symbols.push(...lines[line_index + symbol_line_idx].trim().split(/\s+/))
+        }
+      }
+
+      // Parse atom counts (may span multiple lines)
+      for (let count_line_idx = 0; count_line_idx < symbol_lines; count_line_idx++) {
+        if (line_index + symbol_lines + count_line_idx < lines.length) {
+          const counts = lines[line_index + symbol_lines + count_line_idx]
+            .trim()
+            .split(/\s+/)
+            .map(Number)
+          atom_counts.push(...counts)
+        }
+      }
+
+      line_index += 2 * symbol_lines
+    } else {
+      // VASP 4 format - only atom counts, generate default element symbols
+      atom_counts = lines[line_index].trim().split(/\s+/).map(Number)
+      element_symbols = atom_counts.map((_, idx) =>
+        validate_element_symbol(`Element${idx}`, idx),
+      )
+      line_index += 1
+    }
+
+    if (element_symbols.length !== atom_counts.length) {
+      console.error(`Mismatch between element symbols and atom counts`)
+      return null
+    }
+
+    // Check for selective dynamics
+    let has_selective_dynamics = false
+    if (line_index < lines.length) {
+      let coordinate_mode = lines[line_index].trim().toUpperCase()
+
+      if (coordinate_mode.startsWith(`S`)) {
+        has_selective_dynamics = true
+        line_index += 1
+        if (line_index < lines.length) {
+          coordinate_mode = lines[line_index].trim().toUpperCase()
+        } else {
+          console.error(`Missing coordinate mode after selective dynamics`)
+          return null
+        }
+      }
+
+      // Determine coordinate mode
+      const is_direct = coordinate_mode.startsWith(`D`)
+      const is_cartesian = coordinate_mode.startsWith(`C`) || coordinate_mode.startsWith(`K`)
+
+      if (!is_direct && !is_cartesian) {
+        console.error(`Unknown coordinate mode in POSCAR: ${coordinate_mode}`)
+        return null
+      }
+
+      // Parse atomic positions
+      const poscar_axis_lengths: Vec3 = [
+        Math.hypot(...scaled_lattice[0]),
+        Math.hypot(...scaled_lattice[1]),
+        Math.hypot(...scaled_lattice[2]),
+      ]
+      const poscar_frac_to_cart = math.create_frac_to_cart(scaled_lattice)
+      const poscar_cart_to_frac = try_create_cart_to_frac(scaled_lattice)
+      if (!is_direct && !poscar_cart_to_frac) {
+        console.warn(`POSCAR: singular lattice, using axis-length fallback for cart→frac`)
+      }
+      const sites: Site[] = []
+      let atom_index = 0
+
+      for (let elem_idx = 0; elem_idx < element_symbols.length; elem_idx++) {
+        const element = validate_element_symbol(element_symbols[elem_idx], elem_idx)
+        const count = atom_counts[elem_idx]
+
+        for (let atom_count_idx = 0; atom_count_idx < count; atom_count_idx++) {
+          const coord_line_idx = line_index + 1 + atom_index + atom_count_idx
+          if (coord_line_idx >= lines.length) {
+            console.error(`Not enough coordinate lines in POSCAR`)
+            return null
+          }
+
+          const coords = vec3_from_values(
+            parse_coordinate_line(lines[coord_line_idx]),
+            `POSCAR atom coordinates on line ${coord_line_idx + 1}`,
+          )
+
+          // Parse selective dynamics if present
+          let selective_dynamics: [boolean, boolean, boolean] | undefined
+          if (has_selective_dynamics) {
+            const tokens = lines[coord_line_idx].trim().split(/\s+/)
+            if (tokens.length >= 6) {
+              selective_dynamics = [tokens[3] === `T`, tokens[4] === `T`, tokens[5] === `T`]
+            }
+          }
+          let xyz: Vec3
+          let abc: Vec3
+
+          if (is_direct) {
+            // Store fractional coordinates, wrapping to [0, 1) range
+            abc = wrap_to_unit_cell(coords)
+            xyz = poscar_frac_to_cart(abc)
+          } else {
+            // Already Cartesian, scale if needed
+            xyz = math.scale(coords, scale_factor)
+            const raw_abc = poscar_cart_to_frac
+              ? poscar_cart_to_frac(xyz)
+              : approximate_cart_to_frac(xyz, poscar_axis_lengths)
+            // Wrap fractional coordinates to [0, 1) range
+            abc = wrap_to_unit_cell(raw_abc)
+          }
+
+          const site: Site = {
+            species: [{ element, occu: 1, oxidation_state: 0 }],
+            abc,
+            xyz,
+            label: `${element}${atom_index + atom_count_idx + 1}`,
+            properties: selective_dynamics ? { selective_dynamics: selective_dynamics } : {},
+          }
+
+          sites.push(site)
+        }
+
+        atom_index += count
+      }
+
+      const lattice_params = math.calc_lattice_params(scaled_lattice)
+      const structure: ParsedStructure = {
+        sites,
+        lattice: { matrix: scaled_lattice, ...lattice_params },
+      }
+
+      return structure
+    } else {
+      console.error(`Missing coordinate mode line in POSCAR`)
+      return null
+    }
+  } catch (error) {
+    console.error(`Error parsing POSCAR file:`, error)
+    return null
+  }
+}
+
+// Parse XYZ file format. Supports both standard XYZ and extended XYZ formats with multi-frame support
+export function parse_xyz(content: string): ParsedStructure | null {
+  try {
+    const normalized_content = content.trim()
+    if (!normalized_content) {
+      console.error(`Empty XYZ file`)
+      return null
+    }
+
+    // Split into frames by reading the atom count and slicing lines
+    const all_lines = normalized_content.split(/\r?\n/)
+    const frames: string[] = []
+    let frame_line_idx = 0
+
+    while (frame_line_idx < all_lines.length) {
+      const numAtoms = parseInt(all_lines[frame_line_idx].trim(), 10)
+      if (
+        !isNaN(numAtoms) &&
+        numAtoms > 0 &&
+        frame_line_idx + numAtoms + 1 < all_lines.length
+      ) {
+        const frameLines = all_lines.slice(frame_line_idx, frame_line_idx + numAtoms + 2)
+        frames.push(frameLines.join(`\n`))
+        frame_line_idx += numAtoms + 2
+      } else frame_line_idx++
+    }
+
+    // If no frames found, try simple parsing
+    if (frames.length === 0) frames.push(normalized_content)
+
+    // Parse the last frame (or only frame)
+    const frame_content = frames.at(-1) ?? ``
+    const lines = frame_content.trim().split(/\r?\n/)
+
+    if (lines.length < 2) {
+      console.error(`XYZ frame too short`)
+      return null
+    }
+
+    // Parse number of atoms (line 1)
+    const num_atoms = parseInt(lines[0].trim())
+    if (isNaN(num_atoms) || num_atoms <= 0) {
+      console.error(`Invalid number of atoms in XYZ file`)
+      return null
+    }
+
+    // Parse comment line (line 2) - may contain lattice info for extended XYZ
+    const comment_line = lines[1]
+    let lattice: ParsedStructure[`lattice`] | undefined
+
+    // Check for extended XYZ lattice information in comment line
+    const lattice_match = /Lattice="([^"]+)"/.exec(comment_line)
+    if (lattice_match) {
+      const lattice_values = lattice_match[1].split(/\s+/).map(parse_coordinate)
+      if (lattice_values.length === 9) {
+        const lattice_vectors: math.Matrix3x3 = [
+          vec3_from_values(lattice_values.slice(0, 3), `XYZ lattice vector 1`),
+          vec3_from_values(lattice_values.slice(3, 6), `XYZ lattice vector 2`),
+          vec3_from_values(lattice_values.slice(6, 9), `XYZ lattice vector 3`),
+        ]
+
+        const lattice_params = math.calc_lattice_params(lattice_vectors)
+        lattice = { matrix: lattice_vectors, ...lattice_params }
+      }
+    }
+
+    // Parse atomic coordinates (starting from line 3)
+    const xyz_axis_lengths = lattice ? ([lattice.a, lattice.b, lattice.c] as Vec3) : null
+    let xyz_frac_to_cart: ((v: Vec3) => Vec3) | null = null
+    let xyz_cart_to_frac: ((v: Vec3) => Vec3) | null = null
+    if (lattice) {
+      xyz_frac_to_cart = math.create_frac_to_cart(lattice.matrix)
+      xyz_cart_to_frac = try_create_cart_to_frac(lattice.matrix)
+    }
+    const sites: Site[] = []
+
+    for (let atom_idx = 0; atom_idx < num_atoms; atom_idx++) {
+      const line_idx = atom_idx + 2
+      if (line_idx >= lines.length) {
+        console.error(`Not enough coordinate lines in XYZ file`)
+        return null
+      }
+
+      const parts = lines[line_idx].trim().split(/\s+/)
+      if (parts.length < 4) {
+        console.error(`Invalid coordinate line in XYZ file`)
+        return null
+      }
+
+      const element = validate_element_symbol(parts[0], atom_idx)
+      const xyz = vec3_from_values(
+        parts.slice(1, 4).map(parse_coordinate),
+        `XYZ atom position ${atom_idx + 1}`,
+      )
+
+      // Calculate fractional coordinates if lattice is available
+      let abc: Vec3 = [0, 0, 0]
+      if (lattice && xyz_frac_to_cart && xyz_axis_lengths) {
+        abc = xyz_cart_to_frac
+          ? xyz_cart_to_frac(xyz)
+          : approximate_cart_to_frac(xyz, xyz_axis_lengths)
+
+        // Ensure fractional coordinates are wrapped into [0, 1) for consistency
+        abc = wrap_to_unit_cell(abc)
+
+        // Keep rendered atoms inside primary unit cell by recomputing xyz
+        const wrapped_xyz = xyz_frac_to_cart(abc)
+        xyz[0] = wrapped_xyz[0]
+        xyz[1] = wrapped_xyz[1]
+        xyz[2] = wrapped_xyz[2]
+      }
+
+      const species = [{ element, occu: 1, oxidation_state: 0 }]
+      const label = `${element}${atom_idx + 1}`
+      const site: Site = { species, abc, xyz, label, properties: {} }
+
+      sites.push(site)
+    }
+
+    const structure: ParsedStructure = { sites, ...(lattice && { lattice }) }
+
+    return structure
+  } catch (error) {
+    console.error(`Error parsing XYZ file:`, error)
+    return null
+  }
+}
+
+// Parse a single symmetry expression dimension (e.g., "x-y+1/3" or "-x+y")
+// Returns the numeric coefficient for each variable and the translation constant
+const parse_symmetry_expression = (
+  expr_input: string,
+): { coefficients: Vec3; translation: number } => {
+  const coefficients: Vec3 = [0, 0, 0]
+  let translation = 0
+
+  // Remove all whitespace
+  const expr = expr_input.replace(/\s+/g, ``)
+  if (!expr) return { coefficients, translation }
+
+  // Tokenize: split into terms while preserving signs
+  // E.g., "x-y+1/3" → ["x", "-y", "+1/3"] or "-x+y" → ["-x", "+y"]
+  const tokens: string[] = []
+  let current_token = ``
+
+  for (let idx = 0; idx < expr.length; idx++) {
+    const char = expr[idx]
+    if ((char === `+` || char === `-`) && current_token.length > 0) {
+      tokens.push(current_token)
+      current_token = char
+    } else {
+      current_token += char
+    }
+  }
+  if (current_token) tokens.push(current_token)
+
+  for (const token of tokens) {
+    // Check if this token is a variable term (x, y, or z with optional sign)
+    const var_match = /^([+-]?)([xyz])$/.exec(token)
+    if (var_match) {
+      const sign = var_match[1] === `-` ? -1 : 1
+      const var_char = var_match[2]
+      const var_idx = var_char === `x` ? 0 : var_char === `y` ? 1 : 2
+      coefficients[var_idx] += sign
+      continue
+    }
+
+    // Check if this is a numeric term (integer, decimal, or fraction)
+    let sign = 1
+    let num_str = token
+
+    // Handle leading sign
+    if (num_str.startsWith(`+`)) {
+      num_str = num_str.slice(1)
+    } else if (num_str.startsWith(`-`)) {
+      sign = -1
+      num_str = num_str.slice(1)
+    }
+
+    // Skip empty tokens (from dangling operators like "x+")
+    if (!num_str || num_str === `+` || num_str === `-`) continue
+
+    if (num_str.includes(`/`)) {
+      // Fraction
+      const parts = num_str.split(`/`)
+      if (parts.length === 2) {
+        const numerator = parseFloat(parts[0])
+        const denominator = parseFloat(parts[1])
+        if (!isNaN(numerator) && !isNaN(denominator) && denominator !== 0) {
+          translation += sign * (numerator / denominator)
+        }
+      }
+    } else {
+      // Integer or decimal
+      const val = parseFloat(num_str)
+      if (!isNaN(val)) {
+        translation += sign * val
+      }
+    }
+  }
+
+  return { coefficients, translation }
+}
+
+// Apply symmetry operations to generate equivalent positions
+const apply_symmetry_ops = (
+  atom: CifAtom,
+  symmetry_ops: string[],
+  wrap_fractional_coords: boolean,
+): CifAtom[] => {
+  if (symmetry_ops.length === 0) return [atom]
+
+  const equivalent_atoms: CifAtom[] = []
+  const seen = new Set<string>()
+  const wrap = (coords: Vec3): Vec3 =>
+    wrap_fractional_coords ? wrap_to_unit_cell(coords) : coords
+  // Use 6 decimal places for deduplication to handle floating point imprecision
+  // from compound symmetry operations like x-y, -x+y which can produce small errors
+
+  // Always include base atom (optionally wrapped)
+  const base_coords = wrap(atom.coords)
+  seen.add(cif_coords_key(base_coords))
+  equivalent_atoms.push({ ...atom, coords: base_coords })
+
+  for (const operation of symmetry_ops) {
+    const operation_match = /['"]([^'"]+)['"]/.exec(operation)
+    const expr_str = operation_match ? operation_match[1] : operation.trim()
+    const parts = expr_str.split(`,`).map((part) => part.trim())
+    if (parts.length !== 3) continue
+
+    const new_coords: Vec3 = [0, 0, 0]
+
+    for (let dim = 0; dim < 3; dim++) {
+      const { coefficients, translation } = parse_symmetry_expression(parts[dim])
+      // Apply: new_coord = coeff_x * x + coeff_y * y + coeff_z * z + translation
+      new_coords[dim] =
+        coefficients[0] * atom.coords[0] +
+        coefficients[1] * atom.coords[1] +
+        coefficients[2] * atom.coords[2] +
+        translation
+    }
+
+    // Wrap and deduplicate transformed coordinates
+    const wrapped = wrap(new_coords)
+    const cache_key = cif_coords_key(wrapped)
+    if (seen.has(cache_key)) continue
+    seen.add(cache_key)
+
+    equivalent_atoms.push({
+      ...atom,
+      coords: wrapped,
+      id: `${atom.id}_${equivalent_atoms.length}`,
+    })
+  }
+
+  return equivalent_atoms
+}
+
+const extract_cif_cell_parameters = (text: string, type: string, strict = true): number[] =>
+  text
+    .split(`\n`)
+    .filter((line) => line.startsWith(`_${type}`))
+    .map((line) => {
+      const tokens = line.split(/\s+/).filter((token) => token.length > 0)
+      if (tokens.length < 2) {
+        if (strict) throw new Error(`Invalid CIF cell parameter line format: ${line}`)
+        return null
+      }
+      const value = parseFloat((tokens.at(-1) ?? ``).split(`(`)[0])
+      if (isNaN(value)) {
+        if (strict) throw new Error(`Invalid CIF cell parameter in line: ${line}`)
+        return null // Return null for invalid values in non-strict mode
+      }
+      return value
+    })
+    .filter((val): val is number => val !== null)
+
+// build header index mapping for atom site data (supports fract and Cartn coordinates)
+const build_cif_atom_site_header_indices = (headers: string[]): Record<string, number> => {
+  const indices: Record<string, number> = {}
+  const mappings = [
+    [`_atom_site_label`, `label`],
+    [`_atom_site_type_symbol`, `symbol`],
+    [`_atom_site_fract_x`, `x`],
+    [`_atom_site_fract_y`, `y`],
+    [`_atom_site_fract_z`, `z`],
+    [`_atom_site_cartn_x`, `cart_x`],
+    [`_atom_site_cartn_y`, `cart_y`],
+    [`_atom_site_cartn_z`, `cart_z`],
+    [`_atom_site_occupancy`, `occupancy`],
+    [`_atom_site_disorder_group`, `disorder`],
+  ]
+
+  headers.forEach((header, idx) => {
+    const lower = header.trim().toLowerCase()
+    const mapping = mappings.find(([suffix]) => lower.endsWith(suffix))
+    if (mapping) indices[mapping[1]] = idx
+  })
+
+  return indices
+}
+
+type CifAtom = {
+  id: string
+  element: string
+  coords: Vec3
+  coords_type: `fract` | `cart`
+  occupancy: number
+}
+
+// Parse atom data from CIF with robust error handling
+const parse_cif_atom_data = (
+  raw_data: string[],
+  indices: Record<string, number>,
+  coords_type: `fract` | `cart`,
+): CifAtom => {
+  const { label = 0, symbol = -1, occupancy = -1 } = indices
+  const coord_indices =
+    coords_type === `fract`
+      ? [indices.x, indices.y, indices.z]
+      : [indices.cart_x, indices.cart_y, indices.cart_z]
+
+  if (coord_indices.some((idx) => idx === undefined)) {
+    throw new Error(`Missing coordinate indices`)
+  }
+
+  const coords_triplet = vec3_from_values(
+    coord_indices.map((idx) => {
+      if (idx === undefined) throw new Error(`Invalid coordinate index`)
+      const coord_str = raw_data[idx]
+      if (!coord_str) throw new Error(`Missing coordinate at index ${idx}`)
+      const coord = parseFloat(coord_str.split(`(`)[0])
+      if (isNaN(coord)) throw new Error(`Invalid coordinate: ${coord_str}`)
+      return coord
+    }),
+    `CIF atom coordinates`,
+  )
+
+  const occu =
+    occupancy >= 0 && raw_data[occupancy]
+      ? parseFloat(raw_data[occupancy].split(`(`)[0]) || 1.0
+      : 1.0
+
+  const element_symbol =
+    (symbol >= 0 && /^([A-Z][a-z]*)/.exec(raw_data[symbol])?.[1]) ||
+    raw_data[label]?.match(/([A-Z][a-z]*)/g)?.[0] ||
+    (() => {
+      throw new Error(`Could not extract element symbol from: ${raw_data.join(` `)}`)
+    })()
+
+  return {
+    id: raw_data[label],
+    element: element_symbol,
+    coords: coords_triplet,
+    coords_type,
+    occupancy: occu,
+  }
+}
+
+// Parse CIF (Crystallographic Information File) format
+export function parse_cif(
+  content: string,
+  wrap_fractional_coords: boolean = true,
+  strict: boolean = true,
+): ParsedStructure | null {
+  try {
+    const text = content.trim()
+    if (!text) {
+      console.error(`CIF file is empty`)
+      return null
+    }
+
+    // Find atom site loop that actually contains coordinates (fract or Cartn)
+    const lines = text.split(`\n`)
+    let atom_headers: string[] = []
+    const atom_data_lines: string[] = []
+    const symmetry_ops: string[] = []
+
+    for (let ii = 0; ii < lines.length; ii++) {
+      if (lines[ii].trim() !== `loop_`) continue
+
+      let jj = ii + 1
+      const headers: string[] = []
+
+      // Collect headers for this loop
+      while (jj < lines.length && lines[jj].trim().startsWith(`_`)) {
+        headers.push(lines[jj].trim())
+        jj++
+      }
+
+      // Check if this is a symmetry operations loop
+      if (
+        headers.some(
+          (header) =>
+            header.includes(`_symmetry_equiv_pos_as_xyz`) ||
+            header.includes(`_space_group_symop_operation_xyz`),
+        )
+      ) {
+        // Collect symmetry operations
+        while (jj < lines.length) {
+          const line = lines[jj].trim()
+          if (line === `loop_` || line.startsWith(`data_`)) break
+          if (line && !line.startsWith(`#`) && !line.startsWith(`;`)) {
+            symmetry_ops.push(line)
+          }
+          jj++
+        }
+        continue
+      }
+
+      // Not an atom-site loop → continue search
+      if (!headers.some((header) => header.includes(`_atom_site_`))) continue
+
+      // Check if this loop contains coordinate headers
+      const indices_preview = build_cif_atom_site_header_indices(headers)
+      const has_coords =
+        (indices_preview.x !== undefined &&
+          indices_preview.y !== undefined &&
+          indices_preview.z !== undefined) ||
+        (indices_preview.cart_x !== undefined &&
+          indices_preview.cart_y !== undefined &&
+          indices_preview.cart_z !== undefined)
+
+      if (!has_coords) {
+        ii = jj - 1
+        continue
+      }
+
+      // This is the desired atom-site loop with coordinates: collect data lines
+      atom_headers = headers
+      while (jj < lines.length) {
+        const line = lines[jj].trim()
+        if (line === `loop_` || line.startsWith(`data_`)) break
+        if (line && !line.startsWith(`#`)) {
+          if (line.startsWith(`;`)) {
+            let multi_line_data = ``
+            while (jj < lines.length && !lines[jj].trim().endsWith(`;`)) {
+              multi_line_data += lines[jj] + `\n`
+              jj++
+            }
+            multi_line_data += lines[jj]
+            atom_data_lines.push(multi_line_data.trim())
+          } else {
+            atom_data_lines.push(line)
+          }
+        }
+        jj++
+      }
+      if (atom_data_lines.length > 0) break
+    }
+
+    if (!atom_headers.length || !atom_data_lines.length) {
+      console.error(`No valid atom site loop found in CIF file`)
+      return null
+    }
+
+    // Parse atom data with error handling
+    const header_indices = build_cif_atom_site_header_indices(atom_headers)
+
+    // Determine available coordinate type
+    const coords_type: `fract` | `cart` | null =
+      header_indices.x !== undefined &&
+      header_indices.y !== undefined &&
+      header_indices.z !== undefined
+        ? `fract`
+        : header_indices.cart_x !== undefined &&
+            header_indices.cart_y !== undefined &&
+            header_indices.cart_z !== undefined
+          ? `cart`
+          : null
+
+    if (!coords_type) {
+      console.error(`CIF atom site loop missing coordinates (fract or Cartn)`)
+      return null
+    }
+
+    // Collect required coordinate indices
+    const required_indices =
+      coords_type === `fract`
+        ? [header_indices.x, header_indices.y, header_indices.z]
+        : [header_indices.cart_x, header_indices.cart_y, header_indices.cart_z]
+
+    const atoms = atom_data_lines
+      .map((line) => {
+        // Handle quoted multi-word values by splitting only on whitespace
+        // that is not inside quotes.
+        const tokens = line.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || []
+        return tokens.map((token) => token.replace(/['"]/g, ``))
+      })
+      .filter((tokens) => {
+        const { disorder } = header_indices
+        const max_required_idx = Math.max(...required_indices)
+        return (
+          !(disorder !== undefined && tokens[disorder] === `2`) &&
+          tokens.length > max_required_idx
+        )
+      })
+      .map((tokens) => {
+        try {
+          return parse_cif_atom_data(tokens, header_indices, coords_type)
+        } catch (error) {
+          console.warn(`Skipping invalid atom data: ${error}`)
+          return null
+        }
+      })
+      .filter((atom): atom is NonNullable<typeof atom> => atom !== null)
+
+    if (!atoms.length) {
+      console.error(`No valid atoms found in CIF file`)
+      return null
+    }
+
+    // Extract cell parameters and build lattice
+    const lengths = extract_cif_cell_parameters(text, `cell_length`, strict)
+    const angles = extract_cif_cell_parameters(text, `cell_angle`, strict)
+
+    if (lengths.length < 3 || angles.length < 3) {
+      console.error(`Insufficient cell parameters in CIF file`)
+      return null
+    }
+
+    // Build lattice and create sites
+    const [a, b, c] = lengths
+    const [alpha, beta, gamma] = angles
+    const lattice_matrix = math.cell_to_lattice_matrix(a, b, c, alpha, beta, gamma)
+    const lattice_params = math.calc_lattice_params(lattice_matrix)
+    const frac_to_cart = math.create_frac_to_cart(lattice_matrix)
+    const cart_to_frac = try_create_cart_to_frac(lattice_matrix)
+
+    // Create sites with coordinate conversion and symmetry operations
+    const wrap_vec3 = (v: Vec3): Vec3 => (wrap_fractional_coords ? wrap_to_unit_cell(v) : v)
+
+    // Apply symmetry operations to generate all equivalent positions
+    const all_sites: Site[] = []
+
+    // Normalize symmetry operations (trim/strip quotes) but preserve duplicates; we deduplicate positions later
+    const normalized_ops = symmetry_ops
+      .map((op) => /['"]([^'"]+)['"]/.exec(op)?.[1] || op.trim())
+      .map((op) => op.replace(/\s+/g, ``))
+
+    // Rely on symmetry operations list for all centering/translations to avoid double-counting
+    // TODO: Support conventional cells with centering by discovering centering from space group metadata
+    // when present (e.g. P, I, F, C, R centering types)
+    const centering_vectors: Vec3[] = [[0, 0, 0]]
+
+    // Inspect optional _atom_type_number_in_cell loop to see if atom sites are already expanded
+    const atom_type_counts: Record<string, number> = (() => {
+      const map: Record<string, number> = {}
+      const text_lines = text.split(`\n`)
+      for (let li = 0; li < text_lines.length; li++) {
+        if (text_lines[li].trim() !== `loop_`) {
+          continue
+        }
+        let lj = li + 1
+        const hdrs: string[] = []
+        while (lj < text_lines.length && text_lines[lj].trim().startsWith(`_`)) {
+          hdrs.push(text_lines[lj].trim().toLowerCase())
+          lj++
+        }
+        const sym_idx = hdrs.findIndex((hdr) => hdr.endsWith(`_atom_type_symbol`))
+        const num_idx = hdrs.findIndex((hdr) => hdr.endsWith(`_atom_type_number_in_cell`))
+        if (sym_idx !== -1 && num_idx !== -1) {
+          while (lj < text_lines.length) {
+            const line = text_lines[lj].trim()
+            if (!line || line === `loop_` || line.startsWith(`data_`)) break
+            if (line.startsWith(`#`)) {
+              lj++
+              continue
+            }
+            const toks = (line.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || []).map((tok) =>
+              tok.replace(/['"]/g, ``),
+            )
+            if (toks.length > Math.max(sym_idx, num_idx)) {
+              // Normalize type symbol to bare element (e.g. 'Sn2+' -> 'Sn')
+              const match = /^([A-Z][a-z]*)/.exec(toks[sym_idx])
+              const sym = match ? match[1] : toks[sym_idx]
+              const num = parseInt(toks[num_idx])
+              if (sym && !Number.isNaN(num)) map[sym] = num
+            }
+            lj++
+          }
+          break
+        }
+      }
+      return map
+    })()
+
+    const observed_counts: Record<string, number> = {}
+    for (const atom of atoms) {
+      observed_counts[atom.element] = (observed_counts[atom.element] || 0) + 1
+    }
+
+    const has_expected_counts = Object.keys(atom_type_counts).length > 0
+    const already_enumerated =
+      has_expected_counts &&
+      Object.entries(atom_type_counts).every(([el, exp]) => (observed_counts[el] || 0) >= exp)
+
+    const ops_to_use = already_enumerated ? [] : normalized_ops
+
+    // Global deduplication of final sites (per element + coordinates + label)
+    // Use 6 decimal places to handle floating point imprecision from compound symmetry ops
+    const seen_site_keys = new Set<string>()
+
+    for (const atom of atoms) {
+      const element = validate_element_symbol(atom.element, all_sites.length)
+
+      // Convert to fractional coordinates if needed
+      let fractional_atom: CifAtom
+      if (atom.coords_type === `fract`) {
+        fractional_atom = {
+          ...atom,
+          coords: wrap_vec3(atom.coords),
+          coords_type: `fract`,
+        }
+      } else {
+        const xyz_base: Vec3 = [atom.coords[0], atom.coords[1], atom.coords[2]]
+        const atom_abc = wrap_vec3(
+          cart_to_frac
+            ? cart_to_frac(xyz_base)
+            : approximate_cart_to_frac(xyz_base, [a, b, c]),
+        )
+        fractional_atom = { ...atom, coords: atom_abc, coords_type: `fract` }
+      }
+
+      // First apply symmetry operations in fractional space
+      const equiv_atoms = apply_symmetry_ops(
+        fractional_atom,
+        ops_to_use,
+        wrap_fractional_coords,
+      )
+
+      // Then apply lattice centering shifts to each equivalent position
+      for (const equiv_atom of equiv_atoms) {
+        for (const cv of centering_vectors) {
+          const abc = wrap_vec3([
+            equiv_atom.coords[0] + cv[0],
+            equiv_atom.coords[1] + cv[1],
+            equiv_atom.coords[2] + cv[2],
+          ] as Vec3)
+          const key = cif_site_key(element, abc, equiv_atom.id)
+          if (seen_site_keys.has(key)) continue
+          seen_site_keys.add(key)
+          const xyz = frac_to_cart(abc)
+          all_sites.push({
+            species: [{ element, occu: equiv_atom.occupancy, oxidation_state: 0 }],
+            abc,
+            xyz,
+            label: equiv_atom.id,
+            properties: {},
+          })
+        }
+      }
+    }
+
+    const sites = all_sites
+    return { sites, lattice: { matrix: lattice_matrix, ...lattice_params } }
+  } catch (error) {
+    console.error(`Error parsing CIF file:`, error)
+    return null
+  }
+}
+
+// Convert phonopy cell to ParsedStructure
+function convert_phonopy_cell(cell: PhonopyCell): ParsedStructure {
+  const sites: Site[] = []
+  // Phonopy stores lattice vectors as rows, use them directly
+  const lattice_matrix: math.Matrix3x3 = [
+    vec3_from_values(cell.lattice[0], `phonopy lattice vector 1`),
+    vec3_from_values(cell.lattice[1], `phonopy lattice vector 2`),
+    vec3_from_values(cell.lattice[2], `phonopy lattice vector 3`),
+  ]
+
+  // Process each atomic site
+  const phonopy_frac_to_cart = math.create_frac_to_cart(lattice_matrix)
+  for (const point of cell.points) {
+    const element = validate_element_symbol(point.symbol, sites.length)
+    const abc = vec3_from_values(point.coordinates, `phonopy point coordinates`)
+
+    const xyz = phonopy_frac_to_cart(abc)
+
+    const properties = {
+      mass: point.mass,
+      ...(point.reduced_to !== undefined && { reduced_to: point.reduced_to }),
+    }
+    const species = [{ element, occu: 1.0, oxidation_state: 0 }]
+    const site: Site = { species, abc, xyz, label: point.symbol, properties }
+    sites.push(site)
+  }
+
+  // Calculate lattice parameters
+  const calculated_lattice_params = math.calc_lattice_params(lattice_matrix)
+
+  return { sites, lattice: { matrix: lattice_matrix, ...calculated_lattice_params } }
+}
+
+export type CellType =
+  | `primitive_cell`
+  | `unit_cell`
+  | `supercell`
+  | `phonon_primitive_cell`
+  | `phonon_supercell`
+  | `auto`
+
+const is_phonopy_cell = (value: unknown): value is PhonopyCell => {
+  if (!value || typeof value !== `object`) return false
+  const lattice = `lattice` in value ? value.lattice : undefined
+  const points = `points` in value ? value.points : undefined
+  return Array.isArray(lattice) && Array.isArray(points)
+}
+
+const get_phonopy_cell = (
+  data: unknown,
+  cell_type: Exclude<CellType, `auto`>,
+): PhonopyCell | undefined => {
+  if (!data || typeof data !== `object`) return undefined
+  const cell = Reflect.get(data, cell_type)
+  return is_phonopy_cell(cell) ? cell : undefined
+}
+
+// Parse phonopy YAML file and return the requested cell type (or preferred single structure)
+export function parse_phonopy_yaml(
+  content: string,
+  cell_type?: CellType,
+): ParsedStructure | null {
+  try {
+    // Parse YAML content but exclude large phonon_displacements array for performance
+    const lines = content.split(`\n`)
+    const filtered_lines = []
+    let skip_displacements = false
+
+    for (const line of lines) {
+      // Skip phonon_displacements section for performance
+      if (line.trim().startsWith(`phonon_displacements:`)) {
+        skip_displacements = true
+        continue
+      }
+
+      // Check if we're still in the phonon_displacements section
+      if (skip_displacements) {
+        if (/^[a-zA-Z_]/.exec(line)) {
+          // New top-level key, stop skipping
+          skip_displacements = false
+        } else continue // Still in phonon_displacements, skip this line
+      }
+
+      filtered_lines.push(line)
+    }
+
+    const filtered_content = filtered_lines.join(`\n`)
+    const data = yaml_load(filtered_content)
+
+    if (!data) {
+      console.error(`Failed to parse phonopy YAML`)
+      return null
+    }
+
+    // If specific cell type requested, parse only that one
+    if (cell_type && cell_type !== `auto`) {
+      const cell = get_phonopy_cell(data, cell_type)
+      if (cell) return convert_phonopy_cell(cell)
+      else {
+        console.error(`Requested cell type '${cell_type}' not found in phonopy YAML`)
+        return null
+      }
+    }
+
+    // Auto mode: return preferred structure in order of preference
+    // 1. supercell (most detailed)
+    // 2. phonon_supercell
+    // 3. unit_cell
+    // 4. phonon_primitive_cell
+    // 5. primitive_cell
+
+    const auto_cell =
+      get_phonopy_cell(data, `supercell`) ??
+      get_phonopy_cell(data, `phonon_supercell`) ??
+      get_phonopy_cell(data, `unit_cell`) ??
+      get_phonopy_cell(data, `phonon_primitive_cell`) ??
+      get_phonopy_cell(data, `primitive_cell`)
+    if (auto_cell) return convert_phonopy_cell(auto_cell)
+
+    console.error(`No valid cells found in phonopy YAML`)
+    return null
+  } catch (error) {
+    console.error(`Error parsing phonopy YAML:`, error)
+    return null
+  }
+}
+
+// Recursively search for a valid structure object in nested JSON
+function find_structure_in_json(
+  obj: unknown,
+  visited = new WeakSet(),
+): ParsedStructure | null {
+  // Check if current object is null or undefined
+  if (obj == null) return null
+
+  if (typeof obj !== `object`) return null // If it's not an object, skip it
+
+  if (visited.has(obj)) return null // Check for circular references
+  visited.add(obj)
+
+  // If it's an array, search through each element
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      const result = find_structure_in_json(item, visited)
+      if (result) return result
+    }
+    return null
+  }
+
+  // Check if this object looks like a valid structure
+  if (is_parsed_structure(obj)) return obj
+
+  // Otherwise, recursively search through all properties
+  for (const value of Object.values(obj)) {
+    const result = find_structure_in_json(value, visited)
+    if (result) return result
+  }
+
+  return null
+}
+
+// Type guard to validate structure-like objects
+function is_parsed_structure(obj: unknown): obj is ParsedStructure {
+  if (!obj || typeof obj !== `object`) return false
+  const sites = `sites` in obj ? obj.sites : undefined
+  if (!Array.isArray(sites) || sites.length === 0) return false
+
+  const first_site = sites[0]
+  if (!first_site || typeof first_site !== `object`) return false
+
+  const species = `species` in first_site ? first_site.species : undefined
+  const abc = `abc` in first_site ? first_site.abc : undefined
+  const xyz = `xyz` in first_site ? first_site.xyz : undefined
+  const has_species = Array.isArray(species) && species.length > 0
+  const has_coords = Array.isArray(abc) || Array.isArray(xyz)
+  return has_species && has_coords
+}
+
+// Normalize structure coordinates: wrap fractional coords to [0,1) and recompute Cartesian
+// Only normalizes when lattice matrix is available to ensure abc/xyz stay consistent
+export function normalize_fractional_coords(structure: ParsedStructure): ParsedStructure {
+  if (!structure.sites || structure.sites.length === 0) return structure
+
+  // Require lattice to ensure we can keep abc and xyz consistent after wrapping
+  if (!structure.lattice?.matrix) return structure
+
+  // Check if any sites have fractional coords outside [0, 1) range
+  const needs_wrapping = structure.sites.some((site) =>
+    site.abc?.some((coord) => coord < 0 || coord >= 1),
+  )
+  if (!needs_wrapping) return structure
+
+  const frac_to_cart = math.create_frac_to_cart(structure.lattice.matrix)
+
+  // Wrap fractional coordinates and recompute Cartesian
+  const normalized_sites = structure.sites.map((site) => {
+    if (!site.abc) return site
+    const wrapped_abc = wrap_to_unit_cell(site.abc)
+    return { ...site, abc: wrapped_abc, xyz: frac_to_cart(wrapped_abc) }
+  })
+
+  return { ...structure, sites: normalized_sites }
+}
+
+// Auto-detect file format and parse accordingly
+export function parse_structure_file(
+  content: string,
+  filename?: string,
+): ParsedStructure | null {
+  // If a filename is provided, try to detect format by file extension first
+  if (filename) {
+    // Handle compressed files by removing compression extensions
+    let base_filename = filename.toLowerCase()
+    while (COMPRESSION_EXTENSIONS_REGEX.test(base_filename)) {
+      base_filename = base_filename.replace(COMPRESSION_EXTENSIONS_REGEX, ``)
+    }
+
+    const ext = base_filename.split(`.`).pop()
+
+    // Try to detect format by file extension
+    if (ext === `xyz` || ext === `extxyz`) return parse_xyz(content)
+
+    // CIF files
+    if (ext === `cif`) return parse_cif(content)
+
+    // JSON files - try OPTIMADE JSON structure format first, then pymatgen
+    if (ext === `json`) {
+      try {
+        // Parse once, reuse for detection and parsing
+        const parsed = JSON.parse(content)
+        if (is_optimade_raw(parsed)) {
+          const result = parse_optimade_from_raw(parsed)
+          if (result) return result
+        }
+        // Otherwise, try to parse as pymatgen/nested structure JSON
+        const structure = find_structure_in_json(parsed)
+        if (structure) return normalize_fractional_coords(structure)
+        console.error(`JSON file does not contain a valid structure format`)
+        return null
+      } catch (error) {
+        console.error(`Error parsing JSON file:`, error)
+        return null
+      }
+    }
+
+    // YAML files (phonopy)
+    if (ext === `yaml` || ext === `yml`) return parse_phonopy_yaml(content)
+
+    // POSCAR files may not have extensions or have various names
+    if (ext === `poscar` || base_filename.includes(`poscar`)) {
+      return parse_poscar(content)
+    }
+  }
+
+  // Try to auto-detect based on content
+  const lines = content.trim().split(/\r?\n/)
+
+  if (lines.length < 2) {
+    console.error(`File too short to determine format`)
+    return null
+  }
+
+  // JSON format detection: try to parse as JSON first
+  try {
+    const parsed = JSON.parse(content)
+    if (is_optimade_raw(parsed)) {
+      const result = parse_optimade_from_raw(parsed)
+      if (result) return result
+    }
+    // Otherwise try parsing as regular JSON structure
+    const structure = find_structure_in_json(parsed)
+    if (structure) {
+      return normalize_fractional_coords(structure)
+    }
+  } catch {
+    // Not JSON, continue with other format detection
+  }
+
+  // XYZ format detection: first line should be a number, second line is comment
+  const first_line_number = parseInt(lines[0].trim())
+  if (!isNaN(first_line_number) && first_line_number > 0) {
+    // Check if this looks like XYZ format
+    if (lines.length >= first_line_number + 2) {
+      // Try to parse a coordinate line to see if it looks like XYZ
+      const coord_line_idx = 2 // First coordinate line in XYZ
+      if (coord_line_idx < lines.length) {
+        const parts = lines[coord_line_idx].trim().split(/\s+/)
+        // XYZ format: element symbol followed by 3 coordinates
+        if (parts.length >= 4) {
+          const first_token = parts[0]
+          const coords = parts.slice(1, 4)
+
+          // Check if first token looks like an element symbol (not a number)
+          // and the next 3 tokens look like coordinates (numbers)
+          const is_element_symbol = isNaN(parseInt(first_token)) && first_token.length <= 3
+          const are_coordinates = coords.every((coord) => !isNaN(parseFloat(coord)))
+
+          if (is_element_symbol && are_coordinates) {
+            // First token is likely an element symbol, likely XYZ
+            return parse_xyz(content)
+          }
+        }
+      }
+    }
+  }
+
+  // POSCAR format detection: look for typical structure
+  if (lines.length >= 8) {
+    const second_line_number = parseFloat(lines[1].trim())
+    // Second line is a number (scale factor), likely POSCAR
+    if (!isNaN(second_line_number)) return parse_poscar(content)
+  }
+
+  // CIF format detection: look for CIF-specific keywords
+  const has_cif_keywords = lines.some(
+    (line) =>
+      line.startsWith(`data_`) ||
+      line.includes(`_cell_length_`) ||
+      line.includes(`_atom_site_`) ||
+      line.trim() === `loop_`,
+  )
+  if (has_cif_keywords) return parse_cif(content)
+
+  // YAML format detection: look for phonopy-specific keywords
+  const has_phonopy_keywords = lines.some(
+    (line) =>
+      line.includes(`phono3py:`) ||
+      line.includes(`phonopy:`) ||
+      line.includes(`primitive_cell:`) ||
+      line.includes(`supercell:`) ||
+      line.includes(`phonon_supercell:`),
+  )
+  if (has_phonopy_keywords) return parse_phonopy_yaml(content)
+
+  console.error(`Unable to determine file format`)
+  return null
+}
+
+// Universal parser that handles JSON and structure files
+export function parse_any_structure(content: string, filename: string): AnyStructure | null {
+  const finalize_structure = (structure: ParsedStructure): AnyStructure => ({
+    sites: structure.sites,
+    charge: 0,
+    ...(structure.properties && {
+      properties: clone_structure_properties(structure.properties),
+    }),
+    ...(structure.lattice && {
+      lattice: { ...structure.lattice, pbc: [true, true, true] },
+    }),
+  })
+
+  // Try JSON first, but handle nested structures properly
+  try {
+    const parsed = JSON.parse(content)
+
+    // Check if it's already a valid structure using proper type guard
+    if (is_parsed_structure(parsed)) {
+      // Normalize coordinates (wrap fractional to [0,1) and recompute Cartesian)
+      return finalize_structure(normalize_fractional_coords(parsed))
+    }
+    // If not, use parse_structure_file to find nested structures
+    const structure = parse_structure_file(content, filename)
+
+    return structure ? finalize_structure(structure) : null
+  } catch {
+    // Try structure file formats
+    const parsed = parse_structure_file(content, filename)
+    return parsed ? finalize_structure(parsed) : null
+  }
+}
+
+// Parse OPTIMADE JSON format
+export function parse_optimade_json(content: string): ParsedStructure | null {
+  try {
+    const raw = JSON.parse(content) as unknown
+    return parse_optimade_from_raw(raw)
+  } catch (error) {
+    console.error(`Error parsing OPTIMADE JSON:`, error)
+    return null
+  }
+}
+
+// Parse OPTIMADE from already-parsed JSON
+export function parse_optimade_from_raw(raw: unknown): ParsedStructure | null {
+  try {
+    const structure = extract_optimade_structure_from_raw(raw)
+    if (!structure) {
+      console.error(`No valid OPTIMADE structure found in JSON`)
+      return null
+    }
+    const attrs = structure.attributes
+
+    // Inline validation for conciseness
+    const positions_raw = attrs.cartesian_site_positions
+    const species_raw = attrs.species_at_sites
+    if (!(Array.isArray(positions_raw) && Array.isArray(species_raw))) {
+      console.error(`OPTIMADE JSON missing required position or species data`)
+      return null
+    }
+    if (positions_raw.length !== species_raw.length) {
+      console.error(`OPTIMADE JSON position/species count mismatch`)
+      return null
+    }
+    const positions = positions_raw
+    const species = species_raw
+
+    // Optimade stores lattice vectors as rows, so use as is
+    const lattice_matrix = attrs.lattice_vectors
+      ? ([
+          vec3_from_values(attrs.lattice_vectors[0], `OPTIMADE lattice vector 1`),
+          vec3_from_values(attrs.lattice_vectors[1], `OPTIMADE lattice vector 2`),
+          vec3_from_values(attrs.lattice_vectors[2], `OPTIMADE lattice vector 3`),
+        ] satisfies math.Matrix3x3)
+      : undefined
+    const optimade_lattice_params = lattice_matrix
+      ? math.calc_lattice_params(lattice_matrix)
+      : null
+
+    // Parse atomic sites
+    const optimade_exact_cart_to_frac = lattice_matrix
+      ? try_create_cart_to_frac(lattice_matrix)
+      : null
+    const optimade_cart_to_frac =
+      lattice_matrix && optimade_lattice_params
+        ? (optimade_exact_cart_to_frac ??
+          ((xyz: Vec3): Vec3 =>
+            approximate_cart_to_frac(xyz, [
+              optimade_lattice_params.a,
+              optimade_lattice_params.b,
+              optimade_lattice_params.c,
+            ])))
+        : null
+    if (lattice_matrix && !optimade_exact_cart_to_frac) {
+      console.warn(`Failed to create exact coordinate converter for OPTIMADE structure`)
+    }
+    const sites: Site[] = []
+    for (let idx = 0; idx < positions.length; idx++) {
+      const pos = positions[idx]
+      const element_symbol = species[idx]
+
+      let xyz: Vec3
+      try {
+        xyz = vec3_from_values(pos, `OPTIMADE site ${idx} position`)
+      } catch (error) {
+        console.warn(`Invalid position data at site ${idx}: ${error}`)
+        continue
+      }
+
+      const element = validate_element_symbol(element_symbol, idx)
+
+      // Calculate fractional coordinates if lattice is available
+      const abc: Vec3 = optimade_cart_to_frac ? optimade_cart_to_frac(xyz) : [0, 0, 0]
+
+      const site: Site = {
+        species: [{ element, occu: 1, oxidation_state: 0 }],
+        abc,
+        xyz,
+        label: `${element}${idx + 1}`,
+        properties: {},
+      }
+
+      sites.push(site)
+    }
+
+    if (sites.length === 0) {
+      console.error(`No valid sites found in OPTIMADE JSON`)
+      return null
+    }
+
+    // Create structure object
+    let lattice: ParsedStructure[`lattice`] | undefined
+    if (lattice_matrix && optimade_lattice_params) {
+      lattice = { matrix: lattice_matrix, ...optimade_lattice_params }
+    }
+
+    const structure_result: ParsedStructure = {
+      sites,
+      ...(lattice && { lattice }),
+    }
+
+    return structure_result
+  } catch (error) {
+    console.error(`Error parsing OPTIMADE JSON:`, error)
+    return null
+  }
+}
+
+// Check if JSON content is OPTIMADE format by looking for structure attributes
+export function is_optimade_json(content: string): boolean {
+  try {
+    const raw = JSON.parse(content) as unknown
+    return is_optimade_raw(raw)
+  } catch {
+    return false
+  }
+}
+
+// Check if already-parsed JSON is OPTIMADE-like
+export const is_optimade_raw = (raw: unknown): boolean =>
+  Boolean(extract_optimade_structure_from_raw(raw))
+
+// Shared helper to extract an OPTIMADE structure from raw JSON-like data
+function extract_optimade_structure_from_raw(raw: unknown): OptimadeStructure | null {
+  const payload = unwrap_data(raw)
+  const candidate = Array.isArray(payload) ? payload[0] : payload
+  return is_optimade_structure_object(candidate) ? candidate : null
+}
+
+const unwrap_data = (value: unknown): unknown =>
+  value && typeof value === `object` && `data` in value
+    ? (value as { data?: unknown }).data
+    : value
+
+// Type guard: verify minimal OPTIMADE structure shape
+function is_optimade_structure_object(value: unknown): value is OptimadeStructure {
+  if (!value || typeof value !== `object`) return false
+  const obj = value as { type?: unknown; id?: unknown; attributes?: unknown }
+  const type = obj.type
+  const id = obj.id
+  const attributes = obj.attributes
+  return (
+    type === `structures` &&
+    typeof id === `string` &&
+    typeof attributes === `object` &&
+    attributes !== null
+  )
+}
+
+// Convert OPTIMADE structure to Crystal format
+export function optimade_to_crystal(optimade_structure: OptimadeStructure): Crystal | null {
+  const {
+    lattice_vectors,
+    cartesian_site_positions,
+    species_at_sites,
+    species,
+    ...properties
+  } = optimade_structure.attributes
+
+  if (!lattice_vectors || !cartesian_site_positions || !species_at_sites) {
+    console.error(`Missing required OPTIMADE structure data`)
+    return null
+  }
+
+  try {
+    const lattice_matrix: math.Matrix3x3 = [
+      vec3_from_values(lattice_vectors[0], `OPTIMADE lattice vector 1`),
+      vec3_from_values(lattice_vectors[1], `OPTIMADE lattice vector 2`),
+      vec3_from_values(lattice_vectors[2], `OPTIMADE lattice vector 3`),
+    ]
+    const lattice_params = math.calc_lattice_params(lattice_matrix)
+
+    // Build species lookup for site properties (mass, concentration, etc.)
+    const species_map = new Map(species?.map((spec) => [spec.name, spec]))
+    const crystal_cart_to_frac =
+      try_create_cart_to_frac(lattice_matrix) ??
+      ((xyz: Vec3): Vec3 =>
+        approximate_cart_to_frac(xyz, [lattice_params.a, lattice_params.b, lattice_params.c]))
+
+    const sites = cartesian_site_positions.map((pos, idx) => {
+      const element_symbol = species_at_sites[idx]
+      if (!element_symbol) throw new Error(`Missing species for site ${idx}`)
+      const element = validate_element_symbol(element_symbol, idx)
+
+      const xyz = vec3_from_values(pos, `OPTIMADE atom position ${idx + 1}`)
+      const abc: Vec3 = crystal_cart_to_frac ? crystal_cart_to_frac(xyz) : [0, 0, 0]
+
+      // Extract mass/concentration from species data
+      const spec = species_map.get(element_symbol)
+      const site_props: Record<string, unknown> = {}
+      if (spec?.mass?.[0] !== undefined) site_props.mass = spec.mass[0]
+      if (spec?.concentration?.[0] !== undefined && spec.concentration[0] !== 1) {
+        site_props.concentration = spec.concentration[0]
+      }
+      return {
+        species: [{ element, occu: 1, oxidation_state: 0 }],
+        abc,
+        xyz,
+        label: `${element}${idx + 1}`,
+        properties: site_props,
+      }
+    })
+
+    return {
+      sites,
+      lattice: { matrix: lattice_matrix, ...lattice_params, pbc: [true, true, true] },
+      id: optimade_structure.id,
+      properties,
+    }
+  } catch (err) {
+    console.error(`Error converting OPTIMADE to Crystal format:`, err)
+    return null
+  }
+}
+
+// Check if filename indicates a structure file
+export function is_structure_file(filename: string): boolean {
+  const name = filename.toLowerCase()
+
+  // Trajectory-only formats (can't be structures)
+  if (/\.(traj|xtc|h5|hdf5)$/i.test(name) || /xdatcar/i.test(name)) return false
+
+  // Always structure formats
+  if (STRUCTURE_EXTENSIONS_REGEX.test(name)) return true
+  if (VASP_FILES_REGEX.test(name)) return true
+
+  // .xyz/.extxyz files: structure unless they have trajectory keywords
+  if (/\.(xyz|extxyz)$/i.test(name)) return !TRAJ_KEYWORDS_REGEX.test(name)
+
+  // Keyword-based detection for YAML/XML
+  if (/\.(yaml|yml|xml)$/i.test(name) && STRUCT_KEYWORDS_REGEX.test(name)) return true
+
+  // More restrictive keyword detection for JSON files
+  if (
+    /\.json$/i.test(name) &&
+    STRUCT_KEYWORDS_STRICT_REGEX.test(name) &&
+    !TRAJ_KEYWORDS_REGEX.test(name) &&
+    !CONFIG_DIRS_REGEX.test(name)
+  )
+    return true
+
+  // Compressed files - check base filename recursively
+  if (COMPRESSION_EXTENSIONS_REGEX.test(name)) {
+    return is_structure_file(name.replace(COMPRESSION_EXTENSIONS_REGEX, ``))
+  }
+
+  return false
+}
+
+export const detect_structure_type = (
+  filename: string,
+  content: string,
+): `crystal` | `molecule` | `unknown` => {
+  const lower_filename = filename.toLowerCase()
+
+  // Normalize compressed suffixes (gz, gzip, zip, xz, bz2) for detection parity
+  let name_to_check = lower_filename
+  while (COMPRESSION_EXTENSIONS_REGEX.test(name_to_check)) {
+    name_to_check = name_to_check.replace(COMPRESSION_EXTENSIONS_REGEX, ``)
+  }
+
+  if (name_to_check.endsWith(`.json`)) {
+    try {
+      const parsed = JSON.parse(content)
+      // Check for crystal indicators: lattice, lattice_vectors, or periodic dimensions
+      const dims = parsed.data?.attributes?.dimension_types
+      if (
+        parsed.lattice ||
+        parsed.data?.attributes?.lattice_vectors ||
+        (Array.isArray(dims) && dims.some((dim: number) => dim > 0)) ||
+        parsed.data?.attributes?.nperiodic_dimensions > 0
+      ) {
+        return `crystal`
+      }
+      return `molecule`
+    } catch {
+      return `unknown`
+    }
+  }
+
+  if (name_to_check.endsWith(`.cif`)) return `crystal`
+  if (name_to_check.includes(`poscar`)) return `crystal`
+
+  if (name_to_check.endsWith(`.yaml`) || name_to_check.endsWith(`.yml`)) {
+    const lower_content = content.toLowerCase()
+    return lower_content.includes(`phono3py:`) || lower_content.includes(`phonopy:`)
+      ? `crystal`
+      : `unknown`
+  }
+
+  if (XYZ_EXTXYZ_REGEX.test(name_to_check)) {
+    const lines = content.trim().split(/\r?\n/)
+    return lines.length >= 2 && lines[1].includes(`Lattice=`) ? `crystal` : `molecule`
+  }
+
+  return `unknown`
+}