@matteria-js/symmetry

High-level symmetry-facing helpers for MATTERIA structures.

Current scope:

• convert Structure objects to and from spglib-style cells
• expose SpacegroupAnalyzer as a backend-injected wrapper
• convert raw symmetry operations into small objects
• delegate space-group, point-group, symmetry-operation, Niggli-reduction, and Delaunay-reduction calls to a spglib-like backend

spglibjs is an optional peer dependency. Pass that module, or a compatible subset of it, as the analyzer backend. MATTERIA does not bundle or reimplement spglib.

Example

import * as spglib from "spglibjs";
import { SpacegroupAnalyzer } from "@matteria-js/symmetry";

const analyzer = new SpacegroupAnalyzer(structure, {
  backend: spglib,
  symprec: 1e-5,
});

const cell = analyzer.cell;
const reduced = analyzer.getNiggliReducedLattice();
const dataset = analyzer.getSymmetryDataset();

Full structure symmetry datasets depend on the backend you provide. If the backend does not implement getSymmetryDataset, getSymmetryDataset() throws.

Data Conversion

import { structureFromSpglibCell, toSpglibCell } from "@matteria-js/symmetry";

const cell = toSpglibCell(structure);
const restored = structureFromSpglibCell(cell);

The spglib cell uses row-vector lattice rows, fractional positions, and atomic numbers:

{
  lattice: [[...], [...], [...]],
  positions: [[...], ...],
  numbers: [14, 14]
}

Limits

• No spglib implementation is bundled.
• No conventional or primitive cell builder is implemented directly in MATTERIA yet.
• SeeK-path-style k-path helpers are future work.
• Backend support varies; each delegated method throws when the provided backend lacks the matching function.