matterviz 0.4.0 → 0.4.1

package/dist/trajectory/parse/index.js

@@ -1,21 +1,31 @@
+// Parsing functions for trajectory data from various formats
 import { is_binary } from '../../io/is-binary';
-import * as math from '../../math';
-import { parse_xyz } from '../../structure/parse';
+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 { ext_hint, FORMAT_PATTERNS, is_trajectory_file, strip_compression_extensions, } from '../format-detect';
+import { strip_compression_extensions } from '../../io';
+import { ext_hint, FORMAT_PATTERNS, is_trajectory_file } from '../format-detect';
 import { TrajFrameReader } from '../frame-reader';
-import { count_xyz_frames, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
+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_lammps_trajectory } from './lammps';
+import { parse_pymatgen_trajectory } from './pymatgen';
 import { parse_vasp_xdatcar } from './vasp';
 import { parse_xyz_trajectory } from './xyz';
-// Silently swallow expected parse fallbacks — the caller throws if ALL formats fail
-const log_parse_debug = (_message, _error) => { };
+// Throw on a trajectory frame whose structure isn't a valid parsed structure (non-empty sites with species + coords)
+const assert_frame_structure = (structure, label) => {
+    if (!is_parsed_structure(structure)) {
+        const context = typeof label === `number` ? `trajectory frame ${label}` : label;
+        throw new Error(`Invalid structure in ${context}: expected non-empty 'sites' array with species and coordinates`);
+    }
+};
 // Re-export constants and types for consumers
-export { INDEX_SAMPLE_RATE, LARGE_FILE_THRESHOLD, MAX_BIN_FILE_SIZE, MAX_METADATA_SIZE, MAX_SAFE_STRING_LENGTH, MAX_TEXT_FILE_SIZE, } from '../constants';
+export { LARGE_FILE_THRESHOLD, MAX_BIN_FILE_SIZE, MAX_TEXT_FILE_SIZE, } from '../constants';
 export { is_trajectory_file, TrajFrameReader };
 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);
@@ -46,127 +56,62 @@ export async function parse_trajectory_data(data, filename, atom_type_mapping) {
                     };
                 }
             }
-            catch (error) {
+            catch {
                 // Single-frame XYZ parsing failed, continue to JSON parsing.
-                log_parse_debug(`Single XYZ parse fallback failed for ${filename ?? `unknown file`}:`, error);
             }
         }
         try {
             data = JSON.parse(content);
         }
         catch (error) {
-            log_parse_debug(`JSON parse failed for ${filename ?? `unknown file`}:`, error);
             throw new Error(`Unsupported text format`, { cause: error });
         }
     }
-    if (!data || typeof data !== `object`)
-        throw new Error(`Invalid data format`);
     // Handle JSON formats
     if (Array.isArray(data)) {
         const frames = data.map((frame_data, idx) => {
             const frame_obj = frame_data;
             const frame_step = frame_obj.step;
+            const structure = frame_obj.structure ?? frame_obj;
+            assert_frame_structure(structure, idx);
             return {
-                structure: (frame_obj.structure ?? frame_obj),
+                structure: structure,
                 step: typeof frame_step === `number` ? frame_step : idx,
                 metadata: frame_obj.metadata || {},
             };
         });
         return { frames, metadata: { source_format: `array`, frame_count: frames.length } };
     }
-    const obj = data;
+    if (!is_plain_object(data))
+        throw new Error(`Invalid data format`);
     // Pymatgen format
-    if (obj[`@class`] === `Trajectory` && obj.species && obj.coords && obj.lattice) {
-        const species = obj.species;
-        const frame_elements = 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 (value &&
-                    typeof value === `object` &&
-                    value[`@class`] === `array`) {
-                    // Extract numpy array data
-                    const array_obj = value;
-                    processed_properties[key] = array_obj.data;
-                    // Calculate force statistics for forces
-                    if (key === `forces` && Array.isArray(array_obj.data)) {
-                        const forces = array_obj.data;
-                        const force_magnitudes = forces.map((force) => Math.hypot(...force));
-                        if (force_magnitudes.length > 0) {
-                            processed_properties.force_max = force_magnitudes.reduce((max_val, magnitude) => (magnitude > max_val ? magnitude : max_val), force_magnitudes[0]);
-                            processed_properties.force_norm = Math.sqrt(force_magnitudes.reduce((sum, f) => sum + f ** 2, 0) / force_magnitudes.length);
-                        }
-                    }
-                    // Calculate stress statistics for stress tensor
-                    if (key === `stress` && Array.isArray(array_obj.data)) {
-                        const stress_tensor = array_obj.data;
-                        if (!math.is_square_matrix(stress_tensor, 3)) {
-                            console.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);
-        });
-        return {
-            frames,
-            metadata: {
-                filename,
-                source_format: `pymatgen_trajectory`,
-                frame_count: frames.length,
-                species_list: [...new Set(species.map((specie) => specie.element))],
-                periodic_boundary_conditions: [true, true, true],
-            },
-        };
+    if (data[`@class`] === `Trajectory` && data.species && data.coords && data.lattice) {
+        return parse_pymatgen_trajectory(data, filename);
     }
     // Object with frames
-    if (Array.isArray(obj.frames)) {
-        const metadata = (obj.metadata ?? {});
-        return {
-            frames: obj.frames,
-            metadata: { ...metadata, source_format: `object_with_frames` },
-        };
+    if (Array.isArray(data.frames)) {
+        const metadata = (data.metadata ?? {});
+        const frames = data.frames;
+        frames.forEach((frame, idx) => assert_frame_structure(frame?.structure, idx));
+        return { frames, metadata: { ...metadata, source_format: `object_with_frames` } };
     }
-    // Single structure
-    if (obj.sites) {
-        return {
-            frames: [{ structure: obj, step: 0, metadata: {} }],
-            metadata: { source_format: `single_structure`, frame_count: 1 },
-        };
+    // Single structure (treated as a 1-frame trajectory)
+    if (data.sites) {
+        assert_frame_structure(data, `single structure`);
+        const frames = [{ structure: data, step: 0, metadata: {} }];
+        const metadata = { source_format: `single_structure`, frame_count: 1 };
+        return { frames, metadata };
     }
     throw new Error(`Unrecognized trajectory format`);
 }
 export function get_unsupported_format_message(filename, content) {
     const lower = filename.toLowerCase();
     // Check for unsupported compression formats first
-    const unsupported_compression = [
-        { ext: `.bz2`, name: `BZ2` },
-        { ext: `.xz`, name: `XZ` },
-        { ext: `.zip`, name: `ZIP` },
-    ];
-    for (const { ext, name } of unsupported_compression) {
+    for (const [ext, name] of [
+        [`.bz2`, `BZ2`],
+        [`.xz`, `XZ`],
+        [`.zip`, `ZIP`],
+    ]) {
         if (lower.endsWith(ext)) {
             return `🚫 ${name} compression not supported in browser\nPlease decompress the file first`;
         }
@@ -187,10 +132,20 @@ export function get_unsupported_format_message(filename, content) {
         ? `🚫 Binary format not supported${filename ? `: ${filename}` : ``}`
         : null;
 }
+// Attach non-fatal parse warnings (skipped atoms, dropped frames, plot-metadata
+// extraction failures, ...) collected during parsing to the trajectory metadata so
+// the UI can surface them instead of leaving them in the console only.
+function attach_parse_warnings(trajectory) {
+    const parse_warnings = get_traj_parse_warnings();
+    if (parse_warnings.length === 0)
+        return trajectory;
+    return { ...trajectory, metadata: { ...trajectory.metadata, parse_warnings } };
+}
 // Unified async parser with streaming support
 export async function parse_trajectory_async(data, filename, on_progress, options = {}) {
     const { use_indexing, index_sample_rate = INDEX_SAMPLE_RATE, extract_plot_metadata = true, atom_type_mapping, } = options;
     const update_progress = (current, stage) => on_progress?.({ current, total: 100, stage });
+    reset_traj_parse_warnings();
     try {
         update_progress(0, `Detecting format...`);
         const data_size = data instanceof ArrayBuffer ? data.byteLength : new TextEncoder().encode(data).byteLength;
@@ -208,16 +163,13 @@ export async function parse_trajectory_async(data, filename, on_progress, option
                 ext_hint(filename, /\.(xyz|extxyz)$/) === null &&
                 count_xyz_frames(data.slice(0, 2 ** 20)) >= 1);
         if (should_use_indexing && can_index) {
-            return await parse_with_unified_loader(data, filename, {
-                index_sample_rate,
-                extract_plot_metadata,
-            }, on_progress);
+            return attach_parse_warnings(await parse_with_unified_loader(data, filename, { index_sample_rate, extract_plot_metadata }, on_progress));
         }
         // Fallback to direct parsing
         update_progress(10, `Parsing trajectory...`);
         const result = await parse_trajectory_data(data, filename, atom_type_mapping);
         update_progress(100, `Complete`);
-        return result;
+        return attach_parse_warnings(result);
     }
     catch (error) {
         const error_message = error instanceof Error ? error.message : `Unknown error`;
@@ -259,7 +211,7 @@ async function parse_with_unified_loader(data, filename, options, on_progress) {
             });
         }
         catch (error) {
-            console.warn(`Failed to extract plot metadata:`, error);
+            traj_warn(`Failed to extract plot metadata`, error);
         }
     }
     const stage = `Ready: ${total_frames} frames indexed`;

package/dist/trajectory/parse/lammps.d.ts

@@ -1,5 +1,3 @@
-import * as math from '../../math';
 import type { TrajectoryType } from '../index';
 import type { AtomTypeMapping } from '../types';
-export declare function parse_lammps_box(box_lines: string[], is_triclinic: boolean): math.Matrix3x3 | null;
 export declare function parse_lammps_trajectory(content: string, filename?: string, atom_type_mapping?: AtomTypeMapping): TrajectoryType;

package/dist/trajectory/parse/lammps.js

@@ -1,11 +1,13 @@
 import { ELEM_SYMBOLS } from '../../labels';
 import * as math from '../../math';
-import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+import { coerce_elem_symbol } from '../../element';
+import { 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.
 // Triclinic: converts bounding box to actual dims per https://docs.lammps.org/Howto_triclinic.html
 // Lattice vectors: a=(lx,0,0), b=(xy,ly,0), c=(xz,yz,lz)
-export function parse_lammps_box(box_lines, is_triclinic) {
+function parse_lammps_box(box_lines, is_triclinic) {
     if (box_lines.length !== 3)
         return null;
     const bounds = box_lines.map((line) => line.split(/\s+/).map(Number));
@@ -100,7 +102,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
         if (pos_cols.some((col_idx) => col_idx === undefined))
             continue;
         if (type_col === undefined && element_col === undefined && id_col === undefined) {
-            console.warn(`Skipping LAMMPS frame at timestep ${timestep}: missing type/element/id column`);
+            traj_warn(`Skipping LAMMPS frame at timestep ${timestep}: missing type/element/id column`);
             continue;
         }
         // Parse atom data
@@ -125,9 +127,9 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
                 const raw_symbol = parts[element_col];
                 if (!raw_symbol)
                     continue;
-                element_symbol = coerce_element_symbol(raw_symbol);
+                element_symbol = coerce_elem_symbol(raw_symbol);
                 if (!element_symbol) {
-                    console.warn(`Skipping LAMMPS atom with unknown element symbol "${raw_symbol}" at timestep ${timestep}`);
+                    traj_warn(`Skipping LAMMPS atom with unknown element symbol "${raw_symbol}" at timestep ${timestep}`);
                     continue;
                 }
             }
@@ -135,7 +137,7 @@ export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
                 const atom_id = parseInt(parts[id_col], 10) || 1;
                 atom_types_found.add(atom_id);
                 if (!id_fallback_warning_emitted) {
-                    console.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.`);
+                    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.`);
                     id_fallback_warning_emitted = true;
                 }
                 element_symbol = get_element(atom_id);

package/dist/trajectory/parse/pymatgen.d.ts

@@ -0,0 +1,2 @@
+import type { TrajectoryType } from '../index';
+export declare function parse_pymatgen_trajectory(obj: Record<string, unknown>, filename?: string): TrajectoryType;

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,5 +1,6 @@
 import * as math from '../../math';
-import { create_trajectory_frame, is_valid_element_symbol, validate_3x3_matrix, } from '../helpers';
+import { is_elem_symbol } from '../../element';
+import { create_trajectory_frame, validate_3x3_matrix } from '../helpers';
 // 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) {
@@ -27,7 +28,7 @@ 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));
@@ -46,7 +47,7 @@ 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));
                 }

package/dist/trajectory/parse/xyz.d.ts

@@ -1,26 +1,14 @@
-import type { ElementSymbol } from '../../element/types';
-import * as math from '../../math';
-import type { TrajectoryType } from '../index';
-export declare function parse_extxyz_columns(comment: string): {
-    species_col: number;
-    pos_col: number;
-    forces_col: number;
-    min_cols: number;
-};
-export declare function parse_extxyz_lattice(comment: string): math.Matrix3x3 | undefined;
+import type { TrajectoryFrame, TrajectoryType } from '../index';
 export declare function parse_xyz_comment_metadata(comment: string): {
     step?: number;
     properties: Record<string, number>;
 };
-type ForceStats = {
-    forces: number[][];
-    force_max: number;
-    force_norm: number;
-};
-export declare function parse_xyz_atom_lines(lines: string[], start: number, num_atoms: number, comment: string, frame_label: string): {
-    elements: ElementSymbol[];
-    positions: number[][];
-    force_stats: ForceStats | null;
-};
+export declare function build_xyz_frame(lines: string[], frame: {
+    start: number;
+    num_atoms: number;
+    comment: string;
+}, opts: {
+    frame_label: string;
+    default_step: number;
+}): TrajectoryFrame;
 export declare function parse_xyz_trajectory(content: string): TrajectoryType;
-export {};

package/dist/trajectory/parse/xyz.js

@@ -1,9 +1,11 @@
 import * as math from '../../math';
-import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+import { coerce_elem_symbol } from '../../element';
+import { calc_force_stats, create_trajectory_frame, iter_xyz_frames, } from '../helpers';
+import { 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
-export function parse_extxyz_columns(comment) {
+function parse_extxyz_columns(comment) {
     const fields = /Properties\s*=\s*"?([^"\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
@@ -23,7 +25,7 @@ export function parse_extxyz_columns(comment) {
     return { species_col, pos_col, forces_col, min_cols: Math.max(pos_col + 3, species_col + 1) };
 }
 // Parse Lattice="ax ay az bx by bz cx cy cz" from an extxyz comment line
-export function parse_extxyz_lattice(comment) {
+function parse_extxyz_lattice(comment) {
     const vals = /Lattice\s*=\s*"([^"]+)"/i.exec(comment)?.[1].trim().split(/\s+/).map(Number);
     if (vals?.length !== 9 || !vals.every(Number.isFinite))
         return undefined;
@@ -53,7 +55,7 @@ export function parse_xyz_comment_metadata(comment) {
 // 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.
 // force_stats holds raw forces plus max and RMS force magnitudes when forces are present.
-export function parse_xyz_atom_lines(lines, start, num_atoms, comment, frame_label) {
+function parse_xyz_atom_lines(lines, start, num_atoms, comment, frame_label) {
     const { species_col, pos_col, forces_col, min_cols } = parse_extxyz_columns(comment);
     const elements = [];
     const positions = [];
@@ -64,13 +66,13 @@ export function parse_xyz_atom_lines(lines, start, num_atoms, comment, frame_lab
             continue;
         const pos = parts.slice(pos_col, pos_col + 3).map(parseFloat);
         if (!pos.every(Number.isFinite)) {
-            console.warn(`Skipping XYZ atom with invalid coordinates in ${frame_label} at line ${start + idx + 1}`);
+            traj_warn(`Skipping XYZ atom with invalid coordinates in ${frame_label} at line ${start + idx + 1}`);
             continue;
         }
         const symbol = parts[species_col];
-        const element_symbol = coerce_element_symbol(symbol);
+        const element_symbol = coerce_elem_symbol(symbol);
         if (!element_symbol) {
-            console.warn(`Skipping XYZ atom with unknown element symbol "${symbol}" in ${frame_label}`);
+            traj_warn(`Skipping XYZ atom with unknown element symbol "${symbol}" in ${frame_label}`);
             continue;
         }
         elements.push(element_symbol);
@@ -81,36 +83,29 @@ export function parse_xyz_atom_lines(lines, start, num_atoms, comment, frame_lab
                 forces.push(force_vec);
         }
     }
-    if (forces.length === 0)
-        return { elements, positions, force_stats: null };
-    const mags = forces.map((force) => Math.hypot(...force));
-    const force_norm = Math.sqrt(mags.reduce((sum, mag) => sum + mag ** 2, 0) / mags.length);
-    return {
-        elements,
-        positions,
-        force_stats: { forces, force_max: Math.max(...mags), force_norm },
-    };
+    const stats = calc_force_stats(forces);
+    return { elements, positions, force_stats: stats && { forces, ...stats } };
+}
+// Assemble a TrajectoryFrame from the XYZ frame starting at lines[start] (count line,
+// comment line, atom lines). Shared by the eager parser and the indexed frame reader.
+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 { 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);
 }
 export function parse_xyz_trajectory(content) {
     const lines = content.trim().split(/\r?\n/);
     const frames = [];
-    let line_idx = 0;
-    while (line_idx < lines.length) {
-        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++; // skip blank/invalid lines until the next frame's atom-count line
-            continue;
-        }
-        const comment = lines[line_idx + 1] || ``;
-        const { step, properties } = parse_xyz_comment_metadata(comment);
-        const metadata = { ...properties };
-        const lattice_matrix = parse_extxyz_lattice(comment);
-        if (lattice_matrix)
-            metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
-        const { elements, positions, force_stats } = parse_xyz_atom_lines(lines, line_idx + 2, num_atoms, comment, `frame ${frames.length}`);
-        Object.assign(metadata, force_stats);
-        frames.push(create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step ?? frames.length, metadata));
-        line_idx += num_atoms + 2;
+    for (const frame of iter_xyz_frames(lines)) {
+        frames.push(build_xyz_frame(lines, frame, {
+            frame_label: `frame ${frames.length}`,
+            default_step: frames.length,
+        }));
     }
     return {
         frames,

package/dist/trajectory/plotting.d.ts

@@ -9,7 +9,6 @@ export interface PlotSeriesOptions {
     default_visible_properties?: Set<string>;
 }
 export declare function generate_plot_series(trajectory: TrajectoryType, data_extractor: TrajectoryDataExtractor, options?: PlotSeriesOptions): DataSeries[];
-export declare function toggle_series_visibility(series: DataSeries[], target_series_idx: number): DataSeries[];
 export declare function should_hide_plot(trajectory: TrajectoryType | undefined, plot_series: DataSeries[], tolerance?: number): boolean;
 export declare function generate_axis_labels(plot_series: DataSeries[]): {
     y1: string;