Skip to main content

Process-Bigraph

PyPI GitHub Pages

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.

Process Bigraph composition framework


🧩 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

Quickstart — composites, drafts & templates in code

A runnable five-minute tour of the core concepts. Every block below runs as-is against process-bigraph ≥ 1.8.3. Concepts explained in docs/concepts/composites-and-templates.md.

1. A process wired into a composite over a shared store. A composite is a state map of typed nodes; processes couple only by reading/writing shared stores.

from process_bigraph import Composite, Process, allocate_core
from process_bigraph.emitter import emitter_from_wires, gather_emitter_results

class Grow(Process):                                  # a Process = ports + an update
    config_schema = {'rate': 'float'}
    def inputs(self):  return {'level': 'float'}
    def outputs(self): return {'level': 'float'}
    def update(self, state, interval):
        return {'level': state['level'] * self.config['rate'] * interval}  # a delta

core = allocate_core()
core.register_link('Grow', Grow)                      # register it in the local registry

composite = Composite({'state': {
    'level': 1.0,                                     # a shared store
    'grow': {'_type': 'process', 'address': 'local:Grow', 'config': {'rate': 0.5},
             'interval': 1.0,                         # seconds; a unit string like '1 min' also works
             'inputs': {'level': ['level']}, 'outputs': {'level': ['level']}},
    'emitter': emitter_from_wires({'level': ['level'], 'time': ['global_time']}),
}}, core=core)
composite.run(5.0)
print(gather_emitter_results(composite))
# {('emitter',): [{'level': 1.0, 'time': 0.0}, {'level': 1.5, ...}, ... {'level': 7.59, 'time': 5.0}]}

2. A draft — an open hole whose sort is a contract. A not-yet-implemented process-slot is a hole: an open site (step 3) whose _sort names a ProcessContract (its typed face + conditions). You design and review the topology with the hole in place, then fill it with any process the contract admits. Composite refuses to build while a required hole is open, and reports which hole, what contract it requires, and which registered processes would fill it.

from bigraph_schema.contract import ProcessContract
from process_bigraph import find_candidates, UnfilledHoleError

# register the intended interface as a named contract …
core.register_contract('PTHSecretion', ProcessContract(
    summary='senses serum Ca, secretes PTH',
    face={'inputs': {'ca_sense': 'float'}, 'outputs': {'pth_out': 'float'}}))

# … and leave the slot as a hole sorted by it
template = core.access({'parathyroid': {'ca': 2.5, 'pth': 0.0,
    'secretion': {'_type': 'site', '_sort': 'PTHSecretion'}}})

# Composite(..., unfilled) → UnfilledHoleError, not an opaque KeyError:
#   not ground — required site(s) left unfilled: 'parathyroid/secretion'
#     • parathyroid/secretion
#         requires:
#           inputs: ca_sense: float
#           outputs: pth_out: float
#         candidates:
#           ✓ <any registered process whose contract admits the hole>

Fill it (step 3) with a process find_candidates(core, site) reports as admissible, and build. The full design → inspect → fill → build lifecycle — and the rejection report in full — is in docs/concepts/designing-with-holes.md.

Deprecated: @draft_process / DraftProcess (an inert placeholder node) still work but now emit DraftProcessDeprecationWarning — model a draft as a hole instead. draft_to_contract(cls) bridges an existing draft's interface to a ProcessContract.

3. A template — a composite with an open site (hole). A template is a document that isn't ground: it has open sites ({"_type": "site"}). Composite refuses to run one until every required site is filled.

from process_bigraph import Step
from process_bigraph.templates import open_sites, is_ground_document, template_document

class ReportCard(Step):                               # a fixed downstream verdict
    config_schema = {'threshold': 'float'}
    def inputs(self):  return {'level': 'float'}
    def outputs(self): return {'verdict': 'string'}
    def update(self, state):
        return {'verdict': 'pass' if state['level'] >= self.config['threshold'] else 'fail'}

core.register_link('ReportCard', ReportCard)
MODEL_FACE = {'_type': 'link', '_inputs': {'level': 'float'}, '_outputs': {'level': 'float'}}

template = core.access({'study': {                     # analysis fixed, the model is a HOLE
    'level': 1.0, 'verdict': 'string',
    'model':  {'_type': 'site', '_sort': MODEL_FACE},
    'report': {'_type': 'step', 'address': 'local:ReportCard', 'config': {'threshold': 2.0},
               'inputs': {'level': ['level']}, 'outputs': {'verdict': ['verdict']}}}})

print(open_sites(template), is_ground_document(template))   # [('study', 'model')] False

def model(rate):                                      # any conforming composite fits the hole
    return core.access({'_type': 'process', 'address': 'local:Grow', 'config': {'rate': rate},
                        'interval': 1.0, 'inputs': {'level': ['level']}, 'outputs': {'level': ['level']}})

sim = Composite({'state': template_document(core, template, {'study/model': model(0.5)})}, core=core)
sim.run(4.0)
print(sim.state['study']['verdict'])                  # pass  (a slower model → fail)
# template_document(core, template, {}) → UnfilledHoleError: not ground — required site 'study/model'

4. An investigation — one site per member study; gating is filling. Fill a member's site to admit it; leave it open and it is pruned from the built document, so a blocked prerequisite simply never runs.

from process_bigraph.templates import investigation_document

study = lambda: {'level': 1.0, 'verdict': 'string',
    'model':  {'_type': 'site', '_sort': MODEL_FACE},
    'report': {'_type': 'step', 'address': 'local:ReportCard', 'config': {'threshold': 2.0},
               'inputs': {'level': ['level']}, 'outputs': {'verdict': ['verdict']}}}

inv = core.access({'investigation': {'study_A': study(), 'study_B': study()}})
document, blocked = investigation_document(
    core, inv, {'investigation/study_A/model': model(0.5)}, member_depth=2)  # fill A only
print(blocked, sorted(document['investigation']))     # ['investigation/study_B'] ['study_A']

This same template/site machinery is what viva-superpowers uses to compile a whole investigation into a composite (one StudyStep per member). The study/investigation layer is documented in viva-superpowers docs/concepts/composites-templates-and-the-study-investigation-stack.md.

📘 Tutorials

The Process-Bigraph tutorials are executable Jupyter notebooks, rendered to HTML and published automatically on GitHub Pages.

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. docs/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. docs/emitters.md

  • Tick lifecycle — how a step network is ordered and advanced, and how a protocol runtime batches remote dispatch. docs/tick_lifecycle.md

  • Distributed lifecycles — running parts of a composite off-process. docs/distributed_lifecycles.md

  • Deploying a Step network to Nextflow — opt-in: compile a composite's Step network into a Nextflow DSL2 workflow and run it on a batch backend (local / SLURM). Nothing changes about Composite.run(). docs/nextflow.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



📜 License

Process-Bigraph is open-source software released under the
Apache 2 License.

Metadata

Release files for process-bigraph 1.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for process-bigraph 1.10.0
File Size Uploaded Provenance Actions
process_bigraph-1.10.0.tar.gz 263.2 kB With provenance Details for process_bigraph-1.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for process-bigraph 1.10.0
File Interpreter ABI Platform Actions
process_bigraph-1.10.0-py3-none-any.whl Python 3 none any Details for process_bigraph-1.10.0-py3-none-any.whl

Total release size: 548.0 kB

Release files / process_bigraph-1.10.0.tar.gz

Download URL process_bigraph-1.10.0.tar.gz
Size 263.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1dd5b2cbbd32024fb76c1b77f36b1c27cdb19bc5f7f73c2e7bdcd33cfef1dd8e
BLAKE2b-256 checksum
How to use checksums
02203839eda23b5cc9687744ecce37ef32456e77804a027790a20c9a19c08639
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Release files / process_bigraph-1.10.0-py3-none-any.whl

Download URL process_bigraph-1.10.0-py3-none-any.whl
Size 284.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3dc71a75f851eda518cff659837c4feabc5cab844f5a2011e9e6947a6b06ab3e
BLAKE2b-256 checksum
How to use checksums
6590e66d6670cd3253e33abd910a89721cfa93d68d88c49e1aeec755333fdbb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

Security for process-bigraph 1.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for process_bigraph-1.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.10.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page