scientific_workflow/lib.rs
1//! Rust primitives for reproducible scientific workflows.
2//!
3//! `scientific-workflow` provides the data and execution foundations needed to
4//! describe scientific systems, record their evolution, and organize scoped
5//! computational work. The crate is intentionally divided by responsibility:
6//! state representation, in-memory state time series, storage, dispatch, and
7//! language bridges remain separate modules rather than accumulating behind
8//! one monolithic interface.
9//!
10//! # Current modules
11//!
12//! [`configuration`] provides the standard `config/{fixed,sweep,paths}.json`
13//! project layout, deterministic Cartesian or explicit-case task expansion,
14//! immutable dict-like resolved parameters, named path resolution, and
15//! byte-exact source export.
16//!
17//! [`system_state`] provides:
18//!
19//! - JSON-defined, immutable field layouts;
20//! - optional natural-language field descriptions without persisted Rust types;
21//! - heterogeneous concrete Rust payloads behind a typed API;
22//! - clone-free payload insertion, mutation, and extraction;
23//! - explicit per-payload cloning of complete states;
24//! - mutable, checked time-point progression.
25//!
26//! Type erasure and boxing remain internal to that module. Downstream crates
27//! work with their original concrete payload types.
28//!
29//! [`time_series`] provides the in-memory analysis collection for complete,
30//! ordered states. It enforces shared-layout identity and increasing simulation
31//! indices, offers a lightweight borrowed view, and permits field-level
32//! mutation without exposing mutable state time. It deliberately performs no
33//! serialization, chunking, or filesystem IO.
34//!
35//! [`storage`] provides named partial-state streams with writer-owned sampling
36//! sampling intervals, borrowed JSON encoding only when due, bounded asynchronous
37//! persistence through one worker per recording, byte-targeted chunking, atomic recording
38//! metadata, per-key payload decoders, and verified analysis reconstruction.
39//! Import [`prelude`] when an application wants the complete supported API in
40//! scope without listing each module separately.
41//!
42//! # Basic use
43//!
44//! ```no_run
45//! use scientific_workflow::prelude::*;
46//!
47//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
48//! let spec = SystemStateSchema::load_json_template("state.json")?;
49//! let mut state = spec.create_empty_state(SimulationTime::from_iteration(0));
50//!
51//! assert!(
52//! state
53//! .insert_payload("population", vec![10_u64, 20, 30])?
54//! .is_none()
55//! );
56//! state
57//! .payload_mut::<Vec<u64>>("population")?
58//! .push(40);
59//! let time = state.advance_simulation_time(None)?;
60//! assert_eq!(time.iteration(), 1);
61//! let population = state.take_payload::<Vec<u64>>("population")?;
62//!
63//! assert_eq!(population, vec![10, 20, 30, 40]);
64//! # Ok(())
65//! # }
66//! ```
67//!
68//! Future dispatcher functionality will organize scoped workflow execution
69//! without changing the public state-value ownership or storage contracts.
70
71pub mod configuration;
72pub mod prelude;
73pub mod storage;
74pub mod system_state;
75pub mod time_series;