Process-Bigraph
Process-Bigraph is a compositional runtime and protocol for building and executing multiscale biological models from interoperable processes.
It provides a shared architectural layer for:
- declaring process interfaces
- wiring processes through typed shared state
- orchestrating execution across heterogeneous timescales
- supporting dynamic structure (workflows, division, graph rewrites)
Process-Bigraph is the execution core of Vivarium 2.0, designed to integrate models built with different formalisms—including ODEs, FBA, agent-based models, spatial solvers, and machine-learning components—into a single coherent simulation.
🧩 What is a Process Bigraph?
A process bigraph combines:
- Typed stores — hierarchical, schema-validated state defined with bigraph-schema
- Processes — executable components with explicit input/output ports
- Composites — encapsulated sub-simulations with their own internal structure
- Orchestration patterns — multi-timestepping, directed workflows, and event-driven rewrites
Processes do not mutate state directly. Instead, they emit typed deltas that are merged by the runtime.
This allows:
- numerical updates
- structural rewrites
- scheduling and orchestration
to coexist under a single execution semantics.
In this sense, Process-Bigraph is a composition protocol, not a domain-specific simulator.
📄 Paper reference
The conceptual framework and formal semantics of process bigraphs are introduced in:
Agmon, E. & Spangler, R. K.
Process Bigraphs and the Architecture of Compositional Systems Biology
https://arxiv.org/abs/2512.23754
🚀 Getting Started
Installation
pip install process-bigraph
📘 Tutorials
The Process-Bigraph tutorials are executable Jupyter notebooks, rendered to HTML and published automatically on GitHub Pages.
- 📚 Tutorial Index (all tutorials)
https://vivarium-collective.github.io/process-bigraph/notebooks/index.html
Learning Path (Featured Tutorials)
-
Tutorial 1 — Process-Bigraph Basics
Processes, Steps, ports, Composites, workflows, and emitters
https://vivarium-collective.github.io/process-bigraph/notebooks/tutorial_1.html -
Tutorial 2 — Wrapping an ODE Solver (
odeint)
How to expose an existing scientific API as a Process
https://vivarium-collective.github.io/process-bigraph/notebooks/tutorial_2.html -
Tutorial 3 — Declarative Math
Defining mathematical relationships, signal pipelines, and events usingMathExpressionStep
https://vivarium-collective.github.io/process-bigraph/notebooks/tutorial_3.html -
Tutorial 4 — Composing a Biological Model
The central dogma from four small processes: composition over shared molecular state, biological units in the port types, and adding regulation by adding a wire
https://vivarium-collective.github.io/process-bigraph/notebooks/tutorial_4.html
More tutorials are added continuously and appear automatically in the index.
Architecture
- The framework, end to end — start here to understand the whole system:
what the objects are (documents, sites, handles), how they compose, the
higher-order DAG, templates and gating, content-addressed artifacts, the
git:protocol, and the laws everything else follows from. doc/architecture.md
Topic Guides
-
Emitters — Recording Simulation Results Built-in emitters (RAM, console, JSON, SQLite), how to wire them, retrieve results, store runs long-term, and write your own. doc/emitters.md
-
Tick lifecycle — how a step network is ordered and advanced, and how a protocol runtime batches remote dispatch. doc/tick_lifecycle.md
-
Distributed lifecycles — running parts of a composite off-process. doc/distributed_lifecycles.md
🧪 Reference Implementation: spatio-flux
Process-Bigraph is exercised end-to-end in spatio-flux, a multiscale reference model built entirely using the process-bigraph protocol.
spatio-flux composes spatial fields, particle dynamics, and metabolic processes using typed shared state and declarative orchestration.
GitHub: https://github.com/vivarium-collective/spatio-flux
Live test report: https://vivarium-collective.github.io/spatio-flux/report/index.html
🔗 Related Resources
-
Bigraph Schema Basics
https://vivarium-collective.github.io/bigraph-viz/notebooks/basics.html
Introduction to the schema language underlying Process-Bigraph -
Visualization of Bigraph Document — diagramming and rendering with bigraph-viz
https://vivarium-collective.github.io/bigraph-viz/notebooks/format.html -
E. coli Whole-Cell Wiring Diagram
https://raw.githubusercontent.com/vivarium-collective/bigraph-viz/main/doc/_static/ecoli.png -
Claude Code skills — wrap simulators, compose
pbg-*packages, and scaffold process-bigraph research workspaces with the pbg-superpowers Claude Code plugin (install with/plugin install pbg-superpowers).
📜 License
Process-Bigraph is open-source software released under the
Apache 2 License.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file process_bigraph-1.8.0.tar.gz.
File metadata
- Download URL: process_bigraph-1.8.0.tar.gz
- Upload date:
- Size: 166.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ef216ec888a1488a124119cad6694ab02e624510baabe039d1e2236e2ad64161
|
|
| MD5 |
ebc14710b38b78a3f445d9d961e82559
|
|
| BLAKE2b-256 |
320ff535e92448fb345161da9cdb2d85fc046017b4d497e0544377d4ba83a42f
|
Provenance
The following attestation bundles were made for process_bigraph-1.8.0.tar.gz:
Publisher:
release.yml on vivarium-collective/process-bigraph
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
process_bigraph-1.8.0.tar.gz -
Subject digest:
ef216ec888a1488a124119cad6694ab02e624510baabe039d1e2236e2ad64161 - Sigstore transparency entry: 2335548242
- Sigstore integration time:
-
Permalink:
vivarium-collective/process-bigraph@48f93825cea681ed90856a14b4fcac9146d63685 -
Branch / Tag:
refs/tags/v1.8.0 - Owner: https://github.com/vivarium-collective
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@48f93825cea681ed90856a14b4fcac9146d63685 -
Trigger Event:
push
-
Statement type:
File details
Details for the file process_bigraph-1.8.0-py3-none-any.whl.
File metadata
- Download URL: process_bigraph-1.8.0-py3-none-any.whl
- Upload date:
- Size: 181.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c2cce49dc332d310800f4d878524a16ec9f516d5dde3274778351c0831e9fdea
|
|
| MD5 |
993f6cf5ed54f2a23e3458de83780795
|
|
| BLAKE2b-256 |
2b15e50188cc66afc297e17d1fbe48e375d096a3866e32e395414dcefab470a9
|
Provenance
The following attestation bundles were made for process_bigraph-1.8.0-py3-none-any.whl:
Publisher:
release.yml on vivarium-collective/process-bigraph
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
process_bigraph-1.8.0-py3-none-any.whl -
Subject digest:
c2cce49dc332d310800f4d878524a16ec9f516d5dde3274778351c0831e9fdea - Sigstore transparency entry: 2335548296
- Sigstore integration time:
-
Permalink:
vivarium-collective/process-bigraph@48f93825cea681ed90856a14b4fcac9146d63685 -
Branch / Tag:
refs/tags/v1.8.0 - Owner: https://github.com/vivarium-collective
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@48f93825cea681ed90856a14b4fcac9146d63685 -
Trigger Event:
push
-
Statement type:
