Skip to content

Writing workflows

workflow/v1 YAML. Compose tasks and other workflows; the compiler expands everything statically — there are no runtime loops.

schema: workflow/v1
name: my_protocol
version: 1.0.0
description: What it does, when to use it.
kind: scientific_protocol
domain: [polymer, atomistic]
purpose: [equilibration]
references: ["citation strings"]
assumptions: ["explicit scientific assumptions"]

inputs:
  system: {type: SimulationSystem, required: true}

parameters:
  temperature: {type: temperature, default: 300 K}
  seed: {type: integer, default: 12345}

stages:                      # shorthand for MD protocols
  - {ensemble: minimize, name: min, duration: 5 ps, timestep: 0.5 fs}
  - {ensemble: nvt, name: nvt, temperature: "${params.temperature}", duration: 50 ps}

steps:
  check:
    task: check_polymer_equilibration
    inputs: {thermo: "${nvt.thermo}"}

outputs:
  state: {value: "${nvt.state}"}
  report: {value: "${check.report}"}

References

  • ${inputs.x} — a workflow input artifact.
  • ${step.output} — an output artifact of an earlier step.
  • ${step.output.data.field} / .metadata.field — a value inside the artifact payload (usable in parameters and conditions).
  • ${params.x} — a workflow parameter.
  • Whole-string refs substitute the value; embedded refs interpolate into strings ("${T} K" — handy to build quantities from loop variables).

Step fields

A step may override its task's defaults — notably provider, retry, and resources:

steps:
  production:
    task: run_md
    inputs: {state: "${equil.state}"}
    resources: {cpu: 16, gpu: 1, walltime: 24 h}   # this step only

resources on a step replaces the task's resources block wholesale (it is not a field-level merge: if the task declares {cpu: 4, walltime: 30 min} and the step declares {cpu: 16}, the step runs with no declared walltime — the Slurm time config default applies). Task-level resources are just the author's default sizing; workflows size for their actual systems, and no task ever needs to be duplicated just to change resources. Resources are scheduling-only — they never join cache keys, so re-sizing a step does not invalidate the cache.

stages

{ensemble: minimize|nvt|npt|nve, temperature(_start/_end), pressure, duration, timestep, name} — expanded to chained run tasks (state→state) in declaration order. The first stage binds ${inputs.system}/${inputs.state}. minimize duration maps to relax_duration. For anything beyond a linear chain, use explicit steps.

foreach

steps:
  sweep:
    task: run_npt
    foreach: "${params.temperatures}"   # a JSON list
    as: T
    inputs: {state: "${inputs.state}"}
    parameters:
      temperature: "${T} K"
  collect:
    task: collect_thermo_series          # input declared many: true
    inputs: {series: "${sweep.thermo}"}  # gathers sweep__0..n in order

Expansion is static at compile time (max 256 items), so m3flow workflow plan shows exactly what will run.

conditions

condition: "not ${check.report.equilibrated}" — boolean mini-language (and or not == != < <= > >= parens, literals, ${...} refs). False → the node is SKIPPED and its dependents too. Use for adaptive protocols (equilibrate_polymer extends NPT only when the first check fails).

subworkflows

workflow: npt_thermodynamic_production inlines the child with step. prefixed node ids; the child's inputs bind to parent expressions, its outputs become ${step.output} in the parent. Nesting depth ≤ 8.

outputs

outputs: {name: {value: "${step.out}"}}. Outputs referencing SKIPPED steps are simply absent from run.outputs — document that for consumers.

Discipline

  • m3flow workflow plan <name> before every run — the compiled DAG is the contract.
  • Immutable once used: fork name@new-version to change a protocol.
  • Keep quantities typed end-to-end (temperature: "${params.temperature}", never pre-baked numbers).