matterviz 0.4.0 → 0.4.2

package/dist/trajectory/parse/pymatgen.js

@@ -0,0 +1,74 @@
+import * as math from '../../math';
+import { calc_force_stats, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
+import { is_plain_object } from '../../utils';
+import { traj_warn } from './diagnostics';
+// Non-empty array of pymatgen Species-like objects with non-empty string element
+// symbols (predicate so callers get narrowing; rejects e.g. { element: null })
+const is_species_array = (val) => Array.isArray(val) &&
+    val.length > 0 &&
+    val.every((sp) => sp != null &&
+        typeof sp === `object` &&
+        `element` in sp &&
+        typeof sp.element === `string` &&
+        sp.element.trim().length > 0);
+// Parse an already-JSON-parsed pymatgen Trajectory object (detected via @class === 'Trajectory' with species/coords/lattice present)
+export function parse_pymatgen_trajectory(obj, filename) {
+    // Validate shape upfront so malformed input fails with a clear message
+    // (callers gate only on truthiness, not structure) rather than a cryptic `.map` error
+    if (!is_species_array(obj.species)) {
+        throw new TypeError(`Invalid pymatgen Trajectory: 'species' must be a non-empty array of { element } objects`);
+    }
+    if (!Array.isArray(obj.coords)) {
+        throw new TypeError(`Invalid pymatgen Trajectory: 'coords' must be an array of frames`);
+    }
+    const frame_elements = obj.species.map((specie) => specie.element);
+    const coords = obj.coords;
+    const matrix = validate_3x3_matrix(obj.lattice);
+    const frame_properties = obj.frame_properties || [];
+    const frac_to_cart = math.create_frac_to_cart(matrix);
+    const frames = coords.map((frame_coords, idx) => {
+        const positions = frame_coords.map((abc) => frac_to_cart(abc));
+        // Process frame properties to extract numpy arrays
+        const raw_properties = frame_properties[idx] || {};
+        const processed_properties = {};
+        Object.entries(raw_properties).forEach(([key, value]) => {
+            if (is_plain_object(value) && value[`@class`] === `array`) {
+                processed_properties[key] = value.data;
+                if (key === `forces` && Array.isArray(value.data)) {
+                    // Object.assign ignores the null calc_force_stats returns for empty forces
+                    Object.assign(processed_properties, calc_force_stats(value.data));
+                }
+                if (key === `stress` && Array.isArray(value.data)) {
+                    const stress_tensor = value.data;
+                    if (!math.is_square_matrix(stress_tensor, 3)) {
+                        traj_warn(`Invalid stress tensor structure in frame ${idx}`);
+                    }
+                    else {
+                        // Calculate stress components (diagonal elements represent normal stresses)
+                        const normal_stresses = [
+                            stress_tensor[0][0],
+                            stress_tensor[1][1],
+                            stress_tensor[2][2],
+                        ];
+                        processed_properties.stress_max = Math.max(...normal_stresses.map(Math.abs));
+                        // Calculate hydrostatic pressure (negative of mean normal stress)
+                        processed_properties.pressure =
+                            -(normal_stresses[0] + normal_stresses[1] + normal_stresses[2]) / 3;
+                    }
+                }
+            }
+            else {
+                processed_properties[key] = value;
+            }
+        });
+        return create_trajectory_frame(positions, frame_elements, matrix, [true, true, true], idx, processed_properties);
+    });
+    const metadata = {
+        filename,
+        source_format: `pymatgen_trajectory`,
+        frame_count: frames.length,
+        species_list: [...new Set(frame_elements)],
+        periodic_boundary_conditions: [true, true, true],
+    };
+    return { frames, metadata };
+}

package/dist/trajectory/parse/vasp.js

@@ -1,13 +1,15 @@
 import * as math from '../../math';
-import { create_trajectory_frame, is_valid_element_symbol, validate_3x3_matrix, } from '../helpers';
+import { is_elem_symbol } from '../../element/helpers';
+import { create_trajectory_frame, validate_3x3_matrix } from '../helpers';
+import { parse_leading_num } from '../../utils';
 // Parse the 7-line XDATCAR header at lines[start]: title, scale factor, 3 lattice rows
 // (multiplied by scale), element names, element counts
 function parse_xdatcar_header(lines, start) {
-    const scale = parseFloat(lines[start + 1]);
+    const scale = parse_leading_num(lines[start + 1]);
     const rows = lines.slice(start + 2, start + 5).map((line) => line
         .trim()
         .split(/\s+/)
-        .map((val) => parseFloat(val) * scale));
+        .map((val) => Number(val) * scale));
     const names = lines[start + 5].trim().split(/\s+/);
     const counts = lines[start + 6].trim().split(/\s+/).map(Number);
     return { scale, rows, names, counts };
@@ -27,10 +29,12 @@ export function parse_vasp_xdatcar(content, filename) {
     if (element_counts.some((count) => !Number.isFinite(count) || !Number.isInteger(count) || count <= 0)) {
         throw new Error(`XDATCAR contains invalid element counts: expected finite positive integers`);
     }
-    const bad_element = element_names.find((name) => !is_valid_element_symbol(name));
+    const bad_element = element_names.find((name) => !is_elem_symbol(name));
     if (bad_element)
         throw new Error(`Invalid element symbol in XDATCAR: ${bad_element}`);
-    let elements = element_names.flatMap((name, idx) => Array(element_counts[idx]).fill(name));
+    // "Na Cl" + [2, 2] -> [Na, Na, Cl, Cl]
+    const expand_element_counts = (names, counts) => names.flatMap((name, idx) => Array(counts[idx]).fill(name));
+    let elements = expand_element_counts(element_names, element_counts);
     const frames = [];
     let line_idx = 7;
     let frac_to_cart = math.create_frac_to_cart(lattice_matrix);
@@ -46,16 +50,16 @@ export function parse_vasp_xdatcar(content, filename) {
                 lattice_matrix = validate_3x3_matrix(hdr.rows);
                 frac_to_cart = math.create_frac_to_cart(lattice_matrix);
                 if (hdr.names.length === hdr.counts.length &&
-                    hdr.names.every(is_valid_element_symbol) &&
+                    hdr.names.every(is_elem_symbol) &&
                     hdr.counts.every((count) => Number.isInteger(count) && count > 0)) {
-                    elements = hdr.names.flatMap((name, idx) => Array(hdr.counts[idx]).fill(name));
+                    elements = expand_element_counts(hdr.names, hdr.counts);
                 }
             }
         }
         const config_line = lines[config_idx];
         line_idx = config_idx + 1;
-        const step_match = /configuration=\s*(\d+)/.exec(config_line);
-        const step = step_match ? parseInt(step_match[1], 10) : frames.length + 1;
+        const step_match = /configuration=\s*(?<step>\d+)/.exec(config_line);
+        const step = step_match ? Math.trunc(Number(step_match[1])) : frames.length + 1;
         const positions = [];
         for (let idx = 0; idx < elements.length && line_idx < lines.length; idx++) {
             const coords = lines[line_idx].trim().split(/\s+/).slice(0, 3).map(Number);

package/dist/trajectory/parse/vaspout-electronic.d.ts

@@ -0,0 +1,13 @@
+import type { ElectronicBandStructure, ElectronicDos } from '../../spectral';
+import type * as h5wasm from 'h5wasm';
+export interface VaspoutElectronicData {
+    dos: ElectronicDos | null;
+    bands: ElectronicBandStructure | null;
+}
+export declare const read_vaspout_dos: (h5_file: h5wasm.File) => ElectronicDos | null;
+export declare const line_mode_labels: (labels: string[] | null, per_segment_dataset: number | null, n_kpoints: number) => {
+    labels: (string | null)[];
+    per_segment: number;
+} | null;
+export declare const read_vaspout_bands: (h5_file: h5wasm.File, dos?: ElectronicDos | null) => ElectronicBandStructure | null;
+export declare const read_vaspout_electronic: (h5_file: h5wasm.File) => VaspoutElectronicData | null;

package/dist/trajectory/parse/vaspout-electronic.js

@@ -0,0 +1,207 @@
+// Electronic-structure results (DOS + band eigenvalues) from VASP 6.x vaspout.h5.
+//
+// Reads results/electron_dos* into the ElectronicDos shape and
+// results/electron_eigenvalues* (incl. the _kpoints_opt variants written for
+// band paths from KPOINTS_OPT, e.g. by phelel) into the matterviz
+// ElectronicBandStructure shape consumed by the spectral components.
+//
+// Schema reference: ferrox src/io/vasp/hdf5/mod.rs path constants (which follow
+// py4vasp's VASP 6.x schema definitions).
+import { create_frac_to_cart, euclidean_dist, matrix_inverse_3x3, transpose_3x3_matrix, } from '../../math';
+import { pretty_sym_point } from '../../spectral/helpers';
+import { validate_3x3_matrix } from '../helpers';
+import { read_dataset, scale_matrix, to_scalar_number, to_string_array } from './h5-utils';
+const DOS_GROUPS = [`results/electron_dos`, `results/electron_dos_kpoints_opt`];
+const DOS_ENERGY_NAMES = [`energies`, `energy`];
+const DOS_TOTAL_NAMES = [`dos`, `total`];
+const BANDS_GROUPS = [
+    `results/electron_eigenvalues`,
+    `results/electron_eigenvalues_kpoints_opt`,
+];
+const EIGENVALUE_NAMES = [`eigenvalues`, `eigenvalue`];
+const KPOINT_COORD_NAMES = [`kpoints`, `kpoint_coords`];
+const KPOINT_COORD_FALLBACKS = [`results/kpoints/coordinates`];
+const KPOINT_LABEL_PATHS = [
+    `results/kpoints/labels`,
+    `input/kpoints_opt/labels_kpoints`,
+    `input/kpoints/labels_kpoints`,
+];
+const KPOINTS_PER_SEGMENT_PATHS = [
+    `input/kpoints_opt/number_kpoints`,
+    `input/kpoints/number_kpoints`,
+];
+const read_first_dataset = (h5_file, paths) => {
+    for (const path of paths) {
+        const data = read_dataset(h5_file, path);
+        if (data !== null)
+            return data;
+    }
+    return null;
+};
+const is_number_array = (data) => Array.isArray(data) && data.every((val) => typeof val === `number`);
+export const read_vaspout_dos = (h5_file) => {
+    for (const group of DOS_GROUPS) {
+        const energies = read_first_dataset(h5_file, DOS_ENERGY_NAMES.map((name) => `${group}/${name}`));
+        const total = read_first_dataset(h5_file, DOS_TOTAL_NAMES.map((name) => `${group}/${name}`));
+        if (!is_number_array(energies) || !Array.isArray(total))
+            continue;
+        // Total DOS is (n_spin, n_energies) in real files but tolerate a flat array
+        const spin_channels = is_number_array(total) ? [total] : total;
+        const densities = spin_channels[0];
+        if (!is_number_array(densities) || densities.length !== energies.length)
+            continue;
+        const spin_down = spin_channels[1];
+        const spin_polarized = is_number_array(spin_down) && spin_down.length === energies.length;
+        const efermi = to_scalar_number(read_dataset(h5_file, `${group}/efermi`));
+        return {
+            type: `electronic`,
+            energies,
+            densities,
+            ...(spin_polarized ? { spin_down_densities: spin_down, spin_polarized } : {}),
+            ...(efermi !== null ? { efermi } : {}),
+        };
+    }
+    return null;
+};
+// Real (row-vector) lattice for k-path distances: prefer the relaxed structure's
+// lattice, fall back to the POSCAR input one (bands-only files keep only the latter)
+const read_lattice = (h5_file) => {
+    for (const [lattice_path, scale_path] of [
+        [`results/positions/lattice_vectors`, `results/positions/scale`],
+        [`input/poscar/lattice_vectors`, `input/poscar/scale`],
+    ]) {
+        const lattice_data = read_dataset(h5_file, lattice_path);
+        if (!lattice_data)
+            continue;
+        try {
+            const scale = to_scalar_number(read_dataset(h5_file, scale_path)) ?? 1;
+            return scale_matrix(validate_3x3_matrix(lattice_data), scale);
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+};
+// B = 2π (A⁻¹)ᵀ for row-vector real lattice A; falls back to 2π·identity so
+// bands-only files without any (invertible) lattice still get monotonic path
+// distances.
+const reciprocal_lattice = (lattice) => {
+    let recip = [
+        [1, 0, 0],
+        [0, 1, 0],
+        [0, 0, 1],
+    ];
+    try {
+        if (lattice)
+            recip = transpose_3x3_matrix(matrix_inverse_3x3(lattice));
+    }
+    catch {
+        /* singular lattice: keep identity */
+    }
+    return recip.map((row) => row.map((val) => val * 2 * Math.PI));
+};
+// VASP line-mode label layout: 2 labels per path segment of `per_segment` points
+// (e.g. 12 labels + 51 points/segment = 306 k-points). Returns per-kpoint labels
+// (null between endpoints) or null when the layout doesn't match. When the
+// input/kpoints*/number_kpoints dataset is absent (not all writers emit it),
+// the segment length is inferred from the label/k-point counts instead.
+export const line_mode_labels = (labels, per_segment_dataset, n_kpoints) => {
+    if (!labels || labels.length < 2 || labels.length % 2 !== 0)
+        return null;
+    const n_segments = labels.length / 2;
+    const per_segment = per_segment_dataset ?? n_kpoints / n_segments;
+    if (!Number.isInteger(per_segment) || per_segment < 2)
+        return null;
+    if (n_segments * per_segment !== n_kpoints)
+        return null;
+    const per_kpoint = Array.from({ length: n_kpoints }, () => null);
+    for (let seg = 0; seg < n_segments; seg++) {
+        per_kpoint[seg * per_segment] = pretty_sym_point(labels[2 * seg]);
+        per_kpoint[seg * per_segment + per_segment - 1] = pretty_sym_point(labels[2 * seg + 1]);
+    }
+    return { labels: per_kpoint, per_segment };
+};
+export const read_vaspout_bands = (h5_file, dos = read_vaspout_dos(h5_file)) => {
+    for (const group of BANDS_GROUPS) {
+        const eigenvalues = read_first_dataset(h5_file, EIGENVALUE_NAMES.map((name) => `${group}/${name}`));
+        const kpoint_data = read_first_dataset(h5_file, [
+            ...KPOINT_COORD_NAMES.map((name) => `${group}/${name}`),
+            ...KPOINT_COORD_FALLBACKS,
+        ]);
+        if (!Array.isArray(eigenvalues) || !Array.isArray(kpoint_data))
+            continue;
+        // eigenvalues shape: (n_spin, n_kpoints, n_bands)
+        const n_kpoints = kpoint_data.length;
+        const spin_up = eigenvalues[0];
+        if (!Array.isArray(spin_up) || spin_up.length !== n_kpoints || n_kpoints === 0)
+            continue;
+        const n_bands = spin_up[0]?.length ?? 0;
+        if (n_bands === 0)
+            continue;
+        // [n_kpoints][n_bands] -> [n_bands][n_kpoints] as the spectral components expect
+        const transpose = (spin_eigs) => Array.from({ length: n_bands }, (_, band_idx) => spin_eigs.map((kpt_eigs) => kpt_eigs[band_idx]));
+        const bands = transpose(spin_up);
+        const spin_down = eigenvalues[1];
+        const spin_down_bands = Array.isArray(spin_down) && spin_down.length === n_kpoints
+            ? transpose(spin_down)
+            : undefined;
+        const recip = reciprocal_lattice(read_lattice(h5_file));
+        const line_mode = line_mode_labels(to_string_array(read_first_dataset(h5_file, [`${group}/kpoints_labels`, ...KPOINT_LABEL_PATHS])), to_scalar_number(read_first_dataset(h5_file, KPOINTS_PER_SEGMENT_PATHS)), n_kpoints);
+        const labels = line_mode?.labels ?? null;
+        const distance = [];
+        const qpoints = [];
+        let path_length = 0;
+        let prev_cart = null;
+        const labels_dict = {};
+        const frac_to_cart = create_frac_to_cart(recip);
+        for (const [kpt_idx, kpt] of kpoint_data.entries()) {
+            const frac = [kpt[0] ?? 0, kpt[1] ?? 0, kpt[2] ?? 0];
+            const cart = frac_to_cart(frac);
+            if (prev_cart)
+                path_length += euclidean_dist(cart, prev_cart);
+            prev_cart = cart;
+            distance.push(path_length);
+            const label = labels?.[kpt_idx] ?? null;
+            qpoints.push({ label, frac_coords: frac });
+            if (label)
+                labels_dict[label] = frac;
+        }
+        // One branch per labeled line-mode segment, else a single whole-path branch
+        const per_segment = line_mode?.per_segment ?? 0;
+        const branches = [];
+        if (labels && Number.isInteger(per_segment) && per_segment >= 2) {
+            for (let start = 0; start < n_kpoints; start += per_segment) {
+                const end = start + per_segment - 1;
+                branches.push({
+                    start_index: start,
+                    end_index: end,
+                    name: `${qpoints[start]?.label ?? `?`}-${qpoints[end]?.label ?? `?`}`,
+                });
+            }
+        }
+        else
+            branches.push({ start_index: 0, end_index: n_kpoints - 1, name: `path` });
+        const efermi = dos?.efermi;
+        return {
+            qpoints,
+            branches,
+            distance,
+            bands,
+            ...(spin_down_bands ? { spin_down_bands } : {}),
+            nb_bands: n_bands,
+            labels_dict,
+            recip_lattice: { matrix: recip },
+            is_spin_polarized: spin_down_bands !== undefined,
+            ...(efermi !== undefined ? { efermi } : {}),
+        };
+    }
+    return null;
+};
+// Bundle DOS + bands; null when the file carries neither (so callers can keep
+// their "no structure data" error for files with nothing to show).
+export const read_vaspout_electronic = (h5_file) => {
+    const dos = read_vaspout_dos(h5_file);
+    const bands = read_vaspout_bands(h5_file, dos);
+    return dos || bands ? { dos, bands } : null;
+};

package/dist/trajectory/parse/vaspout-h5.d.ts

@@ -0,0 +1,5 @@
+import type * as h5wasm from 'h5wasm';
+import type { TrajectoryType } from '../index';
+export declare const is_vaspout_h5_file: (h5_file: h5wasm.File) => boolean;
+export declare function parse_vaspout_h5_file(h5_file: h5wasm.File): TrajectoryType;
+export declare function parse_vaspout_h5(buffer: ArrayBuffer, filename?: string): Promise<TrajectoryType>;

package/dist/trajectory/parse/vaspout-h5.js

@@ -0,0 +1,284 @@
+// Parser for VASP 6.x HDF5 output (vaspout.h5, written with LH5=.TRUE.).
+// Reads the ionic-relaxation trajectory from intermediate/ion_dynamics (with
+// per-frame energy/forces so convergence plots come for free) and falls back
+// to the final structure in results/positions for static (NSW=0) runs, which
+// render as single-frame trajectories (structure only, plots hidden).
+//
+// Tolerates files from incomplete/running calculations: datasets flushed
+// mid-write may disagree on step counts (e.g. 5 energies but 4 position
+// frames), so frame count is the minimum over required datasets and per-step
+// reads never index past any dataset's end.
+//
+// Electronic results (results/electron_dos, results/electron_eigenvalues*)
+// are read by ./vaspout-electronic.ts and attached as metadata.electronic;
+// vaspwave.h5 charge density is handled by isosurface/parse-vaspwave.ts.
+//
+// Schema reference: ferrox src/io/vasp/hdf5/mod.rs (which follows py4vasp's
+// VASP 6.x schema definitions).
+import { calc_lattice_params, create_frac_to_cart } from '../../math';
+import { count_elements, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
+import { expand_ion_types, is_hdf5_group, read_dataset, scale_matrix, to_number_array, to_scalar_number, to_string_array, with_h5_file, } from './h5-utils';
+import { read_vaspout_dos, read_vaspout_electronic } from './vaspout-electronic';
+const FINAL_ION_TYPES = `results/positions/ion_types`;
+const FINAL_ION_COUNTS = `results/positions/number_ion_types`;
+const FINAL_LATTICE = `results/positions/lattice_vectors`;
+const FINAL_POSITIONS = `results/positions/position_ions`;
+const FINAL_SCALE = `results/positions/scale`;
+const TRAJ_SCALE = `intermediate/ion_dynamics/scale`;
+const TRAJ_LATTICE = `intermediate/ion_dynamics/lattice_vectors`;
+const TRAJ_POSITIONS = `intermediate/ion_dynamics/position_ions`;
+const TRAJ_FORCES = `intermediate/ion_dynamics/forces`;
+const ENERGY_VALUES = `intermediate/ion_dynamics/energies`;
+const ENERGY_LABELS = `intermediate/ion_dynamics/energies_tags`;
+const OSZICAR_ROWS = `intermediate/ion_dynamics/oszicar`;
+const OSZICAR_LABELS = `intermediate/ion_dynamics/oszicar_label`;
+const ELECTRONIC_STEP_ENERGIES = `intermediate/electronic_steps/energies`;
+// vaspout.h5 root groups per the VASP 6.x schema. torch-sim files use flat
+// dataset names (positions/atomic_numbers/...) and never these groups.
+export const is_vaspout_h5_file = (h5_file) => [`results`, `intermediate`].some((name) => is_hdf5_group(h5_file.get(name))) &&
+    [`input`, `version`, `results`, `intermediate`].filter((name) => is_hdf5_group(h5_file.get(name))).length >= 2;
+// Final-structure datasets may carry a leading singleton step axis
+// ([1, 3, 3] lattices, [1, n_atoms, 3] positions) depending on VASP version.
+const squeeze_leading_axis = (data) => Array.isArray(data) &&
+    data.length === 1 &&
+    Array.isArray(data[0]) &&
+    Array.isArray(data[0][0])
+    ? data[0]
+    : data;
+// VASP writes several energy kinds per step; energies_tags names the columns.
+// Prefer the free energy (TOTEN), then energy(sigma->0), then column 0.
+const pick_energy_column = (tags) => {
+    if (!tags)
+        return { idx: 0, tag: null };
+    for (const needle of [`TOTEN`, `sigma->0`]) {
+        const idx = tags.findIndex((tag) => tag.includes(needle));
+        if (idx !== -1)
+            return { idx, tag: tags[idx] };
+    }
+    return { idx: 0, tag: tags[0] ?? null };
+};
+const finite_or_null = (value) => typeof value === `number` && Number.isFinite(value) ? value : null;
+// OSZICAR rows are [total_scf_rows, n_cols] with oszicar_label naming columns
+// (N, E, dE, d eps, ncg, rms, rms(c)). The N counter resets to 1 at each new
+// ionic step, which is how rows group into ionic steps (same as ferrox).
+const read_oszicar_history = (h5_file) => {
+    const rows = read_dataset(h5_file, OSZICAR_ROWS);
+    const labels = to_string_array(read_dataset(h5_file, OSZICAR_LABELS));
+    if (!rows || !labels)
+        return null;
+    const col = (name) => labels.findIndex((label) => label.trim() === name);
+    const [n_col, energy_col] = [col(`N`), col(`E`)];
+    if (n_col < 0 || energy_col < 0)
+        return null;
+    const [delta_col, rms_col, charge_rms_col] = [col(`dE`), col(`rms`), col(`rms(c)`)];
+    const ionic_steps = [];
+    let current = null;
+    let previous_scf_counter = Infinity;
+    for (const row of rows) {
+        const scf_counter = row[n_col];
+        const energy = finite_or_null(row[energy_col]);
+        if (energy === null || !Number.isFinite(scf_counter))
+            return null;
+        if (scf_counter <= previous_scf_counter || !current) {
+            current = { energies: [], energy_deltas: [], rms: [], charge_rms: [] };
+            ionic_steps.push(current);
+        }
+        current.energies.push(energy);
+        current.energy_deltas.push(delta_col >= 0 ? finite_or_null(row[delta_col]) : null);
+        current.rms.push(rms_col >= 0 ? finite_or_null(row[rms_col]) : null);
+        current.charge_rms.push(charge_rms_col >= 0 ? finite_or_null(row[charge_rms_col]) : null);
+        previous_scf_counter = scf_counter;
+    }
+    return ionic_steps.length > 0 ? ionic_steps : null;
+};
+// Fallback when the OSZICAR mirror is absent: the explicit per-ionic-step SCF
+// energy dataset (shape [n_ionic, n_scf]); deltas derived from consecutive
+// energies, no density residuals available.
+const read_electronic_step_history = (h5_file) => {
+    const rows = read_dataset(h5_file, ELECTRONIC_STEP_ENERGIES);
+    if (!rows)
+        return null;
+    const ionic_steps = rows
+        .map((row) => {
+        const energies = (Array.isArray(row) ? row : [row]).filter((val) => typeof val === `number` && Number.isFinite(val));
+        return {
+            energies,
+            energy_deltas: energies.map((energy, idx) => idx > 0 ? energy - energies[idx - 1] : null),
+            rms: energies.map(() => null),
+            charge_rms: energies.map(() => null),
+        };
+    })
+        .filter((step) => step.energies.length > 0);
+    return ionic_steps.length > 0 ? ionic_steps : null;
+};
+const read_scf_history = (h5_file) => read_oszicar_history(h5_file) ?? read_electronic_step_history(h5_file);
+// Convergence fields (|dE|, density residuals) for one SCF step; negative idx
+// counts from the end (-1 = final step). Shared by the per-frame summary below
+// and the SCF pseudo-frame expansion for single-point runs.
+const scf_step_metadata = (scf, idx) => {
+    const metadata = {};
+    const delta = scf.energy_deltas.at(idx);
+    if (delta != null)
+        metadata.scf_energy_delta = Math.abs(delta);
+    const rms = scf.rms.at(idx);
+    if (rms != null)
+        metadata.scf_rms = rms;
+    const charge_rms = scf.charge_rms.at(idx);
+    if (charge_rms != null)
+        metadata.scf_charge_rms = charge_rms;
+    return metadata;
+};
+// Final-SCF-step summary attached to each ionic frame so relax trajectories
+// plot SCF effort/residuals alongside energy and force_max.
+const scf_frame_metadata = (scf) => {
+    if (!scf || scf.energies.length === 0)
+        return {};
+    const metadata = {
+        n_scf_steps: scf.energies.length,
+        ...scf_step_metadata(scf, -1),
+    };
+    // interrupted writers can drop the final dE entry: derive it from the last two energies
+    if (!(`scf_energy_delta` in metadata) && scf.energies.length >= 2) {
+        metadata.scf_energy_delta = Math.abs(scf.energies.at(-1) - scf.energies.at(-2));
+    }
+    return metadata;
+};
+// Bands/DOS-only outputs (e.g. phelel band-path files) carry no (complete)
+// structure datasets but still have renderable electronic results: surface
+// them as a zero-frame trajectory the webview routes to the spectral
+// components. Files with neither structure nor electronic data throw.
+const electronic_only_trajectory = (h5_file, missing) => {
+    const electronic = read_vaspout_electronic(h5_file);
+    if (!electronic) {
+        throw new Error(`vaspout.h5 file has no structure data (missing ${missing}) — ` +
+            `and no electron_dos/electron_eigenvalues results either`);
+    }
+    return {
+        frames: [],
+        metadata: {
+            source_format: `vaspout_h5`,
+            frame_count: 0,
+            electronic,
+            vaspout_electronic_only: true,
+        },
+    };
+};
+export function parse_vaspout_h5_file(h5_file) {
+    const ion_types = to_string_array(read_dataset(h5_file, FINAL_ION_TYPES));
+    const ion_counts = to_number_array(read_dataset(h5_file, FINAL_ION_COUNTS));
+    if (!ion_types || !ion_counts) {
+        return electronic_only_trajectory(h5_file, `${FINAL_ION_TYPES} / ${FINAL_ION_COUNTS}`);
+    }
+    // expand_ion_types throws on length mismatch and unknown symbols (fail loudly)
+    const elements = expand_ion_types(ion_types, ion_counts);
+    // POSCAR-style universal scaling factor; scalar in real files, but some
+    // writers store it as a 1-element array. Intermediate ion-dynamics frames
+    // carry their own scale (py4vasp's trajectory Cell reads
+    // intermediate/ion_dynamics/scale), distinct from the final-structure scale.
+    const scale = to_scalar_number(read_dataset(h5_file, FINAL_SCALE)) ?? 1;
+    const traj_scale = to_scalar_number(read_dataset(h5_file, TRAJ_SCALE)) ?? scale;
+    const traj_positions = read_dataset(h5_file, TRAJ_POSITIONS);
+    const traj_lattices = read_dataset(h5_file, TRAJ_LATTICE);
+    const traj_forces = read_dataset(h5_file, TRAJ_FORCES);
+    const energies = read_dataset(h5_file, ENERGY_VALUES);
+    const energy_tags = to_string_array(read_dataset(h5_file, ENERGY_LABELS));
+    const { idx: energy_col, tag: energy_tag } = pick_energy_column(energy_tags);
+    const scf_history = read_scf_history(h5_file);
+    const frames = [];
+    let dropped_steps = 0;
+    // Shared frame assembly for the per-step trajectory path and the
+    // final-structure fallback: validate + scale the lattice, convert fractional
+    // positions to Cartesian, attach volume/SCF/energy (and optional forces).
+    const build_frame = (lattice_data, frac_positions, step, scf, raw_energy, forces, frame_scale) => {
+        const lattice = scale_matrix(validate_3x3_matrix(lattice_data), frame_scale);
+        const frac_to_cart = create_frac_to_cart(lattice);
+        const positions = frac_positions.map((frac) => frac_to_cart(frac));
+        const metadata = {
+            volume: calc_lattice_params(lattice).volume,
+            ...scf_frame_metadata(scf),
+        };
+        const energy = finite_or_null(raw_energy);
+        if (energy !== null)
+            metadata.energy = energy;
+        if (Array.isArray(forces))
+            metadata.forces = forces;
+        return create_trajectory_frame(positions, elements, lattice, [true, true, true], step, metadata);
+    };
+    if (traj_positions && traj_lattices) {
+        // A torn file's datasets may disagree on step count; never index past the
+        // shortest required one (forces/energies are optional per step).
+        const n_steps = Math.min(traj_positions.length, traj_lattices.length);
+        for (let step = 0; step < n_steps; step++) {
+            try {
+                frames.push(build_frame(traj_lattices[step], traj_positions[step], step, scf_history?.[step], energies?.[step]?.[energy_col], traj_forces?.[step], traj_scale));
+            }
+            catch {
+                // Torn final step: keep the frames parsed so far.
+                dropped_steps = n_steps - step;
+                break;
+            }
+        }
+    }
+    // Static (NSW=0) runs have no intermediate/ion_dynamics group at all; fall
+    // back to the final structure so the file still opens as a 1-frame view.
+    if (frames.length === 0) {
+        const final_lattice_data = squeeze_leading_axis(read_dataset(h5_file, FINAL_LATTICE));
+        const final_positions_data = squeeze_leading_axis(read_dataset(h5_file, FINAL_POSITIONS));
+        if (!final_lattice_data || !final_positions_data) {
+            // Ion species exist but geometry is missing/torn — a bands/DOS-only
+            // file can still render its electronic results.
+            return electronic_only_trajectory(h5_file, `${TRAJ_POSITIONS} / ${FINAL_POSITIONS}`);
+        }
+        try {
+            frames.push(build_frame(final_lattice_data, final_positions_data, 0, scf_history?.at(-1), energies?.at(-1)?.[energy_col], undefined, scale));
+        }
+        catch {
+            // Geometry datasets present but malformed (file torn mid-write): same
+            // electronic-only fallback as when they're missing entirely.
+            return electronic_only_trajectory(h5_file, `${FINAL_LATTICE} / ${FINAL_POSITIONS}`);
+        }
+    }
+    // Static/single-point runs (one ionic step) get their SCF electronic steps
+    // expanded into pseudo-frames: the structure stays fixed while energy, |dE|,
+    // and the density residuals (incl. OSZICAR's rms(c) charge-density residual)
+    // plot per SCF step — the convergence view that matters when watching a
+    // running static job. Multi-point plots need >=2 frames, so this also makes
+    // single-point files plottable at all.
+    let frames_are_scf_steps = false;
+    const only_scf = scf_history?.length === 1 ? scf_history[0] : null;
+    if (frames.length === 1 && only_scf && only_scf.energies.length >= 2) {
+        const base_frame = frames[0];
+        frames.length = 0;
+        for (const [scf_idx, scf_energy] of only_scf.energies.entries()) {
+            const metadata = {
+                energy: scf_energy,
+                volume: base_frame.metadata?.volume,
+                ...scf_step_metadata(only_scf, scf_idx),
+            };
+            frames.push({ structure: base_frame.structure, step: scf_idx, metadata });
+        }
+        frames_are_scf_steps = true;
+    }
+    // Trajectory views only ever render the DOS panel, so skip reading the
+    // (potentially large) eigenvalue arrays here — bands are read only on the
+    // electronic-only paths above, which are the sole consumers.
+    const dos = read_vaspout_dos(h5_file);
+    return {
+        frames,
+        metadata: {
+            source_format: `vaspout_h5`,
+            frame_count: frames.length,
+            num_atoms: elements.length,
+            element_counts: count_elements(elements),
+            periodic_boundary_conditions: [true, true, true],
+            has_cell_info: true,
+            ...(energy_tag ? { energy_tag } : {}),
+            ...(dropped_steps > 0 ? { dropped_steps } : {}),
+            ...(frames_are_scf_steps ? { frames_are_scf_steps: true } : {}),
+            ...(dos ? { electronic: { dos, bands: null } } : {}),
+        },
+    };
+}
+export async function parse_vaspout_h5(buffer, filename) {
+    return with_h5_file(buffer, filename, parse_vaspout_h5_file);
+}