matterviz 0.3.0 → 0.3.2

package/dist/trajectory/frame-reader.js

@@ -0,0 +1,339 @@
+import * as math from '../math';
+import { MAX_METADATA_SIZE } from './constants';
+import { coerce_element_symbol, 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';
+export class TrajFrameReader {
+    format;
+    global_numbers;
+    constructor(filename) {
+        const base_filename = strip_compression_extensions(filename);
+        this.format = base_filename.endsWith(`.traj`) ? `ase` : `xyz`;
+    }
+    // deno-lint-ignore require-await
+    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;
+    }
+    // deno-lint-ignore require-await
+    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) {
+            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++;
+                continue;
+            }
+            line_idx += 2 + num_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 positions = [];
+        const elements = [];
+        for (let idx = 0; idx < num_atoms; idx++) {
+            const parts = lines[line_idx + 2 + idx]?.trim().split(/\s+/);
+            if (parts?.length >= 4) {
+                const x_coord = parseFloat(parts[1]);
+                const y_coord = parseFloat(parts[2]);
+                const z_coord = parseFloat(parts[3]);
+                if (!Number.isFinite(x_coord) || !Number.isFinite(y_coord) ||
+                    !Number.isFinite(z_coord)) {
+                    console.warn(`Skipping XYZ atom with invalid coordinates in indexed frame ${frame_number} at line ${line_idx + 2 + idx}`);
+                    continue;
+                }
+                const raw_symbol = parts[0];
+                const element_symbol = coerce_element_symbol(raw_symbol);
+                if (!element_symbol) {
+                    console.warn(`Skipping XYZ atom with unknown element symbol "${raw_symbol}" in indexed frame ${frame_number}`);
+                    continue;
+                }
+                elements.push(element_symbol);
+                positions.push([x_coord, y_coord, z_coord]);
+            }
+        }
+        const metadata = this.parse_xyz_metadata(comment, frame_number);
+        return create_trajectory_frame(positions, elements, undefined, undefined, metadata.step, metadata.properties);
+    }
+    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 properties = {};
+        const patterns = {
+            energy: /(?:energy|E|etot)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            volume: /(?:volume|vol|V)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            pressure: /(?:pressure|press|P)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            force_max: /(?:max_force|fmax)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+        };
+        Object.entries(patterns).forEach(([key, pattern]) => {
+            const match = pattern.exec(comment);
+            if (match)
+                properties[key] = parseFloat(match[1]);
+        });
+        const step_match = comment.match(/(?:step|frame)\s*[=:]?\s*(\d+)/i);
+        const step = step_match ? parseInt(step_match[1]) : frame_number;
+        return { frame_number, step, 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';
+import * as math from '../math';
+import type { AnyStructure, Pbc } from '../structure';
+import type { TrajectoryFrame } from './index';
+export declare function is_valid_element_symbol(symbol: string): symbol is ElementSymbol;
+export declare function 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 get_inverse_matrix: (matrix: math.Matrix3x3) => math.Matrix3x3;
+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,187 @@
+// 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);
+export function is_valid_element_symbol(symbol) {
+    return element_symbol_set.has(symbol);
+}
+export function coerce_element_symbol(symbol) {
+    return 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`}`);
+    }
+    const is_valid_row = (row) => {
+        if (Array.isArray(row))
+            return row.length === 3;
+        if (!ArrayBuffer.isView(row))
+            return false;
+        return `length` in row && typeof row.length === `number` && row.length === 3;
+    };
+    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;
+});
+// Cache inverse matrices by original matrix reference for performance
+// IMPORTANT: This cache assumes lattice matrices are immutable. Mutating a cached
+// matrix in place yields incorrect inverses. Always create new matrix instances
+// if modifications are needed.
+const matrix_cache = new WeakMap();
+export const get_inverse_matrix = (matrix) => {
+    const cached = matrix_cache.get(matrix);
+    if (cached)
+        return cached;
+    const inverse = math.matrix_inverse_3x3(matrix);
+    matrix_cache.set(matrix, inverse);
+    return inverse;
+};
+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 inv_matrix = lattice_matrix ? get_inverse_matrix(lattice_matrix) : null;
+    const is_valid_vec3 = (coords) => Array.isArray(coords) &&
+        coords.length === 3 &&
+        coords.every((value) => typeof value === `number` && Number.isFinite(value));
+    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 = inv_matrix
+            ? math.mat3x3_vec3_multiply(inv_matrix, 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])) && 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

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

package/dist/trajectory/index.js

@@ -20,8 +20,11 @@ export function validate_trajectory(trajectory) {
         if (typeof total_frames !== `number` || total_frames < 1) {
             errors.push(`total_frames must be a positive number, got ${total_frames}`);
         }
-        else if (indexed_frames && total_frames !== indexed_frames.length) {
-            errors.push(`total_frames (${total_frames}) inconsistent with indexed_frames length (${indexed_frames.length})`);
+        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) {
@@ -36,8 +39,12 @@ export function validate_trajectory(trajectory) {
                 if (typeof frame_idx.frame_number !== `number`) {
                     errors.push(`indexed_frames[${idx}] missing or invalid frame_number`);
                 }
-                else if (frame_idx.frame_number !== idx) {
-                    errors.push(`indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) should equal index (${idx})`);
+                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`);

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;

package/dist/trajectory/parse/ase.js

@@ -0,0 +1,76 @@
+// ASE trajectory (.traj) parsing - binary format
+import { MAX_SAFE_STRING_LENGTH } from '../constants';
+import { convert_atomic_numbers, create_trajectory_frame, read_ndarray_from_view, validate_3x3_matrix, } from '../helpers';
+export function parse_ase_trajectory(buffer, filename) {
+    const view = new DataView(buffer);
+    let offset = 0;
+    const signature = new TextDecoder().decode(new Uint8Array(buffer, 0, 8));
+    if (signature !== `- of Ulm`)
+        throw new Error(`Invalid ASE trajectory`);
+    offset += 24;
+    const _version = Number(view.getBigInt64(offset, true));
+    offset += 8;
+    const n_items = Number(view.getBigInt64(offset, true));
+    offset += 8;
+    const offsets_pos = Number(view.getBigInt64(offset, true));
+    if (n_items <= 0)
+        throw new Error(`Invalid frame count`);
+    if (offsets_pos < 0 ||
+        offsets_pos + n_items * 8 > buffer.byteLength) {
+        throw new Error(`Invalid ASE frame offsets table bounds: offsets_pos=${offsets_pos}, n_items=${n_items}, byte_length=${buffer.byteLength}`);
+    }
+    const frame_offsets = Array.from({ length: n_items }, (_, idx) => Number(view.getBigInt64(offsets_pos + idx * 8, true)));
+    const frames = [];
+    let global_numbers;
+    for (let idx = 0; idx < n_items; idx++) {
+        try {
+            offset = frame_offsets[idx];
+            const json_length = Number(view.getBigInt64(offset, true));
+            offset += 8;
+            if (json_length > MAX_SAFE_STRING_LENGTH) {
+                console.warn(`Skipping frame ${idx + 1}/${n_items}: too large`);
+                continue;
+            }
+            const frame_data = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, offset, 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 || global_numbers;
+            const numbers = numbers_ref?.ndarray
+                ? read_ndarray_from_view(view, numbers_ref).flat()
+                : numbers_ref;
+            if (numbers)
+                global_numbers = numbers;
+            if (!numbers || !positions) {
+                console.warn(`Skipping ASE frame ${idx + 1}/${n_items}: missing ${!numbers ? `numbers` : `positions`}`);
+                continue;
+            }
+            const elements = convert_atomic_numbers(numbers);
+            const metadata = {
+                step: idx,
+                ...(frame_data.calculator || {}),
+                ...(frame_data.info || {}),
+            };
+            frames.push(create_trajectory_frame(positions, elements, frame_data.cell ? validate_3x3_matrix(frame_data.cell) : undefined, frame_data.pbc || [true, true, true], idx, metadata));
+        }
+        catch (error) {
+            console.warn(`Error processing frame ${idx + 1}/${n_items}:`, error);
+        }
+    }
+    if (frames.length === 0)
+        throw new Error(`No valid frames found`);
+    const first_struct = frames[0]?.structure;
+    const periodic_boundary_conditions = first_struct !== null && first_struct !== undefined &&
+        typeof first_struct === `object` && `lattice` in first_struct
+        ? first_struct.lattice.pbc
+        : [true, true, true];
+    const metadata = {
+        filename,
+        source_format: `ase_trajectory`,
+        frame_count: frames.length,
+        total_atoms: global_numbers?.length || 0,
+        periodic_boundary_conditions,
+    };
+    return { frames, metadata };
+}

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

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