@matteria-js/transformations

Deterministic structure transformation APIs. Current helpers are makeSupercell, makeSupercellMatrix, translateSites, substituteSpecies, applyStrain, rotateStructure, and makeOrientedSlab.

Transformations take structures in and return structures out. They should not own solvers, rendering, workflow queues, or app mutation state.

Example

import {
  applyStrain,
  makeOrientedSlab,
  makeSupercellMatrix,
  rotateStructure,
  substituteSpecies,
  translateSites,
} from "@matteria-js/transformations";

const shifted = translateSites(structure, 0, [0.1, 0, 0]);
const substituted = substituteSpecies(shifted, { Si: "Ge" });
const strained = applyStrain(substituted, [0.01, 0, -0.005]);
const supercell = makeSupercellMatrix(strained, [
  [2, 1, 0],
  [0, 1, 0],
  [0, 0, 1],
]);
const rotated = rotateStructure(supercell, [
  [0, 1, 0],
  [-1, 0, 0],
  [0, 0, 1],
]);
const slab = makeOrientedSlab(rotated, {
  minSlabSize: 12,
  minVacuumSize: 15,
});

makeSupercellMatrix accepts integer 3x3 matrices with positive determinant. rotateStructure validates that the matrix is a proper rotation unless you pass { validateRotation: false }.

makeOrientedSlab is intentionally narrow: it assumes the input structure is already oriented with the surface normal along lattice c, repeats along c until the slab is thick enough, then adds vacuum by extending the c vector. It does not choose Miller planes, terminations, adsorbates, or symmetry-distinct surfaces.

Future scope includes site filtering, Miller-index surface builders, conventional-cell helpers, interfaces, bilayers, and repeatable cleanup operations.

Next Slice

Useful next steps are Miller-index slab and surface builders once symmetry/conventional-cell helpers exist, and interface or bilayer setup utilities that return structures plus metadata for the viewer.

Transformations should return data. They should not decide how a viewer animates, colors, or renders the result.