matterviz 0.4.1 → 0.4.3

package/dist/structure/parse.js

@@ -1,12 +1,13 @@
-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 { FALLBACK_ELEMENTS, is_elem_symbol } from '../element';
-import { strip_compression_extensions } from '../io';
+import { XYZ_EXTXYZ_REGEX } from '../constants';
+import { FALLBACK_ELEMENTS, is_elem_symbol } from '../element/helpers';
+import { strip_compression_extensions } from '../io/decompress';
 import * as math from '../math';
 import { wrap_to_unit_cell } from './pbc';
 import { make_site } from './site';
-import { iter_xyz_frames } from '../trajectory/helpers';
-import { normalize_scientific_notation, to_error } from '../utils';
+import { is_xyz_atom_line, iter_xyz_frames } from '../trajectory/helpers';
+import { normalize_scientific_notation, parse_leading_num, parse_num_token, to_error, } from '../utils';
 import { load as yaml_load } from 'js-yaml';
+export { is_structure_file } from './format-detect';
 // === Parse error contract ===
 // Individual format parsers (parse_poscar, parse_cif, parse_xyz, parse_phonopy_yaml,
 // parse_optimade_json, ...) return `T | null` on failure and record failure reasons in a
@@ -36,27 +37,48 @@ const aggregate_parse_error = (filename) => {
     return new Error(`Failed to parse structure${filename ? ` from '${filename}'` : ``}${detail}`);
 };
 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);
+// Bravais lattice centering translations (excluding the identity) keyed by the
+// leading letter of a space-group Hermann-Mauguin symbol. R is the obverse
+// hexagonal setting.
+const CENTERING_VECTORS = {
+    P: [],
+    I: [[0.5, 0.5, 0.5]],
+    F: [
+        [0, 0.5, 0.5],
+        [0.5, 0, 0.5],
+        [0.5, 0.5, 0],
+    ],
+    A: [[0, 0.5, 0.5]],
+    B: [[0.5, 0, 0.5]],
+    C: [[0.5, 0.5, 0]],
+    R: [
+        [2 / 3, 1 / 3, 1 / 3],
+        [1 / 3, 2 / 3, 2 / 3],
+    ],
+};
+// Detect the centering letter from a CIF's space-group H-M symbol, if present.
+const extract_cif_centering = (text) => {
+    for (const line of text.split(`\n`)) {
+        const match = /^_(?:symmetry_space_group_name_h-m|space_group_name_h-m(?:_alt)?)\s+(?<symbol>.+)/i.exec(line.trim());
+        const letter = match?.groups?.symbol.replaceAll(/['"]/g, ``).trim()[0]?.toUpperCase();
+        if (letter && letter in CENTERING_VECTORS)
+            return letter;
+    }
+    return null;
+};
 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`);
+    if (!coords)
+        throw new Error(`Invalid ${context}: expected 3 finite coordinates, got [${values.map(String).join(`, `)}]`);
+    return coords;
 };
 // 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);
+    const value = Number(normalized);
     if (isNaN(value))
         throw new Error(`Invalid coordinate value: ${str}`);
     return value;
@@ -70,9 +92,9 @@ function parse_coordinate_line(line) {
         const sanitized = line
             .trim()
             // Add space when '-' follows a digit and precedes a digit or dot
-            .replaceAll(/(\d)-(?=[\d.])/g, `$1 -`)
+            .replaceAll(/(?<digit>\d)-(?=[\d.])/g, `$1 -`)
             // Revert accidental spaces after exponent markers
-            .replaceAll(/([eE])\s-\s/g, `$1-`);
+            .replaceAll(/(?<exp_marker>[eE])\s-\s/g, `$1-`);
         tokens = sanitized.split(/\s+/);
     }
     if (tokens.length < 3)
@@ -114,14 +136,6 @@ function resolve_optimade_element(species_name, species_list, index) {
         return { symbol: stripped, sym_idx: -1 };
     return { symbol: validate_element_symbol(species_name, index), sym_idx: -1 };
 }
-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,
@@ -136,9 +150,12 @@ const matrix3x3_from_rows = (rows, context) => [
 // cart→frac converter that falls back to per-axis-length division for singular lattices.
 // axis_lengths defaults to the row norms of the lattice matrix.
 const cart_to_frac_with_fallback = (matrix, axis_lengths) => {
-    const exact_converter = try_create_cart_to_frac(matrix);
-    if (exact_converter)
-        return { convert: exact_converter, exact: true };
+    try {
+        return { convert: math.create_cart_to_frac(matrix), exact: true };
+    }
+    catch {
+        // fall through to the per-axis-length approximation below
+    }
     const lengths = axis_lengths ?? [
         Math.hypot(...matrix[0]),
         Math.hypot(...matrix[1]),
@@ -193,38 +210,24 @@ export function parse_poscar(content) {
         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, 10);
-        const has_element_symbols = isNaN(first_token_as_number);
+        const has_element_symbols = isNaN(parse_leading_num(lines[line_index]));
         if (has_element_symbols) {
-            // VASP 5+ format - parse element symbols (may span multiple lines)
+            // VASP 5+ format - element symbols (possibly spanning multiple lines),
+            // followed by as many atom-count lines. Look ahead to find where numbers start.
             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, 10);
-                if (!isNaN(next_token_as_number)) {
+                if (!isNaN(parse_leading_num(lines[line_index + lookahead_idx]))) {
                     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);
-                }
+            for (let offset = 0; offset < symbol_lines; offset++) {
+                const symbol_tokens = lines[line_index + offset]?.trim().split(/\s+/) ?? [];
+                element_symbols.push(...symbol_tokens);
+                const count_tokens = lines[line_index + symbol_lines + offset]?.trim().split(/\s+/);
+                atom_counts.push(...(count_tokens?.map(Number) ?? []));
             }
             line_index += 2 * symbol_lines;
         }
@@ -329,8 +332,9 @@ export function parse_xyz(content) {
             diag_error(`XYZ frame too short`);
             return null;
         }
-        // Parse number of atoms (line 1)
-        const num_atoms = parseInt(lines[0].trim(), 10);
+        // Parse number of atoms (line 1). Only the first token counts: Tinker-style
+        // XYZ files put a title after the count (e.g. `6 methane`)
+        const num_atoms = Math.trunc(parse_leading_num(lines[0]));
         if (isNaN(num_atoms) || num_atoms <= 0) {
             diag_error(`Invalid number of atoms in XYZ file`);
             return null;
@@ -339,7 +343,7 @@ export function parse_xyz(content) {
         const comment_line = lines[1];
         let lattice;
         // Check for extended XYZ lattice information in comment line
-        const lattice_match = /Lattice="([^"]+)"/.exec(comment_line);
+        const lattice_match = /Lattice="(?<lattice>[^"]+)"/.exec(comment_line);
         if (lattice_match) {
             const lattice_values = lattice_match[1].split(/\s+/).map(parse_coordinate);
             if (lattice_values.length === 9) {
@@ -372,17 +376,14 @@ export function parse_xyz(content) {
                 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}`);
+            let 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_cart_to_frac) {
-                // Ensure fractional coordinates are wrapped into [0, 1) for consistency
+                // Wrap fractional coordinates into [0, 1) and recompute xyz from them so
+                // rendered atoms stay inside the primary unit cell
                 abc = wrap_to_unit_cell(xyz_cart_to_frac(xyz));
-                // 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];
+                xyz = xyz_frac_to_cart(abc);
             }
             sites.push(make_site(element, abc, xyz, `${element}${atom_idx + 1}`));
         }
@@ -399,114 +400,78 @@ export function parse_xyz(content) {
 const parse_symmetry_expression = (expr_input) => {
     const coefficients = [0, 0, 0];
     let translation = 0;
-    // Remove all whitespace
+    // Strip whitespace, then split into signed terms: "x-y+1/3" → ["x", "-y", "+1/3"].
+    // Dangling operators (e.g. "x+") produce no token and are silently ignored.
     const expr = expr_input.replaceAll(/\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;
+    for (const token of expr.match(/[+-]?[^+-]+/g) ?? []) {
+        const sign = token.startsWith(`-`) ? -1 : 1;
+        const term = token.replace(/^[+-]/, ``);
+        // Variable term (x, y, or z)
+        const var_idx = [`x`, `y`, `z`].indexOf(term);
+        if (var_idx !== -1) {
             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 === `-`)
+        // Numeric term: integer, decimal, or fraction like "1/3"
+        const parts = term.split(`/`);
+        // skip malformed terms like "1/2/3"
+        if (parts.length > 2) {
+            diag_warn(`Skipping malformed symmetry term '${term}'`);
             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;
-            }
         }
+        const [numerator, denominator = `1`] = parts;
+        const value = Number(numerator) / Number(denominator);
+        if (Number.isFinite(value))
+            translation += sign * value;
+        else
+            diag_warn(`Skipping non-finite symmetry term '${term}'`);
     }
     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)
+// Apply symmetry operations (and optional lattice-centering translations) to
+// generate all equivalent positions. Deduplication uses 6 decimal places to
+// absorb floating point error from compound ops like x-y, -x+y.
+const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords, centering = []) => {
+    if (symmetry_ops.length === 0 && centering.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 });
+    // Every generated position is also offset by each centering translation
+    const shifts = [[0, 0, 0], ...centering];
+    // Record a position plus its centering images, deduplicating on wrapped coords
+    const add_position = (coords) => {
+        for (const [dx, dy, dz] of shifts) {
+            const wrapped = wrap([coords[0] + dx, coords[1] + dy, coords[2] + dz]);
+            const key = cif_coords_key(wrapped);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const id = equivalent_atoms.length === 0 ? atom.id : `${atom.id}_${equivalent_atoms.length}`;
+            equivalent_atoms.push({ ...atom, coords: wrapped, id });
+        }
+    };
+    add_position(atom.coords); // base atom (+ centering images)
+    // ops arrive pre-normalized (quotes + whitespace already stripped, see normalized_ops)
     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());
+        const parts = operation.split(`,`);
         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;
+            // new_coord = coeff_x * x + coeff_y * y + coeff_z * z + translation
+            new_coords[dim] = math.dot(coefficients, atom.coords) + 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}`,
-        });
+        add_position(new_coords);
     }
     return equivalent_atoms;
 };
+// Parse a CIF numeric token, stripping a trailing uncertainty like "1.234(5)"
+const parse_cif_uncertain_number = (token) => {
+    const value = parse_num_token(token.split(`(`)[0]);
+    return isNaN(value) ? null : value;
+};
 const extract_cif_cell_parameters = (text, type, strict = true) => text
     .split(`\n`)
     .filter((line) => line.startsWith(`_${type}`))
@@ -519,11 +484,9 @@ const extract_cif_cell_parameters = (text, type, strict = true) => text
             throw new Error(`Invalid CIF cell parameter line format: ${line}`);
         return null;
     }
-    const value = parseFloat(tokens[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
+    const value = parse_cif_uncertain_number(tokens[1]);
+    if (value === null && strict) {
+        throw new Error(`Invalid CIF cell parameter in line: ${line}`);
     }
     return value;
 })
@@ -551,6 +514,22 @@ const build_cif_atom_site_header_indices = (headers) => {
     });
     return indices;
 };
+// Which coordinate triple a CIF atom-site loop provides (fractional preferred), or null
+const cif_coords_type = (indices) => {
+    if (indices.x !== undefined && indices.y !== undefined && indices.z !== undefined) {
+        return `fract`;
+    }
+    if (indices.cart_x !== undefined &&
+        indices.cart_y !== undefined &&
+        indices.cart_z !== undefined) {
+        return `cart`;
+    }
+    return null;
+};
+// The 3 column indices for the requested coordinate type
+const cif_coord_indices = (indices, coords_type) => coords_type === `fract`
+    ? [indices.x, indices.y, indices.z]
+    : [indices.cart_x, indices.cart_y, indices.cart_z];
 // Walk CIF loop_ blocks: yields each loop's header tags plus the index of its first data line
 function* iter_cif_loops(lines) {
     for (let idx = 0; idx < lines.length; idx++) {
@@ -571,28 +550,24 @@ const split_cif_tokens = (line) => (line.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)
 // 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`);
-    }
+    // cif_coords_type already guaranteed all three indices for coords_type exist
+    const coord_indices = cif_coord_indices(indices, coords_type);
     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))
+        const coord = parse_cif_uncertain_number(coord_str);
+        if (coord === null)
             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 from_symbol = symbol >= 0 ? /^([A-Z][a-z]*)/.exec(raw_data[symbol])?.[1] : undefined;
-    const element_symbol = from_symbol ?? raw_data[label]?.match(/([A-Z][a-z]*)/g)?.[0];
+    const raw_occu = occupancy >= 0 && raw_data[occupancy]
+        ? parse_cif_uncertain_number(raw_data[occupancy])
+        : null;
+    // Explicit 0 is kept; missing / `.` / `?` (null) default to fully occupied.
+    const occu = raw_occu ?? 1.0;
+    const from_symbol = symbol >= 0 ? /^(?<element>[A-Z][a-z]*)/.exec(raw_data[symbol])?.[1] : undefined;
+    const element_symbol = from_symbol ?? raw_data[label]?.match(/(?:[A-Z][a-z]*)/g)?.[0];
     if (!element_symbol) {
         throw new Error(`Could not extract element symbol from: ${raw_data.join(` `)}`);
     }
@@ -639,13 +614,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 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)
+            if (cif_coords_type(indices_preview) === null)
                 continue;
             // This is the desired atom-site loop with coordinates: collect data lines
             atom_headers = headers;
@@ -679,23 +648,13 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         // 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;
+        const coords_type = cif_coords_type(header_indices);
         if (!coords_type) {
             diag_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 required_indices = cif_coord_indices(header_indices, coords_type);
         const atoms = atom_data_lines
             .map(split_cif_tokens)
             .filter((tokens) => {
@@ -734,15 +693,9 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         const cart_to_frac = cart_to_frac_with_fallback(lattice_matrix, [a, b, c]).convert;
         // Create sites with coordinate conversion and symmetry operations
         const wrap_vec3 = (vec) => wrap_fractional_coords ? wrap_to_unit_cell(vec) : vec;
-        // 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.replaceAll(/\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)
+        // Strip surrounding quotes and all whitespace (preserving duplicates; positions
+        // are deduplicated later). Leaves ops as bare `x,y,z`-style expressions.
+        const normalized_ops = symmetry_ops.map((op) => (/['"](?<expr>[^'"]+)['"]/.exec(op)?.groups?.expr ?? op).replaceAll(/\s+/g, ``));
         // Inspect optional _atom_type_number_in_cell loop to see if atom sites are already expanded
         const atom_type_counts = {};
         for (const { headers, data_start } of iter_cif_loops(lines)) {
@@ -760,11 +713,15 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                 const toks = split_cif_tokens(line);
                 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 match = /^(?<element>[A-Z][a-z]*)/.exec(toks[sym_idx]);
                     const sym = match ? match[1] : toks[sym_idx];
-                    const num = parseInt(toks[num_idx], 10);
-                    if (sym && !Number.isNaN(num))
-                        atom_type_counts[sym] = num;
+                    // Strip standard-uncertainty parentheses (`8(0)` -> `8`) like other CIF
+                    // readers; empty prefixes like `(8)` parse as NaN and get skipped
+                    const num = Math.trunc(parse_num_token(toks[num_idx].split(`(`)[0]));
+                    // sum rows that normalize to the same element (e.g. Fe2+ and Fe3+ → Fe)
+                    if (sym && !Number.isNaN(num)) {
+                        atom_type_counts[sym] = (atom_type_counts[sym] ?? 0) + num;
+                    }
                 }
             }
             break;
@@ -777,38 +734,61 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         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(xyz_base));
-                fractional_atom = { ...atom, coords: atom_abc, coords_type: `fract` };
+        // Candidate lattice-centering translations from the space-group symbol (R
+        // only valid in the hexagonal setting, α≈β≈90°, γ≈120°). Whether to actually
+        // apply them is decided below by reconciling against _atom_type_number_in_cell.
+        const centering_letter = extract_cif_centering(text);
+        const is_hexagonal_setting = Math.abs(alpha - 90) <= 1 && Math.abs(beta - 90) <= 1 && Math.abs(gamma - 120) <= 1;
+        const centering = centering_letter && (centering_letter !== `R` || is_hexagonal_setting)
+            ? CENTERING_VECTORS[centering_letter]
+            : [];
+        // Build all sites by expanding each atom via the symmetry ops (+ optional
+        // centering). Deduplicate globally on element + coordinates + label (6 dp to
+        // absorb floating point error from compound ops).
+        const build_sites = (extra_centering) => {
+            const sites = [];
+            const seen_site_keys = new Set();
+            for (const atom of atoms) {
+                const element = validate_element_symbol(atom.element, sites.length);
+                const coords = atom.coords_type === `fract`
+                    ? wrap_vec3(atom.coords)
+                    : wrap_vec3(cart_to_frac([atom.coords[0], atom.coords[1], atom.coords[2]]));
+                const fractional_atom = { ...atom, coords, coords_type: `fract` };
+                const equiv_atoms = apply_symmetry_ops(fractional_atom, ops_to_use, wrap_fractional_coords, extra_centering);
+                for (const equiv_atom of equiv_atoms) {
+                    const abc = wrap_vec3(equiv_atom.coords);
+                    const key = `${element}|${equiv_atom.id}|${cif_coords_key(abc)}`;
+                    if (seen_site_keys.has(key))
+                        continue;
+                    seen_site_keys.add(key);
+                    sites.push(make_site(element, abc, frac_to_cart(abc), equiv_atom.id, {}, equiv_atom.occupancy));
+                }
             }
-            // First apply symmetry operations in fractional space
-            const equiv_atoms = apply_symmetry_ops(fractional_atom, ops_to_use, wrap_fractional_coords);
-            for (const equiv_atom of equiv_atoms) {
-                const abc = wrap_vec3(equiv_atom.coords);
-                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(make_site(element, abc, xyz, equiv_atom.id, {}, equiv_atom.occupancy));
+            return sites;
+        };
+        // Expand with point-group ops first. If the space group is centered and the
+        // result falls short of _atom_type_number_in_cell, retry with centering and
+        // adopt it only when it reconciles the expected total exactly — this fixes
+        // CIFs listing point-only ops for the asymmetric unit while avoiding
+        // double-counting CIFs whose atom list already embeds centering (e.g. C2/c
+        // COD 7008984, where listed ops + atoms already total the cell contents).
+        let sites = build_sites([]);
+        const expected_total = Object.values(atom_type_counts).reduce((sum, num) => sum + num, 0);
+        if (centering.length > 0 && expected_total > sites.length) {
+            const centered_sites = build_sites(centering);
+            // Adopt centering only when per-element counts reconcile exactly. Checking
+            // the total alone is insufficient: it can coincide while individual element
+            // counts are wrong (e.g. expected Fe 1 / O 3 but centering yields Fe 2 / O 2).
+            const counts = {};
+            for (const site of centered_sites) {
+                const element = site.species[0].element;
+                counts[element] = (counts[element] ?? 0) + 1;
             }
+            const reconciles = centered_sites.length === expected_total &&
+                Object.entries(atom_type_counts).every(([element, exp]) => counts[element] === exp);
+            if (reconciles)
+                sites = centered_sites;
         }
-        const sites = all_sites;
         return { sites, lattice: { matrix: lattice_matrix, ...lattice_params } };
     }
     catch (error) {
@@ -865,7 +845,7 @@ export function parse_phonopy_yaml(content, cell_type) {
             }
             // Check if we're still in the phonon_displacements section
             if (skip_displacements) {
-                if (/^[a-zA-Z_]/.exec(line)) {
+                if (/^[a-zA-Z_]/.test(line)) {
                     // New top-level key, stop skipping
                     skip_displacements = false;
                 }
@@ -888,17 +868,16 @@ export function parse_phonopy_yaml(content, cell_type) {
             diag_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`);
+        // Auto mode: return first available cell, most detailed first
+        const auto_cell = [
+            `supercell`,
+            `phonon_supercell`,
+            `unit_cell`,
+            `phonon_primitive_cell`,
+            `primitive_cell`,
+        ]
+            .map((kind) => get_phonopy_cell(data, kind))
+            .find(Boolean);
         if (auto_cell)
             return convert_phonopy_cell(auto_cell);
         diag_error(`No valid cells found in phonopy YAML`);
@@ -956,6 +935,31 @@ export function is_parsed_structure(obj) {
     const has_coords = Array.isArray(abc) || Array.isArray(xyz);
     return has_species && has_coords;
 }
+// Structure JSON serialized by pymatgen (default verbosity) stores only the lattice
+// matrix + pbc; derive the missing scalar params (a/b/c/angles/volume) from the matrix
+// so downstream consumers (camera auto-fit, density, export) never see NaN.
+export function ensure_lattice_params(structure) {
+    const lattice = structure.lattice;
+    if (!lattice?.matrix)
+        return structure;
+    const params = [
+        lattice.a,
+        lattice.b,
+        lattice.c,
+        lattice.alpha,
+        lattice.beta,
+        lattice.gamma,
+        lattice.volume,
+    ];
+    if (params.every(Number.isFinite))
+        return structure;
+    // The matrix is authoritative: recompute all params from it rather than
+    // trusting a partially-populated (or non-numeric) set of values.
+    return {
+        ...structure,
+        lattice: { ...lattice, ...math.calc_lattice_params(lattice.matrix) },
+    };
+}
 // 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) {
@@ -989,7 +993,7 @@ const detect_json_structure = (content) => {
     }
     // Otherwise try parsing as pymatgen/nested structure JSON
     const structure = find_structure_in_json(parsed);
-    return structure ? normalize_fractional_coords(structure) : null;
+    return structure ? ensure_lattice_params(normalize_fractional_coords(structure)) : null;
 };
 // Internal: auto-detect file format, returns null on failure after recording reasons (see parse error contract at top)
 function parse_structure_file_impl(content, filename) {
@@ -1048,36 +1052,20 @@ function parse_structure_file_impl(content, filename) {
         diag_error(`File too short to determine format`);
         return null;
     }
-    // XYZ format detection: first line should be a number, second line is comment
-    const first_line_number = parseInt(lines[0].trim(), 10);
-    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, 10)) && 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);
-                    }
-                }
-            }
-        }
-    }
+    // XYZ format detection: first line is a positive atom count, second line is a
+    // comment, and the first coordinate line looks like "<element> <x> <y> <z>"
+    const first_line_number = Math.trunc(parse_leading_num(lines[0]));
+    if (!isNaN(first_line_number) &&
+        first_line_number > 0 &&
+        lines.length >= first_line_number + 2 &&
+        is_xyz_atom_line(lines[2]?.trim().split(/\s+/)))
+        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))
+        // Second line starts with a number (scale factor), likely POSCAR. First
+        // token only: POSCAR allows three per-axis scale factors (or trailing
+        // comments) on line 2, and blank lines must not pass
+        if (!isNaN(parse_leading_num(lines[1])))
             return parse_poscar(content);
     }
     // CIF format detection: look for CIF-specific keywords
@@ -1109,16 +1097,19 @@ export function parse_structure_file(content, filename) {
 // Universal parser for JSON and structure files; throws an Error aggregating per-format failure reasons when nothing parses
 export function parse_any_structure(content, filename) {
     reset_parse_diagnostics();
-    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] },
-        }),
-    });
+    const finalize_structure = (parsed_structure) => {
+        const structure = ensure_lattice_params(parsed_structure);
+        return {
+            sites: structure.sites,
+            charge: 0,
+            ...(structure.properties && {
+                properties: structuredClone(structure.properties),
+            }),
+            ...(structure.lattice && {
+                lattice: { ...structure.lattice, pbc: [true, true, true] },
+            }),
+        };
+    };
     // Fast path: content is already a serialized structure object
     try {
         const parsed = JSON.parse(content);
@@ -1271,10 +1262,7 @@ const unwrap_data = (value) => value && typeof value === `object` && `data` in v
 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;
+    const { type, id, attributes } = value;
     return (type === `structures` &&
         typeof id === `string` &&
         typeof attributes === `object` &&
@@ -1306,35 +1294,6 @@ export function optimade_to_crystal(optimade_structure) {
         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) => {
     // Normalize compressed suffixes (gz, gzip, zip, xz, bz2) for detection parity
     const name_to_check = strip_compression_extensions(filename);