matterviz 0.4.1 → 0.4.3

package/dist/trajectory/plotting.js

@@ -1,19 +1,51 @@
 // Plotting utilities for trajectory visualization
 import { PLOT_COLORS } from '../colors';
-import { trajectory_property_config } from '../labels';
+import { SCF_AXIS_GROUP, 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`]);
+// scf_energy_delta lives in its own axis group (see trajectory_property_config), so
+// listing it here only surfaces it when higher-priority groups (energy/force/stress)
+// don't fill both axes — i.e. single-point SCF convergence views.
+const DEFAULT_VISIBLE = new Set([
+    `energy`,
+    `force_max`,
+    `stress_frobenius`,
+    `scf_energy_delta`,
+]);
+// Shared per-series line/point styling derived from a single color
+const series_color_styles = (color) => ({
+    line_style: { stroke: color, stroke_width: 2 },
+    point_style: { fill: color, stroke: color, stroke_width: 1 },
+});
+// Cache the per-frame walk per trajectory so re-renders that only change visible_properties or
+// labels/config reuse it (legend toggles mutate plot_series directly and skip regeneration, so they
+// don't hit this). Keyed by trajectory identity (WeakMap auto-evicts) and invalidated on extractor
+// or frame identity changes.
+const same_frames = (cached_frames, current_frames) => cached_frames.length === current_frames.length &&
+    cached_frames.every((frame, frame_idx) => frame === current_frames[frame_idx]);
+const stats_cache = new WeakMap();
 // 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);
+    // Single-pass extraction with variance detection, cached per trajectory (see stats_cache above)
+    const cached = stats_cache.get(trajectory);
+    let property_stats;
+    if (cached?.extractor === data_extractor && same_frames(cached.frames, trajectory.frames)) {
+        property_stats = cached.stats;
+    }
+    else {
+        property_stats = extract_property_statistics(trajectory, data_extractor);
+        stats_cache.set(trajectory, {
+            extractor: data_extractor,
+            frames: [...trajectory.frames],
+            stats: property_stats,
+        });
+    }
     // Create all series
     const all_series = create_series_from_stats(property_stats, property_config, colors);
     // Group by units and assign axes/visibility
@@ -40,21 +72,14 @@ function extract_property_statistics(trajectory, data_extractor) {
     // 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)
+        if (stat.values.length <= 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;
+        const is_energy = key.toLowerCase() === `energy`;
+        const has_variation = get_coefficient_of_variation(stat.values) >= 1e-6;
         // Skip constant properties except energy
         if (!has_variation && !is_energy)
             continue;
-        result.set(key, {
-            values: stat.values,
-            has_variation,
-            is_energy,
-        });
+        result.set(key, { values: stat.values, has_variation, is_energy });
     }
     return result;
 }
@@ -63,25 +88,25 @@ 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 { clean_label, unit, axis_group } = extract_label_and_unit(key, property_config);
         const color = colors[color_idx % colors.length];
+        // shared per-series metadata (consumers only read metadata[0]); one object, not n copies
+        const series_metadata = {
+            series_label: unit ? `${clean_label} (${unit})` : clean_label,
+            property_key: key, // Store original property key for robust lookups
+        };
         all_series.push({
             x: Array.from({ length: n_values }, (_, idx) => idx),
             y: stat.values,
             label: clean_label,
             unit,
+            ...(axis_group ? { axis_group } : {}),
             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 },
+            metadata: Array.from({ length: n_values }, () => series_metadata),
+            ...series_color_styles(color),
         });
         color_idx++;
     }
@@ -89,10 +114,10 @@ function create_series_from_stats(property_stats, property_config, colors) {
 }
 // Group series and assign visibility/axes
 function group_and_assign_series(series, default_visible_properties) {
-    // Group by unit
+    // Group by axis_group when set (forces a dedicated axis), else by unit
     const unit_map = new Map();
     for (const srs of series) {
-        const unit = srs.unit ?? `dimensionless`;
+        const unit = srs.axis_group ?? srs.unit ?? `dimensionless`;
         const group = unit_map.get(unit) ?? [];
         group.push(srs);
         unit_map.set(unit, group);
@@ -101,12 +126,12 @@ function group_and_assign_series(series, default_visible_properties) {
     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 is_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 };
+        return { unit, series: group_series, priority, is_visible };
     })
         .sort((a, b) => a.priority - b.priority);
     // Apply 2-group visibility limit
@@ -146,8 +171,9 @@ function apply_group_assignments(series, unit_groups) {
 // 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 };
+    if (config) {
+        return { clean_label: config.label, unit: config.unit, axis_group: config.axis_group };
+    }
     return {
         clean_label: key.charAt(0).toUpperCase() + key.slice(1).replaceAll('_', ` `),
         unit: ``,
@@ -219,19 +245,12 @@ function get_axis_label(axis_series) {
     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];
+    for (const srs of visible_series) {
+        const labels = unit_groups.get(srs.unit ?? ``) ?? [];
+        labels.push(srs.label ?? `Value`);
+        unit_groups.set(srs.unit ?? ``, labels);
+    }
+    const [unit, labels] = [...unit_groups.entries()][0];
     const unique_labels = [...new Set(labels)].sort().join(` / `);
     return unit ? `${unique_labels} (${unit})` : unique_labels;
 }
@@ -243,14 +262,47 @@ export function generate_axis_labels(plot_series) {
         y2: get_axis_label(plot_series.filter((srs) => srs.y_axis === `y2`)),
     };
 }
+// Log-scale heuristic: a y-axis defaults to log scale when every visible series on
+// it is strictly positive AND their combined values span at least this many decades.
+// SCF convergence residuals (|ΔE|, density rms) span 6+ decades and degenerate into
+// hockey sticks on linear axes; plain energies (large negative) stay linear.
+const LOG_SCALE_MIN_DECADE_SPAN = 3;
+const LOG_SCALE_AXIS_GROUPS = new Set([SCF_AXIS_GROUP]);
+export function generate_axis_scale_types(plot_series) {
+    const scale_for_axis = (axis) => {
+        let min_val = Infinity;
+        let max_val = -Infinity;
+        for (const srs of plot_series) {
+            if (!srs.visible || (srs.y_axis ?? `y1`) !== axis)
+                continue;
+            if (!srs.axis_group || !LOG_SCALE_AXIS_GROUPS.has(srs.axis_group))
+                return `linear`;
+            for (const val of srs.y) {
+                if (!Number.isFinite(val))
+                    continue;
+                if (val < min_val)
+                    min_val = val;
+                if (val > max_val)
+                    max_val = val;
+            }
+        }
+        if (!Number.isFinite(min_val) || min_val <= 0)
+            return `linear`;
+        return max_val / min_val >= 10 ** LOG_SCALE_MIN_DECADE_SPAN ? `log` : `linear`;
+    };
+    return { y1: scale_for_axis(`y1`), y2: scale_for_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 ordered_metadata = [...metadata_list]
+        .sort((metadata_a, metadata_b) => metadata_a.frame_number - metadata_b.frame_number)
+        .filter((metadata, idx, sorted_metadata) => idx === 0 || metadata.frame_number !== sorted_metadata[idx - 1].frame_number);
+    const sampled_metadata = ordered_metadata.length > max_points
+        ? downsample_metadata(ordered_metadata, max_points)
+        : ordered_metadata;
     const all_properties = new Set();
     sampled_metadata.forEach((metadata) => {
         Object.keys(metadata.properties).forEach((prop) => all_properties.add(prop));
@@ -261,22 +313,27 @@ export function generate_streaming_plot_series(metadata_list, options = {}) {
     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] }));
+            .map((metadata) => ({
+            x: metadata.frame_number,
+            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)))
+        const values = data_points.map((point) => point.y);
+        if (!is_energy && get_coefficient_of_variation(values) < 1e-6)
             continue;
-        const { clean_label, unit } = extract_label_and_unit(property_key, property_config);
+        const { clean_label, unit, axis_group } = 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 });
+            visible_props.push({ property: property_key, unit, axis_group });
         all_series.push({
             x: data_points.map((point) => point.x),
             y: data_points.map((point) => point.y),
             label: clean_label,
             unit,
+            ...(axis_group ? { axis_group } : {}),
             y_axis: determine_axis_from_groups(property_key, unit, visible_props),
             visible: is_visible,
             markers: data_points.length < 1000 ? `line+points` : `line`,
@@ -284,19 +341,16 @@ export function generate_streaming_plot_series(metadata_list, options = {}) {
                 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 },
+            ...series_color_styles(color),
         });
         color_idx++;
     }
     return all_series;
 }
-// Helper functions for streaming
+// Down-sample to at most target_points entries (callers guarantee the list is longer)
 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));
+    const points = Math.max(2, target_points);
     // Evenly spaced indices in [0, total_count-1], guaranteed to include first and last.
     const sampled = [];
     for (let idx = 0; idx < points; idx++) {
@@ -307,16 +361,11 @@ function downsample_metadata(metadata_list, target_points) {
     }
     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 }) => ({
+    const mock_series = visible_properties.map(({ property: prop, unit: prop_unit, axis_group }) => ({
         label: prop,
-        unit: u,
+        unit: prop_unit,
+        ...(axis_group ? { axis_group } : {}),
     }));
     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));

package/dist/utils.d.ts

@@ -1,8 +1,11 @@
 export declare const is_plain_object: (val: unknown) => val is Record<string, unknown>;
+export declare const clamp01: (value: number) => number;
 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 parse_num_token: (token: string) => number;
+export declare const parse_leading_num: (line: string) => number;
 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

@@ -1,5 +1,7 @@
 // Check if value is a plain object (not array, null, or other types)
 export const is_plain_object = (val) => typeof val === `object` && val !== null && !Array.isArray(val);
+// Clamp a number to the [0, 1] range.
+export const clamp01 = (value) => Math.max(0, Math.min(1, value));
 // Merge nested objects (1 level deep).
 export function merge_nested(obj1, obj2) {
     const result = { ...obj1, ...obj2 };
@@ -21,6 +23,11 @@ export const escape_html = (unsafe_string) => unsafe_string
 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`);
+// Number(token) that treats blank strings as NaN, not 0 like Number(``) does
+export const parse_num_token = (token) => token.trim() === `` ? NaN : Number(token);
+// Parse a line's first whitespace-separated token: tolerates trailing
+// tokens/comments (`1.0 ! scale` -> 1.0) like parseFloat, blank lines are NaN
+export const parse_leading_num = (line) => parse_num_token(line.trim().split(/\s+/)[0]);
 // 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() {