@matteria-js/interfaces

Interface and heterostructure helpers for MATTERIA.

This package prepares deterministic data for 2D lattice matching, stacking, heterostructures, and twisted bilayers. It does not run DFT, search every possible coincidence lattice, or render structures.

Included

• In-plane lattice summaries.
• Diagonal 2D commensurate-cell search.
• Film-on-substrate strain and area mismatch scoring.
• Interface supercell size estimates.
• Stacking-shift grids.
• Heterostructure assembly from already oriented film and substrate slabs.
• Simple twisted-bilayer construction with moire length metadata.
• JSON-friendly match, heterostructure, and bilayer summaries for workflow reports and viewer side panels.

Example

import {
  buildHeterostructure,
  findCommensurate2DMatches,
  generateStackingShifts,
  makeTwistedBilayer,
  summarizeHeterostructure,
  summarizeInterfaceMatch,
  summarizeTwistedBilayer,
} from "@matteria-js/interfaces";

const matches = findCommensurate2DMatches(film, substrate, {
  maxRepeat: 6,
  maxStrain: 0.03,
});

const interfaceModel = buildHeterostructure(film, substrate, {
  match: matches[0],
  gap: 3,
  vacuum: 15,
  stackingShift: generateStackingShifts({ grid: [3, 3] })[0],
});
const matchSummary = summarizeInterfaceMatch(matches[0]);
const interfaceSummary = summarizeHeterostructure(interfaceModel);
const twisted = makeTwistedBilayer(film, 1.1);
const twistedSummary = summarizeTwistedBilayer(twisted);

console.log(interfaceModel.metadata.match.score);
console.log(interfaceModel.structure.numSites);
console.log(matchSummary.maxAbsStrain);
console.log(interfaceSummary.componentCounts);
console.log(twistedSummary.moireLengthEstimate);

Limits

• commensurate matching currently scans diagonal in-plane repeats only
• no rotational coincidence search or general integer 2D transformation matrices yet
• heterostructure assembly assumes film and substrate slabs are already oriented along lattice c
• no relaxation, strain policy, charge transfer, adhesion energy, or workflow execution
• twisted bilayers are geometric starting structures, not guaranteed commensurate moire supercells