@matteria-js/surfaces

Surface and slab helpers for MATTERIA structures.

This package prepares data for slab, adsorption, STM, and work-function workflows. It does not run DFT, choose terminations automatically, extract isosurfaces, or render geometry.

Included

• Miller plane metadata from a lattice or structure.
• Oriented slab construction with vacuum through @matteria-js/transformations.
• Surface layer detection along a lattice axis.
• Candidate termination enumeration from detected layer gaps on already-oriented slabs.
• Ontop, bridge, and hollow adsorption-site generation for top, bottom, or both surfaces.
• Adsorbate placement with site metadata.
• STM plane metadata for viewer or workflow code.
• Simple work-function estimates from planar potential profiles.
• JSON-friendly slab and adsorption-site summaries for workflow reports and viewer side panels.

Example

import {
  generateAdsorptionSites,
  getMillerPlane,
  makeSurfaceSlab,
  placeAdsorbate,
  summarizeAdsorptionSites,
  summarizeSurfaceSlab,
  enumerateSurfaceTerminations,
  summarizeSurfaceTerminations,
} from "@matteria-js/surfaces";

const plane = getMillerPlane(structure, [0, 0, 1]);
const slab = makeSurfaceSlab(structure, {
  millerIndex: [0, 0, 1],
  minSlabSize: 12,
  minVacuumSize: 15,
});

const sites = generateAdsorptionSites(slab.structure, {
  side: "top",
  height: 1.8,
  kinds: "all",
});
const terminations = enumerateSurfaceTerminations(slab.structure);

const withHydrogen = placeAdsorbate(slab.structure, "H", sites[0]);
const slabSummary = summarizeSurfaceSlab(slab);
const siteSummary = summarizeAdsorptionSites(sites);
const terminationSummary = summarizeSurfaceTerminations(terminations);

console.log(plane.dSpacing);
console.log(slab.layers.at(-1)?.siteIndices);
console.log(withHydrogen.numSites);
console.log(slabSummary.emptyNormalSpanEstimate);
console.log(siteSummary.labels);
console.log(terminationSummary.labels);

Limits

• slab construction assumes the input structure is already oriented with the surface normal along lattice c
• no Miller-index reorientation, automatic termination choice, reconstruction, or dipole correction policy yet
• termination enumeration reports detected layer-gap candidates only; it collapses repeated lower/upper layer formula pairs by default and does not create new slabs or rank surface energies
• adsorption-site generation covers ontop sites by default and opt-in bridge pairs plus hollow triplets on detected surface layers
• no automatic molecule-orientation or coverage enumeration
• STM helpers return plane metadata only; they do not sample charge density or render an image
• work-function helpers average a caller-provided planar potential profile; they do not parse LOCPOT directly