matterviz 0.3.0 → 0.3.2

package/dist/trajectory/parse/hdf5.js

@@ -0,0 +1,121 @@
+// HDF5 trajectory parsing (torch-sim / generic format)
+import { calc_lattice_params, transpose_3x3_matrix } from '../../math';
+import * as h5wasm from 'h5wasm';
+import { convert_atomic_numbers, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
+const is_hdf5_dataset = (entity) => entity !== null && (`to_array` in entity && entity instanceof h5wasm.Dataset);
+const is_hdf5_group = (entity) => entity !== null && (`keys` in entity && entity instanceof h5wasm.Group);
+export async function parse_torch_sim_hdf5(buffer, filename) {
+    const { FS } = await h5wasm.ready;
+    const file_basename = filename?.split(`/`).at(-1)?.replace(/[^\w.-]/g, `_`) || `temp`;
+    const unique_suffix = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const temp_filename = `${file_basename}-${unique_suffix}.h5`;
+    FS.writeFile(temp_filename, new Uint8Array(buffer));
+    let h5_file = null;
+    try {
+        h5_file = new h5wasm.File(temp_filename, `r`);
+        const found_paths = {};
+        let total_groups_found = 0;
+        const find_dataset = (names) => {
+            const discover = (parent, path = ``) => {
+                total_groups_found++;
+                for (const name of parent.keys()) {
+                    const item = parent.get(name);
+                    const full_path = path ? `${path}/${name}` : `/${name}`;
+                    if (names.includes(name) && is_hdf5_dataset(item)) {
+                        const found_name = names.find((n) => n === name);
+                        if (found_name)
+                            found_paths[found_name] = full_path;
+                        return item;
+                    }
+                    if (is_hdf5_group(item)) {
+                        const result = discover(item, full_path);
+                        if (result)
+                            return result;
+                    }
+                }
+                return null;
+            };
+            return discover(h5_file);
+        };
+        const positions_data = find_dataset([`positions`, `coords`, `coordinates`])
+            ?.to_array();
+        const atomic_numbers_data = find_dataset([`atomic_numbers`, `numbers`, `Z`, `species`])?.to_array();
+        const cells_data = find_dataset([`cell`, `cells`, `lattice`])?.to_array();
+        const energies_data = find_dataset([`potential_energy`, `energy`])?.to_array();
+        if (!positions_data || !atomic_numbers_data) {
+            const missing_datasets = [];
+            if (!positions_data) {
+                missing_datasets.push(`positions (tried: positions, coords, coordinates)`);
+            }
+            if (!atomic_numbers_data) {
+                missing_datasets.push(`atomic numbers (tried: atomic_numbers, numbers, Z, species)`);
+            }
+            const missing_str = missing_datasets.join(`, `);
+            const available_str = Array.from(h5_file.keys()).join(`, `);
+            throw new Error(`Missing required dataset(s) in HDF5 file: ${missing_str}. Available datasets: ${available_str}`);
+        }
+        const positions_are_frames = positions_data.length > 0 &&
+            positions_data.every((entry) => Array.isArray(entry) && entry.every((coord) => Array.isArray(coord)));
+        const positions = positions_are_frames
+            ? positions_data
+            : [positions_data];
+        const atomic_numbers_are_frames = atomic_numbers_data.length > 0 &&
+            atomic_numbers_data.every((entry) => Array.isArray(entry));
+        const atomic_numbers = atomic_numbers_are_frames
+            ? atomic_numbers_data
+            : [atomic_numbers_data];
+        const frames = positions.map((frame_pos, idx) => {
+            const frame_atomic_numbers = atomic_numbers[idx] || atomic_numbers[0];
+            const frame_elements = convert_atomic_numbers(frame_atomic_numbers);
+            const cell = cells_data?.[idx];
+            const lattice_mat = cell
+                ? transpose_3x3_matrix(validate_3x3_matrix(cell))
+                : undefined;
+            const energy_entry = energies_data?.[idx];
+            const energy = Array.isArray(energy_entry) ? energy_entry[0] : energy_entry;
+            const metadata = {};
+            if (energy !== undefined)
+                metadata.energy = energy;
+            if (lattice_mat) {
+                metadata.volume = calc_lattice_params(lattice_mat).volume;
+            }
+            const pbc = lattice_mat ? [true, true, true] : [false, false, false];
+            return create_trajectory_frame(frame_pos, frame_elements, lattice_mat, pbc, idx, metadata);
+        });
+        const first_frame_elements = frames[0]?.structure.sites.map((site) => site.species[0].element) ??
+            [];
+        return {
+            frames,
+            metadata: {
+                source_format: `hdf5_trajectory`,
+                frame_count: frames.length,
+                num_atoms: first_frame_elements.length,
+                periodic_boundary_conditions: cells_data
+                    ? [true, true, true]
+                    : [false, false, false],
+                element_counts: first_frame_elements.reduce((counts, element) => {
+                    counts[element] = (counts[element] || 0) + 1;
+                    return counts;
+                }, {}),
+                discovered_datasets: {
+                    positions: found_paths.positions || found_paths.coords ||
+                        found_paths.coordinates ||
+                        `unknown`,
+                    atomic_numbers: found_paths.atomic_numbers || found_paths.numbers ||
+                        found_paths.Z || found_paths.species || `unknown`,
+                    cells: found_paths.cell || found_paths.cells || found_paths.lattice,
+                    energies: found_paths.potential_energy || found_paths.energy,
+                },
+                total_groups_found,
+                has_cell_info: Boolean(cells_data),
+            },
+        };
+    }
+    finally {
+        h5_file?.close();
+        try {
+            FS.unlink(temp_filename);
+        }
+        catch { /* temp file cleanup is best-effort */ }
+    }
+}

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

@@ -0,0 +1,12 @@
+import { is_trajectory_file } from '../format-detect';
+import { TrajFrameReader } from '../frame-reader';
+import type { FrameLoader, ParseProgress, TrajectoryType } from '../index';
+import type { AtomTypeMapping, LoadingOptions } from '../types';
+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 type { AtomTypeMapping, LoadingOptions } from '../types';
+export { is_trajectory_file, TrajFrameReader };
+export declare function parse_trajectory_data(data: unknown, filename?: string, atom_type_mapping?: AtomTypeMapping): Promise<TrajectoryType>;
+export declare function get_unsupported_format_message(filename: string, content: string): string | null;
+export declare function parse_trajectory_async(data: ArrayBuffer | string, filename: string, on_progress?: (progress: ParseProgress) => void, options?: LoadingOptions): Promise<TrajectoryType>;
+export declare function create_frame_loader(filename: string): FrameLoader;
+export declare function load_binary_traj(resp: Response, type: string, fallback?: boolean): Promise<ArrayBuffer | string>;

package/dist/trajectory/parse/index.js

@@ -0,0 +1,304 @@
+import { is_binary } from '../../io/is-binary';
+import * as math from '../../math';
+import { parse_xyz } from '../../structure/parse';
+import { INDEX_SAMPLE_RATE, LARGE_FILE_THRESHOLD } from '../constants';
+import { FORMAT_PATTERNS, is_trajectory_file, strip_compression_extensions, } from '../format-detect';
+import { TrajFrameReader } from '../frame-reader';
+import { create_trajectory_frame, validate_3x3_matrix } from '../helpers';
+import { parse_ase_trajectory } from './ase';
+import { parse_torch_sim_hdf5 } from './hdf5';
+import { parse_lammps_trajectory } from './lammps';
+import { parse_vasp_xdatcar } from './vasp';
+import { parse_xyz_trajectory } from './xyz';
+const log_parse_debug = (message, error) => {
+    console.debug(message, error);
+};
+// 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 { is_trajectory_file, TrajFrameReader };
+export async function parse_trajectory_data(data, filename, atom_type_mapping) {
+    if (data instanceof ArrayBuffer) {
+        if (FORMAT_PATTERNS.ase(data, filename))
+            return parse_ase_trajectory(data, filename);
+        if (FORMAT_PATTERNS.hdf5(data, filename)) {
+            return await parse_torch_sim_hdf5(data, filename);
+        }
+        throw new Error(`Unsupported binary format${filename ? `: ${filename}` : ``}`);
+    }
+    if (typeof data === `string`) {
+        const content = data.trim();
+        if (FORMAT_PATTERNS.xyz_multi(content, filename))
+            return parse_xyz_trajectory(content);
+        if (FORMAT_PATTERNS.vasp(content, filename)) {
+            return parse_vasp_xdatcar(content, filename);
+        }
+        if (FORMAT_PATTERNS.lammpstrj(content, filename)) {
+            return parse_lammps_trajectory(content, filename, atom_type_mapping);
+        }
+        // Single XYZ fallback
+        if (filename?.toLowerCase().match(/\.(?:xyz|extxyz)$/)) {
+            try {
+                const structure = parse_xyz(content);
+                if (structure) {
+                    return {
+                        frames: [{ structure, step: 0, metadata: {} }],
+                        metadata: { source_format: `single_xyz`, frame_count: 1 },
+                    };
+                }
+            }
+            catch (error) {
+                // 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`);
+        }
+    }
+    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;
+            return {
+                structure: (frame_obj.structure || frame_obj),
+                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;
+    // 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],
+            },
+        };
+    }
+    // Object with frames
+    if (Array.isArray(obj.frames)) {
+        const metadata = (obj.metadata ?? {});
+        return {
+            frames: obj.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 },
+        };
+    }
+    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) {
+        if (lower.endsWith(ext)) {
+            return `🚫 ${name} compression not supported in browser\nPlease decompress the file first`;
+        }
+    }
+    // .dump files are LAMMPS binary dumps which require external tools to parse.
+    // .lammpstrj files are LAMMPS text-based trajectory files supported by parse_lammps_trajectory().
+    const formats = [
+        { extensions: [`.dump`], name: `LAMMPS binary dump`, tool: `pymatgen` },
+        { extensions: [`.nc`, `.netcdf`], name: `NetCDF`, tool: `MDAnalysis` },
+        { extensions: [`.dcd`], name: `DCD`, tool: `MDAnalysis` },
+    ];
+    for (const { extensions, name, tool } of formats) {
+        if (extensions.some((ext) => lower.endsWith(ext))) {
+            return `🚫 ${name} format not supported\nConvert with ${tool} first`;
+        }
+    }
+    return is_binary(content)
+        ? `🚫 Binary format not supported${filename ? `: ${filename}` : ``}`
+        : null;
+}
+// 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 });
+    try {
+        update_progress(0, `Detecting format...`);
+        const data_size = data instanceof ArrayBuffer
+            ? data.byteLength
+            : new TextEncoder().encode(data).byteLength;
+        const is_large_file = data_size > LARGE_FILE_THRESHOLD;
+        const should_use_indexing = use_indexing ?? is_large_file;
+        if (is_large_file) {
+            update_progress(5, `Large file detected (${Math.round(data_size / 1024 / 1024)}MB)`);
+        }
+        // Use indexed loading for supported large files (including compressed names).
+        const base_filename = strip_compression_extensions(filename);
+        if (should_use_indexing && /\.(xyz|extxyz|traj)$/.test(base_filename)) {
+            return 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;
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : `Unknown error`;
+        update_progress(100, `Error: ${error_message}`);
+        throw error;
+    }
+}
+// Unified frame loading using new TrajFrameReader
+async function parse_with_unified_loader(data, filename, options, on_progress) {
+    const { index_sample_rate, extract_plot_metadata } = options;
+    const loader = new TrajFrameReader(filename);
+    on_progress?.({ current: 10, total: 100, stage: `Counting frames...` });
+    const total_frames = await loader.get_total_frames(data);
+    on_progress?.({ current: 20, total: 100, stage: `Building frame index...` });
+    const frame_index = await loader.build_frame_index(data, index_sample_rate, (progress) => {
+        const adjusted = 20 + (progress.current / 100) * 30;
+        on_progress?.({
+            current: adjusted,
+            total: 100,
+            stage: `Building index: ${progress.stage}`,
+        });
+    });
+    on_progress?.({ current: 50, total: 100, stage: `Loading initial frames...` });
+    const initial_frame_count = Math.min(10, total_frames);
+    const frame_promises = Array.from({ length: initial_frame_count }, (_, idx) => loader.load_frame(data, idx));
+    const loaded_frames = await Promise.all(frame_promises);
+    const frames = loaded_frames.filter((frame) => frame !== null);
+    let plot_metadata;
+    if (extract_plot_metadata) {
+        on_progress?.({ current: 70, total: 100, stage: `Extracting plot metadata...` });
+        try {
+            plot_metadata = await loader.extract_plot_metadata(data, { sample_rate: 1 }, (progress) => {
+                const adjusted = 70 + (progress.current / 100) * 20;
+                on_progress?.({
+                    current: adjusted,
+                    total: 100,
+                    stage: `Extracting: ${progress.stage}`,
+                });
+            });
+        }
+        catch (error) {
+            console.warn(`Failed to extract plot metadata:`, error);
+        }
+    }
+    const stage = `Ready: ${total_frames} frames indexed`;
+    on_progress?.({ current: 100, total: 100, stage });
+    return {
+        frames,
+        metadata: {
+            source_format: filename.toLowerCase().endsWith(`.traj`)
+                ? `ase_trajectory`
+                : `xyz_trajectory`,
+            frame_count: total_frames,
+        },
+        total_frames,
+        indexed_frames: frame_index,
+        plot_metadata,
+        is_indexed: true,
+        frame_loader: loader,
+    };
+}
+// Factory function for frame loader (simplified)
+export function create_frame_loader(filename) {
+    if (!filename.toLowerCase().match(/\.(xyz|extxyz|traj)$/)) {
+        throw new Error(`Unsupported format for frame loading: ${filename}`);
+    }
+    return new TrajFrameReader(filename);
+}
+export async function load_binary_traj(resp, type, fallback = false) {
+    try {
+        // Read binary from a clone so the original can be used for text fallback
+        return await resp.clone().arrayBuffer();
+    }
+    catch (binary_error) {
+        if (fallback) {
+            console.warn(`Binary load failed for ${type}, using text fallback:`, binary_error);
+            try {
+                return await resp.text();
+            }
+            catch (text_error) {
+                const combined_error = new AggregateError([binary_error, text_error], `Failed to load ${type} as binary or text`);
+                console.error(`Binary and text fallback both failed for ${type}:`, combined_error);
+                throw combined_error;
+            }
+        }
+        throw new Error(`Failed to load ${type} as binary`, { cause: binary_error });
+    }
+}

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,169 @@
+import { ELEM_SYMBOLS } from '../../labels';
+import * as math from '../../math';
+import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+// 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) {
+    if (box_lines.length !== 3)
+        return null;
+    const bounds = box_lines.map((line) => line.split(/\s+/).map(Number));
+    const min_cols = is_triclinic ? 3 : 2;
+    if (bounds.some((row) => row.length < min_cols || row.slice(0, min_cols).some(isNaN))) {
+        return null;
+    }
+    if (!is_triclinic) {
+        // Orthogonal: bounds = [lo, hi] per dimension
+        const [[lo_x, hi_x], [lo_y, hi_y], [lo_z, hi_z]] = bounds;
+        return [[hi_x - lo_x, 0, 0], [0, hi_y - lo_y, 0], [0, 0, hi_z - lo_z]];
+    }
+    // Triclinic: bounds = [lo_bound, hi_bound, tilt] with tilts xy, xz, yz
+    const [[xlo_b, xhi_b, xy], [ylo_b, yhi_b, xz], [zlo_b, zhi_b, yz]] = bounds;
+    const lx = (xhi_b - Math.max(0, xy, xz, xy + xz)) -
+        (xlo_b - Math.min(0, xy, xz, xy + xz));
+    const ly = (yhi_b - Math.max(0, yz)) - (ylo_b - Math.min(0, yz));
+    const lz = zhi_b - zlo_b;
+    return [[lx, 0, 0], [xy, ly, 0], [xz, yz, lz]];
+}
+// Parse LAMMPS trajectory (.lammpstrj). Atom types mapped to elements via atom_type_mapping
+// or by default: 1→H, 2→He, etc. Supports orthogonal and triclinic simulation boxes.
+export function parse_lammps_trajectory(content, filename, atom_type_mapping) {
+    const lines = content.trim().split(/\r?\n/);
+    const frames = [];
+    const atom_types_found = new Set();
+    let id_fallback_warning_emitted = false;
+    let idx = 0;
+    const read_line = () => lines[idx++]?.trim() ?? ``;
+    const peek_line = () => lines[idx]?.trim() ?? ``;
+    const skip_to = (prefix) => {
+        while (idx < lines.length && !peek_line().startsWith(prefix))
+            idx++;
+        return idx < lines.length;
+    };
+    // Helper to map atom type to element symbol
+    const get_element = (atom_type) => {
+        if (atom_type_mapping?.[atom_type])
+            return atom_type_mapping[atom_type];
+        return ELEM_SYMBOLS[Math.max(0, atom_type - 1) % ELEM_SYMBOLS.length];
+    };
+    while (idx < lines.length) {
+        if (!skip_to(`ITEM: TIMESTEP`))
+            break;
+        idx++;
+        const timestep = parseInt(read_line(), 10) || 0;
+        if (!skip_to(`ITEM: NUMBER OF ATOMS`))
+            break;
+        idx++;
+        const num_atoms = parseInt(read_line(), 10);
+        if (!num_atoms || num_atoms <= 0)
+            continue;
+        // BOX BOUNDS: orthogonal="pp pp pp", triclinic="xy xz yz pp pp pp"
+        if (!skip_to(`ITEM: BOX BOUNDS`))
+            break;
+        const box_header = read_line();
+        const is_triclinic = /BOX BOUNDS\s+xy\s+xz\s+yz/i.test(box_header);
+        const tokens = box_header.replace(`ITEM: BOX BOUNDS`, ``).trim().split(/\s+/).slice(-3);
+        const is_periodic = (tok) => tok.toLowerCase().startsWith(`p`);
+        const pbc = tokens.length === 3
+            ? [is_periodic(tokens[0]), is_periodic(tokens[1]), is_periodic(tokens[2])]
+            : [true, true, true];
+        const lattice_matrix = parse_lammps_box([read_line(), read_line(), read_line()], is_triclinic);
+        if (!lattice_matrix)
+            continue;
+        // Find ITEM: ATOMS and parse column headers
+        if (!skip_to(`ITEM: ATOMS`))
+            break;
+        const cols = read_line().replace(`ITEM: ATOMS`, ``).trim().toLowerCase().split(/\s+/);
+        const col = Object.fromEntries(cols.map((name, col_idx) => [name, col_idx]));
+        // Determine position columns: prefer unwrapped (xu/yu/zu) > scaled (xs/ys/zs) > regular (x/y/z)
+        const pos_keys = [`xu`, `yu`, `zu`].every((key) => key in col)
+            ? [`xu`, `yu`, `zu`]
+            : [`xs`, `ys`, `zs`].every((key) => key in col)
+                ? [`xs`, `ys`, `zs`]
+                : [`x`, `y`, `z`];
+        const pos_cols = pos_keys.map((key) => col[key]);
+        // Atom identity: prefer numeric type, else explicit element symbol.
+        // Fallback to ID-based mapping only for legacy dumps; this can be inaccurate
+        // for large or non-element-like IDs, so prefer TYPE column when available.
+        const type_col = col.type;
+        const element_col = col.element;
+        const id_col = col.id;
+        const use_scaled = pos_keys[0] === `xs`;
+        const max_col_idx = Math.max(...pos_cols, type_col ?? -1, element_col ?? -1, id_col ?? -1);
+        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`);
+            continue;
+        }
+        // Parse atom data
+        const positions = [];
+        const elements = [];
+        const frac_to_cart = use_scaled ? math.create_frac_to_cart(lattice_matrix) : null;
+        for (let atom = 0; atom < num_atoms && idx < lines.length; atom++) {
+            const parts = read_line().split(/\s+/);
+            const coords = pos_cols.map((col_idx) => parseFloat(parts[col_idx]));
+            if (coords.some(isNaN) || parts.length <= max_col_idx)
+                continue;
+            // Convert scaled coordinates to Cartesian if needed
+            const xyz = frac_to_cart ? frac_to_cart(coords) : coords;
+            let element_symbol;
+            if (type_col !== undefined) {
+                // Map atom type to element using custom mapping or default (type 1 -> H, etc.)
+                const atom_type = parseInt(parts[type_col], 10) || 1;
+                atom_types_found.add(atom_type);
+                element_symbol = get_element(atom_type);
+            }
+            else if (element_col !== undefined) {
+                const raw_symbol = parts[element_col];
+                if (!raw_symbol)
+                    continue;
+                element_symbol = coerce_element_symbol(raw_symbol);
+                if (!element_symbol) {
+                    console.warn(`Skipping LAMMPS atom with unknown element symbol "${raw_symbol}" at timestep ${timestep}`);
+                    continue;
+                }
+            }
+            else if (id_col !== undefined) {
+                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.`);
+                    id_fallback_warning_emitted = true;
+                }
+                element_symbol = get_element(atom_id);
+            }
+            if (!element_symbol)
+                continue;
+            positions.push(xyz);
+            elements.push(element_symbol);
+        }
+        if (positions.length === elements.length && positions.length === num_atoms) {
+            const { volume } = math.calc_lattice_params(lattice_matrix);
+            frames.push(create_trajectory_frame(positions, elements, lattice_matrix, pbc, timestep, { volume, timestep }));
+        }
+    }
+    if (frames.length === 0) {
+        throw new Error(`No valid frames found in LAMMPS trajectory`);
+    }
+    const first_frame = frames[0];
+    const element_counts = first_frame.structure.sites.reduce((counts, site) => {
+        const elem = site.species[0].element;
+        counts[elem] = (counts[elem] || 0) + 1;
+        return counts;
+    }, {});
+    return {
+        frames,
+        metadata: {
+            filename,
+            source_format: `lammps_trajectory`,
+            frame_count: frames.length,
+            total_atoms: first_frame.structure.sites.length,
+            periodic_boundary_conditions: (`lattice` in first_frame.structure)
+                ? first_frame.structure.lattice.pbc
+                : [true, true, true],
+            atom_types: Array.from(atom_types_found).sort((a, b) => a - b),
+            element_counts,
+        },
+    };
+}

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

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