matterviz 0.3.6 → 0.3.7

package/dist/structure/parse.js

@@ -0,0 +1,1392 @@
+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 '../constants';
+import { ELEM_SYMBOLS } from '../labels';
+import * as math from '../math';
+import { wrap_to_unit_cell } from './pbc';
+import { normalize_scientific_notation } from '../utils';
+import { load as yaml_load } from 'js-yaml';
+const cif_coords_key = (coords) => `${coords[0].toFixed(6)},${coords[1].toFixed(6)},${coords[2].toFixed(6)}`;
+const cif_site_key = (element, abc, label) => `${element}|${label}|${cif_coords_key(abc)}`;
+const clone_structure_properties = (properties) => structuredClone(properties);
+const FALLBACK_ELEMENTS = [`H`, `He`, `Li`, `Be`, `B`, `C`, `N`, `O`, `F`, `Ne`];
+const is_known_element_symbol = (symbol) => ELEM_SYMBOLS.includes(symbol);
+const vec3_from_values = (values, context) => {
+    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`);
+};
+// Parse a coordinate value that might be in various scientific notation formats
+function parse_coordinate(str) {
+    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) {
+    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, index) {
+    // 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) => {
+    try {
+        return math.create_cart_to_frac(lattice_matrix);
+    }
+    catch {
+        return null;
+    }
+};
+const approximate_cart_to_frac = (xyz, axis_lengths) => [
+    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) {
+    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, line_num) => {
+            const coords = line.trim().split(/\s+/).map(parse_coordinate);
+            return vec3_from_values(coords, `lattice vector on line ${line_num}`);
+        };
+        const lattice_vecs = [
+            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.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 = [];
+        let atom_counts = [];
+        // 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 = [
+                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 = [];
+            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;
+                    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;
+                    let abc;
+                    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 = {
+                        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 = {
+                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) {
+    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 = [];
+        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;
+        // 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 = [
+                    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] : null;
+        let xyz_frac_to_cart = null;
+        let xyz_cart_to_frac = 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 = [];
+        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 = [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 = { species, abc, xyz, label, properties: {} };
+            sites.push(site);
+        }
+        const structure = { 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) => {
+    const coefficients = [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 = [];
+    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, symmetry_ops, wrap_fractional_coords) => {
+    if (symmetry_ops.length === 0)
+        return [atom];
+    const equivalent_atoms = [];
+    const seen = new Set();
+    const wrap = (coords) => 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 = [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, type, strict = true) => 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 !== null);
+// build header index mapping for atom site data (supports fract and Cartn coordinates)
+const build_cif_atom_site_header_indices = (headers) => {
+    const indices = {};
+    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;
+};
+// Parse atom data from CIF with robust error handling
+const parse_cif_atom_data = (raw_data, indices, coords_type) => {
+    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, wrap_fractional_coords = true, strict = true) {
+    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 = [];
+        const atom_data_lines = [];
+        const symmetry_ops = [];
+        for (let ii = 0; ii < lines.length; ii++) {
+            if (lines[ii].trim() !== `loop_`)
+                continue;
+            let jj = ii + 1;
+            const headers = [];
+            // 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 = 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 !== 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) => (wrap_fractional_coords ? wrap_to_unit_cell(v) : v);
+        // Apply symmetry operations to generate all equivalent positions
+        const all_sites = [];
+        // 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 = [[0, 0, 0]];
+        // Inspect optional _atom_type_number_in_cell loop to see if atom sites are already expanded
+        const atom_type_counts = (() => {
+            const map = {};
+            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 = [];
+                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 = {};
+        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();
+        for (const atom of atoms) {
+            const element = validate_element_symbol(atom.element, all_sites.length);
+            // Convert to fractional coordinates if needed
+            let fractional_atom;
+            if (atom.coords_type === `fract`) {
+                fractional_atom = {
+                    ...atom,
+                    coords: wrap_vec3(atom.coords),
+                    coords_type: `fract`,
+                };
+            }
+            else {
+                const xyz_base = [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],
+                    ]);
+                    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) {
+    const sites = [];
+    // Phonopy stores lattice vectors as rows, use them directly
+    const lattice_matrix = [
+        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 = { 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 } };
+}
+const is_phonopy_cell = (value) => {
+    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, cell_type) => {
+    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, cell_type) {
+    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, visited = new WeakSet()) {
+    // 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) {
+    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) {
+    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, filename) {
+    // 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, filename) {
+    const finalize_structure = (structure) => ({
+        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) {
+    try {
+        const raw = JSON.parse(content);
+        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) {
+    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`),
+            ]
+            : 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) => 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 = [];
+        for (let idx = 0; idx < positions.length; idx++) {
+            const pos = positions[idx];
+            const element_symbol = species[idx];
+            let xyz;
+            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 = optimade_cart_to_frac ? optimade_cart_to_frac(xyz) : [0, 0, 0];
+            const 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;
+        if (lattice_matrix && optimade_lattice_params) {
+            lattice = { matrix: lattice_matrix, ...optimade_lattice_params };
+        }
+        const structure_result = {
+            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) {
+    try {
+        const raw = JSON.parse(content);
+        return is_optimade_raw(raw);
+    }
+    catch {
+        return false;
+    }
+}
+// Check if already-parsed JSON is OPTIMADE-like
+export const is_optimade_raw = (raw) => 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) {
+    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) => value && typeof value === `object` && `data` in value
+    ? value.data
+    : value;
+// Type guard: verify minimal OPTIMADE structure shape
+function is_optimade_structure_object(value) {
+    if (!value || typeof value !== `object`)
+        return false;
+    const obj = value;
+    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) {
+    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 = [
+            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) => 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 = 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 = {};
+            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) {
+    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, content) => {
+    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) => 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`;
+};