matterviz 0.4.1 → 0.4.3

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,4 @@
+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;

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

@@ -0,0 +1,281 @@
+// 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, } 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 } } : {}),
+        },
+    };
+}

package/dist/trajectory/parse/xyz.js

@@ -1,17 +1,17 @@
 import * as math from '../../math';
-import { coerce_elem_symbol } from '../../element';
+import { coerce_elem_symbol } from '../../element/helpers';
 import { calc_force_stats, create_trajectory_frame, iter_xyz_frames, } from '../helpers';
-import { traj_warn } from './diagnostics';
+import { get_traj_parse_warnings, traj_warn } from './diagnostics';
 // Resolve species/pos/forces column offsets from an extxyz Properties string of
 // name:type:ncols triples (e.g. "species:S:1:pos:R:3:forces:R:3"), falling back
 // to the conventional "symbol x y z" layout when absent or malformed
 function parse_extxyz_columns(comment) {
-    const fields = /Properties\s*=\s*"?([^"\s]+)"?/i.exec(comment)?.[1].split(`:`) ?? [];
+    const fields = /Properties\s*=\s*"?(?<properties>[^"\s]+)"?/i.exec(comment)?.[1].split(`:`) ?? [];
     // Well-formed Properties is name:type:ncols triples; a non-multiple of 3 is malformed,
     // so bail to the conventional default rather than trusting a partial layout
     let layout = fields.length % 3 === 0 ? {} : null;
     for (let idx = 0, offset = 0; layout && idx + 3 <= fields.length; idx += 3) {
-        const ncols = parseInt(fields[idx + 2], 10);
+        const ncols = Math.trunc(Number(fields[idx + 2]));
         if (Number.isInteger(ncols) && ncols > 0) {
             layout[fields[idx].toLowerCase()] = { offset, ncols };
             offset += ncols;
@@ -26,11 +26,54 @@ function parse_extxyz_columns(comment) {
 }
 // Parse Lattice="ax ay az bx by bz cx cy cz" from an extxyz comment line
 function parse_extxyz_lattice(comment) {
-    const vals = /Lattice\s*=\s*"([^"]+)"/i.exec(comment)?.[1].trim().split(/\s+/).map(Number);
+    const vals = /Lattice\s*=\s*"(?<lattice>[^"]+)"/i
+        .exec(comment)?.[1]
+        .trim()
+        .split(/\s+/)
+        .map(Number);
     if (vals?.length !== 9 || !vals.every(Number.isFinite))
         return undefined;
     return [vals.slice(0, 3), vals.slice(3, 6), vals.slice(6, 9)];
 }
+const EXTXYZ_BOOL = new Map([
+    [`t`, true],
+    [`true`, true],
+    [`1`, true],
+    [`f`, false],
+    [`false`, false],
+    [`0`, false],
+]); // Map avoids Object.prototype hits (e.g. `constructor`)
+function lookup_extxyz_bools(tokens) {
+    if (tokens.length !== 3)
+        return undefined;
+    const [first, second, third] = tokens.map((token) => EXTXYZ_BOOL.get(token.toLowerCase()));
+    if (first === undefined || second === undefined || third === undefined)
+        return undefined;
+    return [first, second, third];
+}
+function parse_extxyz_pbc(comment) {
+    const match = /\bpbc\s*=\s*(?:"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<bare>\S+(?:\s+\S+){0,2}))/iu.exec(comment);
+    const raw = (match?.groups?.double ?? match?.groups?.single ?? match?.groups?.bare)?.trim();
+    if (!raw)
+        return undefined;
+    // Stop before a following `Key=` token that bare matching may have swallowed
+    const split = raw.split(/\s+/u);
+    const cut = split.findIndex((word) => word.includes(`=`));
+    const words = cut === -1 ? split : split.slice(0, cut);
+    if (words.length === 0)
+        return undefined;
+    const [first] = words;
+    if (first.length === 3) {
+        const compact = lookup_extxyz_bools(first.split(``));
+        if (compact)
+            return compact;
+    }
+    if (words.length === 1) {
+        const only = EXTXYZ_BOOL.get(first.toLowerCase());
+        return only === undefined ? undefined : [only, only, only];
+    }
+    return lookup_extxyz_bools(words.slice(0, 3));
+}
 // Keys anchored at ^|\s and followed by [=:] so single-letter keys (E/V/P/T) don't match mid-word
 const make_pattern = (keys) => new RegExp(`(?:^|\\s)(?:${keys})\\s*[=:]\\s*([-+]?\\d*\\.?\\d+(?:[eE][-+]?\\d+)?)`, `i`);
 const METADATA_PATTERNS = {
@@ -47,10 +90,10 @@ export function parse_xyz_comment_metadata(comment) {
     for (const [key, pattern] of Object.entries(METADATA_PATTERNS)) {
         const match = pattern.exec(comment);
         if (match)
-            properties[key] = parseFloat(match[1]);
+            properties[key] = Number(match[1]);
     }
-    const step = /(?:^|\s)(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i.exec(comment)?.[1];
-    return { step: step ? parseInt(step, 10) : undefined, properties };
+    const step = /(?:^|\s)(?:step|frame|ionic_step)\s*[=:]?\s*(?<step>\d+)/i.exec(comment)?.[1];
+    return { step: step ? Math.trunc(Number(step)) : undefined, properties };
 }
 // Parse num_atoms atom lines starting at lines[start], reading species/pos/forces from
 // their Properties-declared column offsets; invalid atoms are skipped with a warning.
@@ -92,11 +135,18 @@ export function build_xyz_frame(lines, frame, opts) {
     const { start, num_atoms, comment } = frame;
     const { step, properties } = parse_xyz_comment_metadata(comment);
     const lattice_matrix = parse_extxyz_lattice(comment);
+    const parsed_pbc = parse_extxyz_pbc(comment);
+    if (parsed_pbc === undefined &&
+        /\bpbc\s*=/iu.test(comment) &&
+        !get_traj_parse_warnings().some((msg) => msg.includes(`Invalid EXTXYZ pbc`))) {
+        traj_warn(`Invalid EXTXYZ pbc (first seen in ${opts.frame_label}); defaulting to fully periodic [T, T, T]`);
+    }
+    const pbc = parsed_pbc ?? [true, true, true];
     const { elements, positions, force_stats } = parse_xyz_atom_lines(lines, start + 2, num_atoms, comment, opts.frame_label);
     const metadata = { ...properties, ...force_stats };
     if (lattice_matrix)
         metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
-    return create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step ?? opts.default_step, metadata);
+    return create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? pbc : undefined, step ?? opts.default_step, metadata);
 }
 export function parse_xyz_trajectory(content) {
     const lines = content.trim().split(/\r?\n/);

package/dist/trajectory/plotting.d.ts

@@ -1,10 +1,8 @@
-import type { DataSeries } from '../plot/core/types';
+import { type TrajPropertyConfig } from '../labels';
+import type { DataSeries, ScaleType } from '../plot/core/types';
 import type { TrajectoryDataExtractor, TrajectoryMetadata, TrajectoryType } from './index';
 export interface PlotSeriesOptions {
-    property_config?: Record<string, {
-        label: string;
-        unit: string;
-    }>;
+    property_config?: Record<string, TrajPropertyConfig>;
     colors?: readonly string[];
     default_visible_properties?: Set<string>;
 }
@@ -14,11 +12,12 @@ export declare function generate_axis_labels(plot_series: DataSeries[]): {
     y1: string;
     y2: string;
 };
+export declare function generate_axis_scale_types(plot_series: DataSeries[]): {
+    y1: ScaleType;
+    y2: ScaleType;
+};
 interface StreamingPlotOptions {
-    property_config?: Record<string, {
-        label: string;
-        unit: string;
-    }>;
+    property_config?: Record<string, TrajPropertyConfig>;
     colors?: readonly string[];
     default_visible_properties?: Set<string>;
     max_points?: number;