matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,218 @@
+// Utility functions for working with trajectory data
+import type { ComponentProps } from 'svelte'
+import type { AnyStructure } from '$lib/structure/index'
+import type Trajectory from './Trajectory.svelte'
+
+export { default as Trajectory } from './Trajectory.svelte'
+export { default as TrajectoryError } from './TrajectoryError.svelte'
+export { default as TrajectoryExportPane } from './TrajectoryExportPane.svelte'
+export { default as TrajectoryInfoPane } from './TrajectoryInfoPane.svelte'
+
+export type TrajectoryFormat = `hdf5` | `json` | `xyz` | `xdatcar` | `traj` | `unknown`
+export type { AtomTypeMapping } from './types'
+
+// Core trajectory types
+export interface ParseProgress {
+  current: number
+  total: number
+  stage: string
+}
+
+export interface TrajectoryFrame {
+  structure: AnyStructure
+  step: number
+  metadata?: Record<string, unknown>
+}
+
+export interface FrameIndex {
+  frame_number: number
+  byte_offset: number
+  estimated_size: number
+}
+
+export interface TrajectoryMetadata {
+  frame_number: number
+  step: number
+  properties: Record<string, number>
+}
+
+// Trajectory type with streaming support
+export interface TrajectoryType {
+  frames: TrajectoryFrame[]
+  metadata?: Record<string, unknown>
+  // Large file streaming properties
+  total_frames?: number
+  indexed_frames?: FrameIndex[]
+  plot_metadata?: TrajectoryMetadata[]
+  is_indexed?: boolean
+  // On-demand frame loading for large/indexed trajectories.
+  frame_loader?: FrameLoader // When present, enables lazy loading of frames instead of loading all frames into memory.
+}
+
+// Unified handler data interface
+export interface TrajHandlerData {
+  trajectory?: TrajectoryType
+  step_idx?: number
+  frame_count?: number
+  frame?: TrajectoryFrame
+  filename?: string
+  file_size?: number
+  total_atoms?: number
+  error_msg?: string
+  fps?: number
+  mode?: ComponentProps<typeof Trajectory>[`display_mode`]
+  fullscreen?: boolean
+}
+
+// Function interfaces for extensibility
+export type TrajectoryDataExtractor = (
+  frame: TrajectoryFrame,
+  trajectory: TrajectoryType,
+) => Record<string, number>
+
+export interface FrameLoader {
+  get_total_frames: (data: string | ArrayBuffer) => Promise<number>
+  build_frame_index: (
+    data: string | ArrayBuffer,
+    sample_rate: number,
+    on_progress?: (progress: ParseProgress) => void,
+  ) => Promise<FrameIndex[]>
+  load_frame: (
+    data: string | ArrayBuffer,
+    frame_number: number,
+  ) => Promise<TrajectoryFrame | null>
+  extract_plot_metadata: (
+    data: string | ArrayBuffer,
+    options?: { sample_rate?: number; properties?: string[] },
+    on_progress?: (progress: ParseProgress) => void,
+  ) => Promise<TrajectoryMetadata[]>
+}
+
+export function validate_trajectory(trajectory: TrajectoryType): string[] {
+  // with detailed error reporting
+  const errors: string[] = []
+  const { frames, total_frames, indexed_frames, plot_metadata, is_indexed } = trajectory
+
+  if (!frames?.length) return [`Trajectory must have at least one frame`]
+
+  frames.forEach((frame, idx) => {
+    if (!frame.structure?.sites?.length) {
+      errors.push(`Frame ${idx} missing structure or sites`)
+    }
+    if (typeof frame.step !== `number`) {
+      errors.push(`Frame ${idx} missing or invalid step number`)
+    }
+  })
+
+  // Validate streaming-related properties
+  if (total_frames !== undefined) {
+    if (typeof total_frames !== `number` || total_frames < 1) {
+      errors.push(`total_frames must be a positive number, got ${total_frames}`)
+    } else if (indexed_frames?.length) {
+      const last_indexed_frame = indexed_frames.at(-1)
+      if (last_indexed_frame && last_indexed_frame.frame_number >= total_frames) {
+        errors.push(`indexed_frames contains frame_number >= total_frames (${total_frames})`)
+      }
+    }
+  }
+
+  if (is_indexed === true && !indexed_frames?.length) {
+    errors.push(`is_indexed is true but indexed_frames is missing or empty`)
+  }
+
+  if (indexed_frames) {
+    if (!Array.isArray(indexed_frames)) {
+      errors.push(`indexed_frames must be an array`)
+    } else {
+      indexed_frames.forEach((frame_idx, idx) => {
+        if (typeof frame_idx.frame_number !== `number`) {
+          errors.push(`indexed_frames[${idx}] missing or invalid frame_number`)
+        } else if (frame_idx.frame_number < 0) {
+          errors.push(
+            `indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) must be non-negative`,
+          )
+        } else if (idx > 0 && frame_idx.frame_number <= indexed_frames[idx - 1].frame_number) {
+          errors.push(
+            `indexed_frames[${idx}] frame_number (${frame_idx.frame_number}) must be strictly increasing`,
+          )
+        }
+        if (typeof frame_idx.byte_offset !== `number`) {
+          errors.push(`indexed_frames[${idx}] missing or invalid byte_offset`)
+        }
+        if (typeof frame_idx.estimated_size !== `number`) {
+          errors.push(`indexed_frames[${idx}] missing or invalid estimated_size`)
+        }
+      })
+    }
+  }
+
+  if (plot_metadata) {
+    if (!Array.isArray(plot_metadata)) {
+      errors.push(`plot_metadata must be an array`)
+    } else {
+      plot_metadata.forEach((meta, idx) => {
+        if (typeof meta.frame_number !== `number`) {
+          errors.push(`plot_metadata[${idx}] missing or invalid frame_number`)
+        }
+        if (typeof meta.step !== `number`) {
+          errors.push(`plot_metadata[${idx}] missing or invalid step`)
+        }
+        if (!meta.properties || typeof meta.properties !== `object`) {
+          errors.push(`plot_metadata[${idx}] missing or invalid properties object`)
+        }
+      })
+    }
+  }
+
+  return errors
+}
+
+export function get_trajectory_stats(trajectory: TrajectoryType): Record<string, unknown> {
+  const { frames, total_frames, indexed_frames, plot_metadata } = trajectory
+  const frame_count = total_frames || frames.length
+  const stats: Record<string, unknown> = {
+    frame_count,
+    is_indexed: trajectory.is_indexed ?? false,
+  }
+
+  if (frames.length > 0) {
+    const [first_frame, last_frame] = [frames[0], frames.at(-1) ?? frames[0]]
+    const max_sample = 100
+
+    const sampled =
+      frames.length <= max_sample
+        ? frames
+        : (() => {
+            const interval = Math.floor(frames.length / max_sample)
+            const result = [first_frame]
+            for (let idx = interval; idx < frames.length - 1; idx += interval) {
+              result.push(frames[idx])
+            }
+            if (result.at(-1) !== last_frame) result.push(last_frame)
+            return result
+          })()
+
+    const counts = sampled.map((frame) => frame.structure.sites.length)
+    const constant = counts.every((count) => count === counts[0])
+    const all_counts = constant
+      ? [first_frame.structure.sites.length]
+      : frames.map((frame) => frame.structure.sites.length)
+
+    stats.steps = frames.map((frame) => frame.step)
+    stats.step_range = [first_frame.step, last_frame.step]
+    stats.constant_atom_count = constant
+    if (constant) stats.total_atoms = first_frame.structure.sites.length
+    else stats.atom_count_range = [Math.min(...all_counts), Math.max(...all_counts)]
+  } else {
+    // Handle empty trajectory case
+    stats.steps = []
+    stats.step_range = undefined
+    stats.constant_atom_count = undefined
+    stats.total_atoms = undefined
+  }
+
+  // Additional metadata for large files
+  if (indexed_frames) stats.indexed_frame_count = indexed_frames.length
+  if (plot_metadata) stats.plot_metadata_count = plot_metadata.length
+  return stats
+}

package/dist/src/lib/trajectory/parse/ase.ts

@@ -0,0 +1,109 @@
+// ASE trajectory (.traj) parsing - binary format
+import { MAX_SAFE_STRING_LENGTH } from '$lib/trajectory/constants'
+import {
+  convert_atomic_numbers,
+  create_trajectory_frame,
+  read_ndarray_from_view,
+  validate_3x3_matrix,
+} from '$lib/trajectory/helpers'
+import type { TrajectoryFrame, TrajectoryType } from '$lib/trajectory/index'
+
+export function parse_ase_trajectory(buffer: ArrayBuffer, filename?: string): TrajectoryType {
+  const view = new DataView(buffer)
+  let offset = 0
+
+  const signature = new TextDecoder().decode(new Uint8Array(buffer, 0, 8))
+  if (signature !== `- of Ulm`) throw new Error(`Invalid ASE trajectory`)
+  offset += 24
+
+  // Skip ASE/Ulm version field; current parsing logic is version-independent.
+  offset += 8
+  const n_items = Number(view.getBigInt64(offset, true))
+  offset += 8
+  const offsets_pos = Number(view.getBigInt64(offset, true))
+
+  if (n_items <= 0) throw new Error(`Invalid frame count`)
+  if (offsets_pos < 0 || offsets_pos + n_items * 8 > buffer.byteLength) {
+    throw new Error(
+      `Invalid ASE frame offsets table bounds: offsets_pos=${offsets_pos}, n_items=${n_items}, byte_length=${buffer.byteLength}`,
+    )
+  }
+
+  const frame_offsets = Array.from({ length: n_items }, (_, idx) =>
+    Number(view.getBigInt64(offsets_pos + idx * 8, true)),
+  )
+
+  const frames: TrajectoryFrame[] = []
+  let global_numbers: number[] | undefined
+
+  for (let idx = 0; idx < n_items; idx++) {
+    try {
+      offset = frame_offsets[idx]
+      const json_length = Number(view.getBigInt64(offset, true))
+      offset += 8
+
+      if (json_length > MAX_SAFE_STRING_LENGTH) {
+        console.warn(`Skipping frame ${idx + 1}/${n_items}: too large`)
+        continue
+      }
+
+      const frame_data = JSON.parse(
+        new TextDecoder().decode(new Uint8Array(buffer, offset, json_length)),
+      )
+
+      const positions_ref = frame_data[`positions.`] ?? frame_data.positions
+      const positions = positions_ref?.ndarray
+        ? read_ndarray_from_view(view, positions_ref)
+        : (positions_ref as number[][])
+
+      const numbers_ref = frame_data[`numbers.`] ?? frame_data.numbers ?? global_numbers
+      const numbers: number[] = numbers_ref?.ndarray
+        ? read_ndarray_from_view(view, numbers_ref).flat()
+        : (numbers_ref as number[])
+
+      if (numbers) global_numbers = numbers
+      if (!numbers || !positions) {
+        console.warn(
+          `Skipping ASE frame ${idx + 1}/${n_items}: missing ${!numbers ? `numbers` : `positions`}`,
+        )
+        continue
+      }
+
+      const elements = convert_atomic_numbers(numbers)
+      const metadata = { step: idx, ...frame_data.calculator, ...frame_data.info }
+
+      frames.push(
+        create_trajectory_frame(
+          positions,
+          elements,
+          frame_data.cell ? validate_3x3_matrix(frame_data.cell) : undefined,
+          frame_data.pbc ?? [true, true, true],
+          idx,
+          metadata,
+        ),
+      )
+    } catch (error) {
+      console.warn(`Error processing frame ${idx + 1}/${n_items}:`, error)
+    }
+  }
+
+  if (frames.length === 0) throw new Error(`No valid frames found`)
+
+  const first_struct = frames[0]?.structure
+  const periodic_boundary_conditions =
+    first_struct !== null &&
+    first_struct !== undefined &&
+    typeof first_struct === `object` &&
+    `lattice` in first_struct
+      ? first_struct.lattice.pbc
+      : [true, true, true]
+
+  const metadata = {
+    filename,
+    source_format: `ase_trajectory`,
+    frame_count: frames.length,
+    total_atoms: global_numbers?.length ?? 0,
+    periodic_boundary_conditions,
+  }
+  return { frames, metadata }
+}

package/dist/src/lib/trajectory/parse/hdf5.ts

@@ -0,0 +1,173 @@
+// HDF5 trajectory parsing (torch-sim / generic format)
+import { calc_lattice_params, transpose_3x3_matrix } from '$lib/math'
+import type { Pbc } from '$lib/structure/pbc'
+import type { Dataset, Entity, Group } from 'h5wasm'
+import * as h5wasm from 'h5wasm'
+import {
+  convert_atomic_numbers,
+  create_trajectory_frame,
+  validate_3x3_matrix,
+} from '$lib/trajectory/helpers'
+import type { TrajectoryType } from '$lib/trajectory/index'
+
+const is_hdf5_dataset = (entity: Entity | null): entity is Dataset =>
+  entity !== null && `to_array` in entity && entity instanceof h5wasm.Dataset
+
+const is_hdf5_group = (entity: Entity | null): entity is Group =>
+  entity !== null && `keys` in entity && entity instanceof h5wasm.Group
+
+export async function parse_torch_sim_hdf5(
+  buffer: ArrayBuffer,
+  filename?: string,
+): Promise<TrajectoryType> {
+  const { FS } = await h5wasm.ready
+  const file_basename =
+    filename
+      ?.split(`/`)
+      .at(-1)
+      ?.replace(/[^\w.-]/g, `_`) || `temp`
+  const unique_suffix = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  const temp_filename = `${file_basename}-${unique_suffix}.h5`
+
+  FS.writeFile(temp_filename, new Uint8Array(buffer))
+  let h5_file: h5wasm.File | null = null
+
+  try {
+    h5_file = new h5wasm.File(temp_filename, `r`)
+    const found_paths: Record<string, string> = {}
+    let total_groups_found = 0
+    const find_dataset = (names: string[]) => {
+      const discover = (parent: Group, path = ``): Dataset | null => {
+        total_groups_found++
+        for (const name of parent.keys()) {
+          const item = parent.get(name)
+          const full_path = path ? `${path}/${name}` : `/${name}`
+          if (names.includes(name) && is_hdf5_dataset(item)) {
+            const found_name = names.find((dataset_name) => dataset_name === name)
+            if (found_name) found_paths[found_name] = full_path
+            return item
+          }
+          if (is_hdf5_group(item)) {
+            const result = discover(item, full_path)
+            if (result) return result
+          }
+        }
+        return null
+      }
+      return discover(h5_file as unknown as Group)
+    }
+
+    const positions_data = find_dataset([`positions`, `coords`, `coordinates`])?.to_array() as
+      | number[][]
+      | number[][][]
+      | null
+    const atomic_numbers_data = find_dataset([
+      `atomic_numbers`,
+      `numbers`,
+      `Z`,
+      `species`,
+    ])?.to_array() as number[] | number[][] | null
+    const cells_data = find_dataset([`cell`, `cells`, `lattice`])?.to_array() as
+      | number[][][]
+      | null
+    const energies_data = find_dataset([`potential_energy`, `energy`])?.to_array() as
+      | number[]
+      | number[][]
+      | null
+
+    if (!positions_data || !atomic_numbers_data) {
+      const missing_datasets = []
+      if (!positions_data) {
+        missing_datasets.push(`positions (tried: positions, coords, coordinates)`)
+      }
+      if (!atomic_numbers_data) {
+        missing_datasets.push(`atomic numbers (tried: atomic_numbers, numbers, Z, species)`)
+      }
+      const missing_str = missing_datasets.join(`, `)
+      const available_str = Array.from(h5_file.keys()).join(`, `)
+      throw new Error(
+        `Missing required dataset(s) in HDF5 file: ${missing_str}. Available datasets: ${available_str}`,
+      )
+    }
+
+    const positions_are_frames =
+      positions_data.length > 0 &&
+      positions_data.every(
+        (entry) => Array.isArray(entry) && entry.every((coord) => Array.isArray(coord)),
+      )
+    const positions = positions_are_frames ? positions_data : [positions_data as number[][]]
+    const atomic_numbers_are_frames =
+      atomic_numbers_data.length > 0 &&
+      atomic_numbers_data.every((entry) => Array.isArray(entry))
+    const atomic_numbers = atomic_numbers_are_frames
+      ? atomic_numbers_data
+      : [atomic_numbers_data as number[]]
+    const frames = positions.map((frame_pos, idx) => {
+      const frame_atomic_numbers = atomic_numbers[idx] || atomic_numbers[0]
+      const frame_elements = convert_atomic_numbers(frame_atomic_numbers)
+      const cell = cells_data?.[idx]
+      const lattice_mat = cell ? transpose_3x3_matrix(validate_3x3_matrix(cell)) : undefined
+      const energy_entry = energies_data?.[idx]
+      const energy = Array.isArray(energy_entry) ? energy_entry[0] : energy_entry
+      const metadata: Record<string, unknown> = {}
+      if (energy !== undefined) metadata.energy = energy
+      if (lattice_mat) {
+        metadata.volume = calc_lattice_params(lattice_mat).volume
+      }
+      const pbc: Pbc = lattice_mat ? [true, true, true] : [false, false, false]
+
+      return create_trajectory_frame(
+        frame_pos,
+        frame_elements,
+        lattice_mat,
+        pbc,
+        idx,
+        metadata,
+      )
+    })
+
+    const first_frame_elements =
+      frames[0]?.structure.sites.map((site) => site.species[0].element) ?? []
+
+    return {
+      frames,
+      metadata: {
+        source_format: `hdf5_trajectory`,
+        frame_count: frames.length,
+        num_atoms: first_frame_elements.length,
+        periodic_boundary_conditions: cells_data ? [true, true, true] : [false, false, false],
+        element_counts: first_frame_elements.reduce(
+          (counts: Record<string, number>, element) => {
+            counts[element] = (counts[element] || 0) + 1
+            return counts
+          },
+          {},
+        ),
+        discovered_datasets: {
+          positions:
+            found_paths.positions ||
+            found_paths.coords ||
+            found_paths.coordinates ||
+            `unknown`,
+          atomic_numbers:
+            found_paths.atomic_numbers ||
+            found_paths.numbers ||
+            found_paths.Z ||
+            found_paths.species ||
+            `unknown`,
+          cells: found_paths.cell || found_paths.cells || found_paths.lattice,
+          energies: found_paths.potential_energy || found_paths.energy,
+        },
+        total_groups_found,
+        has_cell_info: Boolean(cells_data),
+      },
+    }
+  } finally {
+    h5_file?.close()
+    try {
+      FS.unlink(temp_filename)
+    } catch {
+      /* temp file cleanup is best-effort */
+    }
+  }
+}