matterviz 0.3.1 → 0.3.3

package/dist/structure/partial-occupancy.js

@@ -0,0 +1,99 @@
+export const PARTIAL_OCCUPANCY_SLICE_GAP_RAD = 1e-3;
+const OCCUPANCY_EPS = 1e-6;
+const MIN_PHI_LENGTH = 1e-4;
+const MERGE_DISTANCE_TOLERANCE = 1e-8;
+const CAP_ARC_START = Math.PI / 2;
+const is_image_atom = (site) => typeof site.properties?.orig_site_idx === `number`;
+const make_render_site = (sites, site_idx, source_site_indices, site_override) => ({
+    site_idx,
+    site: site_override ?? sites[site_idx],
+    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 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);
+    return visible_species.length === 1 && total_visible_occupancy < 1 - OCCUPANCY_EPS;
+};
+const group_split_partial_indices = (sites, hidden_elements) => {
+    const grouped_centers = [];
+    const grouped_site_indices = [];
+    const non_grouped_site_indices = [];
+    for (const [site_idx, site] of sites.entries()) {
+        if (!is_split_partial_site(site, hidden_elements)) {
+            non_grouped_site_indices.push(site_idx);
+            continue;
+        }
+        const matched_group_idx = grouped_centers.findIndex((center_xyz) => sq_dist(center_xyz, site.xyz) <= MERGE_DISTANCE_TOLERANCE ** 2);
+        if (matched_group_idx === -1) {
+            grouped_centers.push(site.xyz);
+            grouped_site_indices.push([site_idx]);
+            continue;
+        }
+        grouped_site_indices[matched_group_idx].push(site_idx);
+    }
+    return { non_grouped_site_indices, grouped_site_indices };
+};
+const build_render_sites = (sites, non_grouped_site_indices, grouped_site_indices) => {
+    const render_sites = non_grouped_site_indices.map((site_idx) => make_render_site(sites, site_idx, [site_idx]));
+    for (const grouped_indices of grouped_site_indices) {
+        if (grouped_indices.length === 1) {
+            const site_idx = grouped_indices[0];
+            render_sites.push(make_render_site(sites, site_idx, [site_idx]));
+            continue;
+        }
+        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,
+        }));
+    }
+    return render_sites;
+};
+export const PARTIAL_OCCUPANCY_CAP_ARC = {
+    start_cap_arc_start: CAP_ARC_START,
+    end_cap_arc_start: CAP_ARC_START,
+    arc_length: Math.PI,
+};
+export const merge_split_partial_sites = (sites, hidden_elements = new Set()) => {
+    const grouped_indices = group_split_partial_indices(sites, hidden_elements);
+    return build_render_sites(sites, grouped_indices.non_grouped_site_indices, grouped_indices.grouped_site_indices);
+};
+export const compute_slice_geometry = (visible_species, slice_gap_rad = PARTIAL_OCCUPANCY_SLICE_GAP_RAD) => {
+    if (visible_species.length === 0)
+        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 normalized_species = visible_species.map(({ element, occu }) => ({
+        element,
+        occu: occu * occupancy_scale_factor,
+    }));
+    const normalized_total_occupancy = normalized_species.reduce((occupancy_sum, { occu }) => occupancy_sum + occu, 0);
+    const has_vacancy_gap = normalized_total_occupancy < 1 - OCCUPANCY_EPS;
+    const last_visible_species_idx = normalized_species.length - 1;
+    let start_angle = 0;
+    return normalized_species.map(({ element, occu }, species_idx) => {
+        const start_phi_raw = 2 * Math.PI * start_angle;
+        const end_phi_raw = 2 * Math.PI * (start_angle += occu);
+        // 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 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;
+        return {
+            element,
+            occupancy: occu,
+            start_phi,
+            end_phi,
+            phi_length: Math.max(MIN_PHI_LENGTH, end_phi - start_phi),
+            render_start_cap: has_vacancy_gap && species_idx === 0,
+            render_end_cap: has_vacancy_gap && species_idx === last_visible_species_idx,
+        };
+    });
+};

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;

package/dist/structure/supercell.js

@@ -1,9 +1,6 @@
 import * as math from '../math';
-// Wrap fractional coordinates to [0, 1) range, clamping near-1 values to 0
-const wrap_frac = (coord) => {
-    const wrapped = ((coord % 1) + 1) % 1;
-    return wrapped >= 1 - 1e-10 ? 0 : wrapped;
-};
+import { scale_lattice_matrix } from '../math';
+import { wrap_frac_coord } from './pbc';
 // Parse supercell scaling input from various formats. Can be "2x2x2", "2", [2,2,2], or a single number.
 // Returns [x, y, z] scaling factors.
 export function parse_supercell_scaling(scaling) {
@@ -21,7 +18,11 @@ export function parse_supercell_scaling(scaling) {
     }
     if (typeof scaling === `string`) {
         // Parse "2x2x2" format
-        const parts = scaling.trim().toLowerCase().split(/[x×,\s]+/).filter((part) => part.length > 0);
+        const parts = scaling
+            .trim()
+            .toLowerCase()
+            .split(/[x×,\s]+/)
+            .filter((part) => part.length > 0);
         if (parts.length === 1 || parts.length === 3) {
             // Check that all parts are strictly digits to avoid scientific notation/hex/etc per tests
             if (parts.every((part) => /^\d+$/.test(part))) {
@@ -51,19 +52,8 @@ export function generate_lattice_points(scaling_factors) {
     }
     return points;
 }
-// Scale a lattice matrix by supercell factors
-// Takes original 3x3 lattice matrix and [scale_x, scale_y, scale_z] scaling factors
-// Returns new scaled lattice matrix
-export function scale_lattice_matrix(orig_matrix, scaling_factors) {
-    const [nx, ny, nz] = scaling_factors;
-    const [a, b, c] = orig_matrix;
-    // Scale each lattice vector by its corresponding factor
-    return [
-        [a[0] * nx, a[1] * nx, a[2] * nx],
-        [b[0] * ny, b[1] * ny, b[2] * ny],
-        [c[0] * nz, c[1] * nz, c[2] * nz],
-    ];
-}
+// Re-export from $lib/math for backward compatibility
+export { scale_lattice_matrix };
 // Create a supercell from a Crystal
 // Takes original structure, scaling factors, and whether to fold coordinates back to unit cell (default: true)
 // Returns new supercell structure
@@ -111,9 +101,9 @@ export function make_supercell(structure, scaling, to_unit_cell = true) {
                     let new_b = (site.abc[1] + jj) / sy;
                     let new_c = (site.abc[2] + kk) / sz;
                     if (to_unit_cell) {
-                        new_a = wrap_frac(new_a);
-                        new_b = wrap_frac(new_b);
-                        new_c = wrap_frac(new_c);
+                        new_a = wrap_frac_coord(new_a);
+                        new_b = wrap_frac_coord(new_b);
+                        new_c = wrap_frac_coord(new_c);
                     }
                     new_sites[write_idx++] = {
                         species: site.species,

package/dist/structure/validation.js

@@ -1,8 +1,10 @@
 export function is_crystal(obj) {
     if (obj === null || typeof obj !== `object`)
         return false;
-    const input = obj;
-    const has_sites = Array.isArray(input.sites) && input.sites.length > 0;
-    const has_lattice = Boolean(input.lattice) && typeof input.lattice === `object`;
+    const structure_obj = obj;
+    const sites = structure_obj.sites;
+    const lattice = structure_obj.lattice;
+    const has_sites = Array.isArray(sites) && sites.length > 0;
+    const has_lattice = lattice !== undefined && lattice !== null && typeof lattice === `object`;
     return has_sites && has_lattice;
 }

package/dist/symmetry/SymmetryStats.svelte

@@ -1,41 +1,92 @@
-<script lang="ts">import { tooltip } from 'svelte-multiselect';
-import { SETTINGS_CONFIG } from '../settings';
-import { default_sym_settings, wyckoff_positions_from_moyo } from './index';
-import * as spg from './spacegroups';
-let { sym_data, settings = $bindable(default_sym_settings), show_tooltips = true, children, label = `Symmetry`, header, ...rest } = $props();
-const wyckoff_count = $derived(sym_data ? wyckoff_positions_from_moyo(sym_data).length : 0);
-const sym_ops_counts = $derived.by(() => {
-    const EPS = 1e-10;
+<script lang="ts">
+  import type { MoyoDataset } from '@spglib/moyo-wasm'
+  import type { Snippet } from 'svelte'
+  import { tooltip } from 'svelte-multiselect'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { SETTINGS_CONFIG } from '../settings'
+  import type { SymmetrySettings } from './index'
+  import { default_sym_settings, wyckoff_positions_from_moyo } from './index'
+  import * as spg from './spacegroups'
+
+  type SymmetrySnippet = Snippet<
+    [{ sym_data?: MoyoDataset | null; settings: SymmetrySettings }]
+  >
+
+  let {
+    sym_data,
+    settings = $bindable(default_sym_settings),
+    show_tooltips = true,
+    children,
+    label = `Symmetry`,
+    header,
+    ...rest
+  }: HTMLAttributes<HTMLDivElement> & {
+    sym_data?: MoyoDataset | null
+    settings?: SymmetrySettings
+    show_tooltips?: boolean
+    children?: SymmetrySnippet
+    label?: SymmetrySnippet | string
+    header?: SymmetrySnippet
+  } = $props()
+
+  const wyckoff_count = $derived(
+    sym_data ? wyckoff_positions_from_moyo(sym_data).length : 0,
+  )
+  const display_hm_symbol = $derived(sym_data?.hm_symbol?.replace(/\s+/g, ``) ?? `?`)
+
+  const sym_ops_counts = $derived.by(() => {
+    const EPS = 1e-10
     if (!sym_data?.operations) {
-        return { translations: 0, rotations: 0, roto_translations: 0 };
+      return { translations: 0, rotations: 0, roto_translations: 0 }
     }
-    return sym_data.operations.reduce((acc, op) => {
-        const has_translation = op.translation.some((coord) => Math.abs(coord) > EPS);
-        const is_identity = String(op.rotation) === `1,0,0,0,1,0,0,0,1`;
-        if (is_identity && has_translation)
-            acc.translations++;
-        else if (!has_translation)
-            acc.rotations++;
-        else
-            acc.roto_translations++;
-        return acc;
-    }, { translations: 0, rotations: 0, roto_translations: 0 });
-});
-const titles = {
-    symprec: `Symmetry precision control in spglib/moyo. Lower values (e.g. 1e-4, the default) are more strict, higher values (e.g. 1e-1) are more tolerant of numerical errors in atomic positions.`,
-    algo: `Symmetry detection algorithm: Moyo uses moyo's newer recommended settings, Spglib is useful if you need compatible results to an existing set of spglib-detected symmetries.`,
-    space_group: `International Tables Space group number (1-230) - unique identifier for each space group. Higher numbers indicate more symmetries in the crystal.`,
-    crystal_system: `Crystal system classification based on the unit cell symmetry. Seven systems: triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, and cubic.`,
-    hermann_mauguin: `Hermann-Mauguin symbol describes symmetry operations. Format: Lattice type + Point group symmetry. Example: P4/mmm = Primitive + 4-fold rotation + mirror planes`,
-    hall_number: `Hall number: alternative numbering system for space groups. Useful for crystallographic software compatibility.`,
-    pearson_symbol: `Pearson symbol. Format: Crystal system + Number of atoms per unit cell. Example: tP2 = tetragonal primitive with 2 atoms`,
-    symmetry_operations: `Total symmetry operations that map the crystal structure onto itself. Includes rotations, translations, and combinations.`,
-    distinct_orbits: `Number of unique Wyckoff positions (symmetry-equivalent atomic sites) in the crystal structure.`,
+
+    return sym_data.operations.reduce(
+      (acc, op) => {
+        const has_translation = op.translation.some((coord) => Math.abs(coord) > EPS)
+        const is_identity = String(op.rotation) === `1,0,0,0,1,0,0,0,1`
+
+        if (is_identity && has_translation) acc.translations++
+        else if (!has_translation) acc.rotations++
+        else acc.roto_translations++
+
+        return acc
+      },
+      { translations: 0, rotations: 0, roto_translations: 0 },
+    )
+  })
+
+  const titles = {
+    symprec:
+      `Symmetry precision control in spglib/moyo. Lower values (e.g. 1e-4, the default) are more strict, higher values (e.g. 1e-1) are more tolerant of numerical errors in atomic positions.`,
+    algo:
+      `Symmetry detection algorithm: Moyo uses moyo's newer recommended settings, Spglib is useful if you need compatible results to an existing set of spglib-detected symmetries.`,
+    space_group:
+      `International Tables Space group number (1-230) - unique identifier for each space group. Higher numbers indicate more symmetries in the crystal.`,
+    crystal_system:
+      `Crystal system classification based on the unit cell symmetry. Seven systems: triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, and cubic.`,
+    hermann_mauguin:
+      `Hermann-Mauguin symbol describes symmetry operations. Format: Lattice type + Point group symmetry. Example: P4/mmm = Primitive + 4-fold rotation + mirror planes`,
+    hall_number:
+      `Hall number: alternative numbering system for space groups. Useful for crystallographic software compatibility.`,
+    pearson_symbol:
+      `Pearson symbol. Format: Crystal system + Number of atoms per unit cell. Example: tP2 = tetragonal primitive with 2 atoms`,
+    symmetry_operations:
+      `Total symmetry operations that map the crystal structure onto itself. Includes rotations, translations, and combinations.`,
+    distinct_orbits:
+      `Number of unique Wyckoff positions (symmetry-equivalent atomic sites) in the crystal structure.`,
     translations: `Number of translations in the crystal structure.`,
     rotations: `Number of rotations in the crystal structure.`,
     roto_translations: `Number of roto-translations in the crystal structure.`,
-};
-const tooltips = $derived(show_tooltips ? titles : {});
+  }
+  const tooltips: Record<string, string> = $derived(show_tooltips ? titles : {})
+
+  function get_step_from_order_of_magnitude(value: number): number {
+    if (!Number.isFinite(value) || value <= 0) return 1e-5
+    const exponent = Math.floor(Math.log10(value))
+    return Math.pow(10, exponent)
+  }
+
+  const symprec_step = $derived(get_step_from_order_of_magnitude(settings.symprec))
 </script>
 
 <div {...rest} class="symmetry-stats {rest.class ?? ``}">
@@ -55,15 +106,21 @@ const tooltips = $derived(show_tooltips ? titles : {});
       <span {@attach tooltip()} title={tooltips?.symprec}>Precision</span>
       <input
         type="number"
-        step="1e-5"
+        step={symprec_step}
         value={settings.symprec}
-        onchange={(evt) => {
+        oninput={(evt) => {
           const { value } = evt.currentTarget
-          const parsed = parseFloat(value)
+          if (value === ``) return
+          const parsed = Number(value)
           if (Number.isFinite(parsed)) {
             settings = { ...settings, symprec: parsed }
           }
         }}
+        onkeydown={(evt) => {
+          if (evt.key === `Escape`) {
+            evt.currentTarget.blur()
+          }
+        }}
       />
     </label>
     <label>
@@ -91,7 +148,7 @@ const tooltips = $derived(show_tooltips ? titles : {});
         title="{tooltips?.space_group} at {settings.symprec} (using {settings.algo} algo). {tooltips?.hermann_mauguin}"
         {@attach tooltip()}
       >
-        Space Group <strong>{sym_data.number} ({sym_data.hm_symbol ?? `?`})</strong>
+        Space Group <strong>{sym_data.number} ({display_hm_symbol})</strong>
       </div>
       <div title={tooltips?.crystal_system} {@attach tooltip()}>
         Crystal System <strong>{spg.spacegroup_to_crystal_sys(sym_data.number)}</strong>

package/dist/symmetry/WyckoffTable.svelte

@@ -1,8 +1,29 @@
-<script lang="ts">import { contrast_color } from '../colors';
-import { format_fractional } from '../labels';
-import { colors } from '../state.svelte';
-let { wyckoff_positions, on_hover, on_click, active_color = `#2563eb`, ...rest } = $props();
-let selected_wyckoff = $state(null);
+<script lang="ts">
+  import { contrast_color } from '../colors'
+  import { format_fractional } from '../labels'
+  import { colors } from '../state.svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import type { WyckoffPos } from '.'
+
+  let {
+    wyckoff_positions,
+    on_hover,
+    on_click,
+    active_color = `#2563eb`,
+    ...rest
+  }: HTMLAttributes<HTMLTableElement> & {
+    wyckoff_positions: WyckoffPos[]
+    on_hover?: (site_indices: number[] | null) => void
+    on_click?: (site_indices: number[] | null) => void
+    active_color?: string
+  } = $props()
+
+  let selected_key = $state<string | null>(null)
+
+  const get_row_key = (wyckoff_pos: WyckoffPos, row_idx: number) =>
+    `${wyckoff_pos.wyckoff}-${wyckoff_pos.elem}-${
+      wyckoff_pos.site_indices?.join(`,`) ?? `none`
+    }-${row_idx}`
 </script>
 
 {#if wyckoff_positions && wyckoff_positions.length > 0}
@@ -22,10 +43,14 @@ let selected_wyckoff = $state(null);
       </tr>
     </thead>
     <tbody>
-      {#each wyckoff_positions as wyckoff_pos (JSON.stringify(wyckoff_pos))}
+      {#each wyckoff_positions as
+        wyckoff_pos,
+        row_idx
+        (get_row_key(wyckoff_pos, row_idx))
+      }
         {@const { wyckoff, elem, abc, site_indices } = wyckoff_pos}
-        {@const is_selected =
-        JSON.stringify(selected_wyckoff) === JSON.stringify(wyckoff_pos)}
+        {@const row_key = get_row_key(wyckoff_pos, row_idx)}
+        {@const is_selected = selected_key === row_key}
         <tr
           class="wyckoff-row"
           tabindex="0"
@@ -35,16 +60,14 @@ let selected_wyckoff = $state(null);
           onmouseenter={() => on_hover?.(site_indices ?? null)}
           onmouseleave={() => on_hover?.(null)}
           onclick={() => {
-            selected_wyckoff = is_selected ? null : wyckoff_pos
-            on_click?.(selected_wyckoff?.site_indices ?? null)
+            selected_key = is_selected ? null : row_key
+            on_click?.(is_selected ? null : (wyckoff_pos.site_indices ?? null))
           }}
           onkeydown={(event) => {
             if ([`Enter`, ` `].includes(event.key)) {
               event.preventDefault()
-              const is_selected =
-                JSON.stringify(selected_wyckoff) === JSON.stringify(wyckoff_pos)
-              selected_wyckoff = is_selected ? null : wyckoff_pos
-              on_click?.(selected_wyckoff?.site_indices ?? null)
+              selected_key = is_selected ? null : row_key
+              on_click?.(is_selected ? null : (wyckoff_pos.site_indices ?? null))
             }
           }}
         >
@@ -69,6 +92,11 @@ let selected_wyckoff = $state(null);
   .wyckoff-table {
     margin-top: 1em;
   }
+  .wyckoff-table :is(th, td) {
+    padding: 2px 6px;
+    text-align: center;
+    vertical-align: middle;
+  }
   .wyckoff-row {
     cursor: pointer;
     transition: background-color 0.2s ease;

package/dist/symmetry/cell-transform.js

@@ -19,7 +19,7 @@ original_structure) {
     ];
     // Calculate lattice parameters from matrix
     const lattice_params = math.calc_lattice_params(lattice_matrix);
-    const lattice_T = math.transpose_3x3_matrix(lattice_matrix);
+    const frac_to_cart = math.create_frac_to_cart(lattice_matrix);
     // Build sites from positions and atomic numbers
     const sites = cell.positions.map((abc, idx) => {
         const atomic_number = cell.numbers[idx];
@@ -29,8 +29,7 @@ original_structure) {
         }
         // Wrap fractional coordinates to [0, 1) range (moyo-wasm may return outside)
         const wrapped_abc = wrap_to_unit_cell(abc);
-        // Convert fractional to Cartesian: xyz = lattice_T · abc
-        const xyz = math.mat3x3_vec3_multiply(lattice_T, wrapped_abc);
+        const xyz = frac_to_cart(wrapped_abc);
         // Oxidation state is set to 0 (unknown) because moyo-wasm only provides atomic numbers.
         // transformed cell may have different/reordered sites, making it non-trivial to
         // map oxidation states from original structure.
@@ -48,12 +47,14 @@ original_structure) {
 // The conventional cell is the standard crystallographic setting for the space group.
 export function get_conventional_cell(original_structure, // The original input structure
 sym_data) {
+    // The conventional cell as a Crystal
     return moyo_cell_to_structure(sym_data.std_cell, original_structure);
 }
 // Get the primitive cell from symmetry analysis data.
 // The primitive cell is the smallest unit cell with one lattice point.
 export function get_primitive_cell(original_structure, // The original input structure
 sym_data) {
+    // The primitive cell as a Crystal
     return moyo_cell_to_structure(sym_data.prim_std_cell, original_structure);
 }
 // Transform a structure based on the selected cell type.
@@ -61,6 +62,7 @@ sym_data) {
 export function transform_cell(structure, // The original structure
 cell_type, // The desired cell type ('original', 'conventional', or 'primitive')
 sym_data) {
+    //transformed structure (or original if no transformation needed)
     if (cell_type === `original` || !sym_data) {
         return structure;
     }

package/dist/symmetry/index.d.ts

@@ -29,12 +29,15 @@ export type WyckoffPos = {
     abc: Vec3;
     site_indices?: number[];
 };
+export type SymmetryDataset = MoyoDataset & {
+    orig_indices?: number[];
+    orig_site_indices_by_std_idx?: number[][];
+};
 export declare function ensure_moyo_wasm_ready(wasm_url?: string): Promise<void>;
 export declare function to_cell_json(structure: Crystal): string;
-export declare function analyze_structure_symmetry(struct_or_mol: AnyStructure, settings: Partial<SymmetrySettings>): Promise<MoyoDataset>;
+export declare function map_std_to_orig_site_indices(std_positions: Vec3[], std_numbers: number[], input_positions: Vec3[], input_numbers: number[], orig_site_indices_by_input_idx: number[][]): number[][];
+export declare function analyze_structure_symmetry(struct_or_mol: AnyStructure, settings: Partial<SymmetrySettings>): Promise<SymmetryDataset>;
 export declare function simplicity_score(vec: number[]): number;
-export declare function wyckoff_positions_from_moyo(sym_data: (MoyoDataset & {
-    orig_indices?: number[];
-}) | null): WyckoffPos[];
+export declare function wyckoff_positions_from_moyo(sym_data: SymmetryDataset | null): WyckoffPos[];
 export declare function apply_symmetry_operations(position: Vec3, operations: MoyoDataset[`operations`], _tolerance?: number): Vec3[];
 export declare function map_wyckoff_to_all_atoms(wyckoff_positions: WyckoffPos[], displayed_structure: Crystal, orig_structure: Crystal, sym_data: MoyoDataset | null, tolerance?: number): WyckoffPos[];