@matteria-js/project

Serializable calculation project summaries for MATTERIA.

This package accepts a lightweight manifest of files and text snippets, then returns a JSON-friendly CalculationReport. It is intentionally independent of @matteria-js/io, but it accepts the same structural fields used by IO project manifests (path, name, role, kind, size/sizeBytes, and optional text snippets), so browser and Node callers can provide data from any source.

import { createCalculationReport } from "@matteria-js/project";

const report = createCalculationReport({
  files: [
    {
      path: "OUTCAR",
      role: "outcar",
      text: "free  energy   TOTEN  =       -12.3 eV\nE-fermi : 4.5",
    },
    {
      path: "XDATCAR",
      role: "xdatcar",
      kind: "trajectory",
      text: "Direct configuration= 1\n0 0 0\nDirect configuration= 2\n0.1 0 0",
    },
  ],
});

console.log(report.finalEnergy);
console.log(report.trajectory.steps);
console.log(report.sourceSummary.categories);

When a caller already has an @matteria-js/io-style DFT project manifest, use the structural manifest bridge. It can summarize parsed manifest fields even when raw file text was not retained:

import { createCalculationReportFromManifest } from "@matteria-js/project";

const report = createCalculationReportFromManifest(dftProjectManifest);

console.log(report.sourceFiles[0]?.hasText); // reflects original source text availability
console.log(report.sourceSummary.knownSizeBytes);
console.log(report.finalEnergy);

The parser is conservative. It recognizes common VASP and Quantum ESPRESSO snippets for calculation type, final energy, Fermi level, magnetization, force, stress, and basic convergence markers. VASP XDATCAR text can contribute trajectory step counts, parsed QE pw.x manifest summaries can contribute calculation-output metrics without retaining raw text, and QE pp.x snippets or parsed manifest summaries can identify volumetric post-processing reports. sourceSummary reports file counts, known bytes, text availability, role/kind/format counters, and conservative artifact buckets for dashboards. This package still does not try to replace full output parsers.