matterviz 0.3.6 → 0.4.0

package/dist/symmetry/SymmetryStats.svelte

@@ -0,0 +1,226 @@
+<script lang="ts">
+  import type { MoyoDataset } from '@spglib/moyo-wasm'
+  import type { Snippet } from 'svelte'
+  import { tooltip } from 'svelte-multiselect/attachments'
+  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?.replaceAll(/\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 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: 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 10 ** exponent
+  }
+
+  const symprec_step = $derived(get_step_from_order_of_magnitude(settings.symprec))
+</script>
+
+<div {...rest} class="symmetry-stats {rest.class ?? ``}">
+  {#if sym_data}
+    {@render header?.({ sym_data, settings })}
+  {/if}
+
+  <!-- Always show controls so users can adjust settings even after errors -->
+  <div class="controls">
+    {#if typeof label === `string`}
+      <strong>{label}</strong>
+    {:else if label}
+      {@render label?.({ sym_data, settings })}
+    {/if}
+
+    <label>
+      <span {@attach tooltip()} title={tooltips?.symprec}>Precision</span>
+      <input
+        type="number"
+        step={symprec_step}
+        value={settings.symprec}
+        oninput={(evt) => {
+          const { value } = evt.currentTarget
+          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>
+      <span {@attach tooltip()} title={tooltips?.algo}>Algorithm</span>
+
+      <select
+        value={settings.algo}
+        onchange={(evt) =>
+        settings = {
+          ...settings,
+          algo: evt.currentTarget.value as `Moyo` | `Spglib`,
+        }}
+      >
+        {#each Object.keys(SETTINGS_CONFIG.symmetry.algo.enum ?? {}) as value (value)}
+          <option {value}>{value}</option>
+        {/each}
+      </select>
+    </label>
+  </div>
+
+  {@render children?.({ sym_data, settings })}
+  {#if sym_data}
+    <div class="stats-grid">
+      <div
+        title="{tooltips?.space_group} at {settings.symprec} (using {settings.algo} algo). {tooltips?.hermann_mauguin}"
+        {@attach tooltip()}
+      >
+        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>
+      </div>
+      <div title={tooltips?.hall_number} {@attach tooltip()}>
+        Hall Number <strong>{sym_data.hall_number}</strong>
+      </div>
+      <div title={tooltips?.pearson_symbol} {@attach tooltip()}>
+        Pearson <strong>{sym_data.pearson_symbol}</strong>
+      </div>
+      <div title={tooltips?.distinct_orbits} {@attach tooltip()}>
+        Wyckoff Positions <strong>{wyckoff_count}</strong>
+      </div>
+      <div
+        class="sym-ops-summary"
+        title="{sym_ops_counts.translations} translations + {sym_ops_counts.rotations} rotations + {sym_ops_counts.roto_translations} roto-translations"
+        {@attach tooltip()}
+      >
+        Total sym ops: <strong>{sym_data.operations.length}</strong>
+        ({sym_ops_counts.translations}T + {sym_ops_counts.rotations}R + {
+          sym_ops_counts.roto_translations
+        }RT)
+      </div>
+    </div>
+  {:else}
+    <div class="no-data">
+      <p>No symmetry data available</p>
+    </div>
+  {/if}
+</div>
+
+<style>
+  .controls {
+    display: flex;
+    gap: var(--sym-stats-controls-gap, 1em);
+    background: var(--sym-stats-controls-bg, var(--surface-bg));
+    padding: var(--sym-stats-controls-padding, 4pt 6pt);
+    border-radius: var(--sym-stats-controls-border-radius, 4pt);
+    margin-inline: var(--sym-stats-controls-margin-inline, -6pt);
+  }
+  .controls label {
+    display: flex;
+    gap: var(--sym-stats-label-gap, 6pt);
+    place-items: center;
+  }
+  .controls label input {
+    padding: var(--sym-stats-input-padding, 2pt 5pt);
+    width: var(--sym-stats-input-width, 5.5em);
+    box-sizing: border-box;
+  }
+  .stats-grid {
+    display: var(--sym-stats-display, grid);
+    grid-template-columns:
+      var(--sym-stats-grid-columns, repeat(auto-fit, minmax(275px, 1fr)));
+    gap: var(--sym-stats-grid-gap, 1ex 1em);
+    margin-block: var(--sym-stats-grid-margin-block, 1ex);
+    align-items: var(--sym-stats-grid-align, start);
+  }
+  .stats-grid strong {
+    margin: var(--sym-stats-strong-margin, 0 0 0 3pt);
+  }
+  .no-data {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: var(--sym-stats-no-data-min-height, 100px);
+    padding: var(--sym-stats-no-data-padding, 2em);
+    background: var(--sym-stats-no-data-bg, var(--surface-bg, #f5f5f5));
+    border-radius: var(--sym-stats-no-data-border-radius, 4pt);
+    color: var(--sym-stats-no-data-color, var(--text-muted, #666));
+  }
+  .no-data p {
+    margin: 0;
+  }
+</style>

package/dist/symmetry/SymmetryStats.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { MoyoDataset } from '@spglib/moyo-wasm';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { SymmetrySettings } from './index';
+type SymmetrySnippet = Snippet<[
+    {
+        sym_data?: MoyoDataset | null;
+        settings: SymmetrySettings;
+    }
+]>;
+type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
+    sym_data?: MoyoDataset | null;
+    settings?: SymmetrySettings;
+    show_tooltips?: boolean;
+    children?: SymmetrySnippet;
+    label?: SymmetrySnippet | string;
+    header?: SymmetrySnippet;
+};
+declare const SymmetryStats: import("svelte").Component<$$ComponentProps, {}, "settings">;
+type SymmetryStats = ReturnType<typeof SymmetryStats>;
+export default SymmetryStats;

package/dist/symmetry/WyckoffTable.svelte

@@ -0,0 +1,120 @@
+<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}`
+  $effect(() => {
+    if (!selected_key || wyckoff_positions?.some((pos, idx) => get_row_key(pos, idx) === selected_key)) {
+      return
+    }
+    selected_key = null
+    on_click?.(null)
+  })
+</script>
+
+{#if wyckoff_positions && wyckoff_positions.length > 0}
+  <table {...rest} class="wyckoff-table {rest.class ?? ``}">
+    <thead>
+      <tr>
+        {#each [
+          [`Wyckoff`, `Wyckoff position: Multiplicity + Letter`],
+          [`Element`, `Chemical element symbol`],
+          [`Fractional Coords`, `Fractional coordinates within the unit cell`],
+        ] as
+          [col, title]
+          (col)
+        }
+          <th {title}>{col}</th>
+        {/each}
+      </tr>
+    </thead>
+    <tbody>
+      {#each wyckoff_positions as
+        wyckoff_pos,
+        row_idx
+        (get_row_key(wyckoff_pos, row_idx))
+      }
+        {@const { wyckoff, elem, abc, site_indices } = 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"
+          class:selected={is_selected}
+          style:--active-color={active_color}
+          style:--hover-color="#6cf0ff"
+          onmouseenter={() => on_hover?.(site_indices ?? null)}
+          onmouseleave={() => on_hover?.(null)}
+          onclick={() => {
+            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()
+              selected_key = is_selected ? null : row_key
+              on_click?.(is_selected ? null : (wyckoff_pos.site_indices ?? null))
+            }
+          }}
+        >
+          <td>{wyckoff}</td>
+          <td>
+            <span
+              style:background-color={colors.element[elem]}
+              style="display: inline-block; padding: 0 6pt; border-radius: 3pt; line-height: 1.4"
+              {@attach contrast_color()}
+            >
+              {elem}
+            </span>
+          </td>
+          <td>({abc?.map(format_fractional).join(` , `) ?? `N/A`})</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+{/if}
+
+<style>
+  .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;
+  }
+  .wyckoff-row:hover {
+    background-color: color-mix(in srgb, var(--hover-color) 25%, transparent);
+  }
+  .wyckoff-row.selected {
+    background-color: color-mix(in srgb, var(--active-color) 30%, transparent);
+  }
+  .wyckoff-row.selected:hover {
+    background-color: color-mix(in srgb, var(--active-color) 35%, transparent);
+  }
+</style>

package/dist/symmetry/WyckoffTable.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { WyckoffPos } from '.';
+type $$ComponentProps = HTMLAttributes<HTMLTableElement> & {
+    wyckoff_positions: WyckoffPos[];
+    on_hover?: (site_indices: number[] | null) => void;
+    on_click?: (site_indices: number[] | null) => void;
+    active_color?: string;
+};
+declare const WyckoffTable: import("svelte").Component<$$ComponentProps, {}, "">;
+type WyckoffTable = ReturnType<typeof WyckoffTable>;
+export default WyckoffTable;

package/dist/symmetry/cell-transform.d.ts

@@ -0,0 +1,12 @@
+import type { Crystal } from '../structure';
+import type { MoyoCell, MoyoDataset } from '@spglib/moyo-wasm';
+export type CellType = `original` | `conventional` | `primitive`;
+export declare function moyo_cell_to_structure(cell: MoyoCell, // The MoyoCell from symmetry analysis (std_cell or prim_std_cell)
+original_structure: Crystal): Crystal;
+export declare function get_conventional_cell(original_structure: Crystal, // The original input structure
+sym_data: MoyoDataset): Crystal;
+export declare function get_primitive_cell(original_structure: Crystal, // The original input structure
+sym_data: MoyoDataset): Crystal;
+export declare function transform_cell(structure: Crystal, // The original structure
+cell_type: CellType, // The desired cell type ('original', 'conventional', or 'primitive')
+sym_data: MoyoDataset | null): Crystal;

package/dist/symmetry/cell-transform.js

@@ -0,0 +1,91 @@
+import { ATOMIC_NUMBER_TO_SYMBOL } from '../composition/parse';
+import * as math from '../math';
+import { wrap_to_unit_cell } from '../structure/pbc';
+const transferable_properties = (properties) => {
+    if (properties === undefined)
+        return undefined;
+    const rest = { ...properties };
+    delete rest.bonds;
+    return Object.keys(rest).length > 0 ? rest : undefined;
+};
+// Convert a MoyoCell (from moyo-wasm symmetry analysis) to Crystal format.
+// MoyoCell has a flat 9-element basis array and atomic numbers; this converts to
+// the full Crystal with lattice parameters and element symbols.
+export function moyo_cell_to_structure(cell, // The MoyoCell from symmetry analysis (std_cell or prim_std_cell)
+original_structure) {
+    // Convert flat 9-element basis to 3x3 matrix
+    // moyo-wasm uses the same row-major serialization for both input and output
+    // (see to_cell_json comment: column-major(B) == row-major(RB))
+    // So the flat array is row-major: [a1, a2, a3, b1, b2, b3, c1, c2, c3]
+    // where each row is a lattice vector in the pymatgen convention
+    const basis = cell.lattice.basis;
+    const lattice_matrix = [
+        [basis[0], basis[1], basis[2]], // First lattice vector (a)
+        [basis[3], basis[4], basis[5]], // Second lattice vector (b)
+        [basis[6], basis[7], basis[8]], // Third lattice vector (c)
+    ];
+    // Calculate lattice parameters from matrix
+    const lattice_params = math.calc_lattice_params(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];
+        const element = ATOMIC_NUMBER_TO_SYMBOL[atomic_number];
+        if (!element) {
+            throw new Error(`Unknown atomic number: ${atomic_number}`);
+        }
+        // Wrap fractional coordinates to [0, 1) range (moyo-wasm may return outside)
+        const wrapped_abc = wrap_to_unit_cell(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.
+        const species = [{ element, occu: 1, oxidation_state: 0 }];
+        return { species, abc: wrapped_abc, xyz, label: element, properties: {} };
+    });
+    const lattice = {
+        matrix: lattice_matrix,
+        pbc: original_structure.lattice.pbc,
+        ...lattice_params,
+    };
+    const properties = transferable_properties(original_structure.properties);
+    return {
+        lattice,
+        sites,
+        charge: original_structure.charge,
+        id: original_structure.id,
+        ...(properties === undefined ? {} : { properties }),
+    };
+}
+// Get the conventional (standardized) cell from symmetry analysis data.
+// 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.
+// Returns the original structure if cell_type is 'original' or if sym_data is not available.
+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;
+    }
+    if (cell_type === `conventional`) {
+        return get_conventional_cell(structure, sym_data);
+    }
+    if (cell_type === `primitive`) {
+        return get_primitive_cell(structure, sym_data);
+    }
+    // Fallback to original (should never reach here with proper typing)
+    return structure;
+}

package/dist/symmetry/index.d.ts

@@ -0,0 +1,43 @@
+import type { Vec3 } from '../math';
+import type { AnyStructure, Crystal } from '../structure';
+import type { MoyoDataset } from '@spglib/moyo-wasm';
+export * from './cell-transform';
+export * from './spacegroups';
+export { default as SymmetryStats } from './SymmetryStats.svelte';
+export { default as WyckoffTable } from './WyckoffTable.svelte';
+export declare const BRAVAIS_LATTICES: {
+    readonly P: "Primitive";
+    readonly I: "Body-centered";
+    readonly F: "Face-centered";
+    readonly A: "A-face centered";
+    readonly B: "B-face centered";
+    readonly C: "C-face centered";
+    readonly R: "Rhombohedral";
+};
+export type BravaisLattice = (typeof BRAVAIS_LATTICES)[keyof typeof BRAVAIS_LATTICES];
+export type SymmetrySettings = {
+    symprec: number;
+    algo: `Moyo` | `Spglib`;
+};
+export declare const default_sym_settings: {
+    readonly symprec: number;
+    readonly algo: "Moyo" | "Spglib";
+};
+export type WyckoffPos = {
+    wyckoff: string;
+    elem: string;
+    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 const 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: 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[];