matterviz 0.3.6 → 0.4.0

package/dist/trajectory/frame-reader.js

@@ -0,0 +1,299 @@
+// 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';
+export class TrajFrameReader {
+    format;
+    global_numbers;
+    constructor(filename) {
+        const base_filename = strip_compression_extensions(filename);
+        this.format = base_filename.endsWith(`.traj`) ? `ase` : `xyz`;
+    }
+    async get_total_frames(data) {
+        if (this.format === `xyz`) {
+            if (data instanceof ArrayBuffer)
+                throw new Error(`XYZ loader requires text data`);
+            return count_xyz_frames(data);
+        }
+        if (!(data instanceof ArrayBuffer))
+            throw new Error(`ASE loader requires binary data`);
+        const view = new DataView(data);
+        return Number(view.getBigInt64(32, true));
+    }
+    async build_frame_index(data, sample_rate, on_progress) {
+        const total_frames = await this.get_total_frames(data);
+        const frame_index = [];
+        if (this.format === `xyz`) {
+            const data_str = data;
+            const lines = data_str.trim().split(/\r?\n/);
+            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;
+                }
+                if (current_frame % sample_rate === 0) {
+                    frame_index.push({
+                        frame_number: current_frame,
+                        byte_offset,
+                        estimated_size: 0,
+                    });
+                }
+                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) {
+                    on_progress({
+                        current: (current_frame / total_frames) * 100,
+                        total: 100,
+                        stage: `Indexing: ${current_frame}`,
+                    });
+                }
+            }
+        }
+        else {
+            const view = new DataView(data);
+            const offsets_pos = Number(view.getBigInt64(40, true));
+            for (let idx = 0; idx < total_frames; idx += sample_rate) {
+                const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
+                frame_index.push({
+                    frame_number: idx,
+                    byte_offset: frame_offset,
+                    estimated_size: 0,
+                });
+                if (on_progress && idx % 10000 === 0) {
+                    on_progress({
+                        current: (idx / total_frames) * 100,
+                        total: 100,
+                        stage: `Indexing ASE: ${idx}`,
+                    });
+                }
+            }
+        }
+        return frame_index;
+    }
+    async load_frame(data, frame_number) {
+        const actual_data_type = data instanceof ArrayBuffer ? `ArrayBuffer` : typeof data;
+        if (this.format === `xyz`) {
+            if (typeof data !== `string`) {
+                throw new TypeError(`load_frame expected string data for xyz format, received ${actual_data_type}`);
+            }
+            return this.load_xyz_frame(data, frame_number);
+        }
+        if (!(data instanceof ArrayBuffer)) {
+            throw new TypeError(`load_frame expected ArrayBuffer data for ase format, received ${actual_data_type}`);
+        }
+        return this.load_ase_frame(data, frame_number);
+    }
+    async extract_plot_metadata(data, options, on_progress) {
+        const { sample_rate = 1, properties } = options ?? {};
+        const metadata_list = [];
+        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;
+                }
+                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);
+                }
+                line_idx += 2 + num_atoms;
+                current_frame++;
+                if (on_progress && current_frame % 5000 === 0) {
+                    on_progress({
+                        current: (current_frame / total_frames) * 100,
+                        total: 100,
+                        stage: `Extracting: ${current_frame}`,
+                    });
+                }
+            }
+        }
+        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));
+            for (let idx = 0; idx < n_items; idx += sample_rate) {
+                try {
+                    const frame_offset = Number(view.getBigInt64(offsets_pos + idx * 8, true));
+                    const json_length = Number(view.getBigInt64(frame_offset, true));
+                    if (json_length > MAX_METADATA_SIZE) {
+                        console.warn(`Skipping large frame ${idx}: ${Math.round(json_length / 1024 / 1024)}MB`);
+                        continue;
+                    }
+                    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;
+                    }
+                    metadata_list.push(frame_metadata);
+                    if (on_progress && idx % 5000 === 0) {
+                        on_progress({
+                            current: (idx / n_items) * 100,
+                            total: 100,
+                            stage: `Extracting ASE: ${idx}/${n_items}`,
+                        });
+                    }
+                }
+                catch (error) {
+                    console.warn(`Failed to extract metadata from ASE frame ${idx}:`, error);
+                }
+            }
+        }
+        return metadata_list;
+    }
+    load_xyz_frame(data, frame_number) {
+        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);
+    }
+    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));
+            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);
+        }
+        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];
+                }
+            }
+        }
+        if (frame_data.info && typeof frame_data.info === `object`) {
+            const info = frame_data.info;
+            const info_properties = [
+                `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 {
+                const validated_cell = validate_3x3_matrix(frame_data.cell);
+                properties.volume = Math.abs(math.det_3x3(validated_cell));
+            }
+            catch (error) {
+                console.warn(`Failed to calculate volume for ASE frame ${frame_number}:`, error);
+            }
+        }
+        return { frame_number, step, properties };
+    }
+}

package/dist/trajectory/helpers.d.ts

@@ -0,0 +1,15 @@
+import type { ElementSymbol } from '../element/types';
+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 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 function count_xyz_frames(data: string): number;

package/dist/trajectory/helpers.js

@@ -0,0 +1,164 @@
+// Shared utilities for trajectory parsing
+import { ATOMIC_NUMBER_TO_SYMBOL } from '../composition/parse';
+import { ELEM_SYMBOLS } from '../labels';
+import * as math from '../math';
+const element_symbol_set = new Set(ELEM_SYMBOLS);
+const is_valid_row = (row) => {
+    if (!(Array.isArray(row) || (ArrayBuffer.isView(row) && `length` in row)))
+        return false;
+    return math.is_finite_vec3_like(row);
+};
+const is_valid_vec3 = (coords) => Array.isArray(coords) && math.is_finite_vec3_like(coords);
+export const is_valid_element_symbol = (symbol) => element_symbol_set.has(symbol);
+export const coerce_element_symbol = (symbol) => is_valid_element_symbol(symbol) ? symbol : undefined;
+// Validate that data is a proper 3x3 matrix
+// Accepts both regular arrays and typed arrays (Float32Array, Float64Array, etc.)
+export function validate_3x3_matrix(data) {
+    if (!Array.isArray(data) || data.length !== 3) {
+        throw new Error(`Expected 3x3 matrix, got array of length ${Array.isArray(data) ? data.length : `non-array`}`);
+    }
+    if (!data.every(is_valid_row)) {
+        throw new Error(`Invalid 3x3 matrix structure`);
+    }
+    return data;
+}
+export const convert_atomic_numbers = (numbers) => numbers.map((num) => {
+    const symbol = ATOMIC_NUMBER_TO_SYMBOL[num];
+    if (!symbol || !is_valid_element_symbol(symbol)) {
+        throw new Error(`Unknown atomic number in trajectory data: ${num}`);
+    }
+    return symbol;
+});
+export const create_structure = (positions, elements, lattice_matrix, pbc, force_data) => {
+    if (positions.length !== elements.length) {
+        throw new Error(`create_structure requires matching positions and elements lengths, got positions=${positions.length}, elements=${elements.length}`);
+    }
+    const cart_to_frac = lattice_matrix ? math.create_cart_to_frac(lattice_matrix) : null;
+    const sites = positions.map((pos, idx) => {
+        if (!is_valid_vec3(pos)) {
+            throw new Error(`Invalid position at index ${idx}: expected 3 finite coordinates`);
+        }
+        const xyz = pos;
+        const abc = cart_to_frac ? cart_to_frac(xyz) : [0, 0, 0];
+        const force = force_data?.[idx];
+        const properties = is_valid_vec3(force) ? { force } : {};
+        return {
+            species: [{ element: elements[idx], occu: 1, oxidation_state: 0 }],
+            abc,
+            xyz,
+            label: `${elements[idx]}${idx + 1}`,
+            properties,
+        };
+    });
+    return lattice_matrix
+        ? {
+            sites,
+            lattice: {
+                matrix: lattice_matrix,
+                ...math.calc_lattice_params(lattice_matrix),
+                pbc: pbc ?? [true, true, true],
+            },
+        }
+        : { sites };
+};
+export const create_trajectory_frame = (positions, elements, lattice_matrix, pbc, step, metadata = {}) => ({
+    structure: create_structure(positions, elements, lattice_matrix, pbc),
+    step,
+    metadata,
+});
+// Shared utility to read ndarray data from binary format
+export const read_ndarray_from_view = (view, ref) => {
+    const [shape, dtype, array_offset] = ref.ndarray;
+    const total = shape.reduce((product, dim_size) => product * dim_size, 1);
+    const data = [];
+    let pos = array_offset;
+    const readers = {
+        int64: {
+            bytes_per_element: 8,
+            read: () => {
+                const value = Number(view.getBigInt64(pos, true));
+                pos += 8;
+                return value;
+            },
+        },
+        int32: {
+            bytes_per_element: 4,
+            read: () => {
+                const value = view.getInt32(pos, true);
+                pos += 4;
+                return value;
+            },
+        },
+        float64: {
+            bytes_per_element: 8,
+            read: () => {
+                const value = view.getFloat64(pos, true);
+                pos += 8;
+                return value;
+            },
+        },
+        float32: {
+            bytes_per_element: 4,
+            read: () => {
+                const value = view.getFloat32(pos, true);
+                pos += 4;
+                return value;
+            },
+        },
+    };
+    const reader_config = readers[dtype];
+    if (!reader_config)
+        throw new Error(`Unsupported dtype: ${dtype}`);
+    if (!Number.isInteger(array_offset) || array_offset < 0) {
+        throw new Error(`Invalid array_offset: expected non-negative integer, got ${array_offset}`);
+    }
+    const bytes_needed = total * reader_config.bytes_per_element;
+    if (array_offset + bytes_needed > view.byteLength) {
+        throw new Error(`Out-of-bounds read: array_offset + bytesNeeded exceeds view.byteLength`);
+    }
+    for (let idx = 0; idx < total; idx++)
+        data.push(reader_config.read());
+    return shape.length === 1
+        ? [data]
+        : shape.length === 2
+            ? Array.from({ length: shape[0] }, (_, idx) => data.slice(idx * shape[1], (idx + 1) * shape[1]))
+            : (() => {
+                throw new Error(`Unsupported shape`);
+            })();
+};
+// Unified frame counting for XYZ
+export function count_xyz_frames(data) {
+    if (!data || typeof data !== `string`)
+        return 0;
+    const lines = data.trim().split(/\r?\n/);
+    let frame_count = 0;
+    let line_idx = 0;
+    while (line_idx < lines.length) {
+        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 + 2 > lines.length) {
+            line_idx++;
+            continue;
+        }
+        // Quick validation of first few atom lines
+        let valid_coords = 0;
+        for (let idx = 0; idx < Math.min(num_atoms, 3); idx++) {
+            const parts = lines[line_idx + 2 + idx]?.trim().split(/\s+/);
+            if (parts?.length >= 4 && isNaN(parseInt(parts[0], 10)) && parts[0].length <= 3) {
+                if (parts.slice(1, 4).every((coord) => !isNaN(parseFloat(coord))))
+                    valid_coords++;
+            }
+        }
+        if (valid_coords >= Math.min(num_atoms, 3)) {
+            frame_count++;
+            line_idx += 2 + num_atoms;
+        }
+        else {
+            line_idx++;
+        }
+    }
+    return frame_count;
+}

package/dist/trajectory/index.d.ts

@@ -0,0 +1,63 @@
+import type { ComponentProps } from 'svelte';
+import type { AnyStructure } from '../structure/index';
+import type Trajectory from './Trajectory.svelte';
+export { default as Trajectory } from './Trajectory.svelte';
+export { default as TrajectoryError } from './TrajectoryError.svelte';
+export { default as TrajectoryExportPane } from './TrajectoryExportPane.svelte';
+export { default as TrajectoryInfoPane } from './TrajectoryInfoPane.svelte';
+export type TrajectoryFormat = `hdf5` | `json` | `xyz` | `xdatcar` | `traj` | `unknown`;
+export type { AtomTypeMapping } from './types';
+export interface ParseProgress {
+    current: number;
+    total: number;
+    stage: string;
+}
+export interface TrajectoryFrame {
+    structure: AnyStructure;
+    step: number;
+    metadata?: Record<string, unknown>;
+}
+export interface FrameIndex {
+    frame_number: number;
+    byte_offset: number;
+    estimated_size: number;
+}
+export interface TrajectoryMetadata {
+    frame_number: number;
+    step: number;
+    properties: Record<string, number>;
+}
+export interface TrajectoryType {
+    frames: TrajectoryFrame[];
+    metadata?: Record<string, unknown>;
+    total_frames?: number;
+    indexed_frames?: FrameIndex[];
+    plot_metadata?: TrajectoryMetadata[];
+    is_indexed?: boolean;
+    frame_loader?: FrameLoader;
+}
+export interface TrajHandlerData {
+    trajectory?: TrajectoryType;
+    step_idx?: number;
+    frame_count?: number;
+    frame?: TrajectoryFrame;
+    filename?: string;
+    file_size?: number;
+    total_atoms?: number;
+    error_msg?: string;
+    fps?: number;
+    mode?: ComponentProps<typeof Trajectory>[`display_mode`];
+    fullscreen?: boolean;
+}
+export type TrajectoryDataExtractor = (frame: TrajectoryFrame, trajectory: TrajectoryType) => Record<string, number>;
+export interface FrameLoader {
+    get_total_frames: (data: string | ArrayBuffer) => Promise<number>;
+    build_frame_index: (data: string | ArrayBuffer, sample_rate: number, on_progress?: (progress: ParseProgress) => void) => Promise<FrameIndex[]>;
+    load_frame: (data: string | ArrayBuffer, frame_number: number) => Promise<TrajectoryFrame | null>;
+    extract_plot_metadata: (data: string | ArrayBuffer, options?: {
+        sample_rate?: number;
+        properties?: string[];
+    }, on_progress?: (progress: ParseProgress) => void) => Promise<TrajectoryMetadata[]>;
+}
+export declare function validate_trajectory(trajectory: TrajectoryType): string[];
+export declare function get_trajectory_stats(trajectory: TrajectoryType): Record<string, unknown>;

package/dist/trajectory/index.js

@@ -0,0 +1,126 @@
+export { default as Trajectory } from './Trajectory.svelte';
+export { default as TrajectoryError } from './TrajectoryError.svelte';
+export { default as TrajectoryExportPane } from './TrajectoryExportPane.svelte';
+export { default as TrajectoryInfoPane } from './TrajectoryInfoPane.svelte';
+export function validate_trajectory(trajectory) {
+    // with detailed error reporting
+    const errors = [];
+    const { frames, total_frames, indexed_frames, plot_metadata, is_indexed } = trajectory;
+    if (!frames?.length)
+        return [`Trajectory must have at least one frame`];
+    frames.forEach((frame, idx) => {
+        if (!frame.structure?.sites?.length) {
+            errors.push(`Frame ${idx} missing structure or sites`);
+        }
+        if (typeof frame.step !== `number`) {
+            errors.push(`Frame ${idx} missing or invalid step number`);
+        }
+    });
+    // Validate streaming-related properties
+    if (total_frames !== undefined) {
+        if (typeof total_frames !== `number` || total_frames < 1) {
+            errors.push(`total_frames must be a positive number, got ${total_frames}`);
+        }
+        else if (indexed_frames?.length) {
+            const last_indexed_frame = indexed_frames.at(-1);
+            if (last_indexed_frame && last_indexed_frame.frame_number >= total_frames) {
+                errors.push(`indexed_frames contains frame_number >= total_frames (${total_frames})`);
+            }
+        }
+    }
+    if (is_indexed === true && !indexed_frames?.length) {
+        errors.push(`is_indexed is true but indexed_frames is missing or empty`);
+    }
+    if (indexed_frames) {
+        if (!Array.isArray(indexed_frames)) {
+            errors.push(`indexed_frames must be an array`);
+        }
+        else {
+            indexed_frames.forEach((frame_idx, idx) => {
+                if (typeof frame_idx.frame_number !== `number`) {
+                    errors.push(`indexed_frames[${idx}] missing or invalid frame_number`);
+                }
+                else if (frame_idx.frame_number < 0) {
+                    errors.push(`indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) must be non-negative`);
+                }
+                else if (idx > 0 && frame_idx.frame_number <= indexed_frames[idx - 1].frame_number) {
+                    errors.push(`indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) must be strictly increasing`);
+                }
+                if (typeof frame_idx.byte_offset !== `number`) {
+                    errors.push(`indexed_frames[${idx}] missing or invalid byte_offset`);
+                }
+                if (typeof frame_idx.estimated_size !== `number`) {
+                    errors.push(`indexed_frames[${idx}] missing or invalid estimated_size`);
+                }
+            });
+        }
+    }
+    if (plot_metadata) {
+        if (!Array.isArray(plot_metadata)) {
+            errors.push(`plot_metadata must be an array`);
+        }
+        else {
+            plot_metadata.forEach((meta, idx) => {
+                if (typeof meta.frame_number !== `number`) {
+                    errors.push(`plot_metadata[${idx}] missing or invalid frame_number`);
+                }
+                if (typeof meta.step !== `number`) {
+                    errors.push(`plot_metadata[${idx}] missing or invalid step`);
+                }
+                if (!meta.properties || typeof meta.properties !== `object`) {
+                    errors.push(`plot_metadata[${idx}] missing or invalid properties object`);
+                }
+            });
+        }
+    }
+    return errors;
+}
+export function get_trajectory_stats(trajectory) {
+    const { frames, total_frames, indexed_frames, plot_metadata } = trajectory;
+    const frame_count = total_frames ?? frames.length;
+    const stats = {
+        frame_count,
+        is_indexed: trajectory.is_indexed ?? false,
+    };
+    if (frames.length > 0) {
+        const [first_frame, last_frame] = [frames[0], frames.at(-1) ?? frames[0]];
+        const max_sample = 100;
+        const sampled = frames.length <= max_sample
+            ? frames
+            : (() => {
+                const interval = Math.floor(frames.length / max_sample);
+                const result = [first_frame];
+                for (let idx = interval; idx < frames.length - 1; idx += interval) {
+                    result.push(frames[idx]);
+                }
+                if (result.at(-1) !== last_frame)
+                    result.push(last_frame);
+                return result;
+            })();
+        const counts = sampled.map((frame) => frame.structure.sites.length);
+        const constant = counts.every((count) => count === counts[0]);
+        const all_counts = constant
+            ? [first_frame.structure.sites.length]
+            : frames.map((frame) => frame.structure.sites.length);
+        stats.steps = frames.map((frame) => frame.step);
+        stats.step_range = [first_frame.step, last_frame.step];
+        stats.constant_atom_count = constant;
+        if (constant)
+            stats.total_atoms = first_frame.structure.sites.length;
+        else
+            stats.atom_count_range = [Math.min(...all_counts), Math.max(...all_counts)];
+    }
+    else {
+        // Handle empty trajectory case
+        stats.steps = [];
+        stats.step_range = undefined;
+        stats.constant_atom_count = undefined;
+        stats.total_atoms = undefined;
+    }
+    // Additional metadata for large files
+    if (indexed_frames)
+        stats.indexed_frame_count = indexed_frames.length;
+    if (plot_metadata)
+        stats.plot_metadata_count = plot_metadata.length;
+    return stats;
+}

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

@@ -0,0 +1,2 @@
+import type { TrajectoryType } from '../index';
+export declare function parse_ase_trajectory(buffer: ArrayBuffer, filename?: string): TrajectoryType;