spglibJS

JavaScript bindings for spglib with a small plain-data API for Node, browsers, and Web Workers.

The package is meant to do one job well: expose symmetry data, lattice reductions, and k-point mesh helpers without leaking WASM memory details into application code. Higher-level materials objects belong in MATTERIA; rendering belongs in viewer apps such as DRISHTI.

Install

npm install spglibjs

The deterministic JavaScript helpers work from the package source. Structure-aware calls use the WASM backend built from upstream spglib:

npm run build:wasm

Quick Use

import {
  getPointgroup,
  getSpacegroupType,
  getSymmetryFromDatabase,
  version,
} from "spglibjs";

const operations = getSymmetryFromDatabase(523);

console.log(version());
console.log(getSpacegroupType(523).internationalShort);
console.log(getPointgroup(operations.rotations).symbol);

For structure symmetry, create the WASM-backed engine:

import { createSpglib } from "spglibjs";
import createSpglibWasm from "spglibjs/wasm";

const spglib = await createSpglib({ moduleFactory: createSpglibWasm });

const nacl = {
  lattice: [
    [5.64, 0, 0],
    [0, 5.64, 0],
    [0, 0, 5.64],
  ],
  positions: [
    [0, 0, 0],
    [0.5, 0.5, 0.5],
  ],
  numbers: [11, 17],
};

const result = spglib.getSymmetryDataset(nacl);

console.log(result.succeeded);
console.log(result.dataset?.spacegroup.internationalShort);

Inputs are simple objects:

{
  lattice: number[][];   // three row-vector basis vectors
  positions: number[][]; // fractional coordinates
  numbers: number[];     // atomic numbers or symmetry type labels
}

Results are JSON-like objects with arrays, numbers, strings, booleans, and null. They are safe to pass through postMessage and easy for MATTERIA or viewer code to wrap.

Browser Use

The browser build exposes window.spglibJS:

<script src="./dist/spglibjs.global.js"></script>
<script type="module">
  import createSpglibWasm from "./dist/wasm/spglib.mjs";

  const spglib = await window.spglibJS.createSpglib({
    moduleFactory: createSpglibWasm,
    wasmUrl: "./dist/wasm/spglib.wasm",
  });

  console.log(spglib.detectSpaceGroup({
    lattice: [[5.64, 0, 0], [0, 5.64, 0], [0, 0, 5.64]],
    positions: [[0, 0, 0], [0.5, 0.5, 0.5]],
    numbers: [11, 17],
  }).spacegroup?.internationalShort);
</script>

The global name stays spglibJS; the npm package name is scoped as spglibjs.

API Groups

• Space-group records: getSpacegroupType
• Database operations: getSymmetryFromDatabase
• Operation matching: getHallNumberFromSymmetry, getSpacegroupTypeFromSymmetry
• Point groups: getPointgroup
• Reciprocal-grid helpers: getGridPointFromAddress, getGridPointsByRotations
• Lattice reductions: niggliReduce, delaunayReduce
• WASM structure engine: createSpglib

C-style aliases such as spgGetSpacegroupType are kept for callers migrating from spglib naming.

Development

npm install
npm run build
npm test

Useful checks:

npm run test:types
npm run test:parity
npm pack --dry-run

npm run build:wasm requires Emscripten and CMake. Tests that need a local browser or WASM artifact skip when those pieces are not available.

Project Boundary

spglibJS does not parse POSCAR/CIF files, infer bonding, build Three.js scenes, or manage application state. Use MATTERIA for materials data models and DRISHTI or another viewer for UI.

See:

• docs/tutorial.md
• docs/scope-and-roadmap.md

License

BSD-3-Clause. The package includes generated data and behavior derived from upstream spglib.