matterviz 0.3.6 → 0.4.0

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

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

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

@@ -1,173 +0,0 @@
-// 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 */
-    }
-  }
-}