bigraph-schema 0.0.71__py3-none-any.whl

bigraph_schema/__init__.py

@@ -0,0 +1,8 @@
+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.edge import Edge
+from bigraph_schema.type_system import TypeSystem
+from bigraph_schema.protocols import local_lookup_module
+from bigraph_schema.type_functions import FUNCTION_TYPE, METHOD_TYPE, type_schema_keys, resolve_path

bigraph_schema/edge.py

@@ -0,0 +1,129 @@
+"""
+====
+Edge
+====
+
+Base class for all edges in the bigraph schema.
+"""
+
+def default_wires(schema):
+    """
+    Create default wiring for a schema by connecting each port to a store of the same name.
+    """
+    return {
+        key: [key]
+        for key in schema}
+
+
+class Edge:
+    """
+    Base class for all computational edges in the bigraph schema.
+
+    Edges define the interface between simulation processes and the global state,
+    specifying the structure of input and output ports using bigraph types
+    (e.g., 'float', 'map[float]', 'list[integer]', etc.).
+
+    Upon instantiation, each edge registers its port types with the core.
+    """
+
+    config_schema = {}
+
+    def __init__(self, config=None, core=None):
+        """
+        Initialize the edge with a config and simulation core.
+
+        Args:
+            config (dict): Optional configuration dictionary. Defaults to empty dict.
+            core: The core simulation engine that manages this edge and its types.
+
+        Raises:
+            Exception: If `core` is not provided.
+        """
+        if core is None:
+            raise Exception('must provide a core')
+        self.core = core
+
+        if config is None:
+            config = {}
+
+        self._config = self.core.fill(self.config_schema, config)
+        self._composition = 'edge'
+        self._state = {}
+
+        self.initialize(self._config)
+
+    @property
+    def config(self):
+        return self._config
+
+    @config.setter
+    def config(self, config):
+        self._config = config
+
+    @property
+    def composition(self):
+        return self._composition
+
+    @composition.setter
+    def composition(self, composition):
+        self._composition = composition
+
+    @property
+    def state(self):
+        return self._state
+
+    @state.setter
+    def state(self, state):
+        self._state = state
+
+    def initialize(self, config):
+        """Optional hook for subclass-specific initialization."""
+        pass
+
+    def initial_state(self):
+        """Return initial state values, if applicable."""
+        return {}
+
+    @staticmethod
+    def generate_state(config=None):
+        """Generate static initial state for user configuration or inspection."""
+        return {}
+
+    def inputs(self):
+        """
+        Return a dictionary mapping input port names to bigraph types.
+
+        Example:
+            {'glucose': 'float', 'biomass': 'map[float]'}
+        """
+        return {}
+
+    def outputs(self):
+        """
+        Return a dictionary mapping output port names to bigraph types.
+
+        Example:
+            {'growth_rate': 'float'}
+        """
+        return {}
+
+    def default_inputs(self):
+        """Generate default wire paths for inputs: {port: [port]}"""
+        return default_wires(self.inputs())
+
+    def default_outputs(self):
+        """Generate default wire paths for outputs: {port: [port]}"""
+        return default_wires(self.outputs())
+
+    def interface(self):
+        """
+        Return combined interface schema as a dict:
+            {
+                'inputs': {port: type, ...},
+                'outputs': {port: type, ...}
+            }
+        """
+        return {
+            'inputs': self.inputs(),
+            'outputs': self.outputs()
+        }

bigraph_schema/parse.py

@@ -0,0 +1,165 @@
+"""
+======================
+Parse Bigraph Notation
+======================
+
+Parses and renders bigraph-style type expressions used in schema definitions,
+such as parameterized types, nested trees, merges (`|`), and unions (`~`).
+"""
+
+from parsimonious.grammar import Grammar
+from parsimonious.nodes import NodeVisitor
+
+# --- Example Expressions -----------------------------------------------------
+parameter_examples = {
+    'no-parameters': 'simple',
+    'one-parameter': 'parameterized[A]',
+    'three-parameters': 'parameterized[A,B,C]',
+    'nested-parameters': 'nested[outer[inner]]',
+    'multiple-nested-parameters': 'nested[outer[inner],other,later[on,there[is],more]]',
+    'bars': 'a|b|c|zzzz',
+    'union': 'a~b~c~zzzz',
+    'typed': 'a:field[yellow,tree,snake]|b:(x:earth|y:cloud|z:sky)',
+    'typed_parameters': 'edge[a:int|b:(x:length|y:float),v[zz:float|xx:what]]',
+    'inputs_and_outputs': 'edge[input1:float|input2:int,output1:float|output2:int]',
+    'tuple': 'what[is,happening|(with:yellow|this:green)|this:now]',
+    'single': 'hello[(3),over]',
+    'double': 'hello[(3|4),over]',
+    'units_type': 'length^2*mass/time^1_5',
+    'nothing': '()'}
+
+# --- Grammar -----------------------------------------------------------------
+parameter_grammar = Grammar(
+    """
+    expression = merge / union / tree / nothing
+    merge = tree (bar tree)+
+    union = tree (tilde tree)+
+    tree = bigraph / type_name
+    bigraph = group / nest
+    group = paren_left expression paren_right
+    nest = symbol colon tree
+    type_name = symbol parameter_list?
+    parameter_list = square_left expression (comma expression)* square_right
+    symbol = ~r"[\\w\\d-_/*&^%$#@!`+ ]+"
+    dot = "."
+    colon = ":"
+    bar = "|"
+    paren_left = "("
+    paren_right = ")"
+    square_left = "["
+    square_right = "]"
+    comma = ","
+    tilde = "~"
+    not_newline = ~r"[^\\n\\r]"*
+    newline = ~"[\\n\\r]+"
+    ws = ~r"\\s*"
+    nothing = ""
+    """)
+
+
+# --- Visitor -----------------------------------------------------------------
+class ParameterVisitor(NodeVisitor):
+    """Visitor that walks a parsed tree and builds structured type expressions."""
+
+    def visit_expression(self, node, visit):
+        return visit[0]
+
+    def visit_union(self, node, visit):
+        head = [visit[0]]
+        tail = [tree['visit'][1] for tree in visit[1]['visit']]
+        return {'_union': head + tail}
+
+    def visit_merge(self, node, visit):
+        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:
+            return tuple(nodes)
+
+    def visit_tree(self, node, visit):
+        return visit[0]
+
+    def visit_bigraph(self, node, visit):
+        return visit[0]
+
+    def visit_group(self, node, visit):
+        group_value = visit[1]
+        return group_value if isinstance(group_value, (list, tuple, dict)) else (group_value,)
+
+    def visit_nest(self, node, visit):
+        return {visit[0]: visit[2]}
+
+    def visit_type_name(self, node, visit):
+        type_name = visit[0]
+        type_parameters = visit[1]['visit']
+        if type_parameters:
+            return [type_name, type_parameters[0]]
+        return type_name
+
+    def visit_parameter_list(self, node, visit):
+        first = [visit[1]]
+        rest = [inner['visit'][1] for inner in visit[2]['visit']]
+        return first + rest
+
+    def visit_symbol(self, node, visit):
+        return node.text
+
+    def visit_nothing(self, node, visit):
+        return {}
+
+    def generic_visit(self, node, visit):
+        return {'node': node, 'visit': visit}
+
+# --- API ---------------------------------------------------------------------
+def parse_expression(expression):
+    """
+    Parse a bigraph-style type expression into a structured Python object.
+    """
+    parsed = parameter_grammar.parse(expression)
+    visitor = ParameterVisitor()
+    return visitor.visit(parsed)
+
+def is_type_expression(expression):
+    """
+    Return True if the expression is a parameterized type list.
+    """
+    return isinstance(expression, list) and len(expression) == 2 and isinstance(expression[1], list)
+
+def render_expression(expression):
+    """
+    Render a structured type expression back into a bigraph-style string.
+    """
+    if isinstance(expression, str):
+        return expression
+    elif isinstance(expression, list):
+        type_name, parameters = expression
+        inner = ','.join(render_expression(p) for p in parameters)
+        return f'{type_name}[{inner}]'
+    elif isinstance(expression, tuple):
+        return '(' + '|'.join(render_expression(e) for e in expression) + ')'
+    elif isinstance(expression, dict):
+        if '_union' in expression:
+            return '~'.join(render_expression(p) for p in expression['_union'])
+        else:
+            parts = [f'{k}:{render_expression(v)}' for k, v in expression.items()]
+            return f'({ "|".join(parts) })'
+    return str(expression)  # fallback for unknown structures
+
+# --- Debugging/Testing ---------------------------------------------------------
+def test_parse_parameters():
+    """Test parsing and rendering for all example expressions."""
+    for label, expr in parameter_examples.items():
+        parsed = parse_expression(expr)
+        print(f'{label}: {expr}')
+        if parsed:
+            print(f'  Parsed: {parsed}')
+            print(f'  Rendered: {render_expression(parsed)}')
+
+if __name__ == '__main__':
+    test_parse_parameters()

bigraph_schema/protocols.py

@@ -0,0 +1,35 @@
+"""
+=========
+Protocols
+=========
+
+This module contains the protocols for retrieving processes from address.
+"""
+
+import sys
+import inspect
+import importlib
+
+
+def function_module(function):
+    """
+    Retrieves the fully qualified name of a given function.
+    """
+    module = inspect.getmodule(function)
+
+    return f'{module.__name__}.{function.__name__}'
+
+
+def local_lookup_module(address):
+    """Local Module Protocol
+
+    Retrieves local module
+    """
+    if '.' in address:
+        module_name, class_name = address.rsplit('.', 1)
+        module = importlib.import_module(module_name)
+        return getattr(module, class_name)
+    else:
+        module = sys.modules[__name__]
+        if hasattr(module, address):
+            return getattr(sys.modules[__name__], address)

bigraph_schema/registry.py

@@ -0,0 +1,287 @@
+"""
+========
+Registry
+========
+
+Utilities for managing registry entries, hierarchical state structures,
+deep merging, and schema cleaning. Includes the `Registry` class for storing
+type declarations or functions by key.
+"""
+
+import inspect
+import copy
+import collections
+import traceback
+import functools
+import numpy as np
+import pytest
+from pprint import pformat as pf
+
+from bigraph_schema.protocols import local_lookup_module, function_module
+
+# --- Merge Utilities ---------------------------------------------------------
+
+def deep_merge_copy(dct, merge_dct):
+    """Return a deep copy of `dct` with `merge_dct` deeply merged into it."""
+    return deep_merge(copy.deepcopy(dct), merge_dct)
+
+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 validate_merge(state, dct, merge_dct):
+    """
+    Like `deep_merge`, but raises an exception if values conflict and are not in `state`.
+    """
+    dct = dct or {}
+    merge_dct = merge_dct or {}
+    state = state or {}
+
+    for k, v in merge_dct.items():
+        if (k in dct and isinstance(dct[k], dict)
+                and isinstance(v, collections.abc.Mapping)):
+            if k not in state:
+                state[k] = {}
+            validate_merge(state[k], dct[k], v)
+        else:
+            if k in state:
+                dct[k] = state[k]
+            elif k in dct and dct[k] != v:
+                raise Exception(f'cannot merge dicts at key "{k}":\n{dct}\n{merge_dct}')
+            else:
+                dct[k] = v
+    return dct
+
+# --- Tree Path Utilities -----------------------------------------------------
+
+def establish_path(tree, path, top=None, cursor=()):
+    """
+    Create or traverse a path in a nested dictionary (tree structure).
+    """
+    if tree is None:
+        tree = {}
+    if top is None:
+        top = tree
+    if path is None or len(path) == 0:
+        return tree
+    if isinstance(path, str):
+        path = (path,)
+    head = path[0]
+    if head == '..':
+        if len(cursor) == 0:
+            raise Exception(f'trying to travel above the top of the tree: {path}')
+        return establish_path(top, cursor[:-1])
+    if head not in tree:
+        tree[head] = {}
+    return establish_path(tree[head], path[1:], top=top, cursor=cursor + (head,))
+
+def set_path(tree, path, value, top=None, cursor=None):
+    """
+    Set `value` at the given `path` in a tree-like dictionary.
+    """
+    if value is None:
+        return None
+    if len(path) == 0:
+        return value
+    final = path[-1]
+    destination = establish_path(tree, path[:-1])
+    destination[final] = value
+    return tree
+
+def set_star_path(tree, path, value, top=None, cursor=()):
+    """
+    Set a value at a wildcard (`*`) path, filling in multiple keys.
+    """
+    if tree is None:
+        tree = {}
+    if top is None:
+        top = tree
+    if isinstance(path, str):
+        path = (path,)
+    if len(path) == 0:
+        return tree
+
+    head, tail = path[0], path[1:]
+    if head == '..':
+        if len(cursor) == 0:
+            raise Exception(f'trying to travel above the top of the tree: {path}')
+        return set_star_path(top, cursor[:-1], value)
+    elif head == '*':
+        for key in value:
+            tree[key] = set_star_path({}, tail, value[key], cursor=(key,))
+        return top
+    else:
+        if len(tail) == 0:
+            tree[head] = value
+        else:
+            if head not in tree:
+                tree[head] = {}
+            set_star_path(tree[head], tail, value, top=top, cursor=cursor + (head,))
+        return top
+
+def transform_path(tree, path, transform):
+    """
+    Apply a transformation function to a value at a specific path in a tree.
+    """
+    before = establish_path(tree, path)
+    after = transform(before)
+    return set_path(tree, path, after)
+
+def hierarchy_depth(hierarchy, path=()):
+    """
+    Recursively collect all node paths in a hierarchy.
+    """
+    base = {}
+    for key, inner in hierarchy.items():
+        down = path + (key,)
+        if is_schema_key(key):
+            base[path] = inner
+        elif isinstance(inner, dict) and 'instance' not in inner:
+            base.update(hierarchy_depth(inner, down))
+        else:
+            base[down] = inner
+    return base
+
+# --- Schema Tools ------------------------------------------------------------
+
+def remove_omitted(before, after, tree):
+    """
+    Remove keys from `tree` that exist in `before` but not in `after`.
+    """
+    if isinstance(before, dict):
+        if not isinstance(tree, dict):
+            raise Exception(f'trying to remove an entry from non-dict: {tree}')
+        if not isinstance(after, dict):
+            return after
+        for key, down in before.items():
+            if not key.startswith('_'):
+                if key not in after:
+                    tree.pop(key, None)
+                else:
+                    tree[key] = remove_omitted(down, after[key], tree[key])
+    return tree
+
+def is_schema_key(key):
+    """Check if a key is a schema key (starts with underscore)."""
+    return isinstance(key, str) and key.startswith('_')
+
+def non_schema_keys(schema):
+    """Return list of non-schema keys from a dictionary."""
+    return [k for k in schema if not is_schema_key(k)]
+
+def strip_schema_keys(state):
+    """
+    Recursively remove all schema keys from a dictionary.
+    """
+    if isinstance(state, dict):
+        return {k: strip_schema_keys(v) for k, v in state.items() if not is_schema_key(k)}
+    return state
+
+def type_parameter_key(schema, key):
+    """Check if a key is a special parameter override."""
+    return key.strip('_') not in schema.get('_type_parameters', []) and key.startswith('_')
+
+def default(type, default):
+    """Return a schema dictionary with a type and default."""
+    return {'_type': type, '_default': default}
+
+# --- Registry ----------------------------------------------------------------
+
+class Registry:
+    """
+    A registry for managing keyed objects or functions (e.g., schema types).
+
+    Supports registering items under multiple keys, deep merging for dicts,
+    and loading functions by string-qualified names.
+    """
+
+    def __init__(self, function_keys=None):
+        self.registry = {}
+        self.main_keys = set()
+        self.function_keys = set(function_keys or [])
+
+    def register(self, key, item, alternate_keys=(), strict=False):
+        """
+        Register an item under a key (and optional alternate keys).
+        Optionally enforce strict uniqueness.
+
+        If the item is a dict and already registered, a deep merge is attempted.
+        """
+        keys = [key] + list(alternate_keys)
+
+        for registry_key in keys:
+            if registry_key in self.registry:
+                if item != self.registry[registry_key]:
+                    if strict:
+                        raise Exception(
+                            f'Registry conflict for {registry_key}: {self.registry[registry_key]} vs {item}')
+                    elif isinstance(item, dict):
+                        self.registry[registry_key] = deep_merge(self.registry[registry_key], item)
+                    else:
+                        self.registry[registry_key] = item
+            else:
+                self.registry[registry_key] = item
+
+        self.main_keys.add(key)
+
+    def register_function(self, function):
+        """
+        Register a function by name or function object.
+
+        Returns:
+            (function_name, module_key)
+        """
+        if isinstance(function, str):
+            module_key = function
+            found = self.find(module_key) or local_lookup_module(module_key)
+            if found is None:
+                raise Exception(f'Function "{module_key}" not found for type data')
+        elif inspect.isfunction(function):
+            found = function
+            module_key = function_module(found)
+        else:
+            raise TypeError(f'Unsupported function type: {type(function)}')
+
+        function_name = module_key.split('.')[-1]
+        self.register(function_name, found)
+        self.register(module_key, found)
+
+        return function_name, module_key
+
+    def register_multiple(self, schemas, strict=False):
+        """Register multiple schemas from a dictionary of {key: item}."""
+        for key, schema in schemas.items():
+            self.register(key, schema, strict=strict)
+
+    def find(self, key):
+        """Retrieve an item from the registry by key (or None)."""
+        return self.registry.get(key)
+
+    def access(self, key):
+        """Alias for `find()`."""
+        return self.find(key)
+
+    def list(self):
+        """List all primary (non-alternate) keys in the registry."""
+        return list(self.main_keys)
+
+    def validate(self, item):
+        """Stub for validation logic (currently always True)."""
+        return True