matterviz 0.4.1 → 0.4.2

package/dist/trajectory/parse/vaspout-h5.js

@@ -0,0 +1,284 @@
+// Parser for VASP 6.x HDF5 output (vaspout.h5, written with LH5=.TRUE.).
+// Reads the ionic-relaxation trajectory from intermediate/ion_dynamics (with
+// per-frame energy/forces so convergence plots come for free) and falls back
+// to the final structure in results/positions for static (NSW=0) runs, which
+// render as single-frame trajectories (structure only, plots hidden).
+//
+// Tolerates files from incomplete/running calculations: datasets flushed
+// mid-write may disagree on step counts (e.g. 5 energies but 4 position
+// frames), so frame count is the minimum over required datasets and per-step
+// reads never index past any dataset's end.
+//
+// Electronic results (results/electron_dos, results/electron_eigenvalues*)
+// are read by ./vaspout-electronic.ts and attached as metadata.electronic;
+// vaspwave.h5 charge density is handled by isosurface/parse-vaspwave.ts.
+//
+// Schema reference: ferrox src/io/vasp/hdf5/mod.rs (which follows py4vasp's
+// VASP 6.x schema definitions).
+import { calc_lattice_params, create_frac_to_cart } from '../../math';
+import { count_elements, create_trajectory_frame, validate_3x3_matrix, } from '../helpers';
+import { expand_ion_types, is_hdf5_group, read_dataset, scale_matrix, to_number_array, to_scalar_number, to_string_array, with_h5_file, } from './h5-utils';
+import { read_vaspout_dos, read_vaspout_electronic } from './vaspout-electronic';
+const FINAL_ION_TYPES = `results/positions/ion_types`;
+const FINAL_ION_COUNTS = `results/positions/number_ion_types`;
+const FINAL_LATTICE = `results/positions/lattice_vectors`;
+const FINAL_POSITIONS = `results/positions/position_ions`;
+const FINAL_SCALE = `results/positions/scale`;
+const TRAJ_SCALE = `intermediate/ion_dynamics/scale`;
+const TRAJ_LATTICE = `intermediate/ion_dynamics/lattice_vectors`;
+const TRAJ_POSITIONS = `intermediate/ion_dynamics/position_ions`;
+const TRAJ_FORCES = `intermediate/ion_dynamics/forces`;
+const ENERGY_VALUES = `intermediate/ion_dynamics/energies`;
+const ENERGY_LABELS = `intermediate/ion_dynamics/energies_tags`;
+const OSZICAR_ROWS = `intermediate/ion_dynamics/oszicar`;
+const OSZICAR_LABELS = `intermediate/ion_dynamics/oszicar_label`;
+const ELECTRONIC_STEP_ENERGIES = `intermediate/electronic_steps/energies`;
+// vaspout.h5 root groups per the VASP 6.x schema. torch-sim files use flat
+// dataset names (positions/atomic_numbers/...) and never these groups.
+export const is_vaspout_h5_file = (h5_file) => [`results`, `intermediate`].some((name) => is_hdf5_group(h5_file.get(name))) &&
+    [`input`, `version`, `results`, `intermediate`].filter((name) => is_hdf5_group(h5_file.get(name))).length >= 2;
+// Final-structure datasets may carry a leading singleton step axis
+// ([1, 3, 3] lattices, [1, n_atoms, 3] positions) depending on VASP version.
+const squeeze_leading_axis = (data) => Array.isArray(data) &&
+    data.length === 1 &&
+    Array.isArray(data[0]) &&
+    Array.isArray(data[0][0])
+    ? data[0]
+    : data;
+// VASP writes several energy kinds per step; energies_tags names the columns.
+// Prefer the free energy (TOTEN), then energy(sigma->0), then column 0.
+const pick_energy_column = (tags) => {
+    if (!tags)
+        return { idx: 0, tag: null };
+    for (const needle of [`TOTEN`, `sigma->0`]) {
+        const idx = tags.findIndex((tag) => tag.includes(needle));
+        if (idx !== -1)
+            return { idx, tag: tags[idx] };
+    }
+    return { idx: 0, tag: tags[0] ?? null };
+};
+const finite_or_null = (value) => typeof value === `number` && Number.isFinite(value) ? value : null;
+// OSZICAR rows are [total_scf_rows, n_cols] with oszicar_label naming columns
+// (N, E, dE, d eps, ncg, rms, rms(c)). The N counter resets to 1 at each new
+// ionic step, which is how rows group into ionic steps (same as ferrox).
+const read_oszicar_history = (h5_file) => {
+    const rows = read_dataset(h5_file, OSZICAR_ROWS);
+    const labels = to_string_array(read_dataset(h5_file, OSZICAR_LABELS));
+    if (!rows || !labels)
+        return null;
+    const col = (name) => labels.findIndex((label) => label.trim() === name);
+    const [n_col, energy_col] = [col(`N`), col(`E`)];
+    if (n_col < 0 || energy_col < 0)
+        return null;
+    const [delta_col, rms_col, charge_rms_col] = [col(`dE`), col(`rms`), col(`rms(c)`)];
+    const ionic_steps = [];
+    let current = null;
+    let previous_scf_counter = Infinity;
+    for (const row of rows) {
+        const scf_counter = row[n_col];
+        const energy = finite_or_null(row[energy_col]);
+        if (energy === null || !Number.isFinite(scf_counter))
+            return null;
+        if (scf_counter <= previous_scf_counter || !current) {
+            current = { energies: [], energy_deltas: [], rms: [], charge_rms: [] };
+            ionic_steps.push(current);
+        }
+        current.energies.push(energy);
+        current.energy_deltas.push(delta_col >= 0 ? finite_or_null(row[delta_col]) : null);
+        current.rms.push(rms_col >= 0 ? finite_or_null(row[rms_col]) : null);
+        current.charge_rms.push(charge_rms_col >= 0 ? finite_or_null(row[charge_rms_col]) : null);
+        previous_scf_counter = scf_counter;
+    }
+    return ionic_steps.length > 0 ? ionic_steps : null;
+};
+// Fallback when the OSZICAR mirror is absent: the explicit per-ionic-step SCF
+// energy dataset (shape [n_ionic, n_scf]); deltas derived from consecutive
+// energies, no density residuals available.
+const read_electronic_step_history = (h5_file) => {
+    const rows = read_dataset(h5_file, ELECTRONIC_STEP_ENERGIES);
+    if (!rows)
+        return null;
+    const ionic_steps = rows
+        .map((row) => {
+        const energies = (Array.isArray(row) ? row : [row]).filter((val) => typeof val === `number` && Number.isFinite(val));
+        return {
+            energies,
+            energy_deltas: energies.map((energy, idx) => idx > 0 ? energy - energies[idx - 1] : null),
+            rms: energies.map(() => null),
+            charge_rms: energies.map(() => null),
+        };
+    })
+        .filter((step) => step.energies.length > 0);
+    return ionic_steps.length > 0 ? ionic_steps : null;
+};
+const read_scf_history = (h5_file) => read_oszicar_history(h5_file) ?? read_electronic_step_history(h5_file);
+// Convergence fields (|dE|, density residuals) for one SCF step; negative idx
+// counts from the end (-1 = final step). Shared by the per-frame summary below
+// and the SCF pseudo-frame expansion for single-point runs.
+const scf_step_metadata = (scf, idx) => {
+    const metadata = {};
+    const delta = scf.energy_deltas.at(idx);
+    if (delta != null)
+        metadata.scf_energy_delta = Math.abs(delta);
+    const rms = scf.rms.at(idx);
+    if (rms != null)
+        metadata.scf_rms = rms;
+    const charge_rms = scf.charge_rms.at(idx);
+    if (charge_rms != null)
+        metadata.scf_charge_rms = charge_rms;
+    return metadata;
+};
+// Final-SCF-step summary attached to each ionic frame so relax trajectories
+// plot SCF effort/residuals alongside energy and force_max.
+const scf_frame_metadata = (scf) => {
+    if (!scf || scf.energies.length === 0)
+        return {};
+    const metadata = {
+        n_scf_steps: scf.energies.length,
+        ...scf_step_metadata(scf, -1),
+    };
+    // interrupted writers can drop the final dE entry: derive it from the last two energies
+    if (!(`scf_energy_delta` in metadata) && scf.energies.length >= 2) {
+        metadata.scf_energy_delta = Math.abs(scf.energies.at(-1) - scf.energies.at(-2));
+    }
+    return metadata;
+};
+// Bands/DOS-only outputs (e.g. phelel band-path files) carry no (complete)
+// structure datasets but still have renderable electronic results: surface
+// them as a zero-frame trajectory the webview routes to the spectral
+// components. Files with neither structure nor electronic data throw.
+const electronic_only_trajectory = (h5_file, missing) => {
+    const electronic = read_vaspout_electronic(h5_file);
+    if (!electronic) {
+        throw new Error(`vaspout.h5 file has no structure data (missing ${missing}) — ` +
+            `and no electron_dos/electron_eigenvalues results either`);
+    }
+    return {
+        frames: [],
+        metadata: {
+            source_format: `vaspout_h5`,
+            frame_count: 0,
+            electronic,
+            vaspout_electronic_only: true,
+        },
+    };
+};
+export function parse_vaspout_h5_file(h5_file) {
+    const ion_types = to_string_array(read_dataset(h5_file, FINAL_ION_TYPES));
+    const ion_counts = to_number_array(read_dataset(h5_file, FINAL_ION_COUNTS));
+    if (!ion_types || !ion_counts) {
+        return electronic_only_trajectory(h5_file, `${FINAL_ION_TYPES} / ${FINAL_ION_COUNTS}`);
+    }
+    // expand_ion_types throws on length mismatch and unknown symbols (fail loudly)
+    const elements = expand_ion_types(ion_types, ion_counts);
+    // POSCAR-style universal scaling factor; scalar in real files, but some
+    // writers store it as a 1-element array. Intermediate ion-dynamics frames
+    // carry their own scale (py4vasp's trajectory Cell reads
+    // intermediate/ion_dynamics/scale), distinct from the final-structure scale.
+    const scale = to_scalar_number(read_dataset(h5_file, FINAL_SCALE)) ?? 1;
+    const traj_scale = to_scalar_number(read_dataset(h5_file, TRAJ_SCALE)) ?? scale;
+    const traj_positions = read_dataset(h5_file, TRAJ_POSITIONS);
+    const traj_lattices = read_dataset(h5_file, TRAJ_LATTICE);
+    const traj_forces = read_dataset(h5_file, TRAJ_FORCES);
+    const energies = read_dataset(h5_file, ENERGY_VALUES);
+    const energy_tags = to_string_array(read_dataset(h5_file, ENERGY_LABELS));
+    const { idx: energy_col, tag: energy_tag } = pick_energy_column(energy_tags);
+    const scf_history = read_scf_history(h5_file);
+    const frames = [];
+    let dropped_steps = 0;
+    // Shared frame assembly for the per-step trajectory path and the
+    // final-structure fallback: validate + scale the lattice, convert fractional
+    // positions to Cartesian, attach volume/SCF/energy (and optional forces).
+    const build_frame = (lattice_data, frac_positions, step, scf, raw_energy, forces, frame_scale) => {
+        const lattice = scale_matrix(validate_3x3_matrix(lattice_data), frame_scale);
+        const frac_to_cart = create_frac_to_cart(lattice);
+        const positions = frac_positions.map((frac) => frac_to_cart(frac));
+        const metadata = {
+            volume: calc_lattice_params(lattice).volume,
+            ...scf_frame_metadata(scf),
+        };
+        const energy = finite_or_null(raw_energy);
+        if (energy !== null)
+            metadata.energy = energy;
+        if (Array.isArray(forces))
+            metadata.forces = forces;
+        return create_trajectory_frame(positions, elements, lattice, [true, true, true], step, metadata);
+    };
+    if (traj_positions && traj_lattices) {
+        // A torn file's datasets may disagree on step count; never index past the
+        // shortest required one (forces/energies are optional per step).
+        const n_steps = Math.min(traj_positions.length, traj_lattices.length);
+        for (let step = 0; step < n_steps; step++) {
+            try {
+                frames.push(build_frame(traj_lattices[step], traj_positions[step], step, scf_history?.[step], energies?.[step]?.[energy_col], traj_forces?.[step], traj_scale));
+            }
+            catch {
+                // Torn final step: keep the frames parsed so far.
+                dropped_steps = n_steps - step;
+                break;
+            }
+        }
+    }
+    // Static (NSW=0) runs have no intermediate/ion_dynamics group at all; fall
+    // back to the final structure so the file still opens as a 1-frame view.
+    if (frames.length === 0) {
+        const final_lattice_data = squeeze_leading_axis(read_dataset(h5_file, FINAL_LATTICE));
+        const final_positions_data = squeeze_leading_axis(read_dataset(h5_file, FINAL_POSITIONS));
+        if (!final_lattice_data || !final_positions_data) {
+            // Ion species exist but geometry is missing/torn — a bands/DOS-only
+            // file can still render its electronic results.
+            return electronic_only_trajectory(h5_file, `${TRAJ_POSITIONS} / ${FINAL_POSITIONS}`);
+        }
+        try {
+            frames.push(build_frame(final_lattice_data, final_positions_data, 0, scf_history?.at(-1), energies?.at(-1)?.[energy_col], undefined, scale));
+        }
+        catch {
+            // Geometry datasets present but malformed (file torn mid-write): same
+            // electronic-only fallback as when they're missing entirely.
+            return electronic_only_trajectory(h5_file, `${FINAL_LATTICE} / ${FINAL_POSITIONS}`);
+        }
+    }
+    // Static/single-point runs (one ionic step) get their SCF electronic steps
+    // expanded into pseudo-frames: the structure stays fixed while energy, |dE|,
+    // and the density residuals (incl. OSZICAR's rms(c) charge-density residual)
+    // plot per SCF step — the convergence view that matters when watching a
+    // running static job. Multi-point plots need >=2 frames, so this also makes
+    // single-point files plottable at all.
+    let frames_are_scf_steps = false;
+    const only_scf = scf_history?.length === 1 ? scf_history[0] : null;
+    if (frames.length === 1 && only_scf && only_scf.energies.length >= 2) {
+        const base_frame = frames[0];
+        frames.length = 0;
+        for (const [scf_idx, scf_energy] of only_scf.energies.entries()) {
+            const metadata = {
+                energy: scf_energy,
+                volume: base_frame.metadata?.volume,
+                ...scf_step_metadata(only_scf, scf_idx),
+            };
+            frames.push({ structure: base_frame.structure, step: scf_idx, metadata });
+        }
+        frames_are_scf_steps = true;
+    }
+    // Trajectory views only ever render the DOS panel, so skip reading the
+    // (potentially large) eigenvalue arrays here — bands are read only on the
+    // electronic-only paths above, which are the sole consumers.
+    const dos = read_vaspout_dos(h5_file);
+    return {
+        frames,
+        metadata: {
+            source_format: `vaspout_h5`,
+            frame_count: frames.length,
+            num_atoms: elements.length,
+            element_counts: count_elements(elements),
+            periodic_boundary_conditions: [true, true, true],
+            has_cell_info: true,
+            ...(energy_tag ? { energy_tag } : {}),
+            ...(dropped_steps > 0 ? { dropped_steps } : {}),
+            ...(frames_are_scf_steps ? { frames_are_scf_steps: true } : {}),
+            ...(dos ? { electronic: { dos, bands: null } } : {}),
+        },
+    };
+}
+export async function parse_vaspout_h5(buffer, filename) {
+    return with_h5_file(buffer, filename, parse_vaspout_h5_file);
+}

package/dist/trajectory/parse/xyz.js

@@ -1,17 +1,17 @@
 import * as math from '../../math';
-import { coerce_elem_symbol } from '../../element';
+import { coerce_elem_symbol } from '../../element/helpers';
 import { calc_force_stats, create_trajectory_frame, iter_xyz_frames, } from '../helpers';
 import { traj_warn } from './diagnostics';
 // 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
 function parse_extxyz_columns(comment) {
-    const fields = /Properties\s*=\s*"?([^"\s]+)"?/i.exec(comment)?.[1].split(`:`) ?? [];
+    const fields = /Properties\s*=\s*"?(?<properties>[^"\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);
+        const ncols = Math.trunc(Number(fields[idx + 2]));
         if (Number.isInteger(ncols) && ncols > 0) {
             layout[fields[idx].toLowerCase()] = { offset, ncols };
             offset += ncols;
@@ -26,7 +26,11 @@ function parse_extxyz_columns(comment) {
 }
 // Parse Lattice="ax ay az bx by bz cx cy cz" from an extxyz comment line
 function parse_extxyz_lattice(comment) {
-    const vals = /Lattice\s*=\s*"([^"]+)"/i.exec(comment)?.[1].trim().split(/\s+/).map(Number);
+    const vals = /Lattice\s*=\s*"(?<lattice>[^"]+)"/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)];
@@ -47,10 +51,10 @@ export function parse_xyz_comment_metadata(comment) {
     for (const [key, pattern] of Object.entries(METADATA_PATTERNS)) {
         const match = pattern.exec(comment);
         if (match)
-            properties[key] = parseFloat(match[1]);
+            properties[key] = Number(match[1]);
     }
-    const step = /(?:^|\s)(?:step|frame|ionic_step)\s*[=:]?\s*(\d+)/i.exec(comment)?.[1];
-    return { step: step ? parseInt(step, 10) : undefined, properties };
+    const step = /(?:^|\s)(?:step|frame|ionic_step)\s*[=:]?\s*(?<step>\d+)/i.exec(comment)?.[1];
+    return { step: step ? Math.trunc(Number(step)) : 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.

package/dist/trajectory/plotting.d.ts

@@ -1,10 +1,8 @@
-import type { DataSeries } from '../plot/core/types';
+import { type TrajPropertyConfig } from '../labels';
+import type { DataSeries, ScaleType } from '../plot/core/types';
 import type { TrajectoryDataExtractor, TrajectoryMetadata, TrajectoryType } from './index';
 export interface PlotSeriesOptions {
-    property_config?: Record<string, {
-        label: string;
-        unit: string;
-    }>;
+    property_config?: Record<string, TrajPropertyConfig>;
     colors?: readonly string[];
     default_visible_properties?: Set<string>;
 }
@@ -14,11 +12,12 @@ export declare function generate_axis_labels(plot_series: DataSeries[]): {
     y1: string;
     y2: string;
 };
+export declare function generate_axis_scale_types(plot_series: DataSeries[]): {
+    y1: ScaleType;
+    y2: ScaleType;
+};
 interface StreamingPlotOptions {
-    property_config?: Record<string, {
-        label: string;
-        unit: string;
-    }>;
+    property_config?: Record<string, TrajPropertyConfig>;
     colors?: readonly string[];
     default_visible_properties?: Set<string>;
     max_points?: number;

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
@@ -66,22 +98,24 @@ function create_series_from_stats(property_stats, property_config, colors) {
         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 +123,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 +135,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 +180,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: ``,
@@ -243,14 +278,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 +329,26 @@ 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)))
             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,8 +356,7 @@ 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++;
     }
@@ -314,9 +385,10 @@ function has_significant_variation(values, tolerance = 1e-6) {
     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() {