bigraph-schema 1.3.2__tar.gz → 1.3.4__tar.gz

{bigraph_schema-1.3.2/bigraph_schema.egg-info → bigraph_schema-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigraph-schema
-Version: 1.3.2
+Version: 1.3.4
 Summary: A serializable type schema for compositional systems biology
 Author: Eran Agmon, Ryan Spangler
 Requires-Python: >=3.9
@@ -21,6 +21,7 @@ Dynamic: license-file
 
 [![PyPI version](https://img.shields.io/pypi/v/bigraph-schema.svg)](https://pypi.org/project/bigraph-schema/)
 [![Tutorial](https://img.shields.io/badge/GitHub%20Pages-Tutorial-brightgreen)](https://vivarium-collective.github.io/bigraph-schema/notebooks/demo.html)
+[![Units Demo](https://img.shields.io/badge/GitHub%20Pages-Units%20demo-blue)](https://vivarium-collective.github.io/bigraph-schema/notebooks/units.html)
 
 `bigraph-schema` provides a serializable type schema for compositional and multiscale modeling.  
 It defines a compact, extensible language for describing hierarchical data structures — the foundation of the Vivarium 2.0 simulation framework.
@@ -47,6 +48,8 @@ The following resources provide guided introductions and examples:
 
 - [Bigraph Schema Basics Tutorial](https://vivarium-collective.github.io/bigraph-viz/notebooks/basics.html) – Explains how to compose and visualize schema graphs using the `bigraph-schema` syntax.
 
+- [Units Demo](https://vivarium-collective.github.io/bigraph-schema/notebooks/units.html) – Demonstrates `Quantity`, `Number._units`, and wire-level unit conversion.
+
 
 ---
 

{bigraph_schema-1.3.2 → bigraph_schema-1.3.4}/README.md

@@ -2,6 +2,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/bigraph-schema.svg)](https://pypi.org/project/bigraph-schema/)
 [![Tutorial](https://img.shields.io/badge/GitHub%20Pages-Tutorial-brightgreen)](https://vivarium-collective.github.io/bigraph-schema/notebooks/demo.html)
+[![Units Demo](https://img.shields.io/badge/GitHub%20Pages-Units%20demo-blue)](https://vivarium-collective.github.io/bigraph-schema/notebooks/units.html)
 
 `bigraph-schema` provides a serializable type schema for compositional and multiscale modeling.  
 It defines a compact, extensible language for describing hierarchical data structures — the foundation of the Vivarium 2.0 simulation framework.
@@ -28,6 +29,8 @@ The following resources provide guided introductions and examples:
 
 - [Bigraph Schema Basics Tutorial](https://vivarium-collective.github.io/bigraph-viz/notebooks/basics.html) – Explains how to compose and visualize schema graphs using the `bigraph-schema` syntax.
 
+- [Units Demo](https://vivarium-collective.github.io/bigraph-schema/notebooks/units.html) – Demonstrates `Quantity`, `Number._units`, and wire-level unit conversion.
+
 
 ---
 

bigraph_schema-1.3.4/bigraph_schema/json_codec.py

@@ -0,0 +1,310 @@
+"""JSON codec for bigraph-schema state documents.
+
+The dispatch-based :func:`~bigraph_schema.methods.serialize.serialize` /
+:func:`~bigraph_schema.methods.realize.realize` pair handles per-leaf
+serialization when a paired schema is available. Many downstream consumers
+(workspace dashboards, save-state caches, subprocess runners) need to JSON-
+serialize a state document **without** carrying the matched schema, so a
+schema-agnostic codec is required as well.
+
+This module exposes that codec. The wire format uses tagged dicts so values
+round-trip without schema info:
+
+- ``pint.Quantity`` → ``{"__pint__": true, "magnitude": ..., "units": "..."}``
+  (array-valued Quantities also carry ``"__magnitude_dtype__"``)
+- ``numpy.ndarray`` → ``{"__numpy__": true, "dtype": "...", "shape": [...], "data": [...]}``
+- ``numpy`` structured array →
+  ``{"__numpy_structured__": true, "dtype": [...], "shape": [...], "data": [...]}``
+- ``numpy`` scalars → native ``int``/``float``/``bool``
+- ``set``/``frozenset`` → ``{"__set__": true, "data": [...]}``
+- ``bytes`` → ``{"__bytes__": true, "data": "<hex>"}``
+
+Tuples are NOT tagged — ``json.JSONEncoder`` bypasses ``default()`` for
+tuples since they're natively encodable as JSON arrays. They round-trip
+as lists.
+
+This matches the format already in use in ``v2ecoli/cache.py:NumpyJSONEncoder``;
+the canonical implementation now lives here and consumers should import from
+this module rather than redefining their own. Saved state files using the
+v2ecoli encoder remain readable.
+
+The ``pint`` reconstruction uses
+:func:`~bigraph_schema.units.get_quantity_registry`, so consumers that swap
+the registry (e.g. v2ecoli setting pint's application registry to bigraph-
+schema's shared one) get coherent ``Quantity`` instances.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+class BigraphJSONEncoder(json.JSONEncoder):
+    """JSON encoder for bigraph-schema state trees.
+
+    Use directly via ``json.dumps(obj, cls=BigraphJSONEncoder)`` or through
+    the :func:`dumps` convenience wrapper. Pair with :func:`bigraph_json_hook`
+    on the read side.
+    """
+
+    def default(self, obj: Any) -> Any:
+        # pint.Quantity — emit tagged {magnitude, units} so we round-trip
+        # without needing schema info at deserialize time. Array-valued
+        # Quantities also carry their magnitude dtype so e.g. counts stay int.
+        try:
+            import pint
+            if isinstance(obj, pint.Quantity):
+                mag = obj.magnitude
+                try:
+                    import numpy as np
+                    if isinstance(mag, np.ndarray):
+                        return {
+                            '__pint__': True,
+                            'magnitude': mag.tolist(),
+                            '__magnitude_dtype__': str(mag.dtype),
+                            'units': str(obj.units),
+                        }
+                except ImportError:
+                    pass
+                if isinstance(mag, (int, float)):
+                    return {'__pint__': True, 'magnitude': mag, 'units': str(obj.units)}
+                return {'__pint__': True, 'magnitude': float(mag), 'units': str(obj.units)}
+        except ImportError:
+            pass
+
+        # numpy
+        try:
+            import numpy as np
+            if isinstance(obj, np.ndarray):
+                if obj.dtype.names:
+                    dtype_list = []
+                    for name in obj.dtype.names:
+                        field_dtype = obj.dtype[name]
+                        if field_dtype.shape:
+                            dtype_list.append((name, str(field_dtype.base), list(field_dtype.shape)))
+                        else:
+                            dtype_list.append((name, str(field_dtype)))
+                    return {
+                        '__numpy_structured__': True,
+                        'dtype': dtype_list,
+                        'shape': list(obj.shape),
+                        'data': [list(row) for row in obj.tolist()],
+                    }
+                return {
+                    '__numpy__': True,
+                    'dtype': str(obj.dtype),
+                    'shape': list(obj.shape),
+                    'data': obj.tolist(),
+                }
+            if isinstance(obj, np.integer):
+                return int(obj)
+            if isinstance(obj, np.floating):
+                return float(obj)
+            if isinstance(obj, np.bool_):
+                return bool(obj)
+        except ImportError:
+            pass
+
+        # builtins json.dumps can't represent
+        if isinstance(obj, (set, frozenset)):
+            return {'__set__': True, 'data': sorted(obj, key=str)}
+        if isinstance(obj, bytes):
+            return {'__bytes__': True, 'data': obj.hex()}
+        # Note: tuples are NOT tagged. json.JSONEncoder bypasses ``default()``
+        # for tuples because they're natively encodable as JSON arrays, so a
+        # tag here wouldn't fire. Tuples round-trip as lists. Callers that
+        # need tuple-ness preserved should convert at the schema layer.
+
+        return super().default(obj)
+
+
+def bigraph_json_hook(obj: Any) -> Any:
+    """JSON ``object_hook`` that reverses :class:`BigraphJSONEncoder`.
+
+    Pass to ``json.load(f, object_hook=bigraph_json_hook)`` or through
+    :func:`loads`. Recognises the tag keys (``__pint__`` etc.) and rebuilds
+    the corresponding Python objects. Unrecognised dicts pass through
+    unchanged, so plain JSON objects still load as ``dict``.
+    """
+    if not isinstance(obj, dict):
+        return obj
+    if obj.get('__pint__') or obj.get('__pint_array__'):
+        # ``__pint_array__`` is v2ecoli's legacy variant tag for array-valued
+        # Quantities; accept it as an alias of ``__pint__`` so saved state
+        # files from before this module existed keep loading.
+        from bigraph_schema.units import get_quantity_registry
+        ureg = get_quantity_registry()
+        mag = obj.get('magnitude', obj.get('value'))
+        dtype = obj.get('__magnitude_dtype__')
+        if obj.get('__pint_array__') or dtype is not None:
+            import numpy as np
+            mag = np.array(mag, dtype=dtype) if dtype else np.array(mag)
+        return ureg.Quantity(mag, obj['units'])
+    if obj.get('__numpy__'):
+        import numpy as np
+        return np.array(obj['data'], dtype=obj['dtype']).reshape(obj['shape'])
+    if obj.get('__numpy_structured__'):
+        import numpy as np
+        dtype = np.dtype([tuple(field) for field in obj['dtype']])
+        return np.array([tuple(row) for row in obj['data']], dtype=dtype).reshape(obj['shape'])
+    if obj.get('__set__'):
+        return set(obj['data'])
+    if obj.get('__bytes__'):
+        return bytes.fromhex(obj['data'])
+    return obj
+
+
+def dumps(obj: Any, **kwargs: Any) -> str:
+    """Serialize ``obj`` to a JSON string via :class:`BigraphJSONEncoder`."""
+    return json.dumps(obj, cls=BigraphJSONEncoder, **kwargs)
+
+
+def loads(s: str, **kwargs: Any) -> Any:
+    """Deserialize a JSON string via :func:`bigraph_json_hook`."""
+    return json.loads(s, object_hook=bigraph_json_hook, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Tests (inline, run via `python -m bigraph_schema.json_codec` or pytest).
+# ---------------------------------------------------------------------------
+
+def test_pint_scalar_round_trip():
+    import pint
+    from bigraph_schema.units import units as ureg
+    q = ureg.Quantity(5.0, 'femtogram')
+    s = dumps(q)
+    q2 = loads(s)
+    assert isinstance(q2, pint.Quantity)
+    assert q2.magnitude == 5.0
+    assert str(q2.units) == str(q.units)
+
+
+def test_pint_array_round_trip():
+    import numpy as np
+    import pint
+    from bigraph_schema.units import units as ureg
+    q = ureg.Quantity(np.array([1, 2, 3], dtype=np.int64), 'count')
+    s = dumps(q)
+    q2 = loads(s)
+    assert isinstance(q2, pint.Quantity)
+    assert isinstance(q2.magnitude, np.ndarray)
+    assert q2.magnitude.dtype == np.int64
+    assert (q2.magnitude == np.array([1, 2, 3])).all()
+    assert str(q2.units) == str(q.units)
+
+
+def test_pint_int_magnitude_preserved():
+    """Int magnitudes shouldn't silently widen to float on round-trip."""
+    from bigraph_schema.units import units as ureg
+    q = ureg.Quantity(42, 'count')
+    s = dumps(q)
+    q2 = loads(s)
+    assert q2.magnitude == 42
+    assert isinstance(q2.magnitude, int)
+
+
+def test_numpy_ndarray_round_trip():
+    import numpy as np
+    a = np.array([[1.5, 2.5], [3.5, 4.5]])
+    s = dumps(a)
+    a2 = loads(s)
+    assert isinstance(a2, np.ndarray)
+    assert a2.dtype == a.dtype
+    assert a2.shape == a.shape
+    assert (a2 == a).all()
+
+
+def test_numpy_scalar_round_trip():
+    import numpy as np
+    s = dumps({'i': np.int64(7), 'f': np.float32(1.5), 'b': np.bool_(True)})
+    obj = loads(s)
+    assert obj == {'i': 7, 'f': 1.5, 'b': True}
+    assert isinstance(obj['i'], int)
+    assert isinstance(obj['f'], float)
+    assert isinstance(obj['b'], bool)
+
+
+def test_set_round_trip():
+    s = dumps({1, 2, 3})
+    assert loads(s) == {1, 2, 3}
+
+
+def test_bytes_round_trip():
+    payload = b'\x00\x01\xff'
+    assert loads(dumps(payload)) == payload
+
+
+def test_tuple_becomes_list():
+    """Tuples round-trip as lists — json.JSONEncoder bypasses ``default()``
+    for tuples since they're natively JSON-encodable as arrays. Documenting
+    this so callers know tuple-ness isn't preserved by this codec."""
+    out = loads(dumps((1, 'two', 3.0)))
+    assert out == [1, 'two', 3.0]
+    assert isinstance(out, list)
+
+
+def test_nested_state_tree():
+    """The hook must fire at every level — top-level dict with nested Quantities."""
+    import numpy as np
+    from bigraph_schema.units import units as ureg
+    tree = {
+        'agent': {
+            'mass': ureg.Quantity(123.4, 'fg'),
+            'counts': ureg.Quantity(np.array([10, 20], dtype=np.int64), 'count'),
+            'genome': b'ATCG',
+            'tags': {'a', 'b'},
+            'history': [
+                {'t': 0, 'rate': ureg.Quantity(0.5, '1/second')},
+                {'t': 1, 'rate': ureg.Quantity(0.6, '1/second')},
+            ],
+        },
+    }
+    out = loads(dumps(tree))
+    assert out['agent']['mass'].magnitude == 123.4
+    assert (out['agent']['counts'].magnitude == np.array([10, 20])).all()
+    assert out['agent']['counts'].magnitude.dtype == np.int64
+    assert out['agent']['genome'] == b'ATCG'
+    assert out['agent']['tags'] == {'a', 'b'}
+    assert out['agent']['history'][1]['rate'].magnitude == 0.6
+
+
+def test_plain_dict_passes_through():
+    """Dicts without tag keys must round-trip as plain dicts."""
+    payload = {'just': 'a', 'plain': {'nested': [1, 2]}}
+    assert loads(dumps(payload)) == payload
+
+
+def test_v2ecoli_format_compat():
+    """Saved files using v2ecoli's NumpyJSONEncoder must still load.
+
+    v2ecoli emits ``__pint__`` for scalars and ``__pint_array__`` for array-
+    valued Quantities. This codec accepts both so saved state files written
+    before this module existed remain readable.
+    """
+    import numpy as np
+    import pint
+    legacy_blob = (
+        '{"mass": {"__pint__": true, "magnitude": 1.5, "units": "femtogram"},'
+        ' "rates": {"__pint_array__": true, "magnitude": [0.1, 0.2], "units": "1/second"}}'
+    )
+    out = loads(legacy_blob)
+    assert isinstance(out['mass'], pint.Quantity)
+    assert out['mass'].magnitude == 1.5
+    assert isinstance(out['rates'], pint.Quantity)
+    assert isinstance(out['rates'].magnitude, np.ndarray)
+    assert (out['rates'].magnitude == np.array([0.1, 0.2])).all()
+
+
+if __name__ == '__main__':
+    test_pint_scalar_round_trip()
+    test_pint_array_round_trip()
+    test_pint_int_magnitude_preserved()
+    test_numpy_ndarray_round_trip()
+    test_numpy_scalar_round_trip()
+    test_set_round_trip()
+    test_bytes_round_trip()
+    test_tuple_becomes_list()
+    test_nested_state_tree()
+    test_plain_dict_passes_through()
+    test_v2ecoli_format_compat()
+    print('json_codec: all tests passed')

{bigraph_schema-1.3.2 → bigraph_schema-1.3.4}/bigraph_schema/methods/apply.py

@@ -216,6 +216,41 @@ def _deep_merge_into(base, overlay):
     return base
 
 
+def _path_copy_merge(base, overlay):
+    """Persistent-data-structure-style merge.
+
+    Returns a NEW dict whose top-level is a shallow copy of ``base``,
+    with keys present in ``overlay`` recursively replaced. Subtrees of
+    ``base`` not touched by ``overlay`` are shared by reference, not
+    copied. Mutation-free w.r.t. ``base`` for the parts ``overlay``
+    doesn't reach.
+
+    Used by ``_handle_divide_sentinel`` so per-daughter overrides
+    (e.g. ``{division: {config: {agent_id: '00'}}}``) don't poison the
+    shared base produced by the type-driven divide walk (where
+    ``divide(Link)`` deliberately shares ``config`` by reference
+    between daughters so unmodified parameters/sim_data refs aren't
+    deep-copied).
+
+    Allocation cost is proportional to the *depth and width of
+    ``overlay``*, not the size of ``base``. For an override of depth
+    D touching K keys per level, this allocates O(D × K) dicts;
+    everything else (numpy arrays, sim_data references, the other
+    sibling configs) stays shared.
+    """
+    if not isinstance(overlay, dict):
+        return overlay
+    if not isinstance(base, dict):
+        return overlay
+    result = dict(base)
+    for key, overlay_value in overlay.items():
+        if key in base and isinstance(base[key], dict) and isinstance(overlay_value, dict):
+            result[key] = _path_copy_merge(base[key], overlay_value)
+        else:
+            result[key] = overlay_value
+    return result
+
+
 def _handle_divide_sentinel(value_schema, state, update, path):
     """Process a `_divide` sentinel from a Map / dict update.
 
@@ -352,7 +387,12 @@ def _handle_divide_sentinel(value_schema, state, update, path):
     daughters_state = {}
     for i, (key, override) in enumerate(daughter_items):
         baseline = baselines[i]
-        daughter = (_deep_merge_into(baseline, override)
+        # ``_path_copy_merge`` (not the in-place ``_deep_merge_into``)
+        # because divide(Link) shares config dicts by reference between
+        # both baseline daughters — mutating one daughter's override
+        # would silently corrupt the other. Path-copy only allocates
+        # along the override spine; everything else stays shared.
+        daughter = (_path_copy_merge(baseline, override)
                     if override else baseline)
         state[key] = daughter
         daughter_keys.append(key)

{bigraph_schema-1.3.2 → bigraph_schema-1.3.4}/bigraph_schema/methods/realize.py

@@ -658,12 +658,28 @@ def realize_link(core, schema: Link, encode, path=()):
         else:
             config = encode_config
 
-        # Try (config, core) first (standard bigraph signature), then
-        # fall back to (config) only (vivarium-style processes whose
-        # __init__ doesn't accept core).
+        # Pick constructor shape by inspecting the signature, instead
+        # of catching TypeError from edge_class(config, core) (which
+        # would also swallow real TypeErrors from inside __init__ and
+        # mask the underlying bug). Standard bigraph processes accept
+        # ``(config, core)``; vivarium-style processes take ``(config)``.
+        import inspect
         try:
+            sig = inspect.signature(edge_class)
+            accepts_core = (
+                'core' in sig.parameters
+                or any(p.kind == inspect.Parameter.VAR_KEYWORD
+                       for p in sig.parameters.values())
+                or len([p for p in sig.parameters.values()
+                        if p.kind in (inspect.Parameter.POSITIONAL_ONLY,
+                                      inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                                      inspect.Parameter.VAR_POSITIONAL)]) >= 2
+            )
+        except (ValueError, TypeError):
+            accepts_core = True  # default to standard bigraph signature
+        if accepts_core:
             edge_instance = edge_class(config, core)
-        except TypeError:
+        else:
             edge_instance = edge_class(config)
         # Ensure all instances have core for config_schema resolution
         # (needed by serialize). Vivarium-style processes don't accept

{bigraph_schema-1.3.2 → bigraph_schema-1.3.4/bigraph_schema.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigraph-schema
-Version: 1.3.2
+Version: 1.3.4
 Summary: A serializable type schema for compositional systems biology
 Author: Eran Agmon, Ryan Spangler
 Requires-Python: >=3.9
@@ -21,6 +21,7 @@ Dynamic: license-file
 
 [![PyPI version](https://img.shields.io/pypi/v/bigraph-schema.svg)](https://pypi.org/project/bigraph-schema/)
 [![Tutorial](https://img.shields.io/badge/GitHub%20Pages-Tutorial-brightgreen)](https://vivarium-collective.github.io/bigraph-schema/notebooks/demo.html)
+[![Units Demo](https://img.shields.io/badge/GitHub%20Pages-Units%20demo-blue)](https://vivarium-collective.github.io/bigraph-schema/notebooks/units.html)
 
 `bigraph-schema` provides a serializable type schema for compositional and multiscale modeling.  
 It defines a compact, extensible language for describing hierarchical data structures — the foundation of the Vivarium 2.0 simulation framework.
@@ -47,6 +48,8 @@ The following resources provide guided introductions and examples:
 
 - [Bigraph Schema Basics Tutorial](https://vivarium-collective.github.io/bigraph-viz/notebooks/basics.html) – Explains how to compose and visualize schema graphs using the `bigraph-schema` syntax.
 
+- [Units Demo](https://vivarium-collective.github.io/bigraph-schema/notebooks/units.html) – Demonstrates `Quantity`, `Number._units`, and wire-level unit conversion.
+
 
 ---
 

{bigraph_schema-1.3.2 → bigraph_schema-1.3.4}/bigraph_schema.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ bigraph_schema/assembly.py
 bigraph_schema/calculi.py
 bigraph_schema/core.py
 bigraph_schema/edge.py
+bigraph_schema/json_codec.py
 bigraph_schema/parse.py
 bigraph_schema/protocols.py
 bigraph_schema/schema.py

{bigraph_schema-1.3.2 → bigraph_schema-1.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bigraph-schema"
-version = "1.3.2"
+version = "1.3.4"
 description = "A serializable type schema for compositional systems biology"
 readme = "README.md"
 requires-python = ">=3.9"