matterviz 0.3.6 → 0.4.0

package/dist/src/lib/trajectory/plotting.ts

@@ -1,599 +0,0 @@
-// Plotting utilities for trajectory visualization
-import { PLOT_COLORS } from '$lib/colors'
-import { trajectory_property_config } from '$lib/labels'
-import { get_coefficient_of_variation } from '$lib/math'
-import type { DataSeries } from '$lib/plot/types'
-import type { TrajectoryDataExtractor, TrajectoryMetadata, TrajectoryType } from './index'
-
-// 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`])
-
-type VisibleProp = Readonly<{ property: string; unit: string }>
-
-export interface PlotSeriesOptions {
-  property_config?: Record<string, { label: string; unit: string }>
-  colors?: readonly string[]
-  default_visible_properties?: Set<string>
-}
-
-interface UnitGroup {
-  unit: string
-  series: DataSeries[]
-  priority: number
-  is_visible: boolean
-}
-
-// Unified property extraction and series generation
-export function generate_plot_series(
-  trajectory: TrajectoryType,
-  data_extractor: TrajectoryDataExtractor,
-  options: PlotSeriesOptions = {},
-): DataSeries[] {
-  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: TrajectoryType,
-  data_extractor: TrajectoryDataExtractor,
-): Map<
-  string,
-  {
-    values: number[]
-    has_variation: boolean
-    is_energy: boolean
-  }
-> {
-  const property_stats = new Map<
-    string,
-    {
-      values: number[]
-      sum: number
-      sum_squares: number
-      min: number
-      max: number
-    }
-  >()
-
-  // 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<
-    string,
-    {
-      values: number[]
-      has_variation: boolean
-      is_energy: boolean
-    }
-  >()
-
-  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: Map<
-    string,
-    {
-      values: number[]
-      has_variation: boolean
-      is_energy: boolean
-    }
-  >,
-  property_config: Record<string, { label: string; unit: string }>,
-  colors: readonly string[],
-): DataSeries[] {
-  const all_series: DataSeries[] = []
-  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: DataSeries[],
-  default_visible_properties: Set<string>,
-): UnitGroup[] {
-  // Group by unit
-  const unit_map = new Map<string, DataSeries[]>()
-  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 as string) || 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: DataSeries[], unit_groups: UnitGroup[]): void {
-  const visible_groups = unit_groups.filter((group) => group.is_visible)
-  const axis_map = new Map<UnitGroup, `y1` | `y2`>()
-
-  // 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: string,
-  property_config: Record<string, { label: string; unit: string }>,
-): { clean_label: string; unit: string } {
-  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: string, group_series: DataSeries[]): number {
-  // 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: string): string => {
-  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: string,
-  default_properties: Set<string>,
-): boolean => {
-  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: DataSeries[],
-  target_series_idx: number,
-): DataSeries[] {
-  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: DataSeries[]): UnitGroup[] {
-  const unit_map = new Map<string, DataSeries[]>()
-  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: DataSeries[],
-  unit_groups: UnitGroup[],
-): void {
-  // 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<UnitGroup, `y1` | `y2`>()
-  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((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: TrajectoryType | undefined,
-  plot_series: DataSeries[],
-  tolerance = 1e-10,
-): boolean {
-  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: DataSeries[]): string {
-  const visible_series = axis_series.filter((srs) => srs.visible)
-  if (!visible_series.length) return `Value`
-
-  const unit_groups = new Map<string, string[]>()
-  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
-}
-
-export function generate_axis_labels(plot_series: DataSeries[]): {
-  y1: string
-  y2: string
-} {
-  if (!plot_series.length) 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`)),
-  }
-}
-
-// Streaming plot generation (simplified)
-interface StreamingPlotOptions {
-  property_config?: Record<string, { label: string; unit: string }>
-  colors?: readonly string[]
-  default_visible_properties?: Set<string>
-  max_points?: number
-}
-
-export function generate_streaming_plot_series(
-  metadata_list: TrajectoryMetadata[],
-  options: StreamingPlotOptions = {},
-): DataSeries[] {
-  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<string>()
-  sampled_metadata.forEach((metadata) => {
-    Object.keys(metadata.properties).forEach((prop) => all_properties.add(prop))
-  })
-
-  const all_series: DataSeries[] = []
-  const visible_props: VisibleProp[] = []
-  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: TrajectoryMetadata[],
-  target_points: number,
-): TrajectoryMetadata[] {
-  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: TrajectoryMetadata[] = []
-  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: number[], tolerance = 1e-6): boolean {
-  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: string,
-  unit: string,
-  visible_properties: VisibleProp[],
-): `y1` | `y2` {
-  const mock_series = visible_properties.map(({ property: prop, unit: u }) => ({
-    label: prop,
-    unit: u,
-  })) as DataSeries[]
-
-  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/src/lib/trajectory/types.ts

@@ -1,13 +0,0 @@
-import type { ElementSymbol } from '$lib/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 // Threshold in bytes for ArrayBuffer files (default: MAX_BIN_FILE_SIZE)
-  text_file_threshold?: number // Threshold in bytes for string files (default: MAX_TEXT_FILE_SIZE)
-  atom_type_mapping?: AtomTypeMapping // Map LAMMPS atom types to element symbols (e.g. {1: 'Na', 2: 'Cl'})
-}

package/dist/src/lib/utils.ts

@@ -1,56 +0,0 @@
-// Check if value is a plain object (not array, null, or other types)
-const is_plain_object = (val: unknown): val is Record<string, unknown> =>
-  typeof val === `object` && val !== null && !Array.isArray(val)
-
-// Merge nested objects (1 level deep).
-export function merge_nested<T extends Record<string, unknown>>(
-  obj1: T,
-  obj2?: Partial<T>,
-): T {
-  const result = { ...obj1, ...obj2 } as T
-  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: string): string =>
-  unsafe_string
-    .replaceAll(`&`, `&amp;`)
-    .replaceAll(`<`, `&lt;`)
-    .replaceAll(`>`, `&gt;`)
-    .replaceAll(`"`, `&quot;`)
-    .replaceAll(`'`, `&#39;`)
-
-// Normalize unicode minus (U+2212) to ASCII hyphen-minus.
-export const normalize_unicode_minus = (value: string): string => value.replace(/−/g, `-`)
-
-// Normalize scientific notation variants (d/D exponent, Mathematica *^).
-export const normalize_scientific_notation = (value: string): string =>
-  normalize_unicode_minus(value).toLowerCase().replace(/d/g, `e`).replace(/\*\^/g, `e`)
-
-export function make_change_detector(): (value: unknown) => boolean {
-  const unset = Symbol()
-  let prev: unknown = unset
-  return (value: unknown) => {
-    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: string): string | undefined {
-  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
-  }
-}