bigraph-schema 1.0.0__py3-none-any.whl

bigraph_schema/schema.py

@@ -0,0 +1,370 @@
+from __future__ import annotations
+
+import typing
+import numpy as np
+import numpy.lib.format as nf
+import collections
+
+from plum import dispatch
+from dataclasses import dataclass, is_dataclass, field
+
+
+NONE_SYMBOL = '__nil__'
+
+
+@dataclass(kw_only=True)
+class Node():
+    _default: object = None
+
+@dataclass(kw_only=True)
+class Place(Node):
+    _subnodes: dict = field(default_factory=dict)
+
+@dataclass(kw_only=True)
+class Atom(Node):
+    pass
+
+@dataclass(kw_only=True)
+class Empty(Atom):
+    pass
+
+@dataclass(kw_only=True)
+class Union(Node):
+    _options: typing.Tuple[Node] = field(default_factory=tuple)
+
+@dataclass(kw_only=True)
+class Tuple(Node):
+    _values: typing.List[Node] = field(default_factory=list)
+
+@dataclass(kw_only=True)
+class Boolean(Atom):
+    pass
+
+@dataclass(kw_only=True)
+class Or(Boolean):
+    _default: bool = False
+
+@dataclass(kw_only=True)
+class And(Boolean):
+    _default: bool = True
+
+@dataclass(kw_only=True)
+class Xor(Boolean):
+    _default: bool = False
+
+@dataclass(kw_only=True)
+class Number(Atom):
+    pass
+
+@dataclass(kw_only=True)
+class Integer(Number):
+    pass
+
+@dataclass(kw_only=True)
+class Float(Number):
+    pass
+
+@dataclass(kw_only=True)
+class Complex(Float):
+    pass
+
+@dataclass(kw_only=True)
+class Delta(Float):
+    pass
+
+@dataclass(kw_only=True)
+class Nonnegative(Float):
+    pass
+
+@dataclass(kw_only=True)
+class NPRandom(Node):
+    state: Tuple() = field(default_factory=tuple)
+
+@dataclass(kw_only=True)
+class String(Atom):
+    pass
+
+@dataclass(kw_only=True)
+class Enum(String):
+    _values: typing.Tuple[str] = field(default_factory=tuple)
+
+@dataclass(kw_only=True)
+class Wrap(Node):
+    _value: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class Maybe(Wrap):
+    pass
+
+@dataclass(kw_only=True)
+class Overwrite(Wrap):
+    pass
+
+@dataclass(kw_only=True)
+class List(Node):
+    _element: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class Map(Node):
+    _key: Node = field(default_factory=String)
+    _value: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class Tree(Node):
+    _leaf: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class Array(Node):
+    _shape: typing.Tuple[int] = field(default_factory=tuple)
+    _data: np.dtype = field(default_factory=lambda:np.dtype('float64'))
+
+@dataclass(kw_only=True)
+class Path(List):
+    _element: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class Wires(Tree):
+    _leaf: Node = field(default_factory=Path)
+
+@dataclass(kw_only=True)
+class Schema(Tree):
+    _leaf: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class Protocol(Node):
+    protocol: String = field(default_factory=String)
+    data: Node = field(default_factory=Node)
+
+@dataclass(kw_only=True)
+class LocalProtocol(Protocol):
+    data: String = field(default_factory=String)
+
+@dataclass(kw_only=True)
+class Link(Node):
+    address: Protocol = field(default_factory=Protocol)
+    config: Node = field(default_factory=Node)
+    _inputs: dict = field(default_factory=dict)
+    _outputs: dict = field(default_factory=dict)
+    inputs: Wires = field(default_factory=Wires)
+    outputs: Wires = field(default_factory=Wires)
+
+# types for jumps in traversals
+
+@dataclass(kw_only=True)
+class Jump():
+    _value: object
+
+@dataclass(kw_only=True)
+class Key(Jump):
+    _value: str
+
+@dataclass(kw_only=True)
+class Index(Jump):
+    _value: int
+
+@dataclass(kw_only=True)
+class Slice(Jump):
+    _value: slice
+
+@dataclass(kw_only=True)
+class Star(Jump):
+    _value: str = '*'
+
+@dataclass(kw_only=True)
+class Match(Jump):
+    _match = str # regex
+
+def convert_jump(key):
+    if isinstance(key, Jump):
+        return key
+
+    convert_key = None
+    if isinstance(key, str):
+        if key == '*':
+            convert_key = Star(_value=key)
+        else:
+            convert_key = Key(_value=key)
+    elif isinstance(key, int):
+        convert_key = Index(_value=key)
+
+    return convert_key or Jump(_value=key)
+
+def resolve_path(path):
+    """
+    Given a path that includes '..' steps, resolve the path to a canonical form
+    """
+    resolve = []
+
+    for step in path:
+        if step == '..':
+            if len(resolve) == 0:
+                raise Exception(f'cannot go above the top in path: "{path}"')
+            else:
+                resolve = resolve[:-1]
+        else:
+            resolve.append(step)
+
+    return tuple(resolve)
+
+def deep_merge(dct, merge_dct):
+    """
+    Deep merge `merge_dct` into `dct`, modifying `dct` in-place.
+
+    Nested dictionaries are recursively merged.
+    """
+    if dct is None:
+        dct = {}
+    if merge_dct is None:
+        merge_dct = {}
+    if not isinstance(merge_dct, dict):
+        return merge_dct
+
+    for k, v in merge_dct.items():
+        if (k in dct and isinstance(dct[k], dict)
+                and isinstance(v, collections.abc.Mapping)):
+            deep_merge(dct[k], v)
+        else:
+            dct[k] = v
+    return dct
+
+def is_empty(value):
+    return value is None or value == {} or value == []
+
+def convert_path(path):
+    resolved = resolve_path(path)
+    return [
+        convert_jump(key)
+        for key in resolved]
+
+def blank_context(schema, state, path):
+    return {
+        'schema': schema,
+        'state': state,
+        'path': (),
+        'subpath': path}
+
+def walk_path(context, to, subpath=None):
+    return {
+        **context,
+        'path': context['path'] + (to,),
+        'subpath': subpath}
+
+def dtype_schema(dtype: np.dtype):
+    data = nf.dtype_to_descr(dtype)
+    if isinstance(data, str):
+        if 'f' in data or 'd' in data:
+            return Float()
+        elif 'U' in data:
+            return String()
+        elif 'i' in data or 'b' in data or 'h' in data:
+            return Integer()
+        elif 'F' in data or 'D' in data:
+            return Complex()
+    elif isinstance(data, list):
+        result = {}
+        for group in data:
+            key = group[0]
+            subschema = np.dtype(group[1])
+            if len(group) > 2:
+                shape = group[2]
+                subschema = Array(_shape=shape, _data=subschema)
+            result[key] = subschema
+
+        return result
+    else:
+        raise Exception('do not know how to interpret dtype as schema:\n\n{dtype}\n\n')
+    
+
+def make_default(schema, state):
+    return {
+        '_type': schema,
+        '_default': state}
+
+
+@dispatch
+def schema_dtype(schema: Complex):
+    return np.dtype('complex128')
+
+@dispatch
+def schema_dtype(schema: Float):
+    return np.dtype('float64')
+
+@dispatch
+def schema_dtype(schema: Integer):
+    return np.dtype('int32')
+
+@dispatch
+def schema_dtype(schema: Boolean):
+    return np.dtype('bool')
+
+@dispatch
+def schema_dtype(schema: String):
+    return np.dtype('unicode')
+
+@dispatch
+def schema_dtype(schema: str):
+    return np.dtype(schema)
+
+@dispatch
+def schema_dtype(schema: list):
+    return np.dtype(schema)
+
+@dispatch
+def schema_dtype(schema: dict):
+    result = []
+    if not schema:
+        return None
+
+    for key, value in schema.items():
+        subschema = schema_dtype(value)
+        subresult = (key, subschema)
+        if isinstance(subschema, Array):
+            subshape = subschema._shape
+            subresult = subresult + (subshape,)
+
+        result.append(subresult)
+
+    if all([isinstance(key, int) for key in schema.keys()]):
+        shape = max(schema.keys())
+        return Array(_shape=(shape,), _data=result[0][1])
+    else:
+        return np.dtype(result)
+
+@dispatch
+def schema_dtype(schema):
+    raise Exception(f'schema dtype not implemented for:\n\n{schema}\n\n')
+    
+
+BASE_TYPES = {
+    'node': Node,
+    'atom': Atom,
+    'empty': Empty,
+    'union': Union,
+    'tuple': Tuple,
+    'boolean': Boolean,
+    'or': Or,
+    'and': And,
+    'xor': Xor,
+    'number': Number,
+    'integer': Integer,
+    'float': Float,
+    'delta': Delta,
+    'nonnegative': Nonnegative,
+    'random_state': NPRandom,
+    'string': String,
+    'enum': Enum,
+    'wrap': Wrap,
+    'maybe': Maybe,
+    'overwrite': Overwrite,
+    'list': List,
+    'map': Map,
+    'tree': Tree,
+    'array': Array,
+    'path': Path,
+    'wires': Wires,
+    'protocol': Protocol,
+    'local': LocalProtocol,
+    'schema': Schema,
+    'link': Link}
+
+

bigraph_schema/units.py

@@ -0,0 +1,133 @@
+"""
+=====
+Units
+=====
+
+Register all of the unit types from the pint unit registry
+"""
+
+from pint import UnitRegistry
+
+
+units = UnitRegistry()
+
+
+def render_coefficient(original_power):
+    power = abs(original_power)
+    int_part = int(power)
+    root_part = power % 1
+
+    if root_part != 0.0:
+        render = str(root_part)[2:]
+        render = f'{int_part}_{render}'
+    else:
+        render = str(int_part)
+
+    return render
+
+
+def render_units_type(dimensionality):
+    unit_keys = list(dimensionality.keys())
+    unit_keys.sort()
+
+    numerator = []
+    denominator = []
+
+    for unit_key in unit_keys:
+        inner_key = unit_key.strip('[]')
+        power = dimensionality[unit_key]
+        negative = False
+        
+        if power < 0:
+            negative = True
+            power = -power
+
+        if power == 1:
+            render = inner_key
+        else:
+            render = f'{inner_key}^{render_coefficient(power)}'
+
+        if negative:
+            denominator.append(render)
+        else:
+            numerator.append(render)
+
+    render = '*'.join(numerator)
+    if len(denominator) > 0:
+        render_denominator = '*'.join(denominator)
+        render = f'{render}/{render_denominator}'
+
+    return render
+
+
+def parse_coefficient(s):
+    if s is None:
+        return 1
+    elif '_' in s:
+        parts = s.split('_')
+        if len(parts) > 1:
+            base, residue = parts
+            return int(base) + (float(residue) / 10.0)
+        else:
+            return int(parts)
+    else:
+        return int(s)
+
+
+def parse_dimensionality(s):
+    numerator, denominator = s.split('/')
+    numerator_terms = numerator.split('*')
+    denominator_terms = denominator.split('*')
+
+    dimensionality = {}
+
+    for term in numerator_terms:
+        base = term.split('^')
+        exponent = None
+        if len(base) > 1:
+            exponent = base[1]
+        dimensionality[f'[{base[0]}]'] = parse_coefficient(exponent)
+
+    for term in denominator_terms:
+        power = term.split('^')
+        exponent = None
+        if len(power) > 1:
+            exponent = power[1]
+        dimensionality[f'[{power[0]}]'] = -parse_coefficient(exponent)
+
+    return dimensionality
+
+
+def test_units_render():
+    dimensionality = units.newton.dimensionality
+    render = render_units_type(dimensionality)
+    recover = parse_dimensionality(render)
+
+    print(f'original: {dimensionality}')
+    print(f'render: {render}')
+    print(f'parsed: {recover}')
+
+    assert render == 'length*mass/time^2'
+    assert recover == dimensionality
+
+
+def test_roots_cycle():
+    dimensionality = {
+        '[length]': 1.5,
+        '[time]': 3,
+        '[mass]': -2.5,
+    }
+    render = render_units_type(dimensionality)
+    recover = parse_dimensionality(render)
+
+    print(f'original: {dimensionality}')
+    print(f'render: {render}')
+    print(f'parsed: {recover}')
+
+    assert render == 'length^1_5*time^3/mass^2_5'
+    assert recover == dimensionality
+
+
+if __name__ == '__main__':
+    test_units_render()
+    test_roots_cycle()

bigraph_schema-1.0.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: bigraph-schema
+Version: 1.0.0
+Summary: A serializable type schema for compositional systems biology
+Author: Eran Agmon, Ryan Spangler
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: fire
+Requires-Dist: numpy
+Requires-Dist: orjson
+Requires-Dist: parsimonious
+Requires-Dist: pint
+Requires-Dist: plum-dispatch
+Requires-Dist: pytest
+Requires-Dist: ipdb
+Requires-Dist: requests>=2.31.0
+Requires-Dist: setuptools
+Requires-Dist: twine>=4.0.2
+Dynamic: license-file
+
+# Bigraph-Schema
+
+[![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)
+
+`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.
+
+The library offers a unified interface for representing, validating, and transforming schemas and data in structured simulations.  
+By standardizing schema definitions, it enables interoperability between models, extensibility across frameworks, and reproducibility of computational experiments.
+
+---
+
+## Installation
+
+Install directly from PyPI:
+
+```console
+pip install bigraph-schema
+```
+---
+
+## Getting Started
+
+The following resources provide guided introductions and examples:
+
+- [Type System Overview](https://vivarium-collective.github.io/bigraph-schema/notebooks/core.html) – Demonstrates how to use the `Core` API for schema inference, normalization, and serialization.
+
+- [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.
+
+
+---
+
+## Related Projects
+
+- [Vivarium](https://vivarium-collective.github.io/) – a compositional framework for hybrid biological simulations.  
+- [Bigraph-Viz](https://vivarium-collective.github.io/bigraph-viz/) – visualization tools for bigraph-schema models.  
+- [Process-Bigraph](https://github.com/vivarium-collective/process-bigraph) – process composition and orchestration built on bigraph-schema.
+
+---
+
+## License
+
+`bigraph-schema` is open-source software released under the [Apache 2.0 License](https://github.com/vivarium-collective/bigraph-schema/blob/main/LICENSE).

bigraph_schema-1.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+bigraph_schema/__init__.py,sha256=Sbrb4L_RpeuJVuGMbmHVk1pTNE4ucM7qbKxBrdp3nd4,3394
+bigraph_schema/core.py,sha256=l-0jkPiJzxejIjJHTgLYymx2iNqayXXhzImRNN_9Yyk,25453
+bigraph_schema/edge.py,sha256=oEwOQg0-mzZ08JElwT8x2cYmW_IXc9BNO5nG0YWYMyA,3421
+bigraph_schema/parse.py,sha256=EByTwL6d0wrDSSO0mfevHKLtxmBPL9IrtLVP2n3lUaY,6246
+bigraph_schema/protocols.py,sha256=rfJ1-yhtfHwcB3yUdKwQDiamXPpoUWztnTzU2-LB74k,1280
+bigraph_schema/schema.py,sha256=NYAWmWTywcVfdW5V_MW_Lb2C8khs-5EoMeXmsBNAcUg,8178
+bigraph_schema/units.py,sha256=PaeqYpCot3eFfZdOUoGqhZjobONpgjc8zxFNNSKg0e4,3020
+bigraph_schema/methods/__init__.py,sha256=RA7YIIQ8EZeCDXFz6Krtz0SggLAZAZCfvI79UmqAQew,790
+bigraph_schema/methods/apply.py,sha256=-R53tfGuMJMciyrBMy7yxiFNy2FzcUeMunzzRRB152Y,6353
+bigraph_schema/methods/check.py,sha256=tj9hj4N_SIjAxq7XMhuPw1K4BxFitHhWWRgi4lefOTk,4231
+bigraph_schema/methods/default.py,sha256=devfn9BnyFjJmpD82FwFcS1bbBA1aak1xroHs6zqTQo,4277
+bigraph_schema/methods/generalize.py,sha256=iYMkr2qxeg7KdWmMWMigldEgH3k9HPJDhNAqr8xkWwE,7879
+bigraph_schema/methods/handle_parameters.py,sha256=hietX6HuasA10SIwQNRqbXirJtT7Zry3Gn71OTJrz_4,4476
+bigraph_schema/methods/infer.py,sha256=d04C7wjIpsObRtjl1jvu7sJoFl1DlH1Ho4_T7HRiSJw,5322
+bigraph_schema/methods/jump.py,sha256=woc7QqtBy23zHOhWFK2CR1YPikS3d_lTvNWIkMiiHiE,10455
+bigraph_schema/methods/merge.py,sha256=2eiR098Ye0NATNIKqNyEnTM7xr0euTBvJFrNIn_KbRQ,10160
+bigraph_schema/methods/realize.py,sha256=MD63Rotc_KDMQCXdwkJA-TOYMkFjOdP8ArfaPLRMuHk,15206
+bigraph_schema/methods/resolve.py,sha256=jHtDpO6EOOzEPRD2VkbGAExSwq7foAVmlPT81zwwhCY,19655
+bigraph_schema/methods/serialize.py,sha256=cOs7b1_c2wTYQk0Fvn_3TjuXupCV3E3ZGQ5ZWopsPOY,12649
+bigraph_schema/methods/validate.py,sha256=XS0bFTQ3GHryI4hLCmQgnI2zdP5yro1wI8rZ45SO_EI,7382
+bigraph_schema/package/__init__.py,sha256=bx_9iGPudkTuaLQOBxQlw-H8NQ8VZSbONNM-BGYJJTI,62
+bigraph_schema/package/discover.py,sha256=dCQBGcsYvpM5FXyU6EHqD8_w68LcRZk0eGZ3EVXCGQU,3599
+bigraph_schema-1.0.0.dist-info/licenses/AUTHORS.md,sha256=1ndh21uie4wWDB9qYiNofzTjITFC_ZSrP_HqFImvcdo,142
+bigraph_schema-1.0.0.dist-info/licenses/LICENSE,sha256=sF9SV-O54AFkJTMLiJaQw0Ngd4QC7nAkzLV3QBIYnC0,11358
+bigraph_schema-1.0.0.dist-info/METADATA,sha256=vKJdFUgYvBElE47USnAcsWCXz_9N3DADmCqf1uaHlf0,2558
+bigraph_schema-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bigraph_schema-1.0.0.dist-info/top_level.txt,sha256=zce6hZ5UdrtyAiwHWgN62ErKNHqbuEEL6eadbSvLu6g,15
+bigraph_schema-1.0.0.dist-info/RECORD,,

bigraph_schema-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bigraph_schema-1.0.0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,6 @@
+# Authors of Bigraph Schema
+
+The maintainers of the Bigraph-Schema project are:
+
+* Ryan Spangler (@prismofeverything)
+* Eran Agmon  (@eagmon)