sci_task_io 0.0.2

Standard File IO Interface for Scientific Calculation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# 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`](/home/acht/Desktop/Projects/SciTaskIO/schema/schema.md): human-readable schema
  - [`trajectory.json.schema`](/home/acht/Desktop/Projects/SciTaskIO/schema/trajectory.json.schema): machine-readable JSON schema
  - [`signal_label.npy.schema.md`](/home/acht/Desktop/Projects/SciTaskIO/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:

```python
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:

```rust
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`](/home/acht/Desktop/Projects/SciTaskIO/python/examples/basic_usage.py)
- Rust: [`rust/examples/dummy_project.rs`](/home/acht/Desktop/Projects/SciTaskIO/rust/examples/dummy_project.rs)

## Scope

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