@matteria-js/core

Core MATTERIA materials objects and lattice math. This package is the dependency-free base layer for structures, compositions, coordinate conversion, periodic sites, and serialization.

@matteria-js/core is not a solver, renderer, parser, or workflow runtime. Other packages should build on it without pushing file formats, UI state, or simulation execution into this layer.

Public API

• Element: validates element symbols, exposes atomic number metadata, and can look up elements by atomic number.
• Composition: parses simple formulas, reports amounts, and renders full/reduced formulas.
• Lattice: stores row-vector lattice matrices, lengths, angles, volume, reciprocal lattices, coordinate conversion, minimum-image distances, and positive diagonal scaling.
• Site: non-periodic species plus Cartesian coordinates and optional properties.
• PeriodicSite: site plus lattice and fractional coordinates.
• Structure: lattice plus periodic sites, composition/formula accessors, distances, copy/replace/add/remove helpers, site translation, cartesian/fractional transforms, neighbor-image queries, diagonal supercells, and asDict() / fromDict() serialization.
• Types: Vector3, Matrix3, mutable variants, StructureDict, StructureOptions, and related helper types.
• Math helpers: dot, cross, norm, determinant, inverse3x3, fracToCart, cartToFrac, wrapFractional, vectorNearlyEqual, and related utilities.

Create a Structure

import { Lattice, Structure } from "@matteria-js/core";

const silicon = new Structure(
  Lattice.cubic(5.431),
  ["Si", "Si"],
  [
    [0, 0, 0],
    [0.25, 0.25, 0.25],
  ],
);

console.log(silicon.numSites); // 2
console.log(silicon.formula); // Si2
console.log(silicon.reducedFormula); // Si
console.log(silicon.cartCoords);

const distance = silicon.getDistance(0, 1);
const supercell = silicon.makeSupercell([2, 2, 1]);
const restored = Structure.fromDict(silicon.asDict());

Coordinates are fractional by default. Use Cartesian coordinates with:

const cartesian = new Structure(
  Lattice.cubic(5),
  ["Na", "Cl"],
  [
    [0, 0, 0],
    [2.5, 2.5, 2.5],
  ],
  { coordsAreCartesian: true },
);

Fractional coordinates are wrapped into the unit cell by default:

const wrapped = new Structure(Lattice.cubic(1), ["C"], [[1.25, -0.25, 0]]);
console.log(wrapped.fracCoords[0]); // [0.25, 0.75, 0]

const preserved = new Structure(Lattice.cubic(1), ["C"], [[1.25, -0.25, 0]], {
  toUnitCell: false,
});
console.log(preserved.fracCoords[0]); // [1.25, -0.25, 0]

Current Limits

• Species are element symbols with occupancy 1; disordered sites, oxidation states, and isotope metadata are deferred.
• Structure.makeSupercell() supports only positive integer diagonal scaling.
• Minimum-image distances currently use a compact neighboring-image search suitable for ordinary viewer cells; highly skewed cells may need a broader algorithm in a later parity slice.
• Periodic boundary conditions are always [true, true, true] in serialized lattice dictionaries.
• File formats live in @matteria-js/io; this package intentionally stays format-agnostic.

Next Slice

Core hardening should come before broad format growth:

• richer species/site metadata without breaking simple element-symbol inputs
• clearer periodic-boundary metadata
• broader minimum-image search for skewed cells
• stable dictionary shapes for volumetric, electronic, and phonon packages to reference

Keep this package dependency-light. Result-file parsing, symmetry engines, plot payloads, and rendering stay outside @matteria-js/core.