@matteria-js/phonons

Phonon post-processing models for MATTERIA.

This package is not a phonon solver. It stores and validates phonon band structures, phonon density-of-states data, thermal-property curves, force-constant matrix records, q-point paths, and optional eigenvector payloads that viewer code can use for mode animation.

Current scope:

• QPoint
• PhononBandStructure
• PhononDensityOfStates
• PhononThermalProperties
• PhononForceConstants
• q-point path distances
• frequency ranges
• imaginary-mode detection
• DOS trapezoid integration and cumulative integration
• thermal-property point lookup and interpolation
• source-target force-constant 3x3 matrix lookup
• typed eigenvector payloads with qpoint-branch-atom-xyz layout
• JSON-friendly summaries for bands, DOS, thermal-property curves, and force constants

The API is browser-compatible and Node-compatible. It has no rendering dependency and does not depend on Three.js, WebGL, React, or worker frameworks.

import {
  PhononBandStructure,
  PhononDensityOfStates,
  PhononForceConstants,
  PhononThermalProperties,
} from "@matteria-js/phonons";

const bands = new PhononBandStructure({
  qpoints: [
    { label: "G", fractionalCoordinates: [0, 0, 0] },
    { label: "X", fractionalCoordinates: [0.5, 0, 0] },
  ],
  frequencies: [
    [0, 1.2, 2.4],
    [0.2, 1.4, 2.8],
  ],
});

const distances = bands.pathDistances();
const range = bands.frequencyRange();
const unstableModes = bands.imaginaryModes({ tolerance: 1e-4 });
const bandSummary = bands.summary();

const dos = new PhononDensityOfStates({
  frequencies: [0, 1, 2, 3],
  densities: [0, 2, 2, 0],
});

const states = dos.integrate();
const dosSummary = dos.summary({ minFrequency: 0.5, maxFrequency: 2.5 });

const thermal = new PhononThermalProperties({
  temperatures: [0, 300, 600],
  freeEnergies: [-1.0, -0.8, -0.5],
  entropies: [0, 10, 15],
  heatCapacities: [0, 20, 25],
});

const thermalAtRoomTemperature = thermal.interpolate(300);
const thermalSummary = thermal.summary();

const forceConstants = new PhononForceConstants({
  atomCount: 1,
  unit: "eV/angstrom^2",
  values: [
    1, 0, 0,
    0, 2, 0,
    0, 0, 3,
  ],
});
const forceConstantSummary = forceConstants.summary();

console.log(bandSummary.pathLength, bandSummary.imaginaryModes.count);
console.log(dosSummary.peak.frequency, states);
console.log(thermalSummary.freeEnergy.minimum.temperature);
console.log(forceConstants.getMatrix(0, 0), forceConstantSummary.maxAbsComponent);

@matteria-js/io can populate PhononBandStructure from the supported phonopy-style band.yaml subset, PhononDensityOfStates from phonopy DOS text files, PhononThermalProperties from phonopy thermal_properties.yaml, and PhononForceConstants from text FORCE_CONSTANTS:

import {
  parsePhonopyForceConstants,
  parsePhonopyProjectedDos,
  parsePhonopyThermalPropertiesYaml,
  parsePhonopyTotalDos,
  parsePhonopyYaml,
} from "@matteria-js/io";

const parsedBands = parsePhonopyYaml(phonopyBandYaml);
const parsedTotalDos = parsePhonopyTotalDos(totalDosDat);
const parsedProjectedDos = parsePhonopyProjectedDos(projectedDosDat);
const parsedThermal = parsePhonopyThermalPropertiesYaml(thermalPropertiesYaml);
const parsedForceConstants = parsePhonopyForceConstants(forceConstantsText);

console.log(parsedBands.bandStructure.getFrequenciesAtQPoint(0));
console.log(parsedBands.distances); // Float64Array when path distances are present
console.log(parsedBands.bandStructure.summary({
  pathDistances: parsedBands.distances ?? parsedBands.bandStructure.pathDistances(),
}).pathLength);
console.log(parsedTotalDos.dos.densities);
console.log(parsedProjectedDos.series[0]?.densities);
console.log(parsedThermal.thermalProperties.interpolate(300));
console.log(parsedForceConstants.forceConstants.summary().matrixFrobeniusNormRange);

Keep rendering in application code or viewer adapters. MATTERIA should provide stable typed data, validation, and post-processing helpers.