matterviz 0.3.7 → 0.4.1

package/dist/symmetry/index.js

@@ -1,10 +1,17 @@
 import { ATOMIC_NUMBER_TO_SYMBOL, SYMBOL_TO_ATOMIC_NUMBER } from '../composition/parse';
+import * as math from '../math';
 import { DEFAULTS } from '../settings';
 import { merge_split_partial_sites } from '../structure/partial-occupancy';
 import init, { analyze_cell } from '@spglib/moyo-wasm';
 import moyo_wasm_url from '@spglib/moyo-wasm/moyo_wasm_bg.wasm?url';
+import { mat3_from_flat_col_major } from './symmetry-elements';
+import { wyckoff_letter } from './wyckoff-db';
 export * from './cell-transform';
 export * from './spacegroups';
+export * from './symmetry-elements';
+export * from './wyckoff-db';
+export { default as SymmetryElementControls } from './SymmetryElementControls.svelte';
+export { default as SymmetryElements } from './SymmetryElements.svelte';
 export { default as SymmetryStats } from './SymmetryStats.svelte';
 export { default as WyckoffTable } from './WyckoffTable.svelte';
 // Keys are standard crystallographic symbols (P, I, F, A, B, C, R)
@@ -27,13 +34,37 @@ const to_unit = (value) => value - Math.floor(value);
 const near_zero = (value) => Math.min(value, 1 - value);
 const near_half = (value) => Math.abs(value - 0.5);
 const symmetry_position_key = (pos) => pos.map((coord) => to_unit(coord).toFixed(8)).join(`,`);
-const periodic_distance = (pos1, pos2) => Math.sqrt(pos1.reduce((sum, coord, idx) => {
-    // Wrap delta into [-0.5, 0.5) using safe modulo
-    const delta = coord - pos2[idx];
-    const wrapped = ((((delta + 0.5) % 1) + 1) % 1) - 0.5;
-    const distance = Math.abs(wrapped);
-    return sum + distance * distance;
-}, 0));
+const is_near_integer_vec = (vec, tol) => vec.every((coord) => Math.abs(coord - Math.round(coord)) < tol);
+// Wrap fractional coordinates into [0, 1), snapping values within 1e-9 of 1 back to 0.
+// NOTE on epsilon: 1e-9 is deliberately looser than wrap_frac_coord @1e-10
+// [[src/lib/structure/pbc.ts:26]] because inputs here passed through moyo
+// standardization plus a P⁻¹(x − p) matrix transform (make_frac_coord_mapper),
+// accumulating more float error than freshly parsed coords. It is tighter than
+// wrap_point @1e-8 [[src/lib/symmetry/symmetry-elements.ts:214]], which must
+// keep dedup keys stable for fixed points solved from linear systems. Do not
+// unify: each epsilon matches the noise level of its inputs.
+const wrap_frac = (pos) => pos.map((coord) => {
+    const wrapped = coord - Math.floor(coord);
+    return wrapped > 1 - 1e-9 ? 0 : wrapped;
+});
+// Build a mapper from input-cell to standardized-cell fractional coordinates.
+// moyo's (std_linear P, std_origin_shift p) follow the ITA convention for the
+// transformation from the input cell to the standardized cell: x_std = P⁻¹ (x_input − p).
+// Returns null if std_linear is absent or singular.
+function make_frac_coord_mapper(linear_flat, origin_shift) {
+    if (linear_flat?.length !== 9)
+        return null;
+    try {
+        const linear = mat3_from_flat_col_major(linear_flat);
+        const linear_inv = math.matrix_inverse_3x3(linear);
+        const shift = (origin_shift ?? [0, 0, 0]);
+        const to_std = (pos) => math.mat3x3_vec3_multiply(linear_inv, math.subtract(pos, shift));
+        return { to_std, linear, linear_inv, shift };
+    }
+    catch {
+        return null;
+    }
+}
 export async function ensure_moyo_wasm_ready(wasm_url) {
     if (initialized)
         return;
@@ -93,15 +124,32 @@ export function to_cell_json(structure) {
 const fractional_sq_dist = (pos_1, pos_2) => (pos_1[0] - pos_2[0] - Math.round(pos_1[0] - pos_2[0])) ** 2 +
     (pos_1[1] - pos_2[1] - Math.round(pos_1[1] - pos_2[1])) ** 2 +
     (pos_1[2] - pos_2[2] - Math.round(pos_1[2] - pos_2[2])) ** 2;
-export function map_std_to_orig_site_indices(std_positions, std_numbers, input_positions, input_numbers, orig_site_indices_by_input_idx) {
+// Map each standardized-cell site to the input-cell site it descends from, then to
+// original structure indices. When moyo's (std_linear, std_origin_shift) transform is
+// provided, std positions are first mapped into the input frame via x_in = P·x_std + p
+// (the std and input cells use DIFFERENT bases in general, so comparing raw fractional
+// coordinates across them is meaningless). Matches account for crystal translations of
+// both lattices: a difference d is a translation if d ∈ ℤ³ (input lattice) or P⁻¹d ∈ ℤ³
+// (standardized lattice expressed in the input frame).
+export const map_std_to_orig_site_indices = (std_positions, std_numbers, input_positions, input_numbers, orig_site_indices_by_input_idx, transform, tol = 1e-4) => {
+    const mapper = make_frac_coord_mapper(transform?.std_linear, transform?.std_origin_shift);
     return std_positions.map((std_pos, std_idx) => {
+        // Predicted input-frame position of this std site: x_in = P·x_std + p
+        const pred = mapper
+            ? math.add(math.mat3x3_vec3_multiply(mapper.linear, std_pos), mapper.shift)
+            : std_pos;
         const std_number = std_numbers[std_idx];
         let nearest_input_idx = -1;
         let nearest_sq_dist = Infinity;
         for (let input_idx = 0; input_idx < input_positions.length; input_idx += 1) {
             if (input_numbers[input_idx] !== std_number)
                 continue;
-            const sq_dist = fractional_sq_dist(std_pos, input_positions[input_idx]);
+            const delta = math.subtract(pred, input_positions[input_idx]);
+            // Exact match modulo a translation of the standardized lattice
+            const is_std_translation = mapper && is_near_integer_vec(math.mat3x3_vec3_multiply(mapper.linear_inv, delta), tol);
+            const sq_dist = is_std_translation
+                ? 0
+                : fractional_sq_dist(pred, input_positions[input_idx]);
             if (sq_dist < nearest_sq_dist) {
                 nearest_sq_dist = sq_dist;
                 nearest_input_idx = input_idx;
@@ -111,7 +159,7 @@ export function map_std_to_orig_site_indices(std_positions, std_numbers, input_p
             return [];
         return orig_site_indices_by_input_idx[nearest_input_idx] ?? [];
     });
-}
+};
 export async function analyze_structure_symmetry(struct_or_mol, settings) {
     await ensure_moyo_wasm_ready();
     if (!(`lattice` in struct_or_mol)) {
@@ -123,8 +171,16 @@ export async function analyze_structure_symmetry(struct_or_mol, settings) {
     // Map "Moyo" to "Standard" for moyo-wasm
     const moyo_algo = algo === `Moyo` ? `Standard` : algo;
     const sym_data = analyze_cell(cell_json, symprec, moyo_algo);
-    const orig_site_indices_by_std_idx = map_std_to_orig_site_indices(sym_data.std_cell.positions, sym_data.std_cell.numbers, moyo_input_cell.positions, moyo_input_cell.numbers, moyo_input_cell.orig_site_indices_by_input_idx);
-    return { ...sym_data, orig_site_indices_by_std_idx };
+    const orig_site_indices_by_std_idx = map_std_to_orig_site_indices(sym_data.std_cell.positions, sym_data.std_cell.numbers, moyo_input_cell.positions, moyo_input_cell.numbers, moyo_input_cell.orig_site_indices_by_input_idx, { std_linear: sym_data.std_linear, std_origin_shift: sym_data.std_origin_shift }, Math.max(1e-5, symprec * 10));
+    return {
+        ...sym_data,
+        orig_site_indices_by_std_idx,
+        input_cell: {
+            positions: moyo_input_cell.positions,
+            numbers: moyo_input_cell.numbers,
+        },
+        orig_site_indices_by_input_idx: moyo_input_cell.orig_site_indices_by_input_idx,
+    };
 }
 // Helper function to score coordinate simplicity for Wyckoff table
 export function simplicity_score(vec) {
@@ -134,66 +190,74 @@ export function simplicity_score(vec) {
         near_zero(az) +
         0.5 * (near_half(ax) + near_half(ay) + near_half(az)));
 }
-// Generate Wyckoff table rows from symmetry data
-export function wyckoff_positions_from_moyo(sym_data) {
-    if (!sym_data)
-        return [];
-    const { positions, numbers } = sym_data.std_cell;
-    const { wyckoffs, orig_indices, orig_site_indices_by_std_idx } = sym_data;
-    // Group sites by letter-element combination and track all indices
-    const groups = new Map();
-    // Process all atoms in the standardized cell
-    // Note: wyckoffs array may be shorter than std_cell when moyo combines symmetry-equivalent sites
-    for (let idx = 0; idx < numbers.length; idx++) {
-        // Use wyckoff letter if available, otherwise mark as non-symmetric
-        const full = idx < wyckoffs.length ? wyckoffs[idx] : null;
-        const letter = full?.match(/[a-z]+$/)?.[0] ?? full ?? ``;
-        const atomic_num = numbers[idx];
-        const elem = ATOMIC_NUMBER_TO_SYMBOL[atomic_num] ?? `?`;
-        const position = positions[idx];
-        const key = letter ? `${letter}|${elem}` : `nosym|${elem}|${idx}`;
-        const group = groups.get(key) ?? { letter, elem, indices: [], positions: [] };
-        group.indices.push(idx);
-        group.positions.push(position);
-        groups.set(key, group);
-    }
-    const rows = Array.from(groups.values()).map(({ letter, elem, indices, positions: group_positions }) => {
-        // Find the position with the best simplicity score to display
-        const best_pos = group_positions.reduce((best, pos) => {
-            const score = simplicity_score(pos);
-            return score < best.score ? { pos, score } : best;
-        }, { pos: group_positions[0], score: simplicity_score(group_positions[0]) }).pos;
-        // Map standardized cell indices back to original structure indices
-        const orig_site_indices = orig_site_indices_by_std_idx
-            ? indices.flatMap((std_idx) => orig_site_indices_by_std_idx[std_idx] ?? [])
-            : orig_indices
-                ? indices.map((std_idx) => orig_indices[std_idx]).filter((idx) => idx !== undefined)
-                : indices;
-        const wyckoff = letter ? `${indices.length}${letter}` : `1`;
+// Pick the representative coordinate with the lowest simplicity score (ties keep first)
+const simplest_position = (positions) => positions.reduce((best, pos) => simplicity_score(pos) < simplicity_score(best) ? pos : best);
+// Build Wyckoff rows from moyo's input-cell orbits. moyo's per-site arrays (wyckoffs,
+// orbits, site_symmetry_symbols) are indexed by INPUT cell sites — NOT std_cell sites —
+// so rows must be derived by grouping input sites into crystallographic orbits.
+// Multiplicity in the conventional cell is the orbit size scaled by the std/input cell
+// size ratio (e.g. a 1-atom primitive FCC input has orbit size 1 but multiplicity 4).
+function wyckoff_rows_from_input_orbits(sym_data) {
+    const { input_cell, orbits, wyckoffs, site_symmetry_symbols, std_cell, orig_site_indices_by_input_idx, } = sym_data;
+    const n_input = input_cell?.positions.length ?? 0;
+    if (!input_cell || n_input === 0)
+        return null;
+    if (orbits?.length !== n_input || wyckoffs?.length !== n_input)
+        return null;
+    const mapper = make_frac_coord_mapper(sym_data.std_linear, sym_data.std_origin_shift);
+    if (!mapper)
+        return null;
+    // Group input-cell sites by crystallographic orbit (keyed by orbit representative).
+    // Distinct orbits sharing the same Wyckoff letter and element stay separate rows.
+    const orbit_members = new Map();
+    orbits.forEach((rep, idx) => {
+        const members = orbit_members.get(rep) ?? [];
+        members.push(idx);
+        orbit_members.set(rep, members);
+    });
+    const n_std = std_cell?.positions.length ?? n_input;
+    return [...orbit_members.entries()].map(([rep, members]) => {
+        const letter = wyckoff_letter(wyckoffs[rep] ?? ``);
+        const elem = ATOMIC_NUMBER_TO_SYMBOL[input_cell.numbers[rep]] ?? `?`;
+        const multiplicity = Math.round((members.length * n_std) / n_input);
+        // Representative coordinate in the standardized frame, simplest first
+        const best_pos = simplest_position(members.map((idx) => wrap_frac(mapper.to_std(input_cell.positions[idx]))));
+        const orig_site_indices = members.flatMap((idx) => orig_site_indices_by_input_idx?.[idx] ?? [idx]);
+        const site_symmetry = site_symmetry_symbols?.[rep];
         return {
-            wyckoff,
+            wyckoff: letter ? `${multiplicity}${letter}` : `${multiplicity}`,
             elem,
             abc: best_pos,
             site_indices: [...new Set(orig_site_indices)].sort((idx_a, idx_b) => idx_a - idx_b),
+            ...(site_symmetry ? { site_symmetry } : {}),
         };
     });
-    rows.sort((w1, w2) => {
-        const [w1_mult, w2_mult] = [parseInt(w1.wyckoff), parseInt(w2.wyckoff)];
+}
+// Generate Wyckoff table rows from symmetry data by grouping moyo's input-cell sites into
+// crystallographic orbits. moyo's per-site arrays (wyckoffs, orbits, site_symmetry_symbols)
+// always index the input cell and analyze_structure_symmetry always attaches input_cell, so
+// the orbit grouping is the single source of truth for any input cell setting.
+// Rows sort by ascending multiplicity, then Wyckoff label.
+export function wyckoff_positions_from_moyo(sym_data) {
+    if (!sym_data)
+        return [];
+    const orbit_rows = wyckoff_rows_from_input_orbits(sym_data);
+    return (orbit_rows ?? []).sort((w1, w2) => {
+        const [w1_mult, w2_mult] = [parseInt(w1.wyckoff, 10), parseInt(w2.wyckoff, 10)];
         if (w1_mult !== w2_mult)
             return w1_mult - w2_mult;
         return w1.wyckoff.localeCompare(w2.wyckoff);
     });
-    return rows;
 }
 // Apply symmetry operations to find all equivalent positions for a given fractional coordinate
-export function apply_symmetry_operations(position, operations, _tolerance = 1e-6) {
+export function apply_symmetry_operations(position, operations) {
     const seen = new Set();
     return operations
         .map(({ rotation, translation }) => {
-        // Apply 3x3 rotation matrix and translation: new_pos = R * position + t
-        const new_pos = [0, 1, 2].map((dim) => rotation[dim * 3] * position[0] +
-            rotation[dim * 3 + 1] * position[1] +
-            rotation[dim * 3 + 2] * position[2] +
+        // new_pos = W·position + t; moyo serializes W COLUMN-major: W[dim][j] = rotation[dim + 3j]
+        const new_pos = [0, 1, 2].map((dim) => rotation[dim] * position[0] +
+            rotation[dim + 3] * position[1] +
+            rotation[dim + 6] * position[2] +
             translation[dim]);
         return new_pos.map(to_unit);
     })
@@ -205,24 +269,179 @@ export function apply_symmetry_operations(position, operations, _tolerance = 1e-
         return true;
     });
 }
-// Map Wyckoff positions to all equivalent atoms in the displayed structure (including image atoms)
+// Build candidate frames for the displayed structure: original, conventional (moyo
+// std_cell), and primitive (moyo prim_std_cell). The displayed structure's fractional
+// coordinates only match symmetry-equivalent positions when expressed in the same frame.
+function candidate_display_frames(orig_structure, sym_data) {
+    const frames = [
+        {
+            lattice: orig_structure.lattice.matrix,
+            map_equiv: (pos) => pos,
+            input_translation_check: null,
+        },
+    ];
+    const cells = [
+        { cell: sym_data.std_cell, linear: sym_data.std_linear, shift: sym_data.std_origin_shift },
+        {
+            cell: sym_data.prim_std_cell,
+            linear: sym_data.prim_std_linear,
+            shift: sym_data.prim_std_origin_shift,
+        },
+    ];
+    for (const { cell, linear, shift } of cells) {
+        const basis = cell?.lattice?.basis;
+        const mapper = make_frac_coord_mapper(linear, shift);
+        if (basis?.length !== 9 || !mapper)
+            continue;
+        // basis is row-major (each row a lattice vector); same reshape as moyo_cell_to_structure
+        frames.push({
+            lattice: math.vec9_to_mat3x3([...basis]),
+            map_equiv: mapper.to_std,
+            input_translation_check: mapper.linear,
+        });
+    }
+    return frames;
+}
+// Spatial hash over wrapped fractional coordinates for tolerance-based, mod-1 position
+// lookups. Cell size is chosen ≥ tolerance so probing the ±1 neighbor cells (with
+// wraparound) covers every point within tolerance of the query.
+class WrappedPositionIndex {
+    tolerance;
+    buckets = new Map();
+    coords;
+    n_cells;
+    constructor(positions, tolerance) {
+        this.tolerance = tolerance;
+        this.n_cells = Math.min(64, Math.max(1, Math.floor(1 / Math.max(tolerance, 1e-9))));
+        this.coords = positions;
+        positions.forEach((pos, idx) => {
+            const key = this.cell_key(pos, 0, 0, 0);
+            const bucket = this.buckets.get(key);
+            if (bucket)
+                bucket.push(idx);
+            else
+                this.buckets.set(key, [idx]);
+        });
+    }
+    cell_key(pos, dx, dy, dz) {
+        const n_cells = this.n_cells;
+        const cell = (coord, offset) => {
+            const wrapped = coord - Math.floor(coord);
+            return (((Math.floor(wrapped * n_cells) + offset) % n_cells) + n_cells) % n_cells;
+        };
+        return `${cell(pos[0], dx)},${cell(pos[1], dy)},${cell(pos[2], dz)}`;
+    }
+    // Indices of stored positions within `tolerance` of `query` modulo ℤ³
+    query(query, out) {
+        const tol = this.tolerance;
+        for (let dx = -1; dx <= 1; dx++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dz = -1; dz <= 1; dz++) {
+                    const bucket = this.buckets.get(this.cell_key(query, dx, dy, dz));
+                    if (!bucket)
+                        continue;
+                    for (const idx of bucket) {
+                        const pos = this.coords[idx];
+                        const d0 = pos[0] - query[0];
+                        const d1 = pos[1] - query[1];
+                        const d2 = pos[2] - query[2];
+                        if (Math.abs(d0 - Math.round(d0)) < tol &&
+                            Math.abs(d1 - Math.round(d1)) < tol &&
+                            Math.abs(d2 - Math.round(d2)) < tol)
+                            out.add(idx);
+                    }
+                }
+            }
+        }
+    }
+}
+// Map Wyckoff positions to all equivalent atoms in the displayed structure (including
+// image atoms). Handles displayed structures in the original frame as well as
+// conventional/primitive cell transforms and integer supercells of any of those: the
+// displayed lattice L_disp is matched against each candidate frame's lattice L_F via
+// S = L_disp·L_F⁻¹ (S must be near-integer), displayed coords are converted into the
+// frame via x_F = x_disp·S, and matches allow crystal translations of both the frame
+// lattice (d ∈ ℤ³) and the input lattice (P·d ∈ ℤ³). Matching uses spatial hashing:
+// O(N_disp + N_orig·N_ops) instead of O(N_orig·N_disp·N_ops).
 export function map_wyckoff_to_all_atoms(wyckoff_positions, displayed_structure, orig_structure, sym_data, tolerance = 1e-5) {
     if (!sym_data?.operations || !displayed_structure.sites || !orig_structure.sites) {
         return wyckoff_positions;
     }
-    return wyckoff_positions.map((wyckoff_pos) => {
-        const indices = (wyckoff_pos.site_indices || [])
-            .filter((idx) => idx < orig_structure.sites.length)
-            .flatMap((orig_idx) => {
-            const { abc: orig_abc, species } = orig_structure.sites[orig_idx];
-            const element = species[0]?.element;
-            const equivalent_positions = apply_symmetry_operations(orig_abc, sym_data.operations, tolerance);
-            return displayed_structure.sites
-                .map((site, display_idx) => ({ site, display_idx }))
-                .filter(({ site }) => site.species[0]?.element === element)
-                .filter(({ site }) => equivalent_positions.some((equiv_pos) => periodic_distance(equiv_pos, site.abc) < tolerance))
-                .map(({ display_idx }) => display_idx);
+    const map_in_frame = (frame) => {
+        // Supercell factor S = L_disp·L_F⁻¹ must be a near-integer matrix with |det| ≥ 1
+        let scaling;
+        try {
+            scaling = math.dot(displayed_structure.lattice.matrix, math.matrix_inverse_3x3(frame.lattice));
+        }
+        catch {
+            return null;
+        }
+        const is_integer_scaling = scaling.every((row) => row.every((val) => Math.abs(val - Math.round(val)) < tolerance));
+        if (!is_integer_scaling || Math.abs(math.det_3x3(scaling)) < 0.99)
+            return null;
+        // Displayed site coords expressed in frame-F fractional coordinates: x_F = x_disp·S
+        const scaling_transpose = math.transpose_3x3_matrix(scaling);
+        const displayed_frame_coords = displayed_structure.sites.map((site) => math.mat3x3_vec3_multiply(scaling_transpose, site.abc));
+        const displayed_elements = displayed_structure.sites.map((site) => site.species[0]?.element);
+        // Spatial hashes: one over the frame coords directly (matches d ∈ ℤ³), and one over
+        // P·x_F (matches input-lattice translations: d ∈ P⁻¹ℤ³ ⟺ P·d ∈ ℤ³)
+        const direct_index = new WrappedPositionIndex(displayed_frame_coords, tolerance);
+        const check = frame.input_translation_check;
+        const check_index = check
+            ? new WrappedPositionIndex(displayed_frame_coords.map((pos) => math.mat3x3_vec3_multiply(check, pos)), tolerance)
+            : null;
+        let any_matched = false;
+        const rows = wyckoff_positions.map((wyckoff_pos) => {
+            // Union the symmetry orbits of all original sites in this row, grouped by element.
+            // Sites whose (wrapped) position already appears in the accumulated orbit are
+            // skipped — orbit members generate identical orbits, so rows with many sites of
+            // one orbit (e.g. supercells) only pay for one full operation sweep
+            const equiv_by_element = new Map();
+            for (const orig_idx of wyckoff_pos.site_indices ?? []) {
+                if (orig_idx >= orig_structure.sites.length)
+                    continue;
+                const { abc: orig_abc, species } = orig_structure.sites[orig_idx];
+                const element = species[0]?.element;
+                const equivalents = equiv_by_element.get(element) ?? new Map();
+                equiv_by_element.set(element, equivalents);
+                const member_key = symmetry_position_key(frame.map_equiv(orig_abc.map(to_unit)));
+                if (equivalents.has(member_key))
+                    continue;
+                for (const equiv_pos of apply_symmetry_operations(orig_abc, sym_data.operations)) {
+                    const frame_pos = frame.map_equiv(equiv_pos);
+                    const key = symmetry_position_key(frame_pos);
+                    if (!equivalents.has(key))
+                        equivalents.set(key, frame_pos);
+                }
+            }
+            const matched = new Set();
+            for (const [element, equivalents] of equiv_by_element) {
+                const candidates = new Set();
+                for (const equiv_pos of equivalents.values()) {
+                    direct_index.query(equiv_pos, candidates);
+                    if (check && check_index) {
+                        check_index.query(math.mat3x3_vec3_multiply(check, equiv_pos), candidates);
+                    }
+                }
+                for (const display_idx of candidates) {
+                    if (displayed_elements[display_idx] === element)
+                        matched.add(display_idx);
+                }
+            }
+            if (matched.size > 0)
+                any_matched = true;
+            return { ...wyckoff_pos, site_indices: [...matched].sort((a, b) => a - b) };
         });
-        return { ...wyckoff_pos, site_indices: [...new Set(indices)].sort((a, b) => a - b) };
-    });
+        return any_matched || displayed_structure.sites.length === 0 ? rows : null;
+    };
+    // Try frames in order; accept the first whose lattice fits AND that matches any site
+    // (lattices can coincide across frames while origins differ, so a lattice match alone
+    // is not conclusive)
+    for (const frame of candidate_display_frames(orig_structure, sym_data)) {
+        const rows = map_in_frame(frame);
+        if (rows)
+            return rows;
+    }
+    // No frame fits — site indices into the displayed structure cannot be determined
+    return wyckoff_positions.map((pos) => ({ ...pos, site_indices: [] }));
 }

package/dist/symmetry/spacegroups.d.ts

@@ -1,9 +1,20 @@
-export declare const CRYSTAL_SYSTEM_RANGES: Record<CrystalSystem, [number, number]>;
+import type { Vec2 } from '../math';
+import type { SunburstNode } from '../plot/core/types';
+export declare const CRYSTAL_SYSTEM_RANGES: Record<CrystalSystem, Vec2>;
 export declare const CRYSTAL_SYSTEM_COLORS: Record<CrystalSystem, string>;
 export declare const CRYSTAL_SYSTEMS: readonly ["triclinic", "monoclinic", "orthorhombic", "tetragonal", "trigonal", "hexagonal", "cubic"];
 export type CrystalSystem = (typeof CRYSTAL_SYSTEMS)[number];
 export declare function spacegroup_num_to_crystal_sys(spacegroup: number): CrystalSystem | null;
 export declare function spacegroup_to_crystal_sys(spacegroup: number | string): CrystalSystem | null;
+export declare const RHOMBOHEDRAL_SPACEGROUPS: readonly number[];
+export type LatticeSystem = Exclude<CrystalSystem, `trigonal`> | `rhombohedral`;
+export declare function spacegroup_num_to_lattice_system(spacegroup: number): LatticeSystem | null;
 export declare function normalize_spacegroup(spacegroup: number | string): number | null;
 export declare const SPACEGROUP_SYMBOL_TO_NUM: Record<string, number>;
 export declare const SPACEGROUP_NUM_TO_SYMBOL: Record<number, string>;
+export interface SpacegroupSunburstMetadata {
+    spacegroup: number;
+    crystal_system: CrystalSystem;
+    [key: string]: unknown;
+}
+export declare function spacegroup_sunburst_data(spacegroups: readonly (number | string)[]): SunburstNode<SpacegroupSunburstMetadata>[];

package/dist/symmetry/spacegroups.js

@@ -40,24 +40,34 @@ export function spacegroup_num_to_crystal_sys(spacegroup) {
 }
 // Convert space group (number or symbol) to crystal system
 export function spacegroup_to_crystal_sys(spacegroup) {
-    if (typeof spacegroup === `number`)
-        return spacegroup_num_to_crystal_sys(spacegroup);
-    // Try to parse as symbol
-    const number = SPACEGROUP_SYMBOL_TO_NUM[spacegroup];
-    if (number !== undefined)
-        return spacegroup_num_to_crystal_sys(number);
-    // Try to parse string as number
-    const parsed = parseInt(spacegroup, 10);
-    if (!isNaN(parsed))
-        return spacegroup_num_to_crystal_sys(parsed);
-    return null;
+    const num = normalize_spacegroup(spacegroup);
+    return num == null ? null : spacegroup_num_to_crystal_sys(num);
+}
+// Trigonal space groups with rhombohedral (R-centered) Bravais lattices. All other
+// trigonal groups have primitive hexagonal lattices.
+export const RHOMBOHEDRAL_SPACEGROUPS = [146, 148, 155, 160, 161, 166, 167];
+// Convert space group number to lattice system (classification of the Bravais lattice).
+// Differs from the crystal system only for trigonal groups: R-centered ones (R3, R-3m, …)
+// have rhombohedral lattices while P-trigonal ones (P3, P-3m1, …) have hexagonal lattices.
+export function spacegroup_num_to_lattice_system(spacegroup) {
+    const crystal_sys = spacegroup_num_to_crystal_sys(spacegroup);
+    if (crystal_sys === null)
+        return null;
+    if (crystal_sys !== `trigonal`)
+        return crystal_sys;
+    return RHOMBOHEDRAL_SPACEGROUPS.includes(spacegroup) ? `rhombohedral` : `hexagonal`;
 }
-// Normalize space group input to number
+// Normalize space group input (number, Hermann-Mauguin symbol, or numeric string
+// like "225") to a space group number in [1, 230], or null if invalid
 export function normalize_spacegroup(spacegroup) {
     if (typeof spacegroup === `number`) {
         return spacegroup >= 1 && spacegroup <= 230 ? spacegroup : null;
     }
-    return SPACEGROUP_SYMBOL_TO_NUM[spacegroup] ?? null;
+    const from_symbol = SPACEGROUP_SYMBOL_TO_NUM[spacegroup];
+    if (from_symbol !== undefined)
+        return from_symbol;
+    const parsed = parseInt(spacegroup, 10);
+    return isNaN(parsed) ? null : normalize_spacegroup(parsed);
 }
 export const SPACEGROUP_SYMBOL_TO_NUM = {
     // Triclinic
@@ -206,13 +216,13 @@ export const SPACEGROUP_SYMBOL_TO_NUM = {
     'I4/mcm': 140,
     'I4_1/amd': 141,
     'I4_1/acd': 142,
+    // Trigonal
     P3: 143,
     P3_1: 144,
     P3_2: 145,
     R3: 146,
     'P-3': 147,
     'R-3': 148,
-    // Trigonal
     P312: 149,
     P321: 150,
     P3_112: 151,
@@ -392,3 +402,42 @@ export const SPACEGROUP_NUM_TO_SYMBOL = Object.entries(SPACEGROUP_SYMBOL_TO_NUM)
         acc[num] = symbol;
     return acc;
 }, {});
+// Build crystal-system -> spacegroup hierarchy data for the Sunburst component from a
+// list of spacegroup numbers or symbols (one entry per occurrence; counts become leaf
+// values). Leaf ids follow the pymatviz spacegroup_sunburst scheme, e.g. "cubic/225".
+export function spacegroup_sunburst_data(spacegroups) {
+    const counts = new Map();
+    let n_invalid = 0;
+    for (const spacegroup of spacegroups) {
+        const num = normalize_spacegroup(spacegroup); // numbers, symbols, numeric strings
+        if (num == null) {
+            n_invalid += 1;
+            continue;
+        }
+        counts.set(num, (counts.get(num) ?? 0) + 1);
+    }
+    if (n_invalid > 0) {
+        console.warn(`spacegroup_sunburst_data: skipped ${n_invalid} invalid spacegroup(s) (expected numbers 1-230 or Hermann-Mauguin symbols)`);
+    }
+    // Emit crystal systems in canonical (space group number) order, only those present
+    return CRYSTAL_SYSTEMS.flatMap((system) => {
+        const nums = [...counts.keys()]
+            .filter((num) => spacegroup_num_to_crystal_sys(num) === system)
+            .sort((num_a, num_b) => num_a - num_b);
+        if (nums.length === 0)
+            return [];
+        return [
+            {
+                id: system,
+                label: system,
+                color: CRYSTAL_SYSTEM_COLORS[system],
+                children: nums.map((num) => ({
+                    id: `${system}/${num}`,
+                    label: SPACEGROUP_NUM_TO_SYMBOL[num] ?? `${num}`,
+                    value: counts.get(num),
+                    metadata: { spacegroup: num, crystal_system: system },
+                })),
+            },
+        ];
+    });
+}

package/dist/symmetry/symmetry-elements.d.ts

@@ -0,0 +1,33 @@
+import type { Matrix3x3, Vec3 } from '../math';
+import type { MoyoDataset } from '@spglib/moyo-wasm';
+export type SymmetryElementKind = `rotation` | `screw` | `mirror` | `glide` | `inversion` | `rotoinversion`;
+export type SymmetryElement = {
+    kind: SymmetryElementKind;
+    order: number;
+    label: string;
+    axis: Vec3 | null;
+    point: Vec3;
+    translation: Vec3 | null;
+};
+export declare const SYM_ELEM_KINDS: readonly ["rotation", "screw", "rotoinversion", "mirror", "glide", "inversion"];
+export type ShowSymmetryKinds = Partial<Record<SymmetryElementKind, boolean>>;
+export declare const DEFAULT_SHOW_SYM_KINDS: ShowSymmetryKinds;
+export declare const SYM_ELEM_KIND_INFO: Record<SymmetryElementKind, {
+    label: string;
+    color: string;
+}>;
+export declare function count_symmetry_elements(elements: readonly SymmetryElement[]): Partial<Record<SymmetryElementKind, number>>;
+export declare const has_visible_symmetry_overlay: (elements: readonly SymmetryElement[], show_kinds?: ShowSymmetryKinds) => boolean;
+export declare const mat3_from_flat_col_major: (flat: readonly number[]) => Matrix3x3;
+export type ClassifiedOperation = Omit<SymmetryElement, `point`> & {
+    point: Vec3;
+};
+export declare function classify_symmetry_op(rotation: readonly number[], translation: readonly number[], centerings?: readonly Vec3[]): ClassifiedOperation | null;
+export declare function symmetry_elements_from_ops(operations: MoyoDataset[`operations`]): SymmetryElement[];
+export declare function dash_segments(length: number, dash: number, gap: number): {
+    center: number;
+    length: number;
+}[];
+export declare const frac_to_cart_direction: (frac: Vec3, lattice: Matrix3x3) => Vec3;
+export declare function clip_line_to_cell(point: Vec3, direction: Vec3, lattice: Matrix3x3, eps?: number): [Vec3, Vec3] | null;
+export declare function clip_plane_to_cell(point: Vec3, normal_frac: Vec3, lattice: Matrix3x3): Vec3[];