process-bigraph 1.0.5__tar.gz → 1.0.7__tar.gz

process_bigraph-1.0.7/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: process-bigraph
+Version: 1.0.7
+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.7/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.5 → process_bigraph-1.0.7}/process_bigraph/composite.py

@@ -16,6 +16,8 @@ import os
 import copy
 import json
 import math
+import numpy as np
+
 from typing import (
     Any, Dict, List, Optional, Set, Tuple, Union,
     Mapping, MutableMapping, Sequence,
@@ -72,8 +74,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:
@@ -261,7 +266,7 @@ def build_step_network(steps):
 
         # Assign the priority
         if ancestors[step_key]['priority'] is None:
-            ancestors[step_key]['priority'] = step['priority']
+            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 []
@@ -689,6 +694,9 @@ class Process(Open):
         update = self.update(state, interval)
         return SyncUpdate(update)
 
+    def calculate_timestep(self, interval, state):
+        return interval
+
     def update(self, state: Dict[str, Any], interval: float) -> Dict[str, Any]:
         """
         Override this method to implement the process logic.
@@ -703,64 +711,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_'):]
+        if not func.__name__.startswith("update_"):
+            raise AssertionError("Function name must be of the form update_*")
 
-        class FunctionProcess(Process):
-            def __init__(self, config=None, core=None):
-                super().__init__(config=config, core=core)
-
-            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
 
 
@@ -893,7 +911,8 @@ class Composite(Process):
             'inputs': 'wires',
             'outputs': 'wires'
         },
-        'global_time_precision': 'maybe[float]'
+        'global_time_precision': 'maybe[float]',
+        'skip_initial_steps': 'maybe[boolean]'
     }
 
 
@@ -998,11 +1017,16 @@ class Composite(Process):
         # A buffer for updates to be emitted at the composite's output interface.
         self.bridge_updates: List[Any] = []
 
+        # Precompile view/project operations for fast runtime access.
+        self._compiled_links = {}
+        self._build_view_project_cache()
+
         # Build the dependency network between steps and determine which steps should run first.
         self.build_step_network()
 
         # Run all steps that are ready on the first cycle.
-        self.run_steps(self.to_run)
+        if not self.config.get('skip_initial_steps', False):
+            self.run_steps(self.to_run)
 
     @classmethod
     def load(cls, path: str, core: Optional[Any] = None) -> "Composite":
@@ -1051,6 +1075,42 @@ class Composite(Process):
             # do we want to do anything with these?
             removed_front = self.front.pop(removed_key)
 
+    def _build_view_project_cache(self) -> None:
+        """Precompile view/project operations for each process path.
+
+        Delegates to core.precompile_link() which pre-resolves wire paths
+        and precomputes projection schemas so that runtime view/project
+        calls bypass schema traversal entirely.
+        """
+        self._compiled_links = {}
+
+        for path in list(self.process_paths) + list(self.step_paths):
+            compiled = self.core.precompile_link(
+                self.schema, self.state, path)
+            if compiled is not None:
+                self._compiled_links[path] = compiled
+
+    def _invalidate_caches(self) -> None:
+        """Invalidate precompiled link caches, forcing rebuild on next use."""
+        self._compiled_links = {}
+
+    def _cached_view(self, path: Tuple[str, ...]) -> Dict[str, Any]:
+        """Fast view using precompiled link when available."""
+        compiled = self._compiled_links.get(path)
+        if compiled is not None and compiled.get('view') is not None:
+            return self.core.view_fast(compiled['view'], self.state)
+        return self.core.view(self.schema, self.state, path)
+
+    def _cached_project(self, path: Tuple[str, ...], view: Any,
+                        ports_key: str = 'outputs') -> Any:
+        """Fast project using precompiled link when available."""
+        if ports_key == 'outputs':
+            compiled = self._compiled_links.get(path)
+            if compiled is not None and compiled.get('project') is not None:
+                return self.core.project_ports_fast(compiled['project'], view)
+        return self.core.project(
+            self.schema, self.state, path, view, ports_key)
+
     def merge(self, schema: Dict[str, Any], state: Dict[str, Any], path: Optional[List[str]] = None) -> None:
         """
         Merge a new schema/state subtree into the Composite.
@@ -1069,6 +1129,7 @@ class Composite(Process):
             state)
 
         self.find_instance_paths(self.state)
+        self._build_view_project_cache()
 
     def merge_schema(
             self,
@@ -1160,8 +1221,17 @@ class Composite(Process):
 
         os.makedirs(outdir, exist_ok=True)
         filepath = os.path.join(outdir, filename)
-        with open(filepath, 'w') as f:
-            json.dump(document, f, indent=4)
+        # outjson = json.dumps(
+        #     document,
+        #     default=encode_key)
+
+        with open(filepath, 'w') as outfile:
+            json.dump(
+                document,
+                outfile,
+                indent=2,
+                default=encode_key)
+
             print(f"Saved composite to {filepath}")
 
 
@@ -1401,6 +1471,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)
 
@@ -1449,11 +1520,10 @@ class Composite(Process):
                 state = future_front['state']
             else:
                 # Otherwise, slice the current state for the process
-                state = self.core.view(
-                    self.schema,
-                    self.state,
-                    path)
-                process_interval = process['interval']
+                state = self._cached_view(path)
+                state_interval = process['interval']
+                process_interval = process['instance'].calculate_timestep(state_interval, state)
+                process['interval'] = process_interval
 
             # Determine the target time for the next update
             future = (
@@ -1523,9 +1593,7 @@ class Composite(Process):
             if not isinstance(update_results, list):
                 update_results = [update_results]
 
-            return [self.core.project(
-                schema,
-                state,
+            return [self._cached_project(
                 process_path,
                 update_result,
                 ports_key) for update_result in update_results]
@@ -1533,6 +1601,24 @@ class Composite(Process):
         # Return a deferred object that will project the update when requested
         return Defer(update, defer_project, (self.schema, self.state, path))
 
+    @staticmethod
+    def _has_structural_keys(state: Any) -> bool:
+        """Check if a state dict contains keys that signal structural changes.
+
+        Structural changes (_add, _remove, _type) require re-running
+        realize() and find_instance_paths(). Plain value updates do not.
+        """
+        if not isinstance(state, dict):
+            return False
+        for key, value in state.items():
+            if key in ('_add', '_remove'):
+                return True
+            if key == '_type':
+                return True
+            if isinstance(value, dict) and Composite._has_structural_keys(value):
+                return True
+        return False
+
     def apply_updates(self, updates: List["Defer"]) -> List[Union[str, Tuple[str, ...]]]:
         """
         Apply a series of deferred updates and record the resulting bridge outputs.
@@ -1548,6 +1634,7 @@ class Composite(Process):
             A list of update paths (used to determine which processes to refresh).
         """
         update_paths = []
+        had_structural_changes = False
 
         for defer in updates:
             # Resolve deferred computation to get update(s)
@@ -1558,13 +1645,14 @@ class Composite(Process):
                 series = [series]
 
             for update_schema, update_state in series:
-                # if update and isinstance(update, dict) and 'environment' in update and update['environment'] and isinstance(update['environment'], dict) and '_react' in update['environment']:
-                #     import ipdb; ipdb.set_trace()
-
                 # Extract all hierarchical paths touched by this update
                 paths = hierarchy_depth(update_state)
                 update_paths.extend(paths.keys())
 
+                # Detect structural changes before applying
+                if not had_structural_changes:
+                    had_structural_changes = self._has_structural_keys(update_state)
+
                 # Apply update directly to the internal state,
                 # using the schema from the link itself
                 self.state, merges = self.core.apply(
@@ -1572,20 +1660,22 @@ class Composite(Process):
                     self.state,
                     update_state)
 
-                self.schema = self.core.resolve_merges(
-                    self.schema,
-                    merges)
+                if merges:
+                    had_structural_changes = True
+                    self.schema = self.core.resolve_merges(
+                        self.schema,
+                        merges)
 
                 # Read updated bridge outputs, if available
                 bridge_update = self.read_bridge(update_state)
                 if bridge_update:
                     self.bridge_updates.append(bridge_update)
 
-        self.schema, self.state = self.core.realize(self.schema, self.state)
-
-        # TODO: are we doing this twice?
-        # Refresh process and step instance paths
-        self.find_instance_paths(self.state)
+        # Only run expensive realize and instance discovery when structural changes occurred
+        if had_structural_changes:
+            self.schema, self.state = self.core.realize(self.schema, self.state)
+            self.find_instance_paths(self.state)
+            self._build_view_project_cache()
 
         return update_paths
 
@@ -1599,12 +1689,33 @@ class Composite(Process):
         Args:
             update_paths: A list of hierarchical paths that were modified.
         """
+        # Quick check: if no update path shares a first element with any process path,
+        # then no overlap is possible and we can skip the expensive scan.
+        if not hasattr(self, '_process_path_roots'):
+            self._process_path_roots = set()
+        process_roots = self._process_path_roots
+        if not process_roots:
+            process_roots = {p[0] for p in self.process_paths if p}
+            self._process_path_roots = process_roots
+
+        # Fast rejection: check if any update touches a process-adjacent path
+        needs_check = False
+        for update_path in update_paths:
+            if update_path and update_path[0] in process_roots:
+                needs_check = True
+                break
+
+        if not needs_check:
+            return
+
         for update_path in update_paths:
             for process_path in self.process_paths.copy():
                 # Match if update path completely overlaps the process path prefix
                 updated = all(update == process for update, process in zip(update_path, process_path))
                 if updated:
                     self.find_instance_paths(self.state)
+                    self._build_view_project_cache()
+                    self._process_path_roots = set()  # Reset for rebuild
                     return  # Exit early after one match, as paths are re-evaluated
 
 
@@ -1649,3 +1760,16 @@ class Composite(Process):
         self.run(interval)
 
         return self.bridge_updates
+
+
+def encode_key(o):
+        if isinstance(o, np.ndarray):
+            o.tolist()
+
+        elif isinstance(o, dict):
+            return {
+                str(k): encode_key(v)
+                for k, v in o.items()}
+
+        else:
+            return o