Expand description
Configuration-driven scientific workflow execution.
An ordinary application defines registered ExecutionUnit
implementations, writes wf_configs/study.json, its declared named
state-schema documents, and the central wf_configs/parameters.json, then
calls run with the project root. Workflow infers task
instances, phase membership, identities, output paths, progress boundaries,
recording lifecycle, and execution mechanics.
§Ordinary use
use std::path::Path;
fn main() -> Result<(), scientific_workflow::WorkflowError> {
scientific_workflow::run(Path::new("."))
}An execution unit carries its stable manifest key at its implementation:
use serde::Deserialize;
use scientific_workflow::prelude::*;
#[derive(Deserialize)]
struct Constants { initial: u64, steps: u64 }
struct ExampleUnit { state: SystemState, target_iteration: u64 }
#[scientific_workflow::execution_unit("example")]
impl ExecutionUnit for ExampleUnit {
type Constants = Constants;
fn preflight(constants: &Constants, _schema: &SystemStateSchema) -> UnitResult<ObservationPlan> {
constants.initial.checked_add(constants.steps)
.ok_or("initial population plus steps exceeds u64")?;
Ok(ObservationPlan::all_fields())
}
fn initialize(
constants: Constants,
schema: &SystemStateSchema,
_context: &InitializationContext,
) -> UnitResult<Self> {
let mut state = schema.create_empty_state(StateTime::from_iteration(0));
state.initialize_payload("population", constants.initial)?;
state.initialize_payload("cumulative_births", 0_u64)?;
Ok(Self {
state,
target_iteration: constants.steps,
})
}
fn member_count(&self) -> usize { 1 }
fn member(&self, index: usize) -> Option<MemberView<'_>> {
(index == 0).then(|| MemberView::new(
"example",
&self.state,
(self.state.time().iteration() >= self.target_iteration)
.then_some(MemberCompletion::without_reason()),
Some(self.target_iteration),
))
}
fn step(&mut self) -> UnitResult {
let next_time = self.state.time().checked_advance(None)?;
let (population, births) = self.state
.borrow_payloads::<(u64, u64)>(("population", "cumulative_births"))?;
let next_population = population.checked_add(1).ok_or("population exceeds u64")?;
let next_births = births.checked_add(1).ok_or("birth count exceeds u64")?;
let (population, births) = self.state
.borrow_payloads_mut::<(u64, u64)>(("population", "cumulative_births"))?;
*population = next_population;
*births = next_births;
self.state.replace_time(next_time);
Ok(())
}
}§Ownership boundaries
configalone reads and parses project JSON and supplies typed execution-unit constants.studycomposes parsed declarations, state semantics, and compiled execution-unit registrations into immutable, output-free intent.runtimeconsumes a completed Study and owns active execution/output.taskowns execution-unit contracts and automatic lifecycle observation; the crate root re-exports ordinary authoring types.stateowns canonical scientific state and schema.observationowns scientific observation meaning, not persistence mechanics.persistenceowns automatic durable output and verified reading.- Runtime owns lifecycle facts; the private UI subsystem implements their automatically composed terminal presentation.
WorkflowErrorcomposes complete-workflow Study/Runtime failures.
The crate-level run facade performs the sole ordinary transition from
project root to Study to Runtime. Study is the ultimate coordinator of
declared intent; runtime is the ultimate coordinator of active execution.
Inspection and embedding integrations import APIs directly from their
owning module roots. prelude contains only ordinary unit-authoring APIs
and crate conveniences.
Persistence write construction and output allocation are internal and are not available to execution-unit authors.
This crate is pre-1.0 test software and may make coordinated API changes.
Re-exports§
pub use task::ExecutionUnit;pub use task::InitializationContext;pub use task::MemberCompletion;pub use task::MemberView;pub use task::SeedError;pub use task::UnitResult;
Modules§
- config
- Central parsing and resolution of declarative Workflow project parameters.
- observation
- Application-defined scientific observation.
- persistence
- Automatic durable member recordings and program workspaces.
- prelude
- Ordinary execution-unit authoring imports.
- runtime
- Execution of a completely validated immutable study.
- state
- Template-defined scientific state and ordered in-memory state collections.
- study
- Effect-free compilation of project declarations into executable scientific intent.
- task
- Generic application workloads behind one uniform runtime definition.
Enums§
- Workflow
Error - A failure while loading, preflighting, or executing one project.
Functions§
- run
- Loads, preflights, and executes the Workflow project rooted at
project_root.
Attribute Macros§
- execution_
unit - Registers one
ExecutionUnitimplementation under a stable manifest key.