process-bigraph 1.0.4__tar.gz → 1.0.6__tar.gz

process_bigraph-1.0.6/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: process-bigraph
+Version: 1.0.6
+Summary: protocol and execution for compositional systems biology
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: bigraph-schema
+Requires-Dist: ipdb>=0.13.13
+Requires-Dist: matplotlib
+Requires-Dist: pint>=0.24.4
+Requires-Dist: scipy>=1.8
+Requires-Dist: pandas
+Requires-Dist: sympy
+Requires-Dist: ipykernel
+Requires-Dist: jupyter
+Requires-Dist: notebook
+Dynamic: license-file
+
+# Process-Bigraph
+
+[![PyPI](https://img.shields.io/pypi/v/process-bigraph.svg)](https://pypi.org/project/process-bigraph/)
+[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Tutorials-brightgreen)](https://vivarium-collective.github.io/process-bigraph/notebooks/index.html)
+
+**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.
+
+<p align="center">
+  <img src="https://github.com/vivarium-collective/process-bigraph/blob/main/doc/_static/composition_framework.png?raw=true"
+       width="800"
+       alt="Process Bigraph composition framework">
+</p>
+
+---
+
+## 🧩 What is a Process Bigraph?
+
+A **process bigraph** combines:
+
+- **Typed stores** — hierarchical, schema-validated state defined with
+  [**bigraph-schema**](https://github.com/vivarium-collective/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
+
+```console
+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 using `MathExpressionStep`*  
+  https://vivarium-collective.github.io/process-bigraph/notebooks/tutorial_3.html
+
+More tutorials are added continuously and appear automatically in the index.
+
+---
+
+## 🧪 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://github.com/vivarium-collective/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
+
+---
+
+## 📜 License
+
+Process-Bigraph is open-source software released under the  
+[Apache 2 License](https://github.com/vivarium-collective/process-bigraph/blob/main/LICENSE).

process_bigraph-1.0.6/README.md

@@ -0,0 +1,126 @@
+# Process-Bigraph
+
+[![PyPI](https://img.shields.io/pypi/v/process-bigraph.svg)](https://pypi.org/project/process-bigraph/)
+[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Tutorials-brightgreen)](https://vivarium-collective.github.io/process-bigraph/notebooks/index.html)
+
+**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.
+
+<p align="center">
+  <img src="https://github.com/vivarium-collective/process-bigraph/blob/main/doc/_static/composition_framework.png?raw=true"
+       width="800"
+       alt="Process Bigraph composition framework">
+</p>
+
+---
+
+## 🧩 What is a Process Bigraph?
+
+A **process bigraph** combines:
+
+- **Typed stores** — hierarchical, schema-validated state defined with
+  [**bigraph-schema**](https://github.com/vivarium-collective/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
+
+```console
+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 using `MathExpressionStep`*  
+  https://vivarium-collective.github.io/process-bigraph/notebooks/tutorial_3.html
+
+More tutorials are added continuously and appear automatically in the index.
+
+---
+
+## 🧪 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://github.com/vivarium-collective/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
+
+---
+
+## 📜 License
+
+Process-Bigraph is open-source software released under the  
+[Apache 2 License](https://github.com/vivarium-collective/process-bigraph/blob/main/LICENSE).

{process_bigraph-1.0.4 → process_bigraph-1.0.6}/process_bigraph/composite.py

@@ -72,8 +72,11 @@ def find_instances(
 
     for key, inner in state.items():
         if isinstance(inner, dict):
-            if isinstance(inner.get('instance'), process_class):
+            instance = inner.get('instance')
+
+            if isinstance(instance, process_class):
                 found[key] = inner
+
             elif not is_schema_key(key):
                 sub_instances = find_instances(inner, instance_type)
                 if sub_instances:
@@ -116,10 +119,11 @@ def find_step_triggers(
     """
     prefix = tuple(path[:-1])
     triggers: Dict[Tuple[str, ...], List[Union[List[str], Tuple[str, ...]]]] = {}
-    wire_paths = find_leaves(step['inputs'])
+    wire_paths = find_leaves(step['inputs'], path=prefix)
 
     for wire in wire_paths:
-        trigger_path = resolve_path(prefix + tuple(wire))
+        trigger_path = resolve_path(tuple(wire))
+        # trigger_path = resolve_path(prefix + tuple(wire))
         if isinstance(trigger_path, list):
             import ipdb; ipdb.set_trace()
         triggers.setdefault(trigger_path, []).append(path)
@@ -210,7 +214,7 @@ def find_leaves(tree_structure, path=None):
         list: List of leaf paths as tuples.
     """
     leaves = []
-    path = ()
+    path = path or ()
 
     if tree_structure is None:
         pass
@@ -221,7 +225,7 @@ def find_leaves(tree_structure, path=None):
     else:
         for key, value in tree_structure.items():
             if isinstance(value, dict):
-                subleaves = find_leaves(value, path + (key,))
+                subleaves = find_leaves(value, path=path)
                 leaves.extend(subleaves)
             else:
                 leaves.append(path + tuple(value))
@@ -241,7 +245,7 @@ def build_step_network(steps):
         - nodes: A mapping from paths to sets of steps that are dependent on them.
     """
     ancestors = {
-        step_key: {'input_paths': None, 'output_paths': None}
+        step_key: {'input_paths': None, 'output_paths': None, 'priority': None}
         for step_key in steps
     }
     nodes = {}
@@ -252,11 +256,15 @@ def build_step_network(steps):
 
         # Compute input paths once per step
         if ancestors[step_key]['input_paths'] is None:
-            ancestors[step_key]['input_paths'] = find_leaves(step['inputs'])
+            ancestors[step_key]['input_paths'] = find_leaves(step['inputs'], path=step_key[:-1])
 
         # Compute output paths once per step
         if ancestors[step_key]['output_paths'] is None:
-            ancestors[step_key]['output_paths'] = find_leaves(step.get('outputs', {}))
+            ancestors[step_key]['output_paths'] = find_leaves(step.get('outputs', {}), path=step_key[:-1])
+
+        # Assign the priority
+        if ancestors[step_key]['priority'] is None:
+            ancestors[step_key]['priority'] = step.get('priority', 0.0)
 
         input_paths = ancestors[step_key]['input_paths'] or []
         output_paths = ancestors[step_key]['output_paths'] or []
@@ -278,7 +286,7 @@ def build_step_network(steps):
     return ancestors, nodes
 
 
-def build_trigger_state(nodes):
+def build_trigger_state(nodes, paths):
     """
     Initialize the trigger state from dependency nodes.
 
@@ -288,8 +296,10 @@ def build_trigger_state(nodes):
     Returns:
         A mapping of paths to the set of steps waiting on those paths.
     """
+    path_set = set(paths)
+
     return {
-        key: value['before'].copy()
+        key: set(value['before']).intersection(path_set)
         for key, value in nodes.items()}
 
 
@@ -344,13 +354,51 @@ def determine_steps(steps, remaining, fulfilled):
     """
     to_run = []
 
+    if not remaining:
+        return to_run, remaining, fulfilled
+
     for step_path in list(remaining):
         step_inputs = steps[step_path].get('input_paths', []) or []
         if all(len(fulfilled[input]) == 0 for input in step_inputs):
             to_run.append(step_path)
 
+    if not to_run:
+        # cycles
+        visited = set([])
+        cycle = set([])
+        look = list(remaining)
+
+        while look:
+            step_path = look[0]
+            look = look[1:]
+
+            if step_path in visited:
+                if step_path in remaining:
+                    cycle.add(step_path)
+
+            else:
+                visited.add(step_path)
+
+                inputs = steps[step_path]['input_paths']
+                for input_path in inputs:
+                    if input_path in fulfilled:
+                        unfulfilled = fulfilled[input_path]
+                        look += unfulfilled
+
+        if not cycle:
+            return to_run, remaining, fulfilled
+
+        order = sorted(
+            cycle,
+            key=lambda path: steps[path]['priority'])
+
+        priority = order[-1]
+        to_run = [priority]
+
     for step_path in to_run:
-        remaining.remove(step_path)
+        if step_path in remaining:
+            remaining.remove(step_path)
+
         step_outputs = steps[step_path].get('output_paths', []) or []
         for output in step_outputs:
             exploded_path = explode_path(output)[1:]
@@ -658,64 +706,74 @@ class Process(Open):
         return {}
 
 
-def as_step(inputs, outputs, core=None):
+def as_step(inputs, outputs, name=None, aliases=None):
     """
-    Decorator to create a Step from a function named update_*.
-    If core is provided, registers under the name *.
+    Decorator: convert an `update_*` pure function into a Step subclass.
+
+    - Does NOT register into any core.
+    - Adds metadata so discover_packages can register nice aliases (e.g. "add").
     """
     def decorator(func):
-        assert func.__name__.startswith('update_'), "Function name must be of the form update_*"
-        step_name = func.__name__[len('update_'):]
+        if not func.__name__.startswith("update_"):
+            raise AssertionError("Function name must be of the form update_*")
 
-        class FunctionStep(Step):
-            def inputs(self):
-                return inputs
+        step_name = name or func.__name__[len("update_"):]
+        step_aliases = list(aliases or [])
+        # default alias: the function-derived name, e.g. update_add -> "add"
+        if step_name not in step_aliases:
+            step_aliases.insert(0, step_name)
 
-            def outputs(self):
-                return outputs
+        class FunctionStep(Step):
+            def inputs(self): return inputs
+            def outputs(self): return outputs
+            def update(self, state): return func(state)
 
-            def update(self, state):
-                return func(state)
+        FunctionStep.__name__ = f"{step_name}Step"
 
-        FunctionStep.__name__ = step_name + 'Step'
+        # IMPORTANT: make this class look like it belongs to the user's module
+        FunctionStep.__module__ = func.__module__
 
-        if core is not None:
-            core.register_link(step_name, FunctionStep)
+        # Discovery metadata
+        FunctionStep.__pb_kind__ = "step"
+        FunctionStep.__pb_aliases__ = step_aliases
+        FunctionStep.__pb_wrapped__ = func
 
         return FunctionStep
-
     return decorator
 
 
-def as_process(inputs, outputs, core=None):
+def as_process(inputs, outputs, name=None, aliases=None):
     """
-    Decorator to create a Process from a function named update_*.
-    If core is provided, registers under the name *.
+    Decorator: convert an `update_*` function into a Process subclass.
+
+    - Does NOT register into any core.
+    - Adds metadata so discover_packages can register nice aliases (e.g. "odeint").
     """
     def decorator(func):
-        assert func.__name__.startswith('update_'), "Function name must be of the form update_*"
-        process_name = func.__name__[len('update_'):]
-
-        class FunctionProcess(Process):
-            def __init__(self, config=None, core=None):
-                super().__init__(config=config, core=core)
+        if not func.__name__.startswith("update_"):
+            raise AssertionError("Function name must be of the form update_*")
 
-            def inputs(self):
-                return inputs
+        process_name = name or func.__name__[len("update_"):]
+        process_aliases = list(aliases or [])
+        if process_name not in process_aliases:
+            process_aliases.insert(0, process_name)
 
-            def outputs(self):
-                return outputs
+        class FunctionProcess(Process):
+            def inputs(self): return inputs
+            def outputs(self): return outputs
+            def update(self, state, interval): return func(state, interval)
 
-            def update(self, state, interval):
-                return func(state, interval)
+        FunctionProcess.__name__ = f"{process_name}Process"
 
-        FunctionProcess.__name__ = process_name + 'Process'
+        # IMPORTANT: make this class look like it belongs to the user's module
+        FunctionProcess.__module__ = func.__module__
 
-        if core is not None:
-            core.register_link(process_name, FunctionProcess)
+        # Discovery metadata
+        FunctionProcess.__pb_kind__ = "process"
+        FunctionProcess.__pb_aliases__ = process_aliases
+        FunctionProcess.__pb_wrapped__ = func
 
         return FunctionProcess
-
     return decorator
 
 
@@ -1147,9 +1205,6 @@ class Composite(Process):
         """
         state = state or self.state
 
-        # if 'environment' in state and '_add' in state['environment']:
-        #     import ipdb; ipdb.set_trace()
-
         bridge_view = self.core.view_ports(
             self.schema,
             state,
@@ -1229,7 +1284,7 @@ class Composite(Process):
             step_paths: A dictionary of step paths (as keys).
         """
         # Start with a fresh trigger state from the dependency graph
-        self.trigger_state = build_trigger_state(self.node_dependencies)
+        self.trigger_state = build_trigger_state(self.node_dependencies, step_paths)
 
         # Track steps still waiting to be executed in this cycle
         self.steps_remaining: Set[Union[str, Tuple[str, ...]]] = set(step_paths)
@@ -1359,6 +1414,7 @@ class Composite(Process):
                         paths.append(path)
 
                 update_paths = self.apply_updates(updates)
+                update_paths.append(('global_time',)) # updated global time can trigger steps
                 self.expire_process_paths(update_paths)
                 self.trigger_steps(update_paths)
 

{process_bigraph-1.0.4 → process_bigraph-1.0.6}/process_bigraph/processes/growth_division.py

@@ -159,7 +159,7 @@ def grow_divide_agent(config=None, state=None, path=None):
                 'mass': ['mass']}},
 
         'divide': {
-            '_type': 'process',
+            '_type': 'step',
             'address': 'local:Divide',
             'config': divide_config,
             'inputs': {