Work in progress. runflow is still being developed. Until version 1.0 there is no promise to keep its functionality or its syntax (options, directives, settings) as they are: a new version may change or remove them. CHANGELOG.md lists every change and what to do about it; to stay on a known version, check out its release tag, e.g.
git checkout v0.1.0.
The execution environment for OPM (Open Porous Media). runflow runs Flow, Flow's Python and any other program the same way on a workstation and on a cluster. It finds the installed Flow versions and the Python each one needs, runs Flow with MPI, and queues jobs. Use it from the command line, from workflow scripts, or interactively.
runflow -n 4 -c @mpi @flow CASE.DATA # Flow here, on 4 MPI ranks
runflow -c @wait @submit @flow CASE.DATA # as a job, waiting for itThis release runs jobs in its built-in local queue (localq). The LSF,
SLURM and PBS backends are planned; runflow --dry-run -s slurm workflow.sh
already shows the jobs a workflow would submit to them.
runflow is a set of bash scripts and needs no build step. Clone it, and add
its directory to PATH and MANPATH for this shell:
git clone https://github.com/OPM/runflow.git
cd runflow
export PATH="$PWD:$PATH" # the directory: do not symlink the script
export MANPATH="$PWD/man:${MANPATH:-}" # the ":" at the end keeps the system's man pagesFor every new shell, add the same to ~/.bashrc, from the runflow directory:
echo "export PATH=\"$PWD:\$PATH\" MANPATH=\"$PWD/man:\${MANPATH:-}\"" >> ~/.bashrcOn a cluster, clone it where every node finds it at the same path, e.g. on a
shared filesystem (man runflow, CONFIGURATION, "For administrators").
Requirements:
- bash 4.4 or newer, coreutils, util-linux and procps; on macOS:
brew install bash flock, with Homebrew'sbinfirst inPATH. - OPM Flow, and an MPI launcher (
mpirun) for runs with MPI. - For
@flowpyand the examples: a Flow build with its Python bindings (opm.io), and numpy.
Missing tools are reported when runflow starts.
Check the installation:
runflow --version # which runflow this is (CHANGELOG.md: what is in it)
runflow -c @flow -l # the Flow versions found, with their build and Python
runflow -c @wait @submit echo ok # a job in the local queue
runflow --jobs=all # the jobs, also finished onesrunflow works without configuration: it finds Flow through PATH and runs
jobs in its local queue. Every setting, its default and what it does are in
etc/defaults/runflow.conf. Don't edit that file; copy the lines you change
into ~/.config/runflow/runflow.conf (for you), or into etc/runflow.conf in
the runflow directory (for everyone using it; Git ignores it). The files are
bash and are read in that order, so yours extends the site's lists with +=:
RUNFLOW_FLOW_VERSIONS+=('dev=~/opm/build/bin/Release') # the site's names stay; "dev" is added or redefinedThe settings used most:
| Setting | For |
|---|---|
RUNFLOW_FLOW_VERSIONS |
named builds, e.g. ('2025.04=/opt/opm/2025.04/bin/flow' 'dev=~/opm/build/bin') |
RUNFLOW_FLOW_VERSION |
the Flow used without -v |
RUNFLOW_JOB_SETUP |
what jobs run first, e.g. module load ... |
RUNFLOW_MPI_LAUNCHER_LOCAL |
the MPI launcher and its binding |
The environment and runflow's options win over the files. For installing it
for a site, see man runflow, CONFIGURATION, "For administrators".
A workflow is a plain bash script with directives, commands whose names start
with @, run with runflow. Its options are defaults for every directive in
the script:
#!/usr/bin/env bash
# run.sh: two cases in parallel, then a comparison when both completed
a=$(@submit @mpi @flow CASE_A.DATA)
b=$(@submit @mpi @flow CASE_B.DATA)
@submit --depends-on "$a,$b" @flowpy compare.py
@waitrunflow -n 8 --flow-version 2025.04 run.sh # each run on 8 ranks, with that Flow
runflow --dry-run run.sh # the jobs it would submit| Directive | Does |
|---|---|
@flow |
runs Flow |
@flowpy |
runs the Python of a Flow version, with its opm bindings |
@mpi |
runs a program, or @flow, with MPI |
@submit |
queues a job and prints its ID |
@wait |
waits for jobs, or submits and waits: @wait @submit ... |
@cancel |
cancels jobs |
@help |
lists the directives; @help @flow shows the options of one |
runflow --shell starts an interactive bash with the directives, Tab
completion and notices of finished jobs; runflow and man runflow work in
it even without the PATH and MANPATH lines above.
Where things go: a job's output, unless @submit -o names a file, is in
~/.local/state/runflow/logs/localq.HOST.ID.log; the local queue's state in
/var/tmp/runflow-UID/. Flow writes its own output next to the deck.
When something goes wrong:
runflow --dry-run ...shows what would run, and the problems it finds.RUNFLOW_DEBUG=true runflow ...prints what runflow decides.- "Flow version not found":
runflow -c @flow -llists what is found where. - "MPI launcher not found": load the MPI module, or set
RUNFLOW_MPI_LAUNCHER_LOCAL. - "Unknown directive" in a job: the job does not find an extension directive at the same path.
| Where | What |
|---|---|
man runflow |
the reference: options, directives, schedulers, configuration |
| examples/ | short reservoir engineering workflows on SPE1 and SPE9, and a tutorial |
| docs/FLOW.md | how Flow versions, their builds and their Python are found |
| docs/DIRECTIVES.md | writing your own directives |
| docs/BACKENDS.md | adding a scheduler, running on clusters |
| docs/DEVELOPMENT.md | developing runflow: layout, tests, conventions |
| ROADMAP.md | status and known limitations |
| CHANGELOG.md | what changed in each version (runflow --version: which you have) |
Copyright (C) 2026 OPM-OP AS.
runflow is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version (SPDX: GPL-3.0-or-later), as OPM itself is.
It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in LICENSE for more details.