matterviz 0.3.2 → 0.3.4

package/dist/structure/parse.js

@@ -43,6 +43,19 @@ function validate_element_symbol(symbol, index) {
     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 {
@@ -97,9 +110,7 @@ export function parse_poscar(content) {
             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_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;
@@ -151,13 +162,18 @@ export function parse_poscar(content) {
             }
             // Determine coordinate mode
             const is_direct = coordinate_mode.startsWith(`D`);
-            const is_cartesian = coordinate_mode.startsWith(`C`) ||
-                coordinate_mode.startsWith(`K`);
+            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 = scaled_lattice.map((lattice_vec) => Math.hypot(...lattice_vec));
+            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++) {
@@ -175,11 +191,7 @@ export function parse_poscar(content) {
                     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`,
-                            ];
+                            selective_dynamics = [tokens[3] === `T`, tokens[4] === `T`, tokens[5] === `T`];
                         }
                     }
                     let xyz;
@@ -187,45 +199,24 @@ export function parse_poscar(content) {
                     const [x, y, z] = coords;
                     if (is_direct) {
                         // Store fractional coordinates, wrapping to [0, 1) range
-                        abc = [x - Math.floor(x), y - Math.floor(y), z - Math.floor(z)];
-                        // Convert fractional to Cartesian coordinates
-                        const lattice_transposed = math.transpose_3x3_matrix(scaled_lattice);
-                        xyz = math.mat3x3_vec3_multiply(lattice_transposed, abc);
+                        abc = wrap_to_unit_cell([x, y, z]);
+                        xyz = poscar_frac_to_cart(abc);
                     }
-                    else { // Already Cartesian, scale if needed
+                    else {
+                        // Already Cartesian, scale if needed
                         xyz = math.scale([x, y, z], scale_factor);
-                        // Calculate fractional coordinates using proper matrix inversion
-                        // Note: Our lattice matrix is stored as row vectors, but for coordinate conversion
-                        // we need column vectors, so we transpose before inversion
-                        let raw_abc;
-                        try {
-                            const lattice_transposed = math.transpose_3x3_matrix(scaled_lattice);
-                            const lattice_inv = math.matrix_inverse_3x3(lattice_transposed);
-                            raw_abc = math.mat3x3_vec3_multiply(lattice_inv, xyz);
-                        }
-                        catch {
-                            // Fallback to simplified method if matrix is singular
-                            raw_abc = [
-                                xyz[0] / scaled_lattice[0][0],
-                                xyz[1] / scaled_lattice[1][1],
-                                xyz[2] / scaled_lattice[2][2],
-                            ];
-                        }
+                        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 = [
-                            raw_abc[0] - Math.floor(raw_abc[0]),
-                            raw_abc[1] - Math.floor(raw_abc[1]),
-                            raw_abc[2] - Math.floor(raw_abc[2]),
-                        ];
+                        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 }
-                            : {},
+                        properties: selective_dynamics ? { selective_dynamics: selective_dynamics } : {},
                     };
                     sites.push(site);
                 }
@@ -262,9 +253,7 @@ export function parse_xyz(content) {
         let line_idx = 0;
         while (line_idx < all_lines.length) {
             const numAtoms = parseInt(all_lines[line_idx].trim(), 10);
-            if (!isNaN(numAtoms) &&
-                numAtoms > 0 &&
-                line_idx + numAtoms + 1 < all_lines.length) {
+            if (!isNaN(numAtoms) && numAtoms > 0 && line_idx + numAtoms + 1 < all_lines.length) {
                 const frameLines = all_lines.slice(line_idx, line_idx + numAtoms + 2);
                 frames.push(frameLines.join(`\n`));
                 line_idx += numAtoms + 2;
@@ -292,7 +281,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 = comment_line.match(/Lattice="([^"]+)"/);
+        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) {
@@ -306,6 +295,13 @@ export function parse_xyz(content) {
             }
         }
         // 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;
@@ -328,29 +324,14 @@ export function parse_xyz(content) {
             const xyz = [coords[0], coords[1], coords[2]];
             // Calculate fractional coordinates if lattice is available
             let abc = [0, 0, 0];
-            if (lattice) {
-                // Calculate fractional coordinates using proper matrix inversion
-                // Note: Our lattice matrix is stored as row vectors, but for coordinate conversion
-                // we need column vectors, so we transpose before inversion
-                try {
-                    const lattice_transposed = math.transpose_3x3_matrix(lattice.matrix);
-                    const lattice_inv = math.matrix_inverse_3x3(lattice_transposed);
-                    abc = math.mat3x3_vec3_multiply(lattice_inv, xyz);
-                }
-                catch {
-                    // Fallback to simplified method if matrix is singular
-                    abc = [xyz[0] / lattice.a, xyz[1] / lattice.b, xyz[2] / lattice.c];
-                }
+            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 = [
-                    abc[0] - Math.floor(abc[0]),
-                    abc[1] - Math.floor(abc[1]),
-                    abc[2] - Math.floor(abc[2]),
-                ];
+                abc = wrap_to_unit_cell(abc);
                 // Keep rendered atoms inside primary unit cell by recomputing xyz
-                // from the wrapped fractional coordinates using transpose(lattice)
-                const lattice_transposed = math.transpose_3x3_matrix(lattice.matrix);
-                const wrapped_xyz = math.mat3x3_vec3_multiply(lattice_transposed, abc);
+                const wrapped_xyz = xyz_frac_to_cart(abc);
                 xyz[0] = wrapped_xyz[0];
                 xyz[1] = wrapped_xyz[1];
                 xyz[2] = wrapped_xyz[2];
@@ -395,7 +376,7 @@ const parse_symmetry_expression = (expr_input) => {
         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 = token.match(/^([+-]?)([xyz])$/);
+        const var_match = /^([+-]?)([xyz])$/.exec(token);
         if (var_match) {
             const sign = var_match[1] === `-` ? -1 : 1;
             const var_char = var_match[2];
@@ -444,9 +425,7 @@ const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords) => {
         return [atom];
     const equivalent_atoms = [];
     const seen = new Set();
-    const wrap = (coords) => (wrap_fractional_coords
-        ? coords.map((val) => val - Math.floor(val))
-        : coords);
+    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
     const key = (coords) => `${coords[0].toFixed(6)},${coords[1].toFixed(6)},${coords[2].toFixed(6)}`;
@@ -455,7 +434,7 @@ const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords) => {
     seen.add(key(base_coords));
     equivalent_atoms.push({ ...atom, coords: base_coords });
     for (const operation of symmetry_ops) {
-        const operation_match = operation.match(/['"]([^'"]+)['"]/);
+        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)
@@ -464,17 +443,18 @@ const apply_symmetry_ops = (atom, symmetry_ops, wrap_fractional_coords) => {
         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_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 k = key(wrapped);
-        if (seen.has(k))
+        const cache_key = key(wrapped);
+        if (seen.has(cache_key))
             continue;
-        seen.add(k);
+        seen.add(cache_key);
         equivalent_atoms.push({
             ...atom,
             coords: wrapped,
@@ -548,7 +528,7 @@ const parse_cif_atom_data = (raw_data, indices, coords_type) => {
     const occu = occupancy >= 0 && raw_data[occupancy]
         ? parseFloat(raw_data[occupancy].split(`(`)[0]) || 1.0
         : 1.0;
-    const element_symbol = (symbol >= 0 && raw_data[symbol]?.match(/^([A-Z][a-z]*)/)?.[1]) ||
+    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(` `)}`);
@@ -604,9 +584,11 @@ 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 &&
+            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_x !== undefined &&
+                    indices_preview.cart_y !== undefined &&
                     indices_preview.cart_z !== undefined);
             if (!has_coords) {
                 ii = jj - 1;
@@ -644,10 +626,12 @@ 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 &&
+        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_x !== undefined &&
+                header_indices.cart_y !== undefined &&
                 header_indices.cart_z !== undefined
                 ? `cart`
                 : null;
@@ -698,21 +682,15 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
         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 lattice_transposed = math.transpose_3x3_matrix(lattice_matrix);
-        let lattice_inv_transposed = null;
-        try {
-            lattice_inv_transposed = math.matrix_inverse_3x3(lattice_transposed);
-        }
-        catch {
-            lattice_inv_transposed = null;
-        }
+        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 ? v.map((coord) => coord - Math.floor(coord)) : v;
+        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) => op.match(/['\"]([^'\"]+)['\"]/)?.[1] || op.trim())
+            .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
@@ -746,7 +724,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                         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 = toks[sym_idx]?.match(/^([A-Z][a-z]*)/);
+                            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))
@@ -784,13 +762,9 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
             }
             else {
                 const xyz_base = [atom.coords[0], atom.coords[1], atom.coords[2]];
-                let atom_abc;
-                if (lattice_inv_transposed) {
-                    const raw = math.mat3x3_vec3_multiply(lattice_inv_transposed, xyz_base);
-                    atom_abc = wrap_vec3(raw);
-                }
-                else
-                    atom_abc = wrap_vec3([xyz_base[0] / a, xyz_base[1] / b, xyz_base[2] / c]);
+                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
@@ -807,7 +781,7 @@ export function parse_cif(content, wrap_fractional_coords = true, strict = true)
                     if (seen_site_keys.has(key))
                         continue;
                     seen_site_keys.add(key);
-                    const xyz = math.mat3x3_vec3_multiply(lattice_transposed, abc);
+                    const xyz = frac_to_cart(abc);
                     all_sites.push({
                         species: [{ element, occu: equiv_atom.occupancy, oxidation_state: 0 }],
                         abc,
@@ -832,15 +806,11 @@ function convert_phonopy_cell(cell) {
     // Phonopy stores lattice vectors as rows, use them directly
     const lattice_matrix = cell.lattice;
     // 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 = [
-            point.coordinates[0],
-            point.coordinates[1],
-            point.coordinates[2],
-        ];
-        // Convert fractional to Cartesian coordinates
-        const xyz = math.mat3x3_vec3_multiply(math.transpose_3x3_matrix(lattice_matrix), abc);
+        const abc = [point.coordinates[0], point.coordinates[1], point.coordinates[2]];
+        const xyz = phonopy_frac_to_cart(abc);
         const properties = {
             mass: point.mass,
             ...(point.reduced_to !== undefined && { reduced_to: point.reduced_to }),
@@ -868,7 +838,7 @@ export function parse_phonopy_yaml(content, cell_type) {
             }
             // Check if we're still in the phonon_displacements section
             if (skip_displacements) {
-                if (line.match(/^[a-zA-Z_]/)) {
+                if (/^[a-zA-Z_]/.exec(line)) {
                     // New top-level key, stop skipping
                     skip_displacements = false;
                 }
@@ -921,7 +891,7 @@ export function parse_phonopy_yaml(content, cell_type) {
 // 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 || obj === undefined)
+    if (obj == null)
         return null;
     if (typeof obj !== `object`)
         return null; // If it's not an object, skip it
@@ -1073,8 +1043,7 @@ export function parse_structure_file(content, filename) {
                     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 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
@@ -1188,7 +1157,24 @@ export function parse_optimade_from_raw(raw) {
         const species = species_raw;
         // Optimade stores lattice vectors as rows, so use as is
         const lattice_matrix = attrs.lattice_vectors;
+        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];
@@ -1200,18 +1186,7 @@ export function parse_optimade_from_raw(raw) {
             const element = validate_element_symbol(element_symbol, idx);
             const xyz = [pos[0], pos[1], pos[2]];
             // Calculate fractional coordinates if lattice is available
-            let abc = [0, 0, 0];
-            if (lattice_matrix) {
-                try {
-                    const lattice_transposed = math.transpose_3x3_matrix(lattice_matrix);
-                    const lattice_inv = math.matrix_inverse_3x3(lattice_transposed);
-                    abc = math.mat3x3_vec3_multiply(lattice_inv, xyz);
-                }
-                catch {
-                    // Fallback if matrix inversion fails
-                    console.warn(`Failed to calculate fractional coordinates for OPTIMADE structure`);
-                }
-            }
+            const abc = optimade_cart_to_frac ? optimade_cart_to_frac(xyz) : [0, 0, 0];
             const site = {
                 species: [{ element, occu: 1, oxidation_state: 0 }],
                 abc,
@@ -1227,9 +1202,8 @@ export function parse_optimade_from_raw(raw) {
         }
         // Create structure object
         let lattice;
-        if (lattice_matrix) {
-            const lattice_params = math.calc_lattice_params(lattice_matrix);
-            lattice = { matrix: lattice_matrix, ...lattice_params };
+        if (lattice_matrix && optimade_lattice_params) {
+            lattice = { matrix: lattice_matrix, ...optimade_lattice_params };
         }
         const structure_result = {
             sites,
@@ -1260,7 +1234,7 @@ function extract_optimade_structure_from_raw(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)
+const unwrap_data = (value) => value && typeof value === `object` && `data` in value
     ? value.data
     : value;
 // Type guard: verify minimal OPTIMADE structure shape
@@ -1271,8 +1245,10 @@ function is_optimade_structure_object(value) {
     const type = obj.type;
     const id = obj.id;
     const attributes = obj.attributes;
-    return type === `structures` && typeof id === `string` &&
-        typeof attributes === `object` && attributes !== null;
+    return (type === `structures` &&
+        typeof id === `string` &&
+        typeof attributes === `object` &&
+        attributes !== null);
 }
 // Convert OPTIMADE structure to Crystal format
 export function optimade_to_crystal(optimade_structure) {
@@ -1290,21 +1266,15 @@ export function optimade_to_crystal(optimade_structure) {
         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 = [pos[0], pos[1], pos[2]];
-            let abc;
-            try {
-                const lattice_transposed = math.transpose_3x3_matrix(lattice_matrix);
-                const inv_matrix = math.matrix_inverse_3x3(lattice_transposed);
-                abc = math.mat3x3_vec3_multiply(inv_matrix, xyz);
-            }
-            catch {
-                abc = [0, 0, 0];
-            }
+            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 = {};
@@ -1351,8 +1321,10 @@ export function is_structure_file(filename) {
     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))
+    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)) {

package/dist/structure/partial-occupancy.js

@@ -10,9 +10,7 @@ const make_render_site = (sites, site_idx, source_site_indices, site_override) =
     is_image_atom: source_site_indices.some((source_site_idx) => is_image_atom(sites[source_site_idx])),
     source_site_indices,
 });
-const sq_dist = (xyz_1, xyz_2) => (xyz_1[0] - xyz_2[0]) ** 2 +
-    (xyz_1[1] - xyz_2[1]) ** 2 +
-    (xyz_1[2] - xyz_2[2]) ** 2;
+const sq_dist = (xyz_1, xyz_2) => (xyz_1[0] - xyz_2[0]) ** 2 + (xyz_1[1] - xyz_2[1]) ** 2 + (xyz_1[2] - xyz_2[2]) ** 2;
 const is_split_partial_site = (site, hidden_elements) => {
     const visible_species = site.species.filter(({ element }) => !hidden_elements.has(element));
     const total_visible_occupancy = visible_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
@@ -48,7 +46,10 @@ const build_render_sites = (sites, non_grouped_site_indices, grouped_site_indice
         const representative_site_idx = grouped_indices[0];
         const representative_site = sites[representative_site_idx];
         const merged_species = grouped_indices.flatMap((grouped_site_idx) => sites[grouped_site_idx].species);
-        render_sites.push(make_render_site(sites, representative_site_idx, [...grouped_indices], { ...representative_site, species: merged_species }));
+        render_sites.push(make_render_site(sites, representative_site_idx, [...grouped_indices], {
+            ...representative_site,
+            species: merged_species,
+        }));
     }
     return render_sites;
 };
@@ -66,9 +67,7 @@ export const compute_slice_geometry = (visible_species, slice_gap_rad = PARTIAL_
         return [];
     const total_visible_occupancy = visible_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
     // Preserve total angular coverage at one full turn for invalid overfull inputs.
-    const occupancy_scale_factor = total_visible_occupancy > 1 + OCCUPANCY_EPS
-        ? 1 / total_visible_occupancy
-        : 1;
+    const occupancy_scale_factor = total_visible_occupancy > 1 + OCCUPANCY_EPS ? 1 / total_visible_occupancy : 1;
     const normalized_species = visible_species.map(({ element, occu }) => ({
         element,
         occu: occu * occupancy_scale_factor,
@@ -83,9 +82,7 @@ export const compute_slice_geometry = (visible_species, slice_gap_rad = PARTIAL_
         // Keep neighboring wedges from sharing the exact same plane (z-fighting).
         const phi_span_raw = Math.max(0, end_phi_raw - start_phi_raw);
         const max_safe_gap = Math.max(0, phi_span_raw - MIN_PHI_LENGTH);
-        const desired_gap = visible_species.length > 1
-            ? Math.min(slice_gap_rad, phi_span_raw * 0.25)
-            : 0;
+        const desired_gap = visible_species.length > 1 ? Math.min(slice_gap_rad, phi_span_raw * 0.25) : 0;
         const phi_gap = Math.min(desired_gap, max_safe_gap);
         const start_phi = start_phi_raw + phi_gap / 2;
         const end_phi = end_phi_raw - phi_gap / 2;

package/dist/structure/pbc.d.ts

@@ -1,6 +1,7 @@
 import type { Vec3 } from '../math';
 import type { ParsedStructure } from './parse';
 export type Pbc = readonly [boolean, boolean, boolean];
+export declare const wrap_frac_coord: (coord: number) => number;
 export declare const wrap_to_unit_cell: (frac: Vec3) => Vec3;
 export declare function find_image_atoms(structure: ParsedStructure, { tolerance }?: {
     tolerance?: number;

package/dist/structure/pbc.js

@@ -1,9 +1,18 @@
 import * as math from '../math';
+// Wrap a single fractional coordinate to [0, 1), clamping near-1 values to 0
+// and rounding to 15 digits to suppress floating-point noise.
+export const wrap_frac_coord = (coord) => {
+    const wrapped = coord - Math.floor(coord);
+    if (wrapped >= 1 - 1e-10)
+        return 0;
+    return Number(wrapped.toFixed(15));
+};
 // Wrap fractional coordinates to [0, 1) range for periodicity.
-export const wrap_to_unit_cell = (frac) => frac.map((coord) => {
-    const wrapped = ((coord % 1) + 1) % 1;
-    return wrapped >= 1 - 1e-10 ? 0 : wrapped; // clamp near-1 to 0 for float precision
-});
+export const wrap_to_unit_cell = (frac) => [
+    wrap_frac_coord(frac[0]),
+    wrap_frac_coord(frac[1]),
+    wrap_frac_coord(frac[2]),
+];
 export function find_image_atoms(structure, { tolerance } = {}) {
     // Find image atoms for PBC. Returns [atom_idx, image_xyz, image_abc] tuples.
     // Skips image generation for trajectory data with scattered atoms.
@@ -47,7 +56,7 @@ export function find_image_atoms(structure, { tolerance } = {}) {
                 edge_dims.push({ dim, direction: -1 });
         }
         // Generate all translation combinations
-        for (let mask = 1; mask < (1 << edge_dims.length); mask++) {
+        for (let mask = 1; mask < 1 << edge_dims.length; mask++) {
             // Track selected translation per dimension. If both +1 and -1 are selected for a dim,
             // the net shift is zero and we skip because it yields no image.
             const selected_shift = [0, 0, 0];
@@ -69,7 +78,8 @@ export function find_image_atoms(structure, { tolerance } = {}) {
                 site.abc[2] + selected_shift[2],
             ];
             // If no dimension actually shifted, continue
-            if (img_abc[0] === site.abc[0] && img_abc[1] === site.abc[1] &&
+            if (img_abc[0] === site.abc[0] &&
+                img_abc[1] === site.abc[1] &&
                 img_abc[2] === site.abc[2])
                 continue;
             // Compute xyz from img_abc to ensure consistency

package/dist/structure/supercell.d.ts

@@ -1,8 +1,8 @@
 import type { Vec3 } from '../math';
-import * as math from '../math';
+import { scale_lattice_matrix } from '../math';
 import type { Crystal } from './index';
 export declare function parse_supercell_scaling(scaling: string | number | Vec3): Vec3;
 export declare function generate_lattice_points(scaling_factors: Vec3): Vec3[];
-export declare function scale_lattice_matrix(orig_matrix: math.Matrix3x3, scaling_factors: Vec3): math.Matrix3x3;
+export { scale_lattice_matrix };
 export declare function make_supercell(structure: Crystal, scaling: string | number | Vec3, to_unit_cell?: boolean): Crystal;
 export declare function is_valid_supercell_input(input: string): boolean;