Skip to main content

Crate scientific_workflow

Crate scientific_workflow 

Source
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

  • config alone reads and parses project JSON and supplies typed execution-unit constants.
  • study composes parsed declarations, state semantics, and compiled execution-unit registrations into immutable, output-free intent.
  • runtime consumes a completed Study and owns active execution/output.
  • task owns execution-unit contracts and automatic lifecycle observation; the crate root re-exports ordinary authoring types.
  • state owns canonical scientific state and schema.
  • observation owns scientific observation meaning, not persistence mechanics.
  • persistence owns automatic durable output and verified reading.
  • Runtime owns lifecycle facts; the private UI subsystem implements their automatically composed terminal presentation.
  • WorkflowError composes 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§

WorkflowError
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 ExecutionUnit implementation under a stable manifest key.