matterviz 0.3.1 → 0.3.3

package/dist/structure/parse.js

@@ -2,9 +2,8 @@ import { COMPRESSION_EXTENSIONS_REGEX, CONFIG_DIRS_REGEX, STRUCT_KEYWORDS_REGEX,
 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';
-// Normalize scientific notation in coordinate strings (handles eEdD and *^ notation variants)
-const normalize_scientific_notation = (str) => str.toLowerCase().replace(/d/g, `e`).replace(/\*\^/g, `e`);
 // Parse a coordinate value that might be in various scientific notation formats
 function parse_coordinate(str) {
     const normalized = normalize_scientific_notation(str.trim());
@@ -44,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 {
@@ -98,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;
@@ -152,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++) {
@@ -176,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;
@@ -188,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);
                 }
@@ -263,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;
@@ -293,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) {
@@ -307,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;
@@ -329,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];
@@ -396,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];
@@ -445,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)}`;
@@ -456,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)
@@ -465,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,
@@ -549,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(` `)}`);
@@ -605,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;
@@ -645,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;
@@ -699,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
@@ -747,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))
@@ -785,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
@@ -808,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,
@@ -833,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 }),
@@ -869,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;
                 }
@@ -922,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
@@ -939,11 +908,10 @@ function find_structure_in_json(obj, visited = new WeakSet()) {
         return null;
     }
     // Check if this object looks like a valid structure
-    const potential_structure = obj;
-    if (is_parsed_structure(potential_structure))
-        return potential_structure;
+    if (is_parsed_structure(obj))
+        return obj;
     // Otherwise, recursively search through all properties
-    for (const value of Object.values(potential_structure)) {
+    for (const value of Object.values(obj)) {
         const result = find_structure_in_json(value, visited);
         if (result)
             return result;
@@ -954,17 +922,19 @@ function find_structure_in_json(obj, visited = new WeakSet()) {
 function is_parsed_structure(obj) {
     if (!obj || typeof obj !== `object`)
         return false;
-    const record = obj;
-    // Must have non-empty sites array
-    if (!Array.isArray(record.sites) || record.sites.length === 0)
+    const parsed_obj = obj;
+    const sites = parsed_obj.sites;
+    if (!Array.isArray(sites) || sites.length === 0)
         return false;
-    // Check if first site looks valid (has species and coordinates)
-    const first_site = record.sites[0];
+    const first_site = sites[0];
     if (!first_site || typeof first_site !== `object`)
         return false;
-    // Must have species (array) and either abc or xyz coordinates
-    const has_species = Array.isArray(first_site.species) && first_site.species.length > 0;
-    const has_coords = Array.isArray(first_site.abc) || Array.isArray(first_site.xyz);
+    const first_site_obj = first_site;
+    const species = first_site_obj.species;
+    const abc = first_site_obj.abc;
+    const xyz = first_site_obj.xyz;
+    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
@@ -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
@@ -1268,8 +1242,13 @@ function is_optimade_structure_object(value) {
     if (!value || typeof value !== `object`)
         return false;
     const obj = value;
-    return obj.type === `structures` && typeof obj.id === `string` &&
-        typeof obj.attributes === `object` && obj.attributes !== null;
+    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) {
@@ -1287,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 = {};
@@ -1348,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.d.ts

@@ -0,0 +1,25 @@
+import type { Site } from './';
+export declare const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 0.001;
+export type RenderSite = {
+    site_idx: number;
+    site: Site;
+    is_image_atom: boolean;
+    source_site_indices: number[];
+};
+export type SliceGeometry = {
+    element: string;
+    occupancy: number;
+    start_phi: number;
+    end_phi: number;
+    phi_length: number;
+    render_start_cap: boolean;
+    render_end_cap: boolean;
+};
+export type CapArcConfig = {
+    start_cap_arc_start: number;
+    end_cap_arc_start: number;
+    arc_length: number;
+};
+export declare const PARTIAL_OCCUPANCY_CAP_ARC: CapArcConfig;
+export declare const merge_split_partial_sites: (sites: Site[], hidden_elements?: ReadonlySet<string>) => RenderSite[];
+export declare const compute_slice_geometry: (visible_species: Site[`species`], slice_gap_rad?: number) => SliceGeometry[];