matterviz 0.3.6 → 0.4.0

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,87 @@
+import * as math from '../../math';
+import { create_trajectory_frame, is_valid_element_symbol, validate_3x3_matrix, } from '../helpers';
+// Parse the 7-line XDATCAR header at lines[start]: title, scale factor, 3 lattice rows
+// (multiplied by scale), element names, element counts
+function parse_xdatcar_header(lines, start) {
+    const scale = parseFloat(lines[start + 1]);
+    const rows = lines.slice(start + 2, start + 5).map((line) => line
+        .trim()
+        .split(/\s+/)
+        .map((val) => parseFloat(val) * scale));
+    const names = lines[start + 5].trim().split(/\s+/);
+    const counts = lines[start + 6].trim().split(/\s+/).map(Number);
+    return { scale, rows, names, counts };
+}
+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 header = parse_xdatcar_header(lines, 0);
+    const { names: element_names, counts: element_counts } = header;
+    if (isNaN(header.scale))
+        throw new Error(`Invalid scale factor`);
+    let lattice_matrix = validate_3x3_matrix(header.rows);
+    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 bad_element = element_names.find((name) => !is_valid_element_symbol(name));
+    if (bad_element)
+        throw new Error(`Invalid element symbol in XDATCAR: ${bad_element}`);
+    let elements = element_names.flatMap((name, idx) => Array(element_counts[idx]).fill(name));
+    const frames = [];
+    let line_idx = 7;
+    let 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;
+        // Variable-cell runs (NPT/ISIF=3) repeat the full 7-line header before each configuration
+        if (config_idx - line_idx >= 7) {
+            const hdr = parse_xdatcar_header(lines, config_idx - 7);
+            if (Number.isFinite(hdr.scale) &&
+                hdr.rows.every((row) => row.length === 3 && row.every(Number.isFinite))) {
+                lattice_matrix = validate_3x3_matrix(hdr.rows);
+                frac_to_cart = math.create_frac_to_cart(lattice_matrix);
+                if (hdr.names.length === hdr.counts.length &&
+                    hdr.names.every(is_valid_element_symbol) &&
+                    hdr.counts.every((count) => Number.isInteger(count) && count > 0)) {
+                    elements = hdr.names.flatMap((name, idx) => Array(hdr.counts[idx]).fill(name));
+                }
+            }
+        }
+        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], 10) : 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,26 @@
+import type { ElementSymbol } from '../../element/types';
+import * as math from '../../math';
+import type { TrajectoryType } from '../index';
+export declare function parse_extxyz_columns(comment: string): {
+    species_col: number;
+    pos_col: number;
+    forces_col: number;
+    min_cols: number;
+};
+export declare function parse_extxyz_lattice(comment: string): math.Matrix3x3 | undefined;
+export declare function parse_xyz_comment_metadata(comment: string): {
+    step?: number;
+    properties: Record<string, number>;
+};
+type ForceStats = {
+    forces: number[][];
+    force_max: number;
+    force_norm: number;
+};
+export declare function parse_xyz_atom_lines(lines: string[], start: number, num_atoms: number, comment: string, frame_label: string): {
+    elements: ElementSymbol[];
+    positions: number[][];
+    force_stats: ForceStats | null;
+};
+export declare function parse_xyz_trajectory(content: string): TrajectoryType;
+export {};

package/dist/trajectory/parse/xyz.js

@@ -0,0 +1,123 @@
+import * as math from '../../math';
+import { coerce_element_symbol, create_trajectory_frame } from '../helpers';
+// Resolve species/pos/forces column offsets from an extxyz Properties string of
+// name:type:ncols triples (e.g. "species:S:1:pos:R:3:forces:R:3"), falling back
+// to the conventional "symbol x y z" layout when absent or malformed
+export function parse_extxyz_columns(comment) {
+    const fields = /Properties\s*=\s*"?([^"\s]+)"?/i.exec(comment)?.[1].split(`:`) ?? [];
+    // Well-formed Properties is name:type:ncols triples; a non-multiple of 3 is malformed,
+    // so bail to the conventional default rather than trusting a partial layout
+    let layout = fields.length % 3 === 0 ? {} : null;
+    for (let idx = 0, offset = 0; layout && idx + 3 <= fields.length; idx += 3) {
+        const ncols = parseInt(fields[idx + 2], 10);
+        if (Number.isInteger(ncols) && ncols > 0) {
+            layout[fields[idx].toLowerCase()] = { offset, ncols };
+            offset += ncols;
+        }
+        else
+            layout = null;
+    }
+    const species_col = layout?.species?.offset ?? 0;
+    const pos_col = layout?.pos?.offset ?? 1;
+    const forces_col = layout?.forces && layout.forces.ncols >= 3 ? layout.forces.offset : -1;
+    return { species_col, pos_col, forces_col, min_cols: Math.max(pos_col + 3, species_col + 1) };
+}
+// Parse Lattice="ax ay az bx by bz cx cy cz" from an extxyz comment line
+export function parse_extxyz_lattice(comment) {
+    const vals = /Lattice\s*=\s*"([^"]+)"/i.exec(comment)?.[1].trim().split(/\s+/).map(Number);
+    if (vals?.length !== 9 || !vals.every(Number.isFinite))
+        return undefined;
+    return [vals.slice(0, 3), vals.slice(3, 6), vals.slice(6, 9)];
+}
+// Keys anchored at ^|\s and followed by [=:] so single-letter keys (E/V/P/T) don't match mid-word
+const make_pattern = (keys) => new RegExp(`(?:^|\\s)(?:${keys})\\s*[=:]\\s*([-+]?\\d*\\.?\\d+(?:[eE][-+]?\\d+)?)`, `i`);
+const METADATA_PATTERNS = {
+    energy: make_pattern(`energy|E|etot|total_energy`),
+    volume: make_pattern(`volume|vol|V`),
+    pressure: make_pattern(`pressure|press|P`),
+    temperature: make_pattern(`temperature|temp|T`),
+    force_max: make_pattern(`max_force|force_max|fmax`),
+    bandgap: make_pattern(`bandgap|E_gap|gap`),
+};
+// Extract step number and scalar properties from an (ext)XYZ comment line
+export function parse_xyz_comment_metadata(comment) {
+    const properties = {};
+    for (const [key, pattern] of Object.entries(METADATA_PATTERNS)) {
+        const match = pattern.exec(comment);
+        if (match)
+            properties[key] = parseFloat(match[1]);
+    }
+    const step = /(?:^|\s)(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i.exec(comment)?.[1];
+    return { step: step ? parseInt(step, 10) : undefined, properties };
+}
+// Parse num_atoms atom lines starting at lines[start], reading species/pos/forces from
+// their Properties-declared column offsets; invalid atoms are skipped with a warning.
+// force_stats holds raw forces plus max and RMS force magnitudes when forces are present.
+export function parse_xyz_atom_lines(lines, start, num_atoms, comment, frame_label) {
+    const { species_col, pos_col, forces_col, min_cols } = parse_extxyz_columns(comment);
+    const elements = [];
+    const positions = [];
+    const forces = [];
+    for (let idx = 0; idx < num_atoms; idx++) {
+        const parts = lines[start + idx]?.trim().split(/\s+/) ?? [];
+        if (parts.length < min_cols)
+            continue;
+        const pos = parts.slice(pos_col, pos_col + 3).map(parseFloat);
+        if (!pos.every(Number.isFinite)) {
+            console.warn(`Skipping XYZ atom with invalid coordinates in ${frame_label} at line ${start + idx + 1}`);
+            continue;
+        }
+        const symbol = parts[species_col];
+        const element_symbol = coerce_element_symbol(symbol);
+        if (!element_symbol) {
+            console.warn(`Skipping XYZ atom with unknown element symbol "${symbol}" in ${frame_label}`);
+            continue;
+        }
+        elements.push(element_symbol);
+        positions.push(pos);
+        if (forces_col >= 0 && parts.length >= forces_col + 3) {
+            const force_vec = parts.slice(forces_col, forces_col + 3).map(parseFloat);
+            if (force_vec.every(Number.isFinite))
+                forces.push(force_vec);
+        }
+    }
+    if (forces.length === 0)
+        return { elements, positions, force_stats: null };
+    const mags = forces.map((force) => Math.hypot(...force));
+    const force_norm = Math.sqrt(mags.reduce((sum, mag) => sum + mag ** 2, 0) / mags.length);
+    return {
+        elements,
+        positions,
+        force_stats: { forces, force_max: Math.max(...mags), force_norm },
+    };
+}
+export function parse_xyz_trajectory(content) {
+    const lines = content.trim().split(/\r?\n/);
+    const frames = [];
+    let line_idx = 0;
+    while (line_idx < lines.length) {
+        const num_atoms = parseInt(lines[line_idx].trim(), 10);
+        if (isNaN(num_atoms) || num_atoms <= 0 || line_idx + num_atoms + 1 >= lines.length) {
+            line_idx++; // skip blank/invalid lines until the next frame's atom-count line
+            continue;
+        }
+        const comment = lines[line_idx + 1] || ``;
+        const { step, properties } = parse_xyz_comment_metadata(comment);
+        const metadata = { ...properties };
+        const lattice_matrix = parse_extxyz_lattice(comment);
+        if (lattice_matrix)
+            metadata.volume = math.calc_lattice_params(lattice_matrix).volume;
+        const { elements, positions, force_stats } = parse_xyz_atom_lines(lines, line_idx + 2, num_atoms, comment, `frame ${frames.length}`);
+        Object.assign(metadata, force_stats);
+        frames.push(create_trajectory_frame(positions, elements, lattice_matrix, lattice_matrix ? [true, true, true] : undefined, step ?? frames.length, metadata));
+        line_idx += num_atoms + 2;
+    }
+    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/core/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 {};