@matteria-js/defects

Deterministic point-defect builders for MATTERIA structures.

This package creates vacancy, substitution, and interstitial structures plus small metadata records. It is a data-preparation layer for viewers and workflows, not a defect-thermodynamics package.

Example

import {
  createInterstitial,
  createSubstitution,
  createVacancy,
  summarizeDefectResult,
} from "@matteria-js/defects";

const vacancy = createVacancy(structure, 0, {
  label: "V_Si",
  defectCharge: -1,
});

const substitution = createSubstitution(structure, 1, "P", {
  label: "P_on_Si",
});

const interstitial = createInterstitial(structure, "Li", [0.25, 0.25, 0.25], {
  siteProperties: { role: "interstitial" },
});

const summary = summarizeDefectResult(vacancy);

console.log(vacancy.structure.numSites);
console.log(substitution.insertedSite?.species);
console.log(interstitial.insertedSite?.fracCoords);
console.log(summary.compositionDelta);

All helpers return a DefectResult containing the new Structure, removed/inserted site snapshots, optional defect charge, label, and metadata. summarizeDefectResult returns a compact JSON-friendly record with final formula, charges, site-count delta, composition delta, site summaries, and metadata keys for workflow reports or viewer side panels. Inputs are not mutated.

Limits

• no formation energies, corrections, chemical potentials, or charge-transition levels
• no automatic defect-site search or random structure generation
• no symmetry-equivalent site grouping yet
• no relaxation, NEB, queue, or workflow execution
• no rendering or viewer state