matterviz 0.3.6 → 0.3.7

package/dist/trajectory/parse/lammps.js

@@ -0,0 +1,179 @@
+import { ELEM_SYMBOLS } from '../../labels';
+import * as math from '../../math';
+import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+const is_periodic = (token) => token.toLowerCase().startsWith(`p`);
+// Parse LAMMPS box bounds → lattice matrix. Handles orthogonal and triclinic boxes.
+// Triclinic: converts bounding box to actual dims per https://docs.lammps.org/Howto_triclinic.html
+// Lattice vectors: a=(lx,0,0), b=(xy,ly,0), c=(xz,yz,lz)
+export function parse_lammps_box(box_lines, is_triclinic) {
+    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 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;

package/dist/trajectory/parse/vasp.js

@@ -0,0 +1,68 @@
+import * as math from '../../math';
+import { create_trajectory_frame, is_valid_element_symbol, validate_3x3_matrix, } from '../helpers';
+export function parse_vasp_xdatcar(content, filename) {
+    const lines = content.trim().split(/\r?\n/);
+    if (lines.length < 10)
+        throw new Error(`XDATCAR file too short`);
+    const scale = parseFloat(lines[1]);
+    if (isNaN(scale))
+        throw new Error(`Invalid scale factor`);
+    const lattice_matrix = validate_3x3_matrix(lines.slice(2, 5).map((line) => line
+        .trim()
+        .split(/\s+/)
+        .map((component) => parseFloat(component) * scale)));
+    const element_names = lines[5].trim().split(/\s+/);
+    const element_counts = lines[6].trim().split(/\s+/).map(Number);
+    if (element_names.length !== element_counts.length) {
+        throw new Error(`XDATCAR element names/counts mismatch: names=${element_names.length}, counts=${element_counts.length}`);
+    }
+    if (element_counts.some((count) => !Number.isFinite(count) || !Number.isInteger(count) || count <= 0)) {
+        throw new Error(`XDATCAR contains invalid element counts: expected finite positive integers`);
+    }
+    const validated_element_names = element_names.map((name) => {
+        if (!is_valid_element_symbol(name)) {
+            throw new Error(`Invalid element symbol in XDATCAR: ${name}`);
+        }
+        return name;
+    });
+    const elements = validated_element_names.flatMap((name, idx) => Array(element_counts[idx]).fill(name));
+    const frames = [];
+    let line_idx = 7;
+    const frac_to_cart = math.create_frac_to_cart(lattice_matrix);
+    while (line_idx < lines.length) {
+        const config_idx = lines.findIndex((line, idx) => idx >= line_idx && line.includes(`Direct configuration=`));
+        if (config_idx === -1)
+            break;
+        const config_line = lines[config_idx];
+        line_idx = config_idx + 1;
+        const step_match = /configuration=\s*(\d+)/.exec(config_line);
+        const step = step_match ? parseInt(step_match[1]) : frames.length + 1;
+        const positions = [];
+        for (let idx = 0; idx < elements.length && line_idx < lines.length; idx++) {
+            const coords = lines[line_idx].trim().split(/\s+/).slice(0, 3).map(Number);
+            if (coords.length === 3 && !coords.some(isNaN)) {
+                positions.push(frac_to_cart(coords));
+            }
+            line_idx++;
+        }
+        if (positions.length === elements.length) {
+            const pbc = [true, true, true];
+            const { volume } = math.calc_lattice_params(lattice_matrix);
+            frames.push(create_trajectory_frame(positions, elements, lattice_matrix, pbc, step, {
+                volume,
+            }));
+        }
+    }
+    return {
+        frames,
+        metadata: {
+            filename,
+            source_format: `vasp_xdatcar`,
+            frame_count: frames.length,
+            total_atoms: elements.length,
+            periodic_boundary_conditions: [true, true, true],
+            elements: element_names,
+            element_counts,
+        },
+    };
+}

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

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

package/dist/trajectory/parse/xyz.js

@@ -0,0 +1,110 @@
+import * as math from '../../math';
+import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+export function parse_xyz_trajectory(content) {
+    const lines = content.trim().split(/\r?\n/);
+    const frames = [];
+    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 + 1 >= lines.length) {
+            line_idx++;
+            continue;
+        }
+        const comment = lines[++line_idx] || ``;
+        const metadata = {};
+        // Extract properties efficiently
+        const extractors = {
+            step: /(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i,
+            energy: /(?:energy|E|etot|total_energy)\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,
+            temperature: /(?:temperature|temp|T)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            force_max: /(?:max_force|force_max|fmax)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+            bandgap: /(?:bandgap|E_gap|gap)\s*[=:]?\s*([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/i,
+        };
+        const step_match = extractors.step.exec(comment);
+        const step = step_match?.[1] ? parseInt(step_match[1]) : frames.length;
+        Object.entries(extractors).forEach(([key, pattern]) => {
+            if (key === `step`)
+                return;
+            const match = pattern.exec(comment);
+            if (match)
+                metadata[key] = parseFloat(match[1]);
+        });
+        // Extract lattice matrix
+        const lattice_match = /Lattice\s*=\s*"([^"]+)"/i.exec(comment);
+        let lattice_matrix;
+        if (lattice_match) {
+            const values = lattice_match[1].split(/\s+/).map(Number);
+            if (values.length === 9 && values.every((value) => Number.isFinite(value))) {
+                lattice_matrix = [
+                    [values[0], values[1], values[2]],
+                    [values[3], values[4], values[5]],
+                    [values[6], values[7], values[8]],
+                ];
+                metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
+            }
+        }
+        // Parse atoms
+        const positions = [];
+        const elements = [];
+        const forces = [];
+        const has_forces = comment.includes(`forces:R:3`);
+        for (let idx = 0; idx < num_atoms; idx++) {
+            line_idx++;
+            if (line_idx >= lines.length)
+                break;
+            const parts = lines[line_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 frame ${frames.length} at line ${line_idx + 1}`);
+                    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 frame ${frames.length}`);
+                    continue;
+                }
+                elements.push(element_symbol);
+                positions.push([x_coord, y_coord, z_coord]);
+                if (has_forces && parts.length >= 7) {
+                    const force_x = parseFloat(parts[4]);
+                    const force_y = parseFloat(parts[5]);
+                    const force_z = parseFloat(parts[6]);
+                    if (Number.isFinite(force_x) &&
+                        Number.isFinite(force_y) &&
+                        Number.isFinite(force_z)) {
+                        forces.push([force_x, force_y, force_z]);
+                    }
+                }
+            }
+        }
+        if (forces.length > 0) {
+            metadata.forces = forces;
+            const magnitudes = forces.map((force) => Math.hypot(...force));
+            metadata.force_max = Math.max(...magnitudes);
+            // Calculate RMS (root mean square) of force magnitudes
+            metadata.force_norm = Math.sqrt(magnitudes.reduce((sum, mag) => sum + mag ** 2, 0) / magnitudes.length);
+        }
+        frames.push(create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step, metadata));
+        line_idx++;
+    }
+    return {
+        frames,
+        metadata: {
+            source_format: `xyz_trajectory`,
+            frame_count: frames.length,
+            total_atoms: frames[0]?.structure.sites.length || 0,
+        },
+    };
+}

package/dist/trajectory/plotting.d.ts

@@ -0,0 +1,28 @@
+import type { DataSeries } from '../plot/types';
+import type { TrajectoryDataExtractor, TrajectoryMetadata, TrajectoryType } from './index';
+export interface PlotSeriesOptions {
+    property_config?: Record<string, {
+        label: string;
+        unit: string;
+    }>;
+    colors?: readonly string[];
+    default_visible_properties?: Set<string>;
+}
+export declare function generate_plot_series(trajectory: TrajectoryType, data_extractor: TrajectoryDataExtractor, options?: PlotSeriesOptions): DataSeries[];
+export declare function toggle_series_visibility(series: DataSeries[], target_series_idx: number): DataSeries[];
+export declare function should_hide_plot(trajectory: TrajectoryType | undefined, plot_series: DataSeries[], tolerance?: number): boolean;
+export declare function generate_axis_labels(plot_series: DataSeries[]): {
+    y1: string;
+    y2: string;
+};
+interface StreamingPlotOptions {
+    property_config?: Record<string, {
+        label: string;
+        unit: string;
+    }>;
+    colors?: readonly string[];
+    default_visible_properties?: Set<string>;
+    max_points?: number;
+}
+export declare function generate_streaming_plot_series(metadata_list: TrajectoryMetadata[], options?: StreamingPlotOptions): DataSeries[];
+export {};