matterviz 0.3.6 → 0.4.0

package/dist/trajectory/plotting.js

@@ -0,0 +1,423 @@
+// Plotting utilities for trajectory visualization
+import { PLOT_COLORS } from '../colors';
+import { trajectory_property_config } from '../labels';
+import { get_coefficient_of_variation } from '../math';
+// Configuration constants
+const ENERGY_UNITS = [`eV`, `eV/atom`, `hartree`, `kcal/mol`, `kJ/mol`];
+const ENERGY_PROPERTIES = [`energy`, `total_energy`, `potential_energy`];
+const FORCE_PROPERTIES = [`force`, `fmax`, `f`];
+const DEFAULT_VISIBLE = new Set([`energy`, `force_max`, `stress_frobenius`]);
+// Unified property extraction and series generation
+export function generate_plot_series(trajectory, data_extractor, options = {}) {
+    if (!trajectory?.frames?.length)
+        return [];
+    const { property_config = trajectory_property_config, colors = PLOT_COLORS, default_visible_properties = DEFAULT_VISIBLE, } = options;
+    // Single-pass data extraction with variance detection
+    const property_stats = extract_property_statistics(trajectory, data_extractor);
+    // Create all series
+    const all_series = create_series_from_stats(property_stats, property_config, colors);
+    // Group by units and assign axes/visibility
+    const unit_groups = group_and_assign_series(all_series, default_visible_properties);
+    // Apply final assignments to series
+    apply_group_assignments(all_series, unit_groups);
+    return all_series.sort((a, b) => Number(b.visible) - Number(a.visible));
+}
+// Extract statistics for all properties in a single pass
+function extract_property_statistics(trajectory, data_extractor) {
+    const property_stats = new Map();
+    // Extract all data in single pass
+    trajectory.frames.forEach((frame) => {
+        const data = data_extractor(frame, trajectory);
+        Object.entries(data).forEach(([key, value]) => {
+            if (typeof value !== `number` || key === `Step` || key.startsWith(`constant_`)) {
+                return;
+            }
+            if (!property_stats.has(key)) {
+                const stats = { values: [], sum: 0, sum_squares: 0, min: value, max: value };
+                property_stats.set(key, stats);
+            }
+            const stat = property_stats.get(key);
+            if (stat) {
+                stat.values.push(value);
+                stat.sum += value;
+                stat.sum_squares += value * value;
+                stat.min = Math.min(stat.min, value);
+                stat.max = Math.max(stat.max, value);
+            }
+        });
+    });
+    // Convert to final format with variation detection
+    const result = new Map();
+    for (const [key, stat] of property_stats) {
+        const n_values = stat.values.length;
+        if (n_values <= 1)
+            continue;
+        const coefficient_of_variation = get_coefficient_of_variation(stat.values);
+        const lower_key = key.toLowerCase();
+        const is_energy = lower_key === `energy`;
+        const has_variation = coefficient_of_variation >= 1e-6;
+        // Skip constant properties except energy
+        if (!has_variation && !is_energy)
+            continue;
+        result.set(key, {
+            values: stat.values,
+            has_variation,
+            is_energy,
+        });
+    }
+    return result;
+}
+// Create series from statistics
+function create_series_from_stats(property_stats, property_config, colors) {
+    const all_series = [];
+    let color_idx = 0;
+    for (const [key, stat] of property_stats) {
+        if (!stat)
+            continue;
+        const n_values = stat.values.length;
+        const { clean_label, unit } = extract_label_and_unit(key, property_config);
+        const color = colors[color_idx % colors.length];
+        all_series.push({
+            x: Array.from({ length: n_values }, (_, idx) => idx),
+            y: stat.values,
+            label: clean_label,
+            unit,
+            y_axis: `y1`, // Will be reassigned
+            visible: false, // Will be assigned
+            markers: n_values < 30 ? `line+points` : `line`,
+            metadata: Array(n_values).fill({
+                series_label: unit ? `${clean_label} (${unit})` : clean_label,
+                property_key: key, // Store original property key for robust lookups
+            }),
+            line_style: { stroke: color, stroke_width: 2 },
+            point_style: { fill: color, radius: 4, stroke: color, stroke_width: 1 },
+        });
+        color_idx++;
+    }
+    return all_series;
+}
+// Group series and assign visibility/axes
+function group_and_assign_series(series, default_visible_properties) {
+    // Group by unit
+    const unit_map = new Map();
+    for (const srs of series) {
+        const unit = srs.unit ?? `dimensionless`;
+        const group = unit_map.get(unit) ?? [];
+        group.push(srs);
+        unit_map.set(unit, group);
+    }
+    // Create unit groups with priority and visibility
+    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;
+            const property_key = (metadata?.property_key || srs.label) ?? ``;
+            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);
+    // Apply 2-group visibility limit
+    const visible_groups = groups.filter((group) => group.is_visible);
+    if (visible_groups.length > 2) {
+        // Keep only first 2 (highest priority)
+        groups.forEach((group) => {
+            group.is_visible = visible_groups.slice(0, 2).includes(group);
+        });
+    }
+    else if (visible_groups.length === 0 && groups.length > 0) {
+        groups[0].is_visible = true;
+    }
+    return groups;
+}
+// Apply group assignments to individual series
+function apply_group_assignments(series, unit_groups) {
+    const visible_groups = unit_groups.filter((group) => group.is_visible);
+    const axis_map = new Map();
+    // Assign axes
+    if (visible_groups.length === 1) {
+        axis_map.set(visible_groups[0], `y1`);
+    }
+    else if (visible_groups.length === 2) {
+        axis_map.set(visible_groups[0], `y1`);
+        axis_map.set(visible_groups[1], `y2`);
+    }
+    // Apply to series
+    for (const srs of series) {
+        const group = unit_groups.find((unit_group) => unit_group.series.includes(srs));
+        if (group) {
+            srs.visible = group.is_visible;
+            srs.y_axis = axis_map.get(group) ?? `y1`;
+        }
+    }
+}
+// Helper functions
+function extract_label_and_unit(key, property_config) {
+    const config = property_config[key] || property_config[key.toLowerCase()];
+    if (config)
+        return { clean_label: config.label, unit: config.unit };
+    return {
+        clean_label: key.charAt(0).toUpperCase() + key.slice(1).replaceAll('_', ` `),
+        unit: ``,
+    };
+}
+function calculate_priority(unit, group_series) {
+    // Energy units get highest priority
+    const unit_priority = ENERGY_UNITS.indexOf(unit);
+    if (unit_priority !== -1)
+        return unit_priority;
+    // Energy properties get high priority
+    const has_energy = group_series.some((srs) => {
+        const label = srs.label?.toLowerCase() ?? ``;
+        return ENERGY_PROPERTIES.some((prop) => label.includes(prop));
+    });
+    if (has_energy)
+        return 10;
+    // Force properties get medium priority
+    const has_force = group_series.some((srs) => {
+        const label = srs.label?.toLowerCase() ?? ``;
+        return FORCE_PROPERTIES.some((prop) => label.includes(prop));
+    });
+    if (has_force)
+        return 100;
+    return 1000; // Default low priority
+}
+// Normalize property keys for robust matching (handles case, underscores, and common aliases)
+const normalize_property_key = (key) => {
+    const normalized = key
+        .toLowerCase()
+        .replaceAll(/<[^>]*>/g, ``)
+        .replaceAll('_', ` `)
+        .trim();
+    // Map common force property aliases to canonical form
+    return [`fmax`, `f`, `force maximum`].includes(normalized) ? `force max` : normalized;
+};
+const is_default_visible = (property_key, default_properties) => {
+    const normalized_key = normalize_property_key(property_key);
+    for (const prop of default_properties) {
+        if (normalize_property_key(prop) === normalized_key)
+            return true;
+    }
+    return false;
+};
+// Optimized series visibility toggling
+export function toggle_series_visibility(series, target_series_idx) {
+    if (target_series_idx < 0 || target_series_idx >= series.length)
+        return series;
+    const target_series = series[target_series_idx];
+    const new_visibility = !target_series.visible;
+    // Create unit groups from current state
+    const unit_groups = create_unit_groups_from_series(series);
+    const target_group = unit_groups.find((group) => group.series.includes(target_series));
+    if (!target_group)
+        return series;
+    // Start with updating the target series visibility
+    const updated_series = series.map((srs) => srs === target_series ? { ...srs, visible: new_visibility } : { ...srs });
+    // Handle smart group replacement for new groups
+    if (new_visibility && !target_group.is_visible) {
+        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)
+                .pop(); // Get the last (lowest priority) group
+            if (lowest_priority_group) {
+                lowest_priority_group.is_visible = false;
+                // Also hide the actual series in this group
+                lowest_priority_group.series.forEach((srs1) => {
+                    const series_idx = updated_series.findIndex((srs2) => srs2.label === srs1.label && srs2.unit === srs1.unit);
+                    if (series_idx !== -1) {
+                        updated_series[series_idx] = { ...updated_series[series_idx], visible: false };
+                    }
+                });
+            }
+        }
+        target_group.is_visible = true;
+    }
+    // Recalculate group visibility and reassign axes
+    update_group_visibility_and_axes(updated_series, unit_groups);
+    return updated_series;
+}
+function create_unit_groups_from_series(series) {
+    const unit_map = new Map();
+    for (const srs of series) {
+        const unit = srs.unit ?? `dimensionless`;
+        const group = unit_map.get(unit) ?? [];
+        group.push(srs);
+        unit_map.set(unit, group);
+    }
+    return Array.from(unit_map.entries())
+        .map(([unit, group_series]) => ({
+        unit,
+        series: group_series,
+        priority: calculate_priority(unit, group_series),
+        is_visible: group_series.some((srs) => srs.visible),
+    }))
+        .sort((a, b) => a.priority - b.priority);
+}
+function update_group_visibility_and_axes(series, unit_groups) {
+    // Update group visibility based on series
+    for (const group of unit_groups) {
+        group.is_visible = group.series.some((srs1) => series.find((srs2) => srs2.label === srs1.label && srs2.unit === srs1.unit)?.visible);
+    }
+    // Apply 2-group limit
+    if (unit_groups.filter((unit_group) => unit_group.is_visible).length > 2) {
+        for (const group of unit_groups.filter((unit_group) => unit_group.is_visible).slice(2)) {
+            group.is_visible = false;
+            for (const srs1 of group.series) {
+                const idx = series.findIndex((srs2) => srs2.label === srs1.label && srs2.unit === srs1.unit);
+                if (idx !== -1)
+                    series[idx] = { ...series[idx], visible: false };
+            }
+        }
+    }
+    // Assign axes
+    const final_visible = unit_groups
+        .filter((group) => group.is_visible)
+        .sort((g1, g2) => g1.priority - g2.priority);
+    const axis_map = new Map();
+    if (final_visible.length > 0)
+        axis_map.set(final_visible[0], `y1`);
+    if (final_visible.length === 2)
+        axis_map.set(final_visible[1], `y2`);
+    // Apply to series
+    for (const [idx, srs] of series.entries()) {
+        const group = unit_groups.find((unit_group) => unit_group.series.some((member) => member.label === srs.label && member.unit === srs.unit));
+        if (group && axis_map.has(group)) {
+            series[idx] = { ...srs, y_axis: axis_map.get(group) };
+        }
+    }
+}
+// Utility functions
+export function should_hide_plot(trajectory, plot_series, tolerance = 1e-10) {
+    if (!trajectory || trajectory.frames.length <= 1 || plot_series.length === 0) {
+        return true;
+    }
+    const visible_series = plot_series.filter((srs) => srs.visible);
+    if (visible_series.length === 0)
+        return false; // Show empty plot with legend
+    return visible_series.every((srs) => {
+        if (srs.y.length <= 1)
+            return true;
+        // Check if all values are NaN
+        if (srs.y.every(isNaN))
+            return true;
+        // Check if values are constant (ignoring NaN values)
+        const valid_values = srs.y.filter((val) => !isNaN(val));
+        if (valid_values.length <= 1)
+            return true;
+        const first_valid = valid_values[0];
+        return valid_values.every((value) => Math.abs(value - first_valid) <= tolerance);
+    });
+}
+function get_axis_label(axis_series) {
+    const visible_series = axis_series.filter((srs) => srs.visible);
+    if (visible_series.length === 0)
+        return `Value`;
+    const unit_groups = new Map();
+    visible_series.forEach((srs) => {
+        const unit = srs.unit ?? ``;
+        const label = srs.label ?? `Value`;
+        if (!unit_groups.has(unit))
+            unit_groups.set(unit, []);
+        const group = unit_groups.get(unit);
+        if (group)
+            group.push(label);
+    });
+    const unit_entries = Array.from(unit_groups.entries());
+    if (unit_entries.length === 0)
+        return `Value`;
+    const [unit, labels] = unit_entries[0];
+    const unique_labels = [...new Set(labels)].sort().join(` / `);
+    return unit ? `${unique_labels} (${unit})` : unique_labels;
+}
+export function generate_axis_labels(plot_series) {
+    if (plot_series.length === 0)
+        return { y1: `Value`, y2: `Value` };
+    return {
+        y1: get_axis_label(plot_series.filter((srs) => (srs.y_axis ?? `y1`) === `y1`)),
+        y2: get_axis_label(plot_series.filter((srs) => srs.y_axis === `y2`)),
+    };
+}
+export function generate_streaming_plot_series(metadata_list, options = {}) {
+    if (metadata_list.length === 0)
+        return [];
+    const { property_config = trajectory_property_config, colors = PLOT_COLORS, default_visible_properties = DEFAULT_VISIBLE, max_points = 10_000, // 10,000 plot points provides good visual fidelity while maintaining browser performance
+     } = options;
+    const sampled_metadata = metadata_list.length > max_points
+        ? downsample_metadata(metadata_list, max_points)
+        : metadata_list;
+    const all_properties = new Set();
+    sampled_metadata.forEach((metadata) => {
+        Object.keys(metadata.properties).forEach((prop) => all_properties.add(prop));
+    });
+    const all_series = [];
+    const visible_props = [];
+    let color_idx = 0;
+    for (const property_key of all_properties) {
+        const data_points = sampled_metadata
+            .filter((metadata) => property_key in metadata.properties)
+            .map((metadata) => ({ x: metadata.step, y: metadata.properties[property_key] }));
+        if (data_points.length < 2)
+            continue;
+        const is_energy = property_key.toLowerCase() === `energy`;
+        if (!is_energy && !has_significant_variation(data_points.map((point) => point.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 color = colors[color_idx % colors.length];
+        if (is_visible)
+            visible_props.push({ property: property_key, unit });
+        all_series.push({
+            x: data_points.map((point) => point.x),
+            y: data_points.map((point) => point.y),
+            label: clean_label,
+            unit,
+            y_axis: determine_axis_from_groups(property_key, unit, visible_props),
+            visible: is_visible,
+            markers: data_points.length < 1000 ? `line+points` : `line`,
+            metadata: data_points.map(() => ({
+                series_label: unit ? `${clean_label} (${unit})` : clean_label,
+                property_key, // Store original property key for robust lookups
+            })),
+            line_style: { stroke: color, stroke_width: 2 },
+            point_style: { fill: color, radius: 4, stroke: color, stroke_width: 1 },
+        });
+        color_idx++;
+    }
+    return all_series;
+}
+// Helper functions for streaming
+function downsample_metadata(metadata_list, target_points) {
+    const total_count = metadata_list.length;
+    if (total_count <= target_points)
+        return metadata_list;
+    const points = Math.max(2, Math.min(target_points, total_count));
+    // Evenly spaced indices in [0, total_count-1], guaranteed to include first and last.
+    const sampled = [];
+    for (let idx = 0; idx < points; idx++) {
+        const source_idx = Math.floor((idx * (total_count - 1)) / (points - 1));
+        if (sampled.length === 0 || sampled.at(-1) !== metadata_list[source_idx]) {
+            sampled.push(metadata_list[source_idx]);
+        }
+    }
+    return sampled;
+}
+function has_significant_variation(values, tolerance = 1e-6) {
+    if (values.length <= 1)
+        return false;
+    const coefficient_of_variation = get_coefficient_of_variation(values);
+    return coefficient_of_variation >= tolerance;
+}
+function determine_axis_from_groups(property, unit, visible_properties) {
+    const mock_series = visible_properties.map(({ property: prop, unit: u }) => ({
+        label: prop,
+        unit: u,
+    }));
+    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
+        ? `y2`
+        : `y1`;
+}

package/dist/trajectory/types.d.ts

@@ -0,0 +1,11 @@
+import type { ElementSymbol } from '../element/types';
+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

@@ -0,0 +1,7 @@
+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 const to_error: (value: unknown) => Error;
+export declare function make_change_detector(): (value: unknown) => boolean;
+export declare function decode_url_safe_base64(encoded: string): string | undefined;

package/dist/utils.js

@@ -0,0 +1,47 @@
+// Check if value is a plain object (not array, null, or other types)
+const is_plain_object = (val) => typeof val === `object` && val !== null && !Array.isArray(val);
+// Merge nested objects (1 level deep).
+export function merge_nested(obj1, obj2) {
+    const result = { ...obj1, ...obj2 };
+    for (const key in obj1) {
+        if (is_plain_object(obj1[key]) && is_plain_object(obj2?.[key])) {
+            result[key] = { ...obj1[key], ...obj2[key] };
+        }
+    }
+    return result;
+}
+// Escape HTML special characters to prevent XSS attacks
+export const escape_html = (unsafe_string) => unsafe_string
+    .replaceAll(`&`, `&`)
+    .replaceAll(`<`, `&lt;`)
+    .replaceAll(`>`, `&gt;`)
+    .replaceAll(`"`, `&quot;`)
+    .replaceAll(`'`, `&#39;`);
+// Normalize unicode minus (U+2212) to ASCII hyphen-minus.
+export const normalize_unicode_minus = (value) => value.replaceAll('−', `-`);
+// Normalize scientific notation variants (d/D exponent, Mathematica *^).
+export const normalize_scientific_notation = (value) => normalize_unicode_minus(value).toLowerCase().replaceAll('d', `e`).replaceAll('*^', `e`);
+// Coerce an unknown thrown value into an Error (for typed Promise rejections / error callbacks).
+export const to_error = (value) => value instanceof Error ? value : new Error(String(value));
+export function make_change_detector() {
+    const unset = Symbol(`unset`);
+    let prev = unset;
+    return (value) => {
+        const changed = prev !== unset && value !== prev;
+        prev = value;
+        return changed;
+    };
+}
+// 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.replaceAll('-', `+`).replaceAll('_', `/`);
+    const padded = std_b64 + `=`.repeat((4 - (std_b64.length % 4)) % 4);
+    try {
+        return atob(padded);
+    }
+    catch {
+        return undefined;
+    }
+}