matterviz 0.3.4 → 0.3.6

package/dist/trajectory/plotting.js

@@ -1,423 +0,0 @@
-// 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 = stat.values.length;
-        if (n <= 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 = 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 }, (_, idx) => idx),
-            y: stat.values,
-            label: clean_label,
-            unit,
-            y_axis: `y1`, // Will be reassigned
-            visible: false, // Will be assigned
-            markers: n < 30 ? `line+points` : `line`,
-            metadata: Array(n).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((g) => g.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((g) => g.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((g) => g.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).replace(/_/g, ` `),
-        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()
-        .replace(/<[^>]*>/g, ``)
-        .replace(/_/g, ` `)
-        .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((g) => g.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((g) => g.is_visible).length > 2) {
-        for (const group of unit_groups.filter((g) => g.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 >= 1)
-        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((g) => g.series.some((gs) => gs.label === srs.label && gs.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);
-    });
-}
-export function generate_axis_labels(plot_series) {
-    if (!plot_series.length)
-        return { y1: `Value`, y2: `Value` };
-    const get_axis_label = (axis_series) => {
-        const visible_series = axis_series.filter((srs) => srs.visible);
-        if (!visible_series.length)
-            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)
-            return `Value`;
-        const [unit, labels] = unit_entries[0];
-        const unique_labels = [...new Set(labels)].sort().join(` / `);
-        return unit ? `${unique_labels} (${unit})` : unique_labels;
-    };
-    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)
-        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((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 color = colors[color_idx % colors.length];
-        if (is_visible)
-            visible_props.push({ property: property_key, unit });
-        all_series.push({
-            x: data_points.map((p) => p.x),
-            y: data_points.map((p) => p.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

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

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

package/dist/utils.d.ts

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

@@ -1,36 +0,0 @@
-// 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.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;
-    }
-}