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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigraph-schema
-Version: 1.3.4
+Version: 1.4.2
 Summary: A serializable type schema for compositional systems biology
 Author: Eran Agmon, Ryan Spangler
 Requires-Python: >=3.9
@@ -9,7 +9,6 @@ License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: fire
 Requires-Dist: numpy
-Requires-Dist: orjson
 Requires-Dist: pandas
 Requires-Dist: parsimonious
 Requires-Dist: pint

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/__init__.py

@@ -1,13 +1,3 @@
-# from bigraph_schema.registry import (
-#     deep_merge, validate_merge, default, Registry, hierarchy_depth, is_schema_key, establish_path,
-#     strip_schema_keys, type_parameter_key, non_schema_keys, set_path, transform_path)
-
-# from bigraph_schema.utilities import get_path, visit_method
-
-# from bigraph_schema.type_system import TypeSystem
-# from bigraph_schema.type_functions import FUNCTION_TYPE, METHOD_TYPE, type_schema_keys, resolve_path
-
-
 from bigraph_schema.edge import Edge
 from bigraph_schema.protocols import local_lookup_module
 

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/core.py

@@ -19,23 +19,12 @@ validation, and data transformation.
 expressions into structured schema nodes (`Union`, `Tuple`, `Array`, `Link`, etc.).
 """
 
-import sys
 import copy
-import typing
-import inspect
 import collections
 
 from pprint import pformat as pf
 
-import numpy as np
-from numpy import dtype
-import numpy.lib.format as nf
-
-import logging
-
-from plum import dispatch
-from parsimonious.nodes import NodeVisitor
-from dataclasses import dataclass, is_dataclass, replace
+from dataclasses import dataclass, replace
 import importlib.metadata
 
 from bigraph_schema.schema import (
@@ -79,11 +68,10 @@ from bigraph_schema.schema import (
     LocalProtocol
 )
 
-from bigraph_schema.parse import visit_expression
+from bigraph_schema.parse import visit_expression, CoreVisitor
 from bigraph_schema.edge import Edge
 from bigraph_schema.methods import (
     reify_schema,
-    handle_parameters,
     infer,
     default,
     resolve,
@@ -126,122 +114,6 @@ def append_link_path(schema, link_path):
     return schema
 
 
-class CoreVisitor(NodeVisitor):
-    """Visitor that converts parsed bigraph expressions into schema node structures.
-
-    Operates within a `Core` context, mapping grammar constructs
-    (unions, merges, type parameters, and defaults) into dataclass-based nodes.
-    Handles normalization of nested expressions (e.g. `tuple[int,float]`,
-    `link[a:int|b:string]`, `(x:y|z:w)`) into instances of `Union`, `Tuple`,
-    or structured dicts.
-    """
-
-    def __init__(self, operation):
-        """Initialize with the active `Core`."""
-        self.operation = operation
-
-    def visit_expression(self, node, visit):
-        """Top-level entry; returns first child."""
-        return visit[0]
-
-    def visit_union(self, node, visit):
-        """Parse `a~b~c` into a `Union(_options=[a,b,c])`."""
-        head = [visit[0]]
-        tail = [tree['visit'][1] for tree in visit[1]['visit']]
-        return Union(_options=head + tail)
-
-    def visit_merge(self, node, visit):
-        """Parse `a|b|c`; dicts merge to one mapping, others form a `Tuple`."""
-        head = [visit[0]]
-        tail = [tree['visit'][1] for tree in visit[1]['visit']]
-        nodes = head + tail
-        if all(isinstance(tree, dict) for tree in nodes):
-            merged = {}
-            for tree in nodes:
-                merged.update(tree)
-            return merged
-        else:
-            try:
-                values = tuple([int(x) for x in nodes])
-
-                return values
-            except Exception as e:
-                return Tuple(_values=nodes)
-
-    def visit_tree(self, node, visit):
-        """Delegate directly to nested element."""
-        return visit[0]
-
-    def visit_bigraph(self, node, visit):
-        """Alias for tree; allows recursion within nested bigraphs."""
-        return visit[0]
-
-    def visit_group(self, node, visit):
-        """Handle grouped subexpression `( ... )`; return tuple or dict."""
-        group_value = visit[1]
-        return group_value if isinstance(group_value, (list, tuple, dict, Tuple)) else (group_value,)
-
-    def visit_nest(self, node, visit):
-        """Handle `key:subtype` pairs (used in trees/maps).
-
-        The left side of the colon is a dict key — always a plain string,
-        not a resolved type.  We use the raw text from the parse node
-        rather than the visited (type-resolved) value, since key names
-        like ``process`` may collide with registered type names.
-        """
-        key = node.children[0].text
-        return {key: visit[2]}
-
-    def visit_type_name(self, node, visit):
-        """Resolve base type, parameters, and defaults into schema nodes."""
-        schema = visit[0]
-
-        # Parse parameter list
-        type_parameters = [
-            parameter
-            for parameter in visit[1]['visit']]
-
-        if type_parameters:
-            schema = handle_parameters(self.operation, schema, type_parameters[0])
-
-        # Parse default value `{...}`
-        default_visit = visit[2]['visit']
-        if default_visit:
-            default = default_visit[0]
-            if isinstance(schema, Node):
-                schema._default = default
-            elif isinstance(schema, dict):
-                schema['_default'] = default
-
-        return schema
-
-    def visit_parameter_list(self, node, visit):
-        """Return ordered list of parameters `[A,B,C]`."""
-        first = [visit[1]]
-        rest = [inner['visit'][1] for inner in visit[2]['visit']]
-        return first + rest
-
-    def visit_default_block(self, node, visit):
-        """Extract contents of `{...}` blocks."""
-        return visit[1]
-
-    def visit_default(self, node, visit):
-        """Return text inside default braces as string."""
-        return node.text
-
-    def visit_symbol(self, node, visit):
-        """Resolve bare symbol names via the operation registry or parse visitor."""
-        return self.operation.access(node.text)
-
-    def visit_nothing(self, node, visit):
-        """Handle empty productions (e.g., trailing commas)."""
-        return None
-
-    def generic_visit(self, node, visit):
-        """Fallback: return raw parse node and visited children."""
-        return {'node': node, 'visit': visit}
-
-
 class Core:
     """Bigraph-schema operation: registry, parsing, normalization, and ops.
 
@@ -1619,24 +1491,58 @@ class Core:
 
 _cached_base_core = None
 
+
+def _isolated_copy(base):
+    """Return a Core that shares nothing mutable with ``base``.
+
+    ``copy.copy`` alone is a *shallow* copy: the new object would share
+    the very same ``registry``, ``link_registry``, ``method_registry`` and
+    cache dicts as ``base``, so registering a type on one leaks into all
+    others. Here we shallow-copy the object (preserving cheaply-derived
+    state like ``packages_distributions``) and then give the copy its own
+    registry containers plus fresh, empty per-instance caches.
+
+    The copy depth is deliberately container-level, not deep: registry
+    *entries* are immutable schema nodes/dicts, so duplicating the dicts
+    that hold them is enough to prevent key-level leakage between cores
+    without the cost of deep-copying every schema.
+    """
+    import copy
+    clone = copy.copy(base)
+    clone.registry = dict(base.registry)
+    clone.link_registry = dict(base.link_registry)
+    clone.method_registry = dict(base.method_registry)
+    # Fresh, empty per-instance caches so warm entries (and the id-keyed
+    # witnesses they hold) never bleed between independently-allocated cores.
+    clone._access_cache = collections.OrderedDict()
+    clone._access_string_cache = {}
+    clone._link_cache = {}
+    clone._resolve_cache = collections.OrderedDict()
+    clone._promote_cache = collections.OrderedDict()
+    # The parse visitor closes over its owning core; rebind it to the clone.
+    clone.parse_visitor = CoreVisitor(clone)
+    return clone
+
+
 def allocate_core(top=None):
     """Allocate a new Core with all discovered packages.
 
-    The base core (without ``top``) is cached after the first call
-    to avoid repeated expensive package discovery. Each call returns
-    a fresh copy so callers can register additional types independently.
+    The base core (without ``top``) is built once and cached to avoid
+    repeated expensive package discovery. Each call returns an *isolated*
+    copy: it shares no mutable state with any other allocated core, so
+    types/links/methods registered on one core never leak into another,
+    while the base types from discovery are present on every copy. See
+    :func:`_isolated_copy` for the (container-level) copy semantics.
     """
     global _cached_base_core
     if top is None and _cached_base_core is not None:
-        import copy
-        return copy.copy(_cached_base_core)
+        return _isolated_copy(_cached_base_core)
 
     core = Core(BASE_TYPES)
     core = discover_packages(core, top)
 
     if top is None:
         _cached_base_core = core
-        import copy
-        return copy.copy(core)
+        return _isolated_copy(core)
 
     return core

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/edge.py

@@ -6,6 +6,9 @@ Edge
 Base class for all edges in the bigraph schema.
 """
 
+import inspect
+
+
 def default_wires(schema):
     """
     Create default wiring for a schema by connecting each port to a store of the same name.
@@ -28,6 +31,12 @@ class Edge:
 
     config_schema = {}
 
+    # Canonical formal description of this edge — a string (markdown / LaTeX) that
+    # states what the process/step computes (governing equations, assumptions).
+    # Override on subclasses. Tooling reads it via `describe()`, which falls back
+    # to the class docstring when this is left empty.
+    description = ''
+
     def __init__(self, config=None, core=None):
         """
         Initialize the edge with a config and simulation core.
@@ -135,4 +144,16 @@ class Edge:
             'outputs': self.outputs()
         }
 
+    def describe(self):
+        """
+        Return this edge's formal description.
+
+        Returns the ``description`` class attribute — the canonical formal
+        (mathematical) description of what this process/step computes. Falls
+        back to the class docstring when ``description`` is unset, so existing
+        edges still surface something. Subclasses should set ``description`` to
+        a string (markdown / LaTeX) for a precise, standardized description.
+        """
+        return self.description or inspect.getdoc(type(self)) or ''
+
 

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/methods/bundle.py

@@ -74,6 +74,100 @@ REF_KEY = '$bundle_ref'
 MIN_ARRAY_BYTES = 10_000  # ~10 KB threshold for externalizing
 
 
+# ---------------------------------------------------------------------------
+# Parquet array I/O
+# ---------------------------------------------------------------------------
+# The bundle WRITE side lives here because bigraph-schema owns the bundle
+# format (``BundleContext`` + the dispatched ``bundle`` method). The matching
+# READ side, ``_load_array_parquet`` / ``resolve_refs`` / ``load_bundle``, lives
+# in ``process_bigraph.bundle`` (the layer that orchestrates loading). The two
+# are a format pair — keep their column/metadata layout in sync. pyarrow is
+# imported lazily so bigraph-schema does not gain a hard pyarrow dependency
+# (bundling is opt-in).
+
+def _save_array_parquet(arr: "np.ndarray", filepath: str) -> None:
+    """Save a numpy array to a Parquet file.
+
+    Strategy:
+    - 1D/2D numeric arrays: store as columnar Parquet (one column per
+      array column, or a single column for 1D).
+    - Higher-dimensional or structured arrays: store as a binary blob
+      with shape/dtype metadata.
+
+    Counterpart reader: ``process_bigraph.bundle._load_array_parquet``.
+    """
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+
+    if arr.dtype.names:
+        # Structured array — each field becomes one or more Parquet columns.
+        # Sub-array fields (e.g. shape (N, 2)) are flattened into separate
+        # columns: field.0, field.1, etc.
+        columns = {}
+        subarray_meta = {}  # field_name -> {'shape': [...], 'dtype': '...'}
+
+        for name in arr.dtype.names:
+            field_data = arr[name]
+            if field_data.dtype.kind == 'U':
+                columns[name] = pa.array(field_data.tolist(), type=pa.string())
+            elif field_data.ndim > 1:
+                # Sub-array field: flatten into N columns
+                sub_shape = field_data.shape[1:]
+                sub_count = int(np.prod(sub_shape))
+                flat = field_data.reshape(len(field_data), sub_count)
+                for i in range(sub_count):
+                    columns[f'{name}.{i}'] = pa.array(flat[:, i])
+                subarray_meta[name] = {
+                    'shape': list(sub_shape),
+                    'dtype': str(field_data.dtype.base),
+                    'count': sub_count,
+                }
+            else:
+                columns[name] = pa.array(field_data)
+
+        table = pa.table(columns)
+
+        # Store the original dtype string and sub-array info in file metadata
+        file_meta = {
+            'dtype': str(arr.dtype),
+            'subarray_fields': subarray_meta,
+        }
+        schema_meta = table.schema.metadata or {}
+        schema_meta[b'bundle_structured'] = json.dumps(file_meta).encode()
+        table = table.replace_schema_metadata(schema_meta)
+
+        pq.write_table(table, filepath, compression='zstd')
+
+    elif arr.ndim == 1 or (arr.ndim == 2 and arr.shape[1] <= 500):
+        # Dense 1D or moderate 2D array — columnar storage.
+        if arr.ndim == 1:
+            table = pa.table({'c0': pa.array(arr)})
+        else:
+            columns = {
+                f'c{i}': pa.array(arr[:, i])
+                for i in range(arr.shape[1])
+            }
+            table = pa.table(columns)
+
+        # Store original dtype in metadata
+        meta = {b'dtype': str(arr.dtype).encode(),
+                b'shape': json.dumps(list(arr.shape)).encode()}
+        table = table.replace_schema_metadata(meta)
+        pq.write_table(table, filepath, compression='zstd')
+
+    else:
+        # Wide 2D (>500 cols) or 3D+ — binary blob with compression.
+        # Storing as raw bytes in a single Parquet row with zstd
+        # compression. This is still very efficient: a 50MB int8 array
+        # compresses to ~15MB.
+        table = pa.table({
+            'data': [arr.tobytes()],
+            'shape': [json.dumps(list(arr.shape))],
+            'dtype': [str(arr.dtype)],
+        })
+        pq.write_table(table, filepath, compression='zstd')
+
+
 @dataclass
 class BundleContext:
     """Accumulates array files during a bundle operation.
@@ -93,8 +187,6 @@ class BundleContext:
         If an array with identical content has already been saved, the
         existing file is reused (content-addressed deduplication).
         """
-        from process_bigraph.bundle import _save_array_parquet
-
         os.makedirs(self.arrays_dir, exist_ok=True)
 
         content_id = hashlib.sha256(

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/methods/merge.py

@@ -358,17 +358,6 @@ def _value_is_empty(value):
         return not value
 
 
-def tuplify_dict(d):
-    if isinstance(d, dict):
-        tulip = []
-        for key, value in d.items():
-            tulip.append((
-                key,
-                tuplify_dict(value)))
-    else:
-        return d
-
-
 @dispatch
 def merge(schema: dict, current, update, path=()):
     if path:

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/methods/resolve.py

@@ -189,7 +189,15 @@ def resolve(current: Wrap, update: Wrap, path=None):
         return schema
     else:
         # TODO: resolve wrappings somehow?
-        raise Exception(f'cannot resolve two different wrappings {current} {update}')
+        import traceback as _tb
+        _frames = ''.join(_tb.format_stack(limit=12)[:-1])
+        raise Exception(
+            f'cannot resolve two different wrappings at path={path}:\n'
+            f'  current ({type(current).__name__}, _default={getattr(current, "_default", "?")}, '
+            f'_value type={type(getattr(current, "_value", None)).__name__})\n'
+            f'  update ({type(update).__name__}, _default={getattr(update, "_default", "?")}, '
+            f'_value type={type(getattr(update, "_value", None)).__name__})\n'
+            f'  call stack:\n{_frames}')
 
 
 @dispatch
@@ -661,7 +669,6 @@ def resolve(current: Array, update: Node, path=None):
 # @dispatch
 # def resolve(current: Node, update: Array, path=None):
 #     if path:
-#         import ipdb; ipdb.set_trace()
 
 #         return resolve_array_path(update, current, path=path)
 
@@ -840,7 +847,6 @@ def resolve(current: String, update: Node, path=None):
 
 # @dispatch
 # def resolve(current: Node, update: String):
-#     # import ipdb; ipdb.set_trace()
 #     if update._default:
 #         current = replace(current, **{'_default': update._default})
 #     return current

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema/parse.py

@@ -9,6 +9,8 @@ such as parameterized types, nested trees, merges (`|`), and unions (`~`).
 
 from parsimonious.grammar import Grammar
 from parsimonious.nodes import NodeVisitor
+from bigraph_schema.schema import Union, Tuple, Node
+from bigraph_schema.methods import handle_parameters
 
 # --- Example Expressions -----------------------------------------------------
 parameter_examples = {
@@ -122,6 +124,122 @@ class ParameterVisitor(NodeVisitor):
         return {'node': node, 'visit': visit}
 
 # --- API ---------------------------------------------------------------------
+class CoreVisitor(NodeVisitor):
+    """Visitor that converts parsed bigraph expressions into schema node structures.
+
+    Operates within a `Core` context, mapping grammar constructs
+    (unions, merges, type parameters, and defaults) into dataclass-based nodes.
+    Handles normalization of nested expressions (e.g. `tuple[int,float]`,
+    `link[a:int|b:string]`, `(x:y|z:w)`) into instances of `Union`, `Tuple`,
+    or structured dicts.
+    """
+
+    def __init__(self, operation):
+        """Initialize with the active `Core`."""
+        self.operation = operation
+
+    def visit_expression(self, node, visit):
+        """Top-level entry; returns first child."""
+        return visit[0]
+
+    def visit_union(self, node, visit):
+        """Parse `a~b~c` into a `Union(_options=[a,b,c])`."""
+        head = [visit[0]]
+        tail = [tree['visit'][1] for tree in visit[1]['visit']]
+        return Union(_options=head + tail)
+
+    def visit_merge(self, node, visit):
+        """Parse `a|b|c`; dicts merge to one mapping, others form a `Tuple`."""
+        head = [visit[0]]
+        tail = [tree['visit'][1] for tree in visit[1]['visit']]
+        nodes = head + tail
+        if all(isinstance(tree, dict) for tree in nodes):
+            merged = {}
+            for tree in nodes:
+                merged.update(tree)
+            return merged
+        else:
+            try:
+                values = tuple([int(x) for x in nodes])
+
+                return values
+            except Exception as e:
+                return Tuple(_values=nodes)
+
+    def visit_tree(self, node, visit):
+        """Delegate directly to nested element."""
+        return visit[0]
+
+    def visit_bigraph(self, node, visit):
+        """Alias for tree; allows recursion within nested bigraphs."""
+        return visit[0]
+
+    def visit_group(self, node, visit):
+        """Handle grouped subexpression `( ... )`; return tuple or dict."""
+        group_value = visit[1]
+        return group_value if isinstance(group_value, (list, tuple, dict, Tuple)) else (group_value,)
+
+    def visit_nest(self, node, visit):
+        """Handle `key:subtype` pairs (used in trees/maps).
+
+        The left side of the colon is a dict key — always a plain string,
+        not a resolved type.  We use the raw text from the parse node
+        rather than the visited (type-resolved) value, since key names
+        like ``process`` may collide with registered type names.
+        """
+        key = node.children[0].text
+        return {key: visit[2]}
+
+    def visit_type_name(self, node, visit):
+        """Resolve base type, parameters, and defaults into schema nodes."""
+        schema = visit[0]
+
+        # Parse parameter list
+        type_parameters = [
+            parameter
+            for parameter in visit[1]['visit']]
+
+        if type_parameters:
+            schema = handle_parameters(self.operation, schema, type_parameters[0])
+
+        # Parse default value `{...}`
+        default_visit = visit[2]['visit']
+        if default_visit:
+            default = default_visit[0]
+            if isinstance(schema, Node):
+                schema._default = default
+            elif isinstance(schema, dict):
+                schema['_default'] = default
+
+        return schema
+
+    def visit_parameter_list(self, node, visit):
+        """Return ordered list of parameters `[A,B,C]`."""
+        first = [visit[1]]
+        rest = [inner['visit'][1] for inner in visit[2]['visit']]
+        return first + rest
+
+    def visit_default_block(self, node, visit):
+        """Extract contents of `{...}` blocks."""
+        return visit[1]
+
+    def visit_default(self, node, visit):
+        """Return text inside default braces as string."""
+        return node.text
+
+    def visit_symbol(self, node, visit):
+        """Resolve bare symbol names via the operation registry or parse visitor."""
+        return self.operation.access(node.text)
+
+    def visit_nothing(self, node, visit):
+        """Handle empty productions (e.g., trailing commas)."""
+        return None
+
+    def generic_visit(self, node, visit):
+        """Fallback: return raw parse node and visited children."""
+        return {'node': node, 'visit': visit}
+
+
 def parsed_leftmost_leaf(parsed):
     if len(parsed.children) == 0:
         return parsed
@@ -170,7 +288,7 @@ def render_expression(expression):
     return str(expression)  # fallback for unknown structures
 
 # --- Debugging/Testing ---------------------------------------------------------
-def test_parse_parameters():
+def _demo_parse_parameters():
     """Test parsing and rendering for all example expressions."""
     for label, expr in parameter_examples.items():
         parsed = parse_expression(expr)
@@ -180,4 +298,4 @@ def test_parse_parameters():
             print(f'  Rendered: {render_expression(parsed)}')
 
 if __name__ == '__main__':
-    test_parse_parameters()
+    _demo_parse_parameters()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigraph-schema
-Version: 1.3.4
+Version: 1.4.2
 Summary: A serializable type schema for compositional systems biology
 Author: Eran Agmon, Ryan Spangler
 Requires-Python: >=3.9
@@ -9,7 +9,6 @@ License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: fire
 Requires-Dist: numpy
-Requires-Dist: orjson
 Requires-Dist: pandas
 Requires-Dist: parsimonious
 Requires-Dist: pint

{bigraph_schema-1.3.4 → bigraph_schema-1.4.2}/bigraph_schema.egg-info/requires.txt

@@ -1,6 +1,5 @@
 fire
 numpy
-orjson
 pandas
 parsimonious
 pint

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bigraph-schema"
-version = "1.3.4"
+version = "1.4.2"
 description = "A serializable type schema for compositional systems biology"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -15,7 +15,6 @@ authors = [
 dependencies = [
     "fire",
     "numpy",
-    "orjson",
     "pandas",
     "parsimonious",
     "pint",