@matteria-js/electronic

Electronic-structure post-processing primitives for MATTERIA.

This package does not run DFT calculations and does not render plots. It stores and analyzes data that comes from VASP, Quantum ESPRESSO, PyProcar-like workflows, Materials Project records, or viewer-side imports.

Included

• Spin channels for spin-resolved data.
• KPoint metadata.
• BandStructure with typed-array band storage.
• DensityOfStates with typed-array energy and density grids.
• ProjectedDensityOfStates records for site, element, orbital, and spin projections.
• Fermi-level shifting helpers.
• VBM, CBM, direct gap, indirect gap, and metallic crossing analysis for simple band arrays.
• Parabolic effective-mass fitting from band energies and k-point path distances.
• Trapezoidal DOS integration with optional energy windows.
• JSON-friendly summaries for band, DOS, and projected-DOS metadata.

Band arrays use the common post-processing shape:

bands[bandIndex][kpointIndex]

Effective-mass fitting expects reciprocal-space path distances in inverse angstrom. If distances are omitted, every KPoint must include cartesian reciprocal coordinates.

Example

import { BandStructure, DensityOfStates, Spin, analyzeBandGap, fitEffectiveMass } from "@matteria-js/electronic";

const bandStructure = new BandStructure({
  kpoints: [
    { fracCoords: [0, 0, 0], cartCoords: [0, 0, 0], label: "G" },
    { fracCoords: [0.25, 0, 0], cartCoords: [0.25, 0, 0] },
    { fracCoords: [0.5, 0, 0], cartCoords: [0.5, 0, 0], label: "X" },
  ],
  fermiLevel: 0,
  bands: {
    [Spin.Up]: [
      [-1.0, -0.5, -0.2],
      [0.4, 0.6, 0.9],
    ],
  },
});

const gap = analyzeBandGap(bandStructure);
const bandSummary = bandStructure.summary();
console.log(gap.gap, gap.isDirect);
console.log(bandSummary.totalBandCount, bandSummary.energyRange);

const electronMass = fitEffectiveMass(bandStructure, {
  bandIndex: 1,
  kpointIndex: 1,
  carrier: "electron",
});
console.log(electronMass.effectiveMass); // in electron-mass units

const dos = new DensityOfStates({
  energies: [-1, 0, 1],
  densities: [0, 2, 0],
  fermiLevel: 0,
});

console.log(dos.integrate());
console.log(dos.summary({ fromEnergy: -0.5, toEnergy: 0.5 }).integratedDensity);

The data structures are browser and Node.js compatible. Plotting, Three.js geometry, and UI state belong in viewer packages, not here.

@matteria-js/io can populate DensityOfStates and ProjectedDensityOfStates from VASP DOSCAR, BandStructure from VASP EIGENVAL, and QE/VASP projection data from parser-specific files. More code-specific parsers should live in @matteria-js/io and return these electronic data containers.