matterviz 0.3.1 → 0.3.3

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';
+// 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;

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((x) => parseFloat(x) * 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.js

@@ -107,7 +107,8 @@ function group_and_assign_series(series, default_visible_properties) {
         unit_map.set(unit, group);
     }
     // Create unit groups with priority and visibility
-    const groups = Array.from(unit_map.entries()).map(([unit, group_series]) => {
+    const groups = Array.from(unit_map.entries())
+        .map(([unit, group_series]) => {
         const priority = calculate_priority(unit, group_series);
         const has_default_visible = group_series.some((srs) => {
             const metadata = Array.isArray(srs.metadata) ? srs.metadata[0] : srs.metadata;
@@ -115,7 +116,8 @@ function group_and_assign_series(series, default_visible_properties) {
             return is_default_visible(property_key, default_visible_properties);
         });
         return { unit, series: group_series, priority, is_visible: has_default_visible };
-    }).sort((a, b) => a.priority - b.priority);
+    })
+        .sort((a, b) => a.priority - b.priority);
     // Apply 2-group visibility limit
     const visible_groups = groups.filter((g) => g.is_visible);
     if (visible_groups.length > 2) {
@@ -183,7 +185,11 @@ function calculate_priority(unit, group_series) {
 }
 // Normalize property keys for robust matching (handles case, underscores, and common aliases)
 const normalize_property_key = (key) => {
-    const normalized = key.toLowerCase().replace(/<[^>]*>/g, ``).replace(/_/g, ` `).trim();
+    const normalized = key
+        .toLowerCase()
+        .replace(/<[^>]*>/g, ``)
+        .replace(/_/g, ` `)
+        .trim();
     // Map common force property aliases to canonical form
     return [`fmax`, `f`, `force maximum`].includes(normalized) ? `force max` : normalized;
 };
@@ -213,7 +219,8 @@ export function toggle_series_visibility(series, target_series_idx) {
         const visible_groups = unit_groups.filter((group) => group.is_visible);
         if (visible_groups.length >= 2) {
             // Hide lowest priority group (highest priority number)
-            const lowest_priority_group = visible_groups.sort((g1, g2) => g1.priority - g2.priority)
+            const lowest_priority_group = visible_groups
+                .sort((g1, g2) => g1.priority - g2.priority)
                 .pop(); // Get the last (lowest priority) group
             if (lowest_priority_group) {
                 lowest_priority_group.is_visible = false;
@@ -358,8 +365,7 @@ export function generate_streaming_plot_series(metadata_list, options = {}) {
         if (!is_energy && !has_significant_variation(data_points.map((p) => p.y)))
             continue;
         const { clean_label, unit } = extract_label_and_unit(property_key, property_config);
-        const is_visible = is_default_visible(property_key, default_visible_properties) ||
-            color_idx < 2;
+        const is_visible = is_default_visible(property_key, default_visible_properties) || color_idx < 2;
         const color = colors[color_idx % colors.length];
         if (is_visible)
             visible_props.push({ property: property_key, unit });
@@ -411,8 +417,7 @@ function determine_axis_from_groups(property, unit, visible_properties) {
     }));
     const groups = group_and_assign_series(mock_series, new Set([property]));
     const target_group = groups.find((group) => group.series.some((srs) => srs.label === property && srs.unit === unit));
-    return target_group &&
-        groups.filter((group) => group.is_visible).indexOf(target_group) === 1
+    return target_group && groups.filter((group) => group.is_visible).indexOf(target_group) === 1
         ? `y2`
         : `y1`;
 }

package/dist/trajectory/types.d.ts

@@ -0,0 +1,11 @@
+import type { ElementSymbol } from '../element';
+export type AtomTypeMapping = Record<number, ElementSymbol>;
+export interface LoadingOptions {
+    use_indexing?: boolean;
+    buffer_size?: number;
+    index_sample_rate?: number;
+    extract_plot_metadata?: boolean;
+    bin_file_threshold?: number;
+    text_file_threshold?: number;
+    atom_type_mapping?: AtomTypeMapping;
+}

package/dist/trajectory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -1,2 +1,5 @@
 export declare function merge_nested<T extends Record<string, unknown>>(obj1: T, obj2?: Partial<T>): T;
 export declare const escape_html: (unsafe_string: string) => string;
+export declare const normalize_unicode_minus: (value: string) => string;
+export declare const normalize_scientific_notation: (value: string) => string;
+export declare function decode_url_safe_base64(encoded: string): string | undefined;

package/dist/utils.js

@@ -17,3 +17,20 @@ export const escape_html = (unsafe_string) => unsafe_string
     .replaceAll(`>`, `>`)
     .replaceAll(`"`, `"`)
     .replaceAll(`'`, `'`);
+// Normalize unicode minus (U+2212) to ASCII hyphen-minus.
+export const normalize_unicode_minus = (value) => value.replace(/−/g, `-`);
+// Normalize scientific notation variants (d/D exponent, Mathematica *^).
+export const normalize_scientific_notation = (value) => normalize_unicode_minus(value).toLowerCase().replace(/d/g, `e`).replace(/\*\^/g, `e`);
+// Decode a URL-safe base64 string (RFC 4648 §5) to its original text.
+// Converts `-` → `+`, `_` → `/`, restores padding, then decodes.
+// Returns undefined if decoding fails.
+export function decode_url_safe_base64(encoded) {
+    const std_b64 = encoded.replace(/-/g, `+`).replace(/_/g, `/`);
+    const padded = std_b64 + `=`.repeat((4 - (std_b64.length % 4)) % 4);
+    try {
+        return atob(padded);
+    }
+    catch {
+        return undefined;
+    }
+}