matterviz 0.4.0 → 0.4.2

package/dist/trajectory/extract.js

@@ -1,5 +1,6 @@
 // Data extraction functions for trajectory analysis and plotting
 import { get_density } from '../structure/index';
+import { calc_force_stats, copy_numeric_fields } from './helpers';
 // Common data extractor that extracts energy and structural properties
 export const energy_data_extractor = (frame) => {
     const data = {
@@ -7,18 +8,13 @@ export const energy_data_extractor = (frame) => {
     };
     if (frame.metadata) {
         // Extract energy-related properties
-        const energy_fields = [
+        copy_numeric_fields(data, frame.metadata, [
             `energy`,
             `energy_per_atom`,
             `potential_energy`,
             `kinetic_energy`,
             `total_energy`,
-        ];
-        for (const field of energy_fields) {
-            if (field in frame.metadata && typeof frame.metadata[field] === `number`) {
-                data[field] = frame.metadata[field];
-            }
-        }
+        ]);
     }
     return data;
 };
@@ -30,13 +26,8 @@ export const force_stress_data_extractor = (frame) => {
     if (frame.metadata) {
         // Calculate force properties from forces array if available (preferred)
         if (frame.metadata.forces && Array.isArray(frame.metadata.forces)) {
-            const forces = frame.metadata.forces;
-            if (forces.length > 0) {
-                const force_magnitudes = forces.map((force) => Math.hypot(...force));
-                data.force_max = Math.max(...force_magnitudes);
-                // Calculate RMS (root mean square) of force magnitudes
-                data.force_norm = Math.sqrt(force_magnitudes.reduce((sum, f) => sum + f ** 2, 0) / force_magnitudes.length);
-            }
+            // Object.assign ignores the null calc_force_stats returns for empty forces
+            Object.assign(data, calc_force_stats(frame.metadata.forces));
         }
         else {
             // Fallback to metadata values if forces array not available
@@ -52,12 +43,29 @@ export const force_stress_data_extractor = (frame) => {
             }
         }
         // Extract other stress and pressure properties (no duplicates expected)
-        const other_stress_fields = [`stress_max`, `stress_frobenius`, `stress_trace`, `pressure`];
-        for (const field of other_stress_fields) {
-            if (field in frame.metadata && typeof frame.metadata[field] === `number`) {
-                data[field] = frame.metadata[field];
-            }
-        }
+        copy_numeric_fields(data, frame.metadata, [
+            `stress_max`,
+            `stress_frobenius`,
+            `stress_trace`,
+            `pressure`,
+        ]);
+    }
+    return data;
+};
+// Data extractor for SCF/electronic-convergence properties. Parsers emit these
+// per frame (per ionic step, or per SCF step for static single-point runs) —
+// e.g. the vaspout.h5 parser fills them from VASP's OSZICAR data.
+const scf_data_extractor = (frame) => {
+    const data = {
+        Step: frame.step,
+    };
+    if (frame.metadata) {
+        copy_numeric_fields(data, frame.metadata, [
+            `n_scf_steps`,
+            `scf_energy_delta`,
+            `scf_rms`,
+            `scf_charge_rms`,
+        ]);
     }
     return data;
 };
@@ -79,31 +87,20 @@ export const structural_data_extractor = (frame) => {
     }
     if (frame.metadata) {
         // Extract other structural properties, avoiding volume duplicate
-        const structural_fields = [`temperature`];
-        for (const field of structural_fields) {
-            if (field in frame.metadata && typeof frame.metadata[field] === `number`)
-                data[field] = frame.metadata[field];
-        }
-        // Handle density separately - prefer metadata, but calculate if not available
-        if (frame.metadata.density && typeof frame.metadata.density === `number`) {
+        copy_numeric_fields(data, frame.metadata, [`temperature`]);
+        // Prefer metadata density (fall back to calculating from structure below).
+        // Finite-number check (not truthiness) so a legitimate density of 0 is kept.
+        if (typeof frame.metadata.density === `number` &&
+            Number.isFinite(frame.metadata.density)) {
             data.density = frame.metadata.density;
         }
-        else if (`lattice` in frame.structure) {
-            try {
-                data.density = get_density(frame.structure);
-            }
-            catch (error) {
-                console.warn(`Failed to calculate density for frame ${frame.step}:`, error);
-            }
-        }
         // Only use metadata volume if lattice volume is not available
         if (!data.volume && frame.metadata.volume && typeof frame.metadata.volume === `number`) {
             data.volume = frame.metadata.volume;
         }
         // Note: pressure is handled by force_stress_data_extractor to avoid duplication
     }
-    else if (`lattice` in frame.structure) {
-        // Calculate density even when no metadata is available
+    if (data.density === undefined && `lattice` in frame.structure) {
         try {
             data.density = get_density(frame.structure);
         }
@@ -113,50 +110,55 @@ export const structural_data_extractor = (frame) => {
     }
     return data;
 };
-// Helper function to check if a property varies across trajectory frames
-function property_varies(trajectory, property_key, tolerance = 1e-10) {
-    if (trajectory.frames.length <= 1)
-        return false;
-    const values = [];
+const LATTICE_PARAMS = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`];
+// Cache per trajectory: full_data_extractor runs once per frame, so without this it
+// rescans all frames on every call (O(n²)). WeakMap → GC'd with the trajectory.
+const constant_params_cache = new WeakMap();
+// Lattice params constant across the trajectory, in a single pass (prefer lattice value,
+// else metadata; tol 1e-10). A param must be observed in ≥1 frame to count as constant;
+// params absent from every frame are excluded (not silently treated as "constant").
+function get_constant_lattice_params(trajectory) {
+    const cached = constant_params_cache.get(trajectory);
+    if (cached)
+        return cached;
+    const tolerance = 1e-10;
+    const first_values = new Map();
+    const varies = new Set();
     for (const frame of trajectory.frames) {
-        // Check both direct structure properties and metadata
-        let value;
-        if (`lattice` in frame.structure) {
-            const lattice_value = frame.structure.lattice[property_key];
-            if (typeof lattice_value === `number`)
-                value = lattice_value;
-        }
-        if (value === undefined && frame.metadata && property_key in frame.metadata) {
-            const metadata_value = frame.metadata[property_key];
-            if (typeof metadata_value === `number`) {
-                value = metadata_value;
-            }
-        }
-        if (value !== undefined) {
-            values.push(value);
+        const lattice = `lattice` in frame.structure
+            ? frame.structure.lattice
+            : null;
+        for (const param of LATTICE_PARAMS) {
+            if (varies.has(param))
+                continue; // already known to vary, skip
+            const lattice_value = lattice?.[param];
+            const value = typeof lattice_value === `number` ? lattice_value : frame.metadata?.[param];
+            // Number.isFinite: NaN is typeof `number` but Math.abs(next-NaN)=NaN → false constant
+            if (typeof value !== `number` || !Number.isFinite(value))
+                continue;
+            const first = first_values.get(param);
+            if (first === undefined)
+                first_values.set(param, value);
+            else if (Math.abs(value - first) > tolerance)
+                varies.add(param);
         }
     }
-    if (values.length <= 1)
-        return false;
-    const first_value = values[0];
-    return values.some((value) => Math.abs(value - first_value) > tolerance);
+    // only params observed in ≥1 frame; a never-present param is not "constant"
+    const constant = new Set([...first_values.keys()].filter((param) => !varies.has(param)));
+    constant_params_cache.set(trajectory, constant);
+    return constant;
 }
 // Combined data extractor that extracts all common properties
 export const full_data_extractor = (frame, trajectory) => {
-    const base_data = {
+    const result = {
         ...energy_data_extractor(frame, trajectory),
         ...force_stress_data_extractor(frame, trajectory),
+        ...scf_data_extractor(frame, trajectory),
         ...structural_data_extractor(frame, trajectory),
     };
-    // Check which lattice parameters vary
-    const lattice_params = [`a`, `b`, `c`, `alpha`, `beta`, `gamma`];
-    const result = { ...base_data };
-    // Add metadata to specify which properties don't vary
-    for (const param of lattice_params) {
-        if (!property_varies(trajectory, param)) {
-            // Mark individual lattice parameters as constant
-            result[`constant_${param}`] = 1;
-        }
+    // Mark individual lattice parameters that don't vary across the trajectory
+    for (const param of get_constant_lattice_params(trajectory)) {
+        result[`constant_${param}`] = 1;
     }
     return result;
 };

package/dist/trajectory/format-detect.d.ts

@@ -1,4 +1,3 @@
-export declare function strip_compression_extensions(filename: string): string;
 export declare function ext_hint(filename: string | undefined, ext_regex: RegExp): boolean | null;
 export declare const FORMAT_PATTERNS: {
     readonly ase: (data: unknown, filename?: string) => boolean;

package/dist/trajectory/format-detect.js

@@ -1,16 +1,11 @@
 // Format detection for trajectory files
-import { COMPRESSION_EXTENSIONS_REGEX, CONFIG_DIRS_REGEX, MD_SIM_EXCLUDE_REGEX, TRAJ_EXTENSIONS_REGEX, TRAJ_FALLBACK_EXTENSIONS_REGEX, TRAJ_KEYWORDS_SIMPLE_REGEX, XDATCAR_REGEX, } from '../constants';
+import { CONFIG_DIRS_REGEX, MD_SIM_EXCLUDE_REGEX, TRAJ_EXTENSIONS_REGEX, TRAJ_FALLBACK_EXTENSIONS_REGEX, TRAJ_KEYWORDS_SIMPLE_REGEX, XDATCAR_REGEX, } from '../constants';
+import { strip_compression_extensions } from '../io/decompress';
+import { parse_leading_num } from '../utils';
 import { count_xyz_frames } from './helpers';
-export function strip_compression_extensions(filename) {
-    let base_name = filename.toLowerCase();
-    while (COMPRESSION_EXTENSIONS_REGEX.test(base_name)) {
-        base_name = base_name.replace(COMPRESSION_EXTENSIONS_REGEX, ``);
-    }
-    return base_name;
-}
 // Extensions that explicitly identify a format — when present, format detection trusts
 // the extension instead of sniffing content
-const KNOWN_FORMAT_EXT_REGEX = /\.(xyz|extxyz|traj|h5|hdf5|lammpstrj|json|cif|poscar|vasp|yaml|yml|xml|csv)$/;
+const KNOWN_FORMAT_EXT_REGEX = /\.(?:xyz|extxyz|traj|h5|hdf5|lammpstrj|json|cif|poscar|vasp|yaml|yml|xml|csv)$/;
 // Classify the filename hint for a format whose extensions match ext_regex:
 // true = filename matches, false = filename names a different known format,
 // null = no usable hint (missing filename or unrecognized extension, e.g. the UUID
@@ -35,12 +30,12 @@ export const FORMAT_PATTERNS = {
         return [0x2d, 0x20, 0x6f, 0x66, 0x20, 0x55, 0x6c, 0x6d].every((byte, idx) => view[idx] === byte);
     },
     hdf5: (data, filename) => {
-        if (ext_hint(filename, /\.(h5|hdf5)$/) === false)
+        if (ext_hint(filename, /\.(?:h5|hdf5)$/) === false)
             return false;
         if (!(data instanceof ArrayBuffer) || data.byteLength < 8)
             return false;
         const signature = new Uint8Array(data.slice(0, 8));
-        return [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a].every((b, idx) => signature[idx] === b);
+        return [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a].every((byte, idx) => signature[idx] === byte);
     },
     vasp: (data, filename) => {
         const basename = filename?.toLowerCase().split(`/`).pop() ?? ``;
@@ -49,11 +44,11 @@ export const FORMAT_PATTERNS = {
         const lines = data.trim().split(/\r?\n/);
         return (lines.length >= 10 &&
             lines.some((line) => line.includes(`Direct configuration=`)) &&
-            !isNaN(parseFloat(lines[1])) &&
+            !isNaN(parse_leading_num(lines[1])) &&
             lines.slice(2, 5).every((line) => line.trim().split(/\s+/).length === 3));
     },
     xyz_multi: (data, filename) => {
-        if (ext_hint(filename, /\.(xyz|extxyz)$/) === false)
+        if (ext_hint(filename, /\.(?:xyz|extxyz)$/) === false)
             return false;
         return count_xyz_frames(data) >= 2;
     },
@@ -69,7 +64,7 @@ export function is_trajectory_file(filename, content) {
         return false;
     const base_name = strip_compression_extensions(filename);
     // For xyz/extxyz files, use content-based detection if available
-    if (/\.(xyz|extxyz)$/i.test(base_name)) {
+    if (/\.(?:xyz|extxyz)$/i.test(base_name)) {
         if (content)
             return count_xyz_frames(content) >= 2;
         return TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name);
@@ -80,9 +75,10 @@ export function is_trajectory_file(filename, content) {
     // Special exclusion for generic md_simulation pattern with certain extensions
     if (MD_SIM_EXCLUDE_REGEX.test(base_name))
         return false;
-    // For .h5/.hdf5 files, require trajectory keywords
-    if (/\.(h5|hdf5)$/i.test(base_name)) {
-        return TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name);
+    // For .h5/.hdf5 files, require trajectory keywords. vaspout.h5 (VASP's
+    // HDF5 output) is always trajectory-shaped regardless of keywords.
+    if (/\.(?:h5|hdf5)$/i.test(base_name)) {
+        return /vaspout/i.test(base_name) || TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name);
     }
     // For other extensions, require both keywords and specific extensions
     return (TRAJ_KEYWORDS_SIMPLE_REGEX.test(base_name) &&

package/dist/trajectory/frame-reader.d.ts

@@ -2,6 +2,7 @@ import type { FrameIndex, FrameLoader, ParseProgress, TrajectoryFrame, Trajector
 export declare class TrajFrameReader implements FrameLoader {
     private readonly format;
     private global_numbers?;
+    private xyz_cache?;
     constructor(filename: string);
     get_total_frames(data: string | ArrayBuffer): Promise<number>;
     build_frame_index(data: string | ArrayBuffer, sample_rate: number, on_progress?: (progress: ParseProgress) => void): Promise<FrameIndex[]>;
@@ -10,8 +11,8 @@ export declare class TrajFrameReader implements FrameLoader {
         sample_rate?: number;
         properties?: string[];
     }, on_progress?: (progress: ParseProgress) => void): Promise<TrajectoryMetadata[]>;
+    private get_xyz_cache;
     private load_xyz_frame;
     private load_ase_frame;
-    private parse_xyz_metadata;
     private parse_ase_metadata;
 }

package/dist/trajectory/frame-reader.js

@@ -1,12 +1,22 @@
 // Unified frame loader for XYZ and ASE trajectories (large file indexing)
 import * as math from '../math';
 import { MAX_METADATA_SIZE } from './constants';
-import { convert_atomic_numbers, count_xyz_frames, create_trajectory_frame, read_ndarray_from_view, validate_3x3_matrix, } from './helpers';
-import { strip_compression_extensions } from './format-detect';
-import { parse_extxyz_lattice, parse_xyz_atom_lines, parse_xyz_comment_metadata, } from './parse/xyz';
+import { copy_numeric_fields, count_xyz_frames, iter_xyz_frames, validate_3x3_matrix, } from './helpers';
+import { strip_compression_extensions } from '../io/decompress';
+import { decode_ase_frame, read_ase_header } from './parse/ase';
+import { build_xyz_frame, parse_xyz_comment_metadata } from './parse/xyz';
+// Restrict frame metadata to the requested property keys (no-op when unset)
+const filter_properties = (metadata, properties) => {
+    if (!properties)
+        return;
+    metadata.properties = Object.fromEntries(Object.entries(metadata.properties).filter(([key]) => properties.includes(key)));
+};
 export class TrajFrameReader {
     format;
     global_numbers;
+    // Split lines + per-frame start indices for the last XYZ payload, so repeat seeks are
+    // O(1) lookup instead of re-splitting + rescanning from line 0 (was O(n²) over playback)
+    xyz_cache;
     constructor(filename) {
         const base_filename = strip_compression_extensions(filename);
         this.format = base_filename.endsWith(`.traj`) ? `ase` : `xyz`;
@@ -19,8 +29,7 @@ export class TrajFrameReader {
         }
         if (!(data instanceof ArrayBuffer))
             throw new Error(`ASE loader requires binary data`);
-        const view = new DataView(data);
-        return Number(view.getBigInt64(32, true));
+        return read_ase_header(new DataView(data)).n_items;
     }
     async build_frame_index(data, sample_rate, on_progress) {
         const total_frames = await this.get_total_frames(data);
@@ -31,35 +40,25 @@ export class TrajFrameReader {
             const encoder = new TextEncoder();
             const newline_sequence = data_str.includes(`\r\n`) ? `\r\n` : `\n`;
             const newline_byte_len = encoder.encode(newline_sequence).length;
-            let [current_frame, line_idx, byte_offset] = [0, 0, 0];
-            while (line_idx < lines.length && current_frame < total_frames) {
-                if (!lines[line_idx]?.trim()) {
-                    byte_offset += encoder.encode(lines[line_idx]).length + newline_byte_len;
-                    line_idx++;
-                    continue;
-                }
-                const num_atoms = parseInt(lines[line_idx].trim(), 10);
-                if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 1 >= lines.length) {
-                    byte_offset += encoder.encode(lines[line_idx]).length + newline_byte_len;
-                    line_idx++;
-                    continue;
-                }
+            const line_bytes = (idx) => encoder.encode(lines[idx]).length + newline_byte_len;
+            // cursor = next line whose bytes haven't been added to byte_offset yet
+            let [current_frame, cursor, byte_offset] = [0, 0, 0];
+            for (const { start, num_atoms } of iter_xyz_frames(lines)) {
+                if (current_frame >= total_frames)
+                    break;
+                // Accumulate bytes of blank/invalid lines skipped before this frame
+                for (; cursor < start; cursor++)
+                    byte_offset += line_bytes(cursor);
+                let frame_size = 0;
+                for (; cursor < start + num_atoms + 2; cursor++)
+                    frame_size += line_bytes(cursor);
                 if (current_frame % sample_rate === 0) {
                     frame_index.push({
                         frame_number: current_frame,
                         byte_offset,
-                        estimated_size: 0,
+                        estimated_size: frame_size,
                     });
                 }
-                const frame_start = line_idx;
-                line_idx += 2 + num_atoms;
-                let frame_size = 0;
-                for (let idx = frame_start; idx < line_idx; idx++) {
-                    frame_size += encoder.encode(lines[idx]).length + newline_byte_len;
-                }
-                if (current_frame % sample_rate === 0) {
-                    frame_index[frame_index.length - 1].estimated_size = frame_size;
-                }
                 byte_offset += frame_size;
                 current_frame++;
                 if (on_progress && current_frame % 1000 === 0) {
@@ -73,7 +72,7 @@ export class TrajFrameReader {
         }
         else {
             const view = new DataView(data);
-            const offsets_pos = Number(view.getBigInt64(40, true));
+            const { offsets_pos } = read_ase_header(view);
             for (let idx = 0; idx < total_frames; idx += sample_rate) {
                 const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
                 frame_index.push({
@@ -111,34 +110,21 @@ export class TrajFrameReader {
         const total_frames = await this.get_total_frames(data);
         if (this.format === `xyz`) {
             const lines = data.trim().split(/\r?\n/);
-            let [current_frame, line_idx] = [0, 0];
-            while (line_idx < lines.length && current_frame < total_frames) {
-                if (!lines[line_idx]?.trim()) {
-                    line_idx++;
-                    continue;
-                }
-                const num_atoms = parseInt(lines[line_idx].trim(), 10);
-                if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 1 >= lines.length) {
-                    line_idx++;
-                    continue;
-                }
+            let current_frame = 0;
+            for (const { comment } of iter_xyz_frames(lines)) {
+                if (current_frame >= total_frames)
+                    break;
                 if (current_frame % sample_rate === 0) {
-                    const comment = lines[line_idx + 1] || ``;
-                    let frame_metadata = null;
-                    try {
-                        frame_metadata = this.parse_xyz_metadata(comment, current_frame);
-                    }
-                    catch (error) {
-                        console.warn(`Failed to parse XYZ metadata for frame ${current_frame} at line ${line_idx + 1}:`, error);
-                    }
-                    if (frame_metadata && properties) {
-                        const filtered = Object.fromEntries(Object.entries(frame_metadata.properties).filter(([key]) => properties.includes(key)));
-                        frame_metadata.properties = filtered;
-                    }
-                    if (frame_metadata)
-                        metadata_list.push(frame_metadata);
+                    // parse_xyz_comment_metadata is pure regex/parseFloat and never throws
+                    const { step, properties: props } = parse_xyz_comment_metadata(comment);
+                    const frame_metadata = {
+                        frame_number: current_frame,
+                        step: step ?? current_frame,
+                        properties: props,
+                    };
+                    filter_properties(frame_metadata, properties);
+                    metadata_list.push(frame_metadata);
                 }
-                line_idx += 2 + num_atoms;
                 current_frame++;
                 if (on_progress && current_frame % 5000 === 0) {
                     on_progress({
@@ -151,8 +137,7 @@ export class TrajFrameReader {
         }
         else if (this.format === `ase`) {
             const view = new DataView(data);
-            const n_items = Number(view.getBigInt64(32, true));
-            const offsets_pos = Number(view.getBigInt64(40, true));
+            const { n_items, offsets_pos } = read_ase_header(view);
             for (let idx = 0; idx < n_items; idx += sample_rate) {
                 try {
                     const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
@@ -163,10 +148,7 @@ export class TrajFrameReader {
                     }
                     const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(data, frame_offset + 8, json_length)));
                     const frame_metadata = this.parse_ase_metadata(frame_data, idx);
-                    if (properties) {
-                        const filtered = Object.fromEntries(Object.entries(frame_metadata.properties).filter(([key]) => properties.includes(key)));
-                        frame_metadata.properties = filtered;
-                    }
+                    filter_properties(frame_metadata, properties);
                     metadata_list.push(frame_metadata);
                     if (on_progress && idx % 5000 === 0) {
                         on_progress({
@@ -183,107 +165,63 @@ export class TrajFrameReader {
         }
         return metadata_list;
     }
-    load_xyz_frame(data, frame_number) {
+    // Build + cache the line array and per-frame start indices once per payload
+    get_xyz_cache(data) {
+        if (this.xyz_cache?.data === data)
+            return this.xyz_cache;
         const lines = data.trim().split(/\r?\n/);
-        let [current_frame, line_idx] = [0, 0];
-        while (line_idx < lines.length && current_frame < frame_number) {
-            const skip_atoms = parseInt(lines[line_idx].trim(), 10);
-            if (isNaN(skip_atoms) || skip_atoms <= 0) {
-                line_idx++; // skip blank/invalid lines until the next frame's atom-count line
-                continue;
-            }
-            line_idx += 2 + skip_atoms;
-            current_frame++;
-        }
-        if (line_idx >= lines.length)
-            return null;
-        const num_atoms = parseInt(lines[line_idx].trim(), 10);
-        if (isNaN(num_atoms) || line_idx + num_atoms + 1 >= lines.length)
-            return null;
-        const comment = lines[line_idx + 1] || ``;
-        const lattice_matrix = parse_extxyz_lattice(comment);
-        const { elements, positions, force_stats } = parse_xyz_atom_lines(lines, line_idx + 2, num_atoms, comment, `indexed frame ${frame_number}`);
-        const { step, properties } = this.parse_xyz_metadata(comment, frame_number);
-        const metadata = { ...properties, ...force_stats };
-        // Derive volume from the lattice (parity with the eager parse_xyz_trajectory parser)
-        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, metadata);
+        const frame_starts = Array.from(iter_xyz_frames(lines), ({ start }) => start);
+        this.xyz_cache = { data, lines, frame_starts };
+        return this.xyz_cache;
+    }
+    load_xyz_frame(data, frame_number) {
+        const { lines, frame_starts } = this.get_xyz_cache(data);
+        const start = frame_starts[frame_number];
+        if (start === undefined)
+            return null; // out-of-range frame
+        const num_atoms = Math.trunc(Number(lines[start]?.trim()));
+        const comment = lines[start + 1] ?? ``;
+        return build_xyz_frame(lines, { start, num_atoms, comment }, {
+            frame_label: `indexed frame ${frame_number}`,
+            default_step: frame_number,
+        });
     }
     load_ase_frame(data, frame_number) {
         try {
             const view = new DataView(data);
-            const n_items = Number(view.getBigInt64(32, true));
-            const offsets_pos = Number(view.getBigInt64(40, true));
+            const { n_items, offsets_pos } = read_ase_header(view);
             if (frame_number >= n_items)
                 return null;
             const frame_offset = Number(view.getBigInt64(offsets_pos + frame_number * 8, true));
-            const json_length = Number(view.getBigInt64(frame_offset, true));
-            const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(data, frame_offset + 8, json_length)));
-            const positions_ref = frame_data[`positions.`] ?? frame_data.positions;
-            const positions = positions_ref?.ndarray
-                ? read_ndarray_from_view(view, positions_ref)
-                : positions_ref;
-            const numbers_ref = frame_data[`numbers.`] ?? frame_data.numbers ?? this.global_numbers;
-            const numbers = numbers_ref?.ndarray
-                ? read_ndarray_from_view(view, numbers_ref).flat()
-                : numbers_ref;
-            if (numbers)
-                this.global_numbers = numbers;
-            if (!numbers || !positions)
-                throw new Error(`Missing atomic numbers or positions`);
-            const cell = frame_data.cell ? validate_3x3_matrix(frame_data.cell) : undefined;
-            const metadata = {
-                step: frame_number,
-                ...frame_data.calculator,
-                ...frame_data.info,
-            };
-            if (cell) {
-                try {
-                    metadata.volume = Math.abs(math.det_3x3(cell));
-                }
-                catch (error) {
-                    console.warn(`Failed to calculate volume for frame ${frame_number}:`, error);
-                }
-            }
-            return create_trajectory_frame(positions, convert_atomic_numbers(numbers), cell, frame_data.pbc ?? [true, true, true], frame_number, metadata);
+            const { frame, numbers } = decode_ase_frame(view, data, frame_offset, frame_number, this.global_numbers);
+            this.global_numbers = numbers;
+            return frame;
         }
         catch (error) {
             console.warn(`Failed to load ASE frame ${frame_number}:`, error);
             return null;
         }
     }
-    parse_xyz_metadata(comment, frame_number) {
-        const { step, properties } = parse_xyz_comment_metadata(comment);
-        return { frame_number, step: step ?? frame_number, properties };
-    }
     parse_ase_metadata(frame_data, frame_number) {
         const properties = {};
         const step = frame_number;
         if (frame_data.calculator && typeof frame_data.calculator === `object`) {
-            const calculator = frame_data.calculator;
-            const calc_properties = [`energy`, `potential_energy`, `kinetic_energy`, `total_energy`];
-            for (const prop of calc_properties) {
-                if (prop in calculator && typeof calculator[prop] === `number`) {
-                    properties[prop] = calculator[prop];
-                }
-            }
+            copy_numeric_fields(properties, frame_data.calculator, [
+                `energy`,
+                `potential_energy`,
+                `kinetic_energy`,
+                `total_energy`,
+            ]);
         }
         if (frame_data.info && typeof frame_data.info === `object`) {
-            const info = frame_data.info;
-            const info_properties = [
+            copy_numeric_fields(properties, frame_data.info, [
                 `force_max`,
                 `force_norm`,
                 `stress_max`,
                 `stress_frobenius`,
                 `pressure`,
                 `temperature`,
-            ];
-            for (const prop of info_properties) {
-                if (prop in info && typeof info[prop] === `number`) {
-                    properties[prop] = info[prop];
-                }
-            }
+            ]);
         }
         if (frame_data.cell && Array.isArray(frame_data.cell)) {
             try {

package/dist/trajectory/helpers.d.ts

@@ -3,13 +3,23 @@ import * as math from '../math';
 import type { AnyStructure } from '../structure/index';
 import type { Pbc } from '../structure/pbc';
 import type { TrajectoryFrame } from './index';
-export declare const is_valid_element_symbol: (symbol: string) => symbol is ElementSymbol;
-export declare const coerce_element_symbol: (symbol: string) => ElementSymbol | undefined;
 export declare function validate_3x3_matrix(data: unknown): math.Matrix3x3;
 export declare const convert_atomic_numbers: (numbers: number[]) => ElementSymbol[];
+export declare const count_elements: (elements: readonly string[]) => Record<string, number>;
 export declare const create_structure: (positions: number[][], elements: ElementSymbol[], lattice_matrix?: math.Matrix3x3, pbc?: Pbc, force_data?: number[][]) => AnyStructure;
 export declare const create_trajectory_frame: (positions: number[][], elements: ElementSymbol[], lattice_matrix: math.Matrix3x3 | undefined, pbc: Pbc | undefined, step: number, metadata?: Record<string, unknown>) => TrajectoryFrame;
 export declare const read_ndarray_from_view: (view: DataView, ref: {
     ndarray: unknown[];
 }) => number[][];
+export declare const copy_numeric_fields: (target: Record<string, number>, source: Record<string, unknown>, fields: readonly string[]) => void;
+export declare function calc_force_stats(forces: number[][]): {
+    force_max: number;
+    force_norm: number;
+} | null;
+export declare const is_xyz_atom_line: (parts: string[] | undefined) => boolean;
+export declare function iter_xyz_frames(lines: string[]): Generator<{
+    start: number;
+    num_atoms: number;
+    comment: string;
+}>;
 export declare function count_xyz_frames(data: string): number;