matterviz 0.4.1 → 0.4.2

package/dist/trajectory/parse/index.js

@@ -3,13 +3,13 @@ import { is_binary } from '../../io/is-binary';
 import { is_plain_object } from '../../utils';
 import { is_parsed_structure, parse_xyz } from '../../structure/parse';
 import { INDEX_SAMPLE_RATE, LARGE_FILE_THRESHOLD } from '../constants';
-import { strip_compression_extensions } from '../../io';
-import { ext_hint, FORMAT_PATTERNS, is_trajectory_file } from '../format-detect';
+import { strip_compression_extensions } from '../../io/decompress';
+import { ext_hint, FORMAT_PATTERNS } from '../format-detect';
 import { TrajFrameReader } from '../frame-reader';
 import { count_xyz_frames } from '../helpers';
 import { parse_ase_trajectory } from './ase';
 import { get_traj_parse_warnings, reset_traj_parse_warnings, traj_warn } from './diagnostics';
-import { parse_torch_sim_hdf5 } from './hdf5';
+import { parse_hdf5_trajectory } from './hdf5';
 import { parse_lammps_trajectory } from './lammps';
 import { parse_pymatgen_trajectory } from './pymatgen';
 import { parse_vasp_xdatcar } from './vasp';
@@ -23,14 +23,15 @@ const assert_frame_structure = (structure, label) => {
 };
 // Re-export constants and types for consumers
 export { LARGE_FILE_THRESHOLD, MAX_BIN_FILE_SIZE, MAX_TEXT_FILE_SIZE, } from '../constants';
-export { is_trajectory_file, TrajFrameReader };
+export { is_trajectory_file } from '../format-detect';
+export { TrajFrameReader } from '../frame-reader';
 export async function parse_trajectory_data(data, filename, atom_type_mapping) {
     reset_traj_parse_warnings();
     if (data instanceof ArrayBuffer) {
         if (FORMAT_PATTERNS.ase(data, filename))
             return parse_ase_trajectory(data, filename);
         if (FORMAT_PATTERNS.hdf5(data, filename))
-            return parse_torch_sim_hdf5(data, filename);
+            return parse_hdf5_trajectory(data, filename);
         throw new Error(`Unsupported binary format${filename ? `: ${filename}` : ``}`);
     }
     if (typeof data === `string`) {
@@ -45,19 +46,15 @@ export async function parse_trajectory_data(data, filename, atom_type_mapping) {
         }
         // Single XYZ fallback (content-sniffed when the filename gives no format hint,
         // e.g. blob: object URLs whose basenames are UUIDs)
-        const xyz_hint = ext_hint(filename, /\.(xyz|extxyz)$/);
+        const xyz_hint = ext_hint(filename, /\.(?:xyz|extxyz)$/);
         if (xyz_hint || (xyz_hint === null && count_xyz_frames(content) === 1)) {
-            try {
-                const structure = parse_xyz(content);
-                if (structure) {
-                    return {
-                        frames: [{ structure, step: 0, metadata: {} }],
-                        metadata: { source_format: `single_xyz`, frame_count: 1 },
-                    };
-                }
-            }
-            catch {
-                // Single-frame XYZ parsing failed, continue to JSON parsing.
+            // parse_xyz never throws (it returns null); fall through to JSON parsing.
+            const structure = parse_xyz(content);
+            if (structure) {
+                return {
+                    frames: [{ structure, step: 0, metadata: {} }],
+                    metadata: { source_format: `single_xyz`, frame_count: 1 },
+                };
             }
         }
         try {
@@ -158,9 +155,9 @@ export async function parse_trajectory_async(data, filename, on_progress, option
         // When the filename gives no format hint (e.g. blob: URLs), sniff a content
         // prefix for XYZ frames so large extensionless files still get indexed.
         const base_filename = strip_compression_extensions(filename);
-        const can_index = /\.(xyz|extxyz|traj)$/.test(base_filename) ||
+        const can_index = /\.(?:xyz|extxyz|traj)$/.test(base_filename) ||
             (typeof data === `string` &&
-                ext_hint(filename, /\.(xyz|extxyz)$/) === null &&
+                ext_hint(filename, /\.(?:xyz|extxyz)$/) === null &&
                 count_xyz_frames(data.slice(0, 2 ** 20)) >= 1);
         if (should_use_indexing && can_index) {
             return attach_parse_warnings(await parse_with_unified_loader(data, filename, { index_sample_rate, extract_plot_metadata }, on_progress));
@@ -231,7 +228,7 @@ async function parse_with_unified_loader(data, filename, options, on_progress) {
 }
 // Factory function for frame loader (simplified)
 export function create_frame_loader(filename) {
-    if (!/\.(xyz|extxyz|traj)$/.exec(filename.toLowerCase())) {
+    if (!/\.(?:xyz|extxyz|traj)$/.test(filename.toLowerCase())) {
         throw new Error(`Unsupported format for frame loading: ${filename}`);
     }
     return new TrajFrameReader(filename);

package/dist/trajectory/parse/lammps.js

@@ -1,7 +1,7 @@
 import { ELEM_SYMBOLS } from '../../labels';
 import * as math from '../../math';
-import { coerce_elem_symbol } from '../../element';
-import { create_trajectory_frame } from '../helpers';
+import { coerce_elem_symbol } from '../../element/helpers';
+import { count_elements, create_trajectory_frame } from '../helpers';
 import { traj_warn } from './diagnostics';
 const is_periodic = (token) => token.toLowerCase().startsWith(`p`);
 // Parse LAMMPS box bounds → lattice matrix. Handles orthogonal and triclinic boxes.
@@ -60,11 +60,11 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
         if (!skip_to(`ITEM: TIMESTEP`))
             break;
         idx++;
-        const timestep = parseInt(read_line(), 10) || 0;
+        const timestep = Math.trunc(Number(read_line())) || 0;
         if (!skip_to(`ITEM: NUMBER OF ATOMS`))
             break;
         idx++;
-        const num_atoms = parseInt(read_line(), 10);
+        const num_atoms = Math.trunc(Number(read_line()));
         if (!num_atoms || num_atoms <= 0)
             continue;
         // BOX BOUNDS: orthogonal="pp pp pp", triclinic="xy xz yz pp pp pp"
@@ -111,7 +111,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
         const frac_to_cart = use_scaled ? math.create_frac_to_cart(lattice_matrix) : null;
         for (let atom = 0; atom < num_atoms && idx < lines.length; atom++) {
             const parts = read_line().split(/\s+/);
-            const coords = pos_cols.map((col_idx) => parseFloat(parts[col_idx]));
+            const coords = pos_cols.map((col_idx) => Number(parts[col_idx]));
             if (coords.some(isNaN) || parts.length <= max_col_idx)
                 continue;
             // Convert scaled coordinates to Cartesian if needed
@@ -119,7 +119,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
             let element_symbol;
             if (type_col !== undefined) {
                 // Map atom type to element using custom mapping or default (type 1 -> H, etc.)
-                const atom_type = parseInt(parts[type_col], 10) || 1;
+                const atom_type = Math.trunc(Number(parts[type_col])) || 1;
                 atom_types_found.add(atom_type);
                 element_symbol = get_element(atom_type);
             }
@@ -134,7 +134,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
                 }
             }
             else if (id_col !== undefined) {
-                const atom_id = parseInt(parts[id_col], 10) || 1;
+                const atom_id = Math.trunc(Number(parts[id_col])) || 1;
                 atom_types_found.add(atom_id);
                 if (!id_fallback_warning_emitted) {
                     traj_warn(`LAMMPS parser fallback: mapping atom IDs to elements from ID column; this may be incorrect for large or sequential IDs. Prefer a TYPE column when available.`);
@@ -159,11 +159,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
         throw new Error(`No valid frames found in LAMMPS trajectory`);
     }
     const first_frame = frames[0];
-    const element_counts = first_frame.structure.sites.reduce((counts, site) => {
-        const elem = site.species[0].element;
-        counts[elem] = (counts[elem] || 0) + 1;
-        return counts;
-    }, {});
+    const element_counts = count_elements(first_frame.structure.sites.map((site) => site.species[0].element));
     return {
         frames,
         metadata: {

package/dist/trajectory/parse/vasp.js

@@ -1,14 +1,15 @@
 import * as math from '../../math';
-import { is_elem_symbol } from '../../element';
+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 };
@@ -31,7 +32,9 @@ export function parse_vasp_xdatcar(content, filename) {
     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);
@@ -49,14 +52,14 @@ export function parse_vasp_xdatcar(content, filename) {
                 if (hdr.names.length === hdr.counts.length &&
                     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>;