pyBondGraph 0.1.0__tar.gz → 0.2.0__tar.gz

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.1.0
+Version: 0.2.0
 Summary: Modelling tool for linear bond graph systems in Python
 Author-email: Matthias Panny <matthias.panny@mci.edu>
 License-Expression: CC-BY-NC-SA-4.0
@@ -44,12 +44,15 @@ Bond graphs provide a **domain-independent modeling framework** for physical sys
 
 # Installation
 
-## Install directly from GitHub
-The easiest way to install the library is directly via pip:
+## Install from PyPI or Github
+The easiest way to install the library is via your preferred package manager (e.g. pip) directly from PyPI:
+```bash
+pip install pyBondGraph
+```
+Alternatively one can install the latest development version directly from the GitHub repository:
 ```bash
 pip install git+https://github.com/MrP123/pyBondGraph.git
 ```
-This installs the latest version of the package from the repository.
 
 ---
 

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/README.md

@@ -18,12 +18,15 @@ Bond graphs provide a **domain-independent modeling framework** for physical sys
 
 # Installation
 
-## Install directly from GitHub
-The easiest way to install the library is directly via pip:
+## Install from PyPI or Github
+The easiest way to install the library is via your preferred package manager (e.g. pip) directly from PyPI:
+```bash
+pip install pyBondGraph
+```
+Alternatively one can install the latest development version directly from the GitHub repository:
 ```bash
 pip install git+https://github.com/MrP123/pyBondGraph.git
 ```
-This installs the latest version of the package from the repository.
 
 ---
 

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/pyBondGraph/__init__.py

@@ -14,6 +14,8 @@ from .elements import (
     Gyrator,
 )
 from .sensors import IntegratedEffortSensor, IntegratedFlowSensor
+from .subbondgraph import SubBondGraph
+from .core import Port  # type alias: dict[str, Node]
 
 from .bondgraph import BondGraph
 
@@ -35,4 +37,6 @@ __all__ = [
     "BondGraph",
     "IntegratedEffortSensor",
     "IntegratedFlowSensor",
+    "Port",
+    "SubBondGraph",
 ]

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/pyBondGraph/bondgraph.py

@@ -1,9 +1,14 @@
+from __future__ import annotations
+
 import sympy as sp
 import networkx as nx
 import numpy as np
+
+from matplotlib.lines import Line2D
 import matplotlib.pyplot as plt
 
 from collections.abc import Callable
+from typing import TYPE_CHECKING
 
 from .core import (
     Causality,
@@ -16,19 +21,30 @@ from .core import (
 )
 from .elements import SourceEffort, SourceFlow, OneJunction, ZeroJunction
 
+from .core import Port
+
+if TYPE_CHECKING:
+    from .subbondgraph import SubBondGraph
+
 type SolutionType = dict[sp.Expr, sp.Expr]
 
 
 class BondGraph:
     """Represents a bond graph consisting of elements and the bonds that connect them."""
 
-    def __init__(self):
-        """Initializes a new bond graph without any elements or bonds."""
+    def __init__(self, name: str = ""):
+        """Initializes a new bond graph without any elements or bonds.
 
-        Bond.counter = 0  # Reset bond counter for future bond graphs after solution has been computed --> ToDo: fix this hacky solution
+        Parameters
+        ----------
+        name : str, optional
+            Name of the bond graph. Used as namespace prefix when merging sub-models.
+        """
 
-        self.elements = []
+        self.name = name
+        self.elements: list[Node] = []
         self.bonds: list[Bond] = []
+        self._bond_counter = 0  # Instance-scoped bond counter
 
         self.state_vars: list[sp.Expr] = []
         self.equations: list[sp.Expr] = []
@@ -56,6 +72,14 @@ class BondGraph:
         if bond in self.bonds:
             raise ValueError(f"Bond {bond} is already part of the bond graph.")
 
+        # Renumber the bond using the instance-scoped counter to avoid collisions
+        subs = bond.rename_symbols(new_num=self._bond_counter)
+        self._bond_counter += 1
+
+        # Propagate renamed symbols into any equations that already reference the old symbols
+        # (relevant when merging sub-models whose equations were built with different numbering)
+        self.equations = [eq.subs(subs) for eq in self.equations]
+
         self.bonds.append(bond)
 
         for element in bond.elements:
@@ -160,8 +184,6 @@ class BondGraph:
     def get_solution_equations(self) -> SolutionType:
         """Returns the symbolic equations defining the solution of the bond graph.
         The solution is computed by solving the accumulated equations of the bond graph symbolically using `sympy.solve`.
-        The bond counter is reset after computation to allow for future bond graphs to be created without conflicts.
-        This is a temporary workaround and should be (urgently) improved in the future.
 
         Returns
         -------
@@ -172,8 +194,6 @@ class BondGraph:
 
         self.__handle_bonds()
         self.__handle_equations()
-        Bond.counter = 0  # Reset bond counter for future bond graphs after solution has been computed --> ToDo: fix this hacky solution
-
         state_derivatives = [sp.Derivative(var, "t") for var in self.state_vars]
         self.solution = sp.solve(
             self.equations,
@@ -255,6 +275,93 @@ class BondGraph:
 
         return A, B, C, D, sp.Matrix(self.state_vars), n_states, n_inputs, n_outputs
 
+    def add_subbondgraph(self, sub_bondgraph: SubBondGraph, instance_name: str | None = None, is_prefix: bool = True) -> Port:
+        """Instantiate a SubBondGraph into this bond graph.
+
+        Deep-copies all elements and bonds from the sub-model with
+        namespace prefixing, merges them into this graph, and returns
+        the instantiated ports for subsequent ``connect()`` calls.
+
+        Parameters
+        ----------
+        sub_bondgraph : SubBondGraph
+            The sub-model to instantiate.
+        instance_name : str | None, optional
+            Override the namespace prefix.  Defaults to the sub-model's name.
+        is_prefix : bool, optional
+            Whether to use the instance name as a prefix or suffix for the copied elements.  Defaults to True.
+
+        Returns
+        -------
+        Port
+            Mapping of port names to new Node objects belonging
+            to this graph.
+        """
+        return sub_bondgraph._instantiate(self, instance_name, is_prefix)
+
+    def connect(
+        self,
+        node_a: Node,
+        node_b: Node,
+        causality: Causality = Causality.EFFORT_OUT,
+    ) -> Bond:
+        """Connect two nodes by adding a bond between them.
+
+        Also used after :meth:`add_subbondgraph` to wire up the
+        returned port nodes — but any :class:`Node` already in the
+        graph (or about to be added) works.
+
+        ``node_a`` becomes the bond's ``from_element`` and ``node_b``
+        the ``to_element`` — just like the positional convention of
+        the :class:`Bond` constructor.  For two-port elements
+        (:class:`Transformer`, :class:`Gyrator`) the existing
+        ``__handle_bonds`` logic uses this direction to assign
+        ``bond1`` (to_element) vs ``bond2`` (from_element), so no
+        extra ``side`` parameter is needed::
+
+            # Bond INTO gyrator → bond1 (primary)
+            system.connect(junction_node, gyrator, causality)
+
+            # Bond FROM gyrator → bond2 (secondary)
+            system.connect(gyrator, junction_node, causality)
+
+        Parameters
+        ----------
+        node_a : Node
+            Source — becomes ``from_element`` of the new bond.
+        node_b : Node
+            Destination — becomes ``to_element`` of the new bond.
+        causality : Causality, optional
+            Causality of the connecting bond.  Defaults to
+            ``Causality.EFFORT_OUT``.
+
+        Returns
+        -------
+        Bond
+            The newly created connecting bond.
+
+        Raises
+        ------
+        TypeError
+            If an argument is not a Node.
+        """
+        if not isinstance(node_a, Node):
+            raise TypeError(
+                f"node_a must be a Node, got {type(node_a).__name__}"
+            )
+        if not isinstance(node_b, Node):
+            raise TypeError(
+                f"node_b must be a Node, got {type(node_b).__name__}"
+            )
+
+        bond = Bond(
+            from_element=node_a,
+            to_element=node_b,
+            causality=causality,
+        )
+        self.add_bond(bond)
+        return bond
+
     def plot(self, layout: Callable[[nx.Graph, ...], dict] = nx.spectral_layout, **kwargs) -> tuple[plt.Figure, plt.Axes]:
         """Plots the bond graph as a `networkx` graph.
 
@@ -269,6 +376,7 @@ class BondGraph:
         -------
         tuple[plt.Figure, plt.Axes]
             Matplotlib Figure and axes objects for the plot.
+            
         Raises
         ------
         ValueError
@@ -286,19 +394,25 @@ class BondGraph:
                 bond.to_element.name,
                 label=bond.num,
                 causality=bond.causality,
+                bond=bond,
             )
 
-        # https://networkx.org/documentation/stable/auto_examples/graph/plot_dag_layout.html
-        if nx.is_directed_acyclic_graph(G):
-            for layer, nodes in enumerate(nx.topological_generations(G)):
-                # `multipartite_layout` expects the layer as a node attribute, so add the
-                # numeric layer value as a node attribute
-                for node in nodes:
-                    G.nodes[node]["layer"] = layer
-
-            pos = nx.multipartite_layout(G, subset_key="layer")
-        else:
-            pos = layout(G, **kwargs)
+        # Try Graphviz 'dot' layout first — it minimises edge crossings
+        # and produces clean left-to-right hierarchical layouts.
+        try:
+            pos = nx.drawing.nx_agraph.graphviz_layout(
+                G, prog="dot",
+                args='-Grankdir=LR -Gnodesep=0.8 -Granksep=1.2 -Gordering=out'
+            )
+        except (ImportError, Exception):
+            # Fall back to the previous layout strategy
+            if nx.is_directed_acyclic_graph(G):
+                for layer, nodes in enumerate(nx.topological_generations(G)):
+                    for node in nodes:
+                        G.nodes[node]["layer"] = layer
+                pos = nx.multipartite_layout(G, subset_key="layer")
+            else:
+                pos = layout(G, **kwargs)
 
         fig, ax = plt.subplots(figsize=(10, 8))
         ax.set_axis_off()
@@ -313,13 +427,20 @@ class BondGraph:
             font_color="black",
             arrows=True,
         )
-        nx.draw_networkx_edge_labels(
-            G,
-            pos,
-            edge_labels=nx.get_edge_attributes(G, "label"),
-            font_size=8,
-            ax=ax,
-        )
+        # Draw bond-number labels at varied positions along each edge so
+        # that crossing bonds don't produce overlapping text.
+        for edge_idx, (u, v, data) in enumerate(G.edges(data=True)):
+            x1, y1 = pos[u]
+            x2, y2 = pos[v]
+            # Vary the parameter t ∈ [0.35, 0.65] per edge
+            t = 0.35 + 0.3 * ((edge_idx * 7 + 3) % 11) / 10.0
+            lx = x1 + t * (x2 - x1)
+            ly = y1 + t * (y2 - y1)
+            ax.text(
+                lx, ly, str(data.get("label", "")),
+                fontsize=8, ha="center", va="center",
+                bbox=dict(boxstyle="round,pad=0.15", fc="white", ec="none", alpha=0.8),
+            )
 
         # Function to add a perpendicular line
         def draw_causal_stroke(ax, p1, p2, at="head", length=20, node_size=2000, padding=2):
@@ -385,15 +506,34 @@ class BondGraph:
 
             ax.plot([p_start[0], p_end[0]], [p_start[1], p_end[1]], color="k", lw=1.0)
 
-        # Add perpendicular lines to edges
+        # Collect causal-stroke specs so they can be redrawn on resize.
+        # One entry per bond
+        _stroke_specs: list[tuple] = []
         for u, v, data in G.edges(data=True):
             causality = data.get("causality", None)
-
             if causality is Causality.EFFORT_OUT:
-                draw_causal_stroke(ax, pos[u], pos[v], at="head", padding=-2)
+                _stroke_specs.append((pos[u], pos[v], "head", -2))
             elif causality is Causality.FLOW_OUT:
-                draw_causal_stroke(ax, pos[u], pos[v], at="tail", padding=-2)
+                _stroke_specs.append((pos[u], pos[v], "tail", -2))
             else:
                 raise ValueError(f"Edge {u}->{v} has no valid causality: {causality} --> this should never happen!")
 
+        _stroke_artists: list[Line2D] = []
+
+        def _refresh_strokes(event=None):
+            """Recompute causal strokes in current display coords."""
+
+            for a in _stroke_artists:
+                a.remove() #removes artist (Line2D) from axes
+            _stroke_artists.clear()
+
+            for p1, p2, at, padding in _stroke_specs:
+                draw_causal_stroke(ax, p1, p2, at=at, padding=padding)
+
+            # Newly created Line2D artists are the last len(_stroke_specs) items (i.e. # of bonds lines) on ax.lines --> store to remove later
+            _stroke_artists.extend(ax.lines[-len(_stroke_specs):])
+
+        _refresh_strokes()                                    # initial draw
+        fig.canvas.mpl_connect("resize_event", _refresh_strokes)  # stay correct on resize
+
         return fig, ax

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/pyBondGraph/core.py

@@ -49,9 +49,9 @@ class Node(ABC):
 class Bond:
     """Represents a bond between two elements in the bond graph."""
 
-    counter = 0
+    _counter = 0  # Global fallback counter; prefer BondGraph-scoped numbering
 
-    def __init__(self, from_element: Node, to_element: Node, causality: str | Causality):
+    def __init__(self, from_element: Node, to_element: Node, causality: str | Causality, num: int | None = None, instance_name: str = "", is_prefix: bool = True):
         """Create a bond between two elements with specified causality.
         The positive direction of this power bond is from `from_element` to `to_element`.
         Efforts and flows are represented by symbolic `sympy.Symbol`s that are strictly real-valued.
@@ -70,6 +70,14 @@ class Bond:
             `OneJunction` imposes effort on the `Inductor`, meaning it has an equivalent `effort_in` causality.
             Likewise a `Bond(OneJunction(...), Capacitor(...), "flow_out")` means that the `OneJunction` imposes
             flow on the `Capacitor`, meaning it has an equivalent `flow_in`/`effort_out` causality.
+        num : int | None, optional
+            Explicit bond number. If None, the global fallback counter is used.
+            When bonds are added to a BondGraph, the graph manages numbering.
+        instance_name : str, optional
+            Instance name for symbol names (e.g. "Motor_"). Used when merging sub-models
+            to avoid symbol collisions.
+        is_prefix : bool, optional
+            Whether to use the instance name as a prefix or suffix. Defaults to True.
 
         Raises
         ------
@@ -86,17 +94,64 @@ class Bond:
 
         self.causality: Causality = causality
 
-        self.num = Bond.counter
-        Bond.counter += 1
+        if num is None:
+            self.num = Bond._counter
+            Bond._counter += 1
+        else:
+            self.num = num
 
-        self.effort = sp.Symbol(f"e_{self.num}", real=True)
-        self.flow = sp.Symbol(f"f_{self.num}", real=True)
+        self.instance_name = instance_name
+
+        if is_prefix:
+            self.effort = sp.Symbol(f"e_{self.instance_name}{self.num}", real=True)
+            self.flow = sp.Symbol(f"f_{self.instance_name}{self.num}", real=True)
+        else:
+            self.effort = sp.Symbol(f"e_{self.num}_{self.instance_name}", real=True)
+            self.flow = sp.Symbol(f"f_{self.num}_{self.instance_name}", real=True)
 
     @property
     def elements(self) -> tuple[Node, Node]:
         """tuple[Node, Node]: The two elements connected by the bond. First element is `from_element`, second is `to_element`."""
         return (self.from_element, self.to_element)
 
+    def rename_symbols(self, new_num: int | None = None, new_instance_name: str | None = None, is_prefix: bool = True) -> dict[sp.Symbol, sp.Symbol]:
+        """Rename the effort/flow symbols of this bond and return the substitution map.
+        This is used during sub-model merging to avoid symbol collisions.
+
+        Parameters
+        ----------
+        new_num : int | None, optional
+            New bond number. If None, keeps the current number.
+        new_instance_name : str | None, optional
+            New instance name. If None, keeps the current instance name.
+        is_prefix : bool, optional
+            Whether to use the instance name as a prefix or suffix. Defaults to True.
+
+        Returns
+        -------
+        dict[sp.Symbol, sp.Symbol]
+            Mapping from old symbols to new symbols, for use with `sp.Expr.subs()`.
+        """
+        old_effort = self.effort
+        old_flow = self.flow
+
+        if new_num is not None:
+            self.num = new_num
+        if new_instance_name is not None:
+            self.instance_name = new_instance_name
+
+
+        if is_prefix:
+            padded_name = "_" + self.instance_name + "_" if self.instance_name != "" else "_"
+            self.effort = sp.Symbol(f"e{padded_name}{self.num}", real=True)
+            self.flow = sp.Symbol(f"f{padded_name}{self.num}", real=True)
+        else:
+            padded_name = self.instance_name if self.instance_name != "" else "" # conditional can be skipped            
+            self.effort = sp.Symbol(f"e_{self.num}{padded_name}", real=True)
+            self.flow = sp.Symbol(f"f_{self.num}{padded_name}", real=True)
+
+        return {old_effort: self.effort, old_flow: self.flow}
+
     def __repr__(self) -> str:
         return f"Bond(from={self.from_element}, to={self.to_element}, causality={self.causality})"
 
@@ -186,3 +241,7 @@ class ElementTwoPort(Node, ABC):
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(name = {self.name}, value = {self.value})"
+
+
+# Type alias — a port mapping is simply {name: node, ...}.
+type Port = dict[str, Node]

pybondgraph-0.2.0/pyBondGraph/subbondgraph.py

@@ -0,0 +1,315 @@
+"""SubBondGraph — a reusable, connectable sub-model.
+
+A SubBondGraph wraps a BondGraph together with named ports.
+It can be instantiated (deep-copied with namespace prefixing) into
+a parent BondGraph, and two sub-models can be connected at their
+ports via a new bond.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import sympy as sp
+
+if TYPE_CHECKING:
+    from .bondgraph import BondGraph
+
+from .core import (
+    Bond,
+    Causality,
+    Node,
+    Junction,
+    ElementOnePort,
+    ElementTwoPort,
+    StatefulElement,
+)
+from .core import Port
+
+
+class SubBondGraph:
+    """A reusable bond-graph sub-model with named connection ports.
+
+    Parameters
+    ----------
+    name : str
+        Unique name for this sub-model.  Used as namespace prefix
+        when the sub-model is instantiated into a parent graph
+        (e.g. ``"Motor"`` produces symbols like ``e_Motor_0``).
+    bondgraph : BondGraph
+        The internal bond graph that defines this sub-model's
+        physics.
+    ports : dict[str, Node]
+        Named mapping of port names to boundary :class:`Node` objects
+        (e.g. ``{"in": j1_mech, "out": gyrator}``).  The type alias
+        :data:`Port` is provided for convenience.
+    """
+
+    def __init__(self, name: str, bondgraph: BondGraph, ports: Port):
+        self.name = name
+        self.bondgraph = bondgraph
+        self.ports = ports
+
+        # Validate that every port node is actually in the bondgraph
+        bg_elements = set(bondgraph.elements)
+        for port_name, node in ports.items():
+            if node not in bg_elements:
+                raise ValueError(
+                    f"Port '{port_name}' references node "
+                    f"{node} which is not in the bond graph."
+                )
+
+    # ------------------------------------------------------------------
+    # Instantiation (deep-copy with namespace prefixing)
+    # ------------------------------------------------------------------
+
+    def _instantiate(self, parent_bondgraph: BondGraph, instance_name: str | None = None, is_prefix: bool = True) -> Port:
+        """Create a namespace-prefixed copy and merge it into *parent_bondgraph*.
+
+        .. note::
+            This is an internal method.  Prefer
+            :meth:`BondGraph.add_subbondgraph` which delegates here
+            and provides a cleaner, graph-centric API::
+
+                ports = system.add_subbondgraph(sub, "inst1")
+
+        Every element and bond is deep-copied.  Element names and bond
+        symbols are prefixed with ``instance_name + "_"`` so that
+        multiple instances of the same sub-model can coexist without
+        symbol collisions.
+
+        Parameters
+        ----------
+        parent_bondgraph : BondGraph
+            The parent graph to merge into.
+        instance_name : str | None, optional
+            Override the namespace prefix.  Defaults to ``self.name``.
+
+        Returns
+        -------
+        Port
+            A mapping of port names to *new* Node objects whose
+            elements belong to the parent graph.  Use these for
+            subsequent :meth:`BondGraph.connect` calls.
+        """
+
+        if instance_name is None:
+            instance_name = self.name
+
+        def get_new_name(orig_name: str) -> str:
+            """Return a new name for an element or symbol, with prefix/suffix."""
+            if is_prefix:
+                return instance_name + "_" + orig_name
+            else:
+                return orig_name + "_" + instance_name
+
+        # 1. Deep-copy all elements and build old→new mapping
+        elem_map: dict[int, Node] = {}  # id(old_element) → new_element
+        for elem in self.bondgraph.elements:
+            new_elem = copy.deepcopy(elem)
+            new_elem.name = get_new_name(new_elem.name)
+
+            # Prefix the symbolic value for one-port and two-port elements
+            # (skip sensors whose value is empty/unused)
+            if isinstance(new_elem, ElementOnePort):
+                old_val = new_elem.value
+                if str(old_val):  # skip empty-value sensors
+                    new_elem.value = sp.Symbol(
+                        get_new_name(str(old_val)),
+                        real=True, positive=True,
+                    )
+                new_elem.bond = None  # will be re-wired by parent
+
+            elif isinstance(new_elem, ElementTwoPort):
+                old_val = new_elem.value
+                new_elem.value = sp.Symbol(
+                    get_new_name(str(old_val)),
+                    real=True, positive=True,
+                )
+                new_elem.bond1 = None
+                new_elem.bond2 = None
+
+            elif isinstance(new_elem, Junction):
+                new_elem.bonds = []
+                new_elem.strong_bond = None
+
+            elem_map[id(elem)] = new_elem
+
+        # 2. Deep-copy bonds, re-pointing to new elements and prefixing symbols
+        for bond in self.bondgraph.bonds:
+            new_from = elem_map[id(bond.from_element)]
+            new_to = elem_map[id(bond.to_element)]
+            new_bond = Bond(
+                from_element=new_from,
+                to_element=new_to,
+                causality=bond.causality,
+                instance_name=instance_name,
+                is_prefix=is_prefix
+            )
+            parent_bondgraph.add_bond(new_bond)
+
+        # 3. Build new port mapping
+        new_ports: Port = {}
+        for port_name, node in self.ports.items():
+            new_ports[port_name] = elem_map[id(node)]
+
+        return new_ports
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def save(self, filepath: str | Path) -> None:
+        """Save this sub-model definition to a JSON file.
+
+        The file stores the structural description (element types,
+        names, values, bond connectivity, causality, ports) — enough
+        to reconstruct the sub-model from scratch.
+
+        Parameters
+        ----------
+        filepath : str | Path
+            Destination file path (typically ``*.json``).
+        """
+        data = self._to_dict()
+        Path(filepath).write_text(
+            json.dumps(data, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    @classmethod
+    def load(cls, filepath: str | Path) -> SubBondGraph:
+        """Load a sub-model definition from a JSON file.
+
+        Parameters
+        ----------
+        filepath : str | Path
+            Source file path.
+
+        Returns
+        -------
+        SubBondGraph
+            The reconstructed sub-model.
+        """
+        data = json.loads(Path(filepath).read_text(encoding="utf-8"))
+        return cls._from_dict(data)
+
+    # ------------------------------------------------------------------
+    # Internal serialization helpers
+    # ------------------------------------------------------------------
+
+    def _to_dict(self) -> dict:
+        """Convert this sub-model to a JSON-serializable dict."""
+        from .elements import (
+            SourceEffort, SourceFlow, Capacitor, Inductor,
+            Resistor, Transformer, Gyrator,
+            OneJunction, ZeroJunction,
+        )
+        from .sensors import IntegratedEffortSensor, IntegratedFlowSensor
+
+        # Map each element to an index for bond connectivity
+        elem_index: dict[int, int] = {}
+        elements_data = []
+        for i, elem in enumerate(self.bondgraph.elements):
+            elem_index[id(elem)] = i
+            entry = {
+                "type": type(elem).__name__,
+                "name": elem.name,
+            }
+            if isinstance(elem, (ElementOnePort, ElementTwoPort)):
+                if not isinstance(elem, (IntegratedEffortSensor, IntegratedFlowSensor)):
+                    entry["value"] = str(elem.value)
+            elements_data.append(entry)
+
+        bonds_data = []
+        for bond in self.bondgraph.bonds:
+            bonds_data.append({
+                "from": elem_index[id(bond.from_element)],
+                "to": elem_index[id(bond.to_element)],
+                "causality": bond.causality.value,
+            })
+
+        ports_data = {}
+        for port_name, node in self.ports.items():
+            ports_data[port_name] = {
+                "node_index": elem_index[id(node)],
+            }
+
+        return {
+            "name": self.name,
+            "elements": elements_data,
+            "bonds": bonds_data,
+            "ports": ports_data,
+        }
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> SubBondGraph:
+        """Reconstruct a SubBondGraph from a dict (inverse of ``_to_dict``)."""
+        from .bondgraph import BondGraph
+        from .elements import (
+            SourceEffort, SourceFlow, Capacitor, Inductor,
+            Resistor, Transformer, Gyrator,
+            OneJunction, ZeroJunction,
+        )
+        from .sensors import IntegratedEffortSensor, IntegratedFlowSensor
+
+        # Element type registry
+        TYPE_MAP = {
+            "SourceEffort": SourceEffort,
+            "SourceFlow": SourceFlow,
+            "Capacitor": Capacitor,
+            "Compliance": Capacitor,
+            "Inductor": Inductor,
+            "Inertance": Inductor,
+            "Resistor": Resistor,
+            "Resistance": Resistor,
+            "Transformer": Transformer,
+            "Gyrator": Gyrator,
+            "OneJunction": OneJunction,
+            "ZeroJunction": ZeroJunction,
+            "IntegratedEffortSensor": IntegratedEffortSensor,
+            "IntegratedFlowSensor": IntegratedFlowSensor,
+        }
+
+        # Reconstruct elements
+        elements = []
+        for entry in data["elements"]:
+            elem_cls = TYPE_MAP[entry["type"]]
+            if issubclass(elem_cls, Junction):
+                elem = elem_cls(name=entry["name"])
+            elif issubclass(elem_cls, (IntegratedEffortSensor, IntegratedFlowSensor)):
+                elem = elem_cls(name=entry["name"])
+            else:
+                elem = elem_cls(name=entry["name"], value=entry["value"])
+            elements.append(elem)
+
+        # Reconstruct bonds and build BondGraph
+        bg = BondGraph(name=data["name"])
+        for bond_entry in data["bonds"]:
+            bond = Bond(
+                from_element=elements[bond_entry["from"]],
+                to_element=elements[bond_entry["to"]],
+                causality=bond_entry["causality"],
+            )
+            bg.add_bond(bond)
+
+        # Reconstruct ports
+        ports: Port = {}
+        for port_name, port_data in data["ports"].items():
+            # Support both old "junction_index" and new "node_index" keys
+            idx = port_data.get("node_index", port_data.get("junction_index"))
+            ports[port_name] = elements[idx]
+
+        return cls(name=data["name"], bondgraph=bg, ports=ports)
+
+    def __repr__(self) -> str:
+        port_names = list(self.ports.keys())
+        return (
+            f"SubBondGraph(name={self.name!r}, "
+            f"elements={len(self.bondgraph.elements)}, "
+            f"bonds={len(self.bondgraph.bonds)}, "
+            f"ports={port_names})"
+        )

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/pyBondGraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.1.0
+Version: 0.2.0
 Summary: Modelling tool for linear bond graph systems in Python
 Author-email: Matthias Panny <matthias.panny@mci.edu>
 License-Expression: CC-BY-NC-SA-4.0
@@ -44,12 +44,15 @@ Bond graphs provide a **domain-independent modeling framework** for physical sys
 
 # Installation
 
-## Install directly from GitHub
-The easiest way to install the library is directly via pip:
+## Install from PyPI or Github
+The easiest way to install the library is via your preferred package manager (e.g. pip) directly from PyPI:
+```bash
+pip install pyBondGraph
+```
+Alternatively one can install the latest development version directly from the GitHub repository:
 ```bash
 pip install git+https://github.com/MrP123/pyBondGraph.git
 ```
-This installs the latest version of the package from the repository.
 
 ---
 

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/pyBondGraph.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ pyBondGraph/bondgraph.py
 pyBondGraph/core.py
 pyBondGraph/elements.py
 pyBondGraph/sensors.py
+pyBondGraph/subbondgraph.py
 pyBondGraph.egg-info/PKG-INFO
 pyBondGraph.egg-info/SOURCES.txt
 pyBondGraph.egg-info/dependency_links.txt

{pybondgraph-0.1.0 → pybondgraph-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyBondGraph"
-version = "0.1.0"
+version = "0.2.0"
 description = "Modelling tool for linear bond graph systems in Python"
 readme = "README.md"
 authors = [