sci_task_io

sci_task_io is a cross-language library for reading, writing, validating, and organizing scientific trajectory data.

The repository defines one canonical JSON trajectory contract and provides:

• a Python runtime for trajectory IO, aggregation, processed NPY output, and model discovery
• a Rust runtime for trajectory IO, validation, checkpoint handling, and directory-backed trajectory series loading

Repository Layout

• schema/
  • schema.md: human-readable schema
  • trajectory.json.schema: machine-readable JSON schema
  • signal_label.npy.schema.md: processed NPY payload shape
  • fixtures/contract/: valid and invalid JSON fixtures
• python/
  • src/sci_task_io/trajectory/: trajectory API
  • src/sci_task_io/model/: model and model-cluster utilities
  • examples/: runnable examples
• rust/
  • src/trajectory/: Rust trajectory modules
  • examples/: runnable examples

Trajectory Contract

Canonical JSON files are stored as <series_id>.json.

Top-level shape:

• metadata: optional object
• scalars: optional scalar key-value object
• signals: required object keyed as track_1, track_2, ...

Each track contains:

• label: non-empty string
• times: array of time values
• signal: array aligned 1:1 with times

Python can also write processed per-label outputs as <signal_label>.npy.

Python API

Top-level imports from sci_task_io:

• Trajectory
• SignalTrack
• TrajectorySeries
• Model
• ModelCluster
• load_trajectory_json
• save_trajectory_json
• trajectory_from_payload
• validate_trajectory_payload

Typical usage:

from sci_task_io import Trajectory, TrajectorySeries, SignalTrack

trajectory = Trajectory.from_json("run_A.json")
trajectory.save_json("copy.json")

series = TrajectorySeries.from_dir("runs")
written = series.process("processed")

track = SignalTrack.from_npy("frequencies.npy")

Rust API

Main module:

• sci_task_io::trajectory

Important exports:

• Trajectory
• SignalTrack
• TrajectorySeries
• TrajectoryHub
• load_trajectory_json
• save_trajectory_json
• trajectory_from_payload
• validate_trajectory_payload
• checkpoint helpers such as load_latest_checkpoint and sync_checkpoint_dirs

Typical usage:

use sci_task_io::trajectory::{Trajectory, TrajectorySeries};

let mut trajectory = Trajectory::with_track_capacity(1);
trajectory
    .metadata_mut()
    .insert("series_id".to_string(), "run_A".into());
trajectory.push_row("frequencies", 0usize, vec![0.5f64, 0.5f64])?;
trajectory.push_row("frequencies", 1usize, vec![0.6f64, 0.4f64])?;
trajectory.save_json(out_path)?;

let trajectory = Trajectory::from_json(path, false)?;
let frequencies = trajectory.track_by_label("frequencies");

let mut series = TrajectorySeries::from_dir(dir, false)?;
let ids = series.serial_ids()?;

Examples

• Python: python/examples/basic_usage.py
• Rust: rust/examples/dummy_project.rs

Scope

• Python includes model discovery and processed NPY helpers.
• Rust currently does not implement model discovery or NPY processing.