process-bigraph 1.4.16__tar.gz → 1.4.18__tar.gz

{process_bigraph-1.4.16/process_bigraph.egg-info → process_bigraph-1.4.18}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: process-bigraph
-Version: 1.4.16
+Version: 1.4.18
 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>=1.2.3
+Requires-Dist: bigraph-schema>=1.4.2
 Requires-Dist: matplotlib
 Requires-Dist: pint>=0.24.4
 Requires-Dist: scipy>=1.8
@@ -150,6 +150,11 @@ Live test report: https://vivarium-collective.github.io/spatio-flux/report/index
 - **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**](https://github.com/vivarium-collective/pbg-superpowers)
+  Claude Code plugin (install with `/plugin install pbg-superpowers`).
+
 ---
 
 ## 📜 License

{process_bigraph-1.4.16 → process_bigraph-1.4.18}/README.md

@@ -124,6 +124,11 @@ Live test report: https://vivarium-collective.github.io/spatio-flux/report/index
 - **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**](https://github.com/vivarium-collective/pbg-superpowers)
+  Claude Code plugin (install with `/plugin install pbg-superpowers`).
+
 ---
 
 ## 📜 License

{process_bigraph-1.4.16 → process_bigraph-1.4.18}/process_bigraph/__init__.py

@@ -3,7 +3,7 @@ from bigraph_schema import allocate_core
 from process_bigraph.composite import (
     Process, Step, Composite, TimingSummary, interval_time_precision, wire_step_layers,
 )
-from process_bigraph.bundle import save_bundle, load_bundle
+from process_bigraph.bundle import load_bundle
 from process_bigraph.emitter import Emitter, gather_emitter_results, generate_emitter_state
 from process_bigraph.types import StepLink, ProcessLink, CompositeLink
 

process_bigraph-1.4.18/process_bigraph/bundle.py

@@ -0,0 +1,179 @@
+"""
+bundle.py — Bundle loading for composite documents.
+
+A bundle is a directory containing:
+    document.json     — the composite document with large arrays replaced
+                        by ``{"$bundle_ref": "arrays/<hash>.parquet"}`` markers
+    arrays/           — externalized arrays as Parquet files
+
+This module provides the bundle *load* path — ``_load_array_parquet`` plus
+``resolve_refs`` / ``load_bundle``. The matching *write* primitive,
+``_save_array_parquet``, lives in ``bigraph_schema.methods.bundle`` (the layer
+that owns the bundle format via ``BundleContext`` + the dispatched ``bundle``
+method); the two are a format pair and must stay in sync. The save *path* is
+driven by ``Composite.save_bundle`` → ``core.bundle`` + ``BundleContext``.
+
+The format is designed to be:
+- Language-independent (Parquet is readable from Python, R, Rust, Java, …)
+- Self-contained (everything needed to reconstruct the composite)
+- Human-inspectable (document.json is small enough to open in an editor)
+"""
+
+import json
+import os
+from typing import Any, Dict
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+ARRAY_DIR = 'arrays'
+DOCUMENT_FILE = 'document.json'
+REF_KEY = '$bundle_ref'
+
+# Minimum estimated JSON size (bytes) before an array gets externalized.
+# 10 KB — small arrays stay inline for readability.
+MIN_ARRAY_BYTES = 10_000
+
+
+# ---------------------------------------------------------------------------
+# Parquet array reading (the writer is bigraph_schema.methods.bundle)
+# ---------------------------------------------------------------------------
+
+def _load_array_parquet(filepath: str) -> np.ndarray:
+    """Load a numpy array from a Parquet file written by
+    ``bigraph_schema.methods.bundle._save_array_parquet`` (the format pair)."""
+    import pyarrow.parquet as pq
+
+    # Use ParquetFile.read() rather than pq.read_table: the latter
+    # auto-infers hive partition columns from the path (e.g.
+    # ``variant=0/seed=1/...``) and appends them to every table read,
+    # which both clobbers metadata and adds spurious data columns.
+    table = pq.ParquetFile(filepath).read()
+    meta = table.schema.metadata or {}
+
+    # Check for binary blob format (3D+ arrays)
+    col_names = table.column_names
+    if col_names == ['data', 'shape', 'dtype']:
+        shape = json.loads(table.column('shape')[0].as_py())
+        dtype = np.dtype(table.column('dtype')[0].as_py())
+        data = table.column('data')[0].as_py()
+        # np.frombuffer returns a read-only view; copy to make writable
+        return np.frombuffer(data, dtype=dtype).reshape(shape).copy()
+
+    # Check for structured array
+    if b'bundle_structured' in meta:
+        import ast
+        struct_meta = json.loads(meta[b'bundle_structured'].decode())
+        dtype = np.dtype(ast.literal_eval(struct_meta['dtype']))
+        subarray_fields = struct_meta.get('subarray_fields', {})
+
+        n_rows = table.num_rows
+        result = np.zeros(n_rows, dtype=dtype)
+
+        for name in dtype.names:
+            if name in subarray_fields:
+                # Reconstruct sub-array from flattened columns
+                info = subarray_fields[name]
+                sub_count = info['count']
+                sub_shape = info['shape']
+                cols = [table.column(f'{name}.{i}').to_numpy()
+                        for i in range(sub_count)]
+                flat = np.column_stack(cols)
+                result[name] = flat.reshape((n_rows,) + tuple(sub_shape))
+            elif dtype[name].kind == 'U':
+                result[name] = table.column(name).to_pylist()
+            else:
+                result[name] = table.column(name).to_numpy()
+
+        return result
+
+    # Dense numeric array
+    dtype_str = meta.get(b'dtype', b'float64').decode()
+    shape_str = meta.get(b'shape', b'null').decode()
+    dtype = np.dtype(dtype_str)
+
+    if len(col_names) == 1:
+        arr = table.column('c0').to_numpy().astype(dtype)
+    else:
+        cols = [table.column(f'c{i}').to_numpy() for i in range(len(col_names))]
+        arr = np.column_stack(cols).astype(dtype)
+
+    if shape_str != 'null':
+        shape = json.loads(shape_str)
+        arr = arr.reshape(shape)
+
+    return arr
+
+
+# ---------------------------------------------------------------------------
+# Resolve $bundle_ref markers back into data
+# ---------------------------------------------------------------------------
+
+def resolve_refs(
+    document: Dict[str, Any],
+    bundle_dir: str,
+    as_numpy: bool = False,
+) -> Dict[str, Any]:
+    """Walk *document* and replace ``$bundle_ref`` markers with loaded data.
+
+    Args:
+        document: The document dict (from document.json).
+        bundle_dir: Path to the bundle directory.
+        as_numpy: If True, return numpy arrays directly. If False (default),
+            return nested Python lists (for passing to Composite constructor
+            which handles realize).
+    """
+
+    def _walk(node):
+        if isinstance(node, dict):
+            if REF_KEY in node:
+                ref_path = os.path.join(bundle_dir, node[REF_KEY])
+                arr = _load_array_parquet(ref_path)
+                if node.get('structured'):
+                    # Reconstruct __structured_array__ format for
+                    # downstream deserializers that expect it
+                    if as_numpy:
+                        return arr
+                    return {
+                        '__structured_array__': True,
+                        'dtype': str(arr.dtype),
+                        'data': [list(row) for row in arr.tolist()],
+                    }
+                if as_numpy:
+                    return arr
+                return arr.tolist()
+            return {k: _walk(v) for k, v in node.items()}
+        if isinstance(node, list):
+            return [_walk(item) for item in node]
+        return node
+
+    return _walk(document)
+
+
+# ---------------------------------------------------------------------------
+# Public API: load_bundle (the save path lives on Composite.save_bundle)
+# ---------------------------------------------------------------------------
+
+def load_bundle(
+    bundle_dir: str,
+    as_numpy: bool = False,
+) -> Dict[str, Any]:
+    """Load a composite document from a bundle directory.
+
+    Args:
+        bundle_dir: Path to the bundle directory.
+        as_numpy: If True, arrays are returned as numpy arrays.
+            If False, as nested Python lists (for Composite constructor).
+
+    Returns:
+        The fully resolved document dict.
+    """
+    doc_path = os.path.join(bundle_dir, DOCUMENT_FILE)
+    with open(doc_path, 'r') as f:
+        document = json.load(f)
+
+    return resolve_refs(document, bundle_dir, as_numpy=as_numpy)