pyBondGraph 0.1.0__py3-none-any.whl

pyBondGraph/__init__.py

@@ -0,0 +1,38 @@
+from .core import Bond, Causality
+from .elements import (
+    SourceEffort,
+    SourceFlow,
+    OneJunction,
+    ZeroJunction,
+    Capacitor,
+    Compliance,
+    Inductor,
+    Inertance,
+    Resistor,
+    Resistance,
+    Transformer,
+    Gyrator,
+)
+from .sensors import IntegratedEffortSensor, IntegratedFlowSensor
+
+from .bondgraph import BondGraph
+
+__all__ = [
+    "Bond",
+    "Causality",
+    "SourceEffort",
+    "SourceFlow",
+    "OneJunction",
+    "ZeroJunction",
+    "Capacitor",
+    "Compliance",
+    "Inductor",
+    "Inertance",
+    "Resistor",
+    "Resistance",
+    "Transformer",
+    "Gyrator",
+    "BondGraph",
+    "IntegratedEffortSensor",
+    "IntegratedFlowSensor",
+]

pyBondGraph/bondgraph.py

@@ -0,0 +1,399 @@
+import sympy as sp
+import networkx as nx
+import numpy as np
+import matplotlib.pyplot as plt
+
+from collections.abc import Callable
+
+from .core import (
+    Causality,
+    Node,
+    StatefulElement,
+    Bond,
+    ElementOnePort,
+    ElementTwoPort,
+    Junction,
+)
+from .elements import SourceEffort, SourceFlow, OneJunction, ZeroJunction
+
+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."""
+
+        Bond.counter = 0  # Reset bond counter for future bond graphs after solution has been computed --> ToDo: fix this hacky solution
+
+        self.elements = []
+        self.bonds: list[Bond] = []
+
+        self.state_vars: list[sp.Expr] = []
+        self.equations: list[sp.Expr] = []
+        self.inputs: list[sp.Symbol] = []
+
+        self.solution: SolutionType = None
+
+    def add_bond(self, bond: Bond) -> None:
+        """Adds a bond to the bond graph by appending it to `self.bonds`.
+        This adds the connected elements to `self.elements` if they are not already present.
+        If the added bond connects to a `SourceEffort` or `SourceFlow`, its value is added to `self.inputs`.
+        This is needed for generating the state space representation.
+
+        Parameters
+        ----------
+        bond : Bond
+            The bond to be added to the bond graph.
+
+        Raises
+        ------
+        ValueError
+            If the bond is already part of the bond graph.
+        """
+
+        if bond in self.bonds:
+            raise ValueError(f"Bond {bond} is already part of the bond graph.")
+
+        self.bonds.append(bond)
+
+        for element in bond.elements:
+            if element in self.elements:
+                continue
+
+            self.elements.append(element)
+
+            if isinstance(element, SourceEffort) or isinstance(element, SourceFlow):
+                self.inputs.append(element.value)
+
+    def __handle_bonds(self) -> None:
+        """Handles the bonds in the bond graph by assigning them to the appropriate elements.
+        This assignment propagates the bond references to the elements, so that each element knows which bonds it is connected to.
+        """
+
+        def handle_bond_element(element: Node, bond: Bond):
+            """Internal helper function to handle the assignment of a bond to an element.
+
+            Parameters
+            ----------
+            element : Node
+                Element of the bond to handle. Must be called with both `from_element` and `to_element` of the bond.
+            bond : Bond
+                The bond to assign to the element.
+
+            Raises
+            ------
+            ValueError
+                If the element is a junction and it is attemped to add a second strong bond.
+            """
+
+            if isinstance(element, ElementOnePort):
+                element.bond = bond
+
+            elif isinstance(element, ElementTwoPort):
+                if bond.to_element == element:
+                    element.bond1 = bond
+                elif bond.from_element == element:
+                    element.bond2 = bond
+
+            elif isinstance(element, Junction):
+                element.bonds.append(bond)
+
+                if isinstance(element, OneJunction):
+                    if (bond.from_element == element and bond.causality == Causality.EFFORT_OUT) or (bond.to_element == element and bond.causality == Causality.FLOW_OUT):
+                        # bond is strong bond for one junction
+                        if element.strong_bond is None:
+                            element.strong_bond = bond
+                            print(f"Assigned strong bond {bond} to OneJunction {element}.")
+                        else:
+                            raise ValueError(f"OneJunction {element} already has a strong bond: {element.strong_bond}. Cannot assign {bond}.")
+
+                elif isinstance(element, ZeroJunction):
+                    if (bond.from_element == element and bond.causality == Causality.FLOW_OUT) or (bond.to_element == element and bond.causality == Causality.EFFORT_OUT):
+                        # bond is strong bond for zero junction
+                        if element.strong_bond is None:
+                            element.strong_bond = bond
+                            print(f"Assigned strong bond {bond} to ZeroJunction {element}.")
+                        else:
+                            raise ValueError(f"ZeroJunction {element} already has a strong bond: {element.strong_bond}. Cannot assign {bond}.")
+
+        # Call helper function for both elements of each bond
+        for bond in self.bonds:
+            handle_bond_element(bond.from_element, bond)
+            handle_bond_element(bond.to_element, bond)
+
+    def __handle_equations(self) -> None:
+        """Accumulates the equations from all elements and junctions in the bond graph.
+        Also collects the state variables from all stateful elements.
+
+        Raises
+        ------
+        ValueError
+            If an element is not fully connected with bonds.
+        """
+
+        for element in self.elements:
+            if isinstance(element, ElementOnePort):
+                bond = element.bond
+                if bond is None:
+                    raise ValueError(f"Element {element} has no connected bond.")
+
+                # Add equations from the element to the bond graph
+                self.equations.extend(element.equations)
+
+                if isinstance(element, StatefulElement):
+                    self.state_vars.append(element.state_var)
+
+            elif isinstance(element, ElementTwoPort):
+                bond1 = element.bond1
+                bond2 = element.bond2
+                if bond1 is None or bond2 is None:
+                    raise ValueError(f"Element {element} has no connected bonds.")
+
+                # Add equations from the element to the bond graph
+                self.equations.extend(element.equations)
+
+            elif isinstance(element, Junction):
+                self.equations.extend(element.equations)
+
+    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
+        -------
+        SolutionType
+            A dictionary mapping each symbolic variable to its solved expression.
+            The keys include the time derivatives of the state variables and the efforts and flows of all bonds.
+        """
+
+        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,
+            state_derivatives
+            + [b.effort for b in self.bonds]
+            + [b.flow for b in self.bonds],
+        )
+        return self.solution
+
+    def get_state_space(self) -> tuple[sp.Matrix, sp.Matrix, sp.Matrix, sp.Matrix, sp.Matrix, int, int, int]:
+        """Calculates the linear state space representation of the bond graph.
+        This method automatically calls `get_solution_equations` if the solution has not yet been computed.
+
+        Depending on the number of state variables, inputs, and outputs, the state space representation is either SISO, MIMO or a hybrid.
+        The general form of a (nonlinear) state space model is given by the equations:
+            x_dot = f(x, u)
+                y = h(x, u)
+        where x is the state vector, u is the input vector, and y is the output vector.
+        As the bond graph framework currently only supports linear elements, the state space representation can be simplified to a linear form.
+        The linear state space representation is given by the matrices A, B, C, D in the equations:
+            x_dot = A*x + B*u
+                y = C*x + D*u
+        The matrices are computed by taking the Jacobians of the functions f and h with respect to the state variables and inputs.
+        The output y is defined to be all efforts and flows of all bonds in the bond graph, with the efforts coming first and then the flows.
+        The input u is defined to be all sources (i.e. `SourceEffort` and `SourceFlow` elements) in the bond graph.
+        The state variables x are defined to be the state variables of all `StatefulElement` elements in the bond graph.
+
+        Returns
+        -------
+        tuple[sp.Matrix, sp.Matrix, sp.Matrix, sp.Matrix, sp.Matrix, int, int, int]
+            Returns the matrices A, B, C, D of the state space representation, the state vector x,
+            as well as the number of states, inputs, and outputs.
+            A in R^(n_states x n_states)
+            B in R^(n_states x n_inputs)
+            C in R^(n_outputs x n_states)
+            D in R^(n_outputs x n_inputs)
+            x in R^(n_states x 1)
+
+        Raises
+        ------
+        ValueError
+            If the system of equations for this bond graph could not be solved.
+        """
+
+        # Retrieve solution if needed
+        if self.solution is None:
+            if not self.get_solution_equations():
+                raise ValueError("Could not compute solution.")
+
+        n_states = len(self.state_vars)
+        n_inputs = len(self.inputs)  # Number of inputs (sources)
+        n_outputs = 2 * len(self.bonds)  # effort & flow for each bond
+
+        # General form of a state space model
+        # x_dot = f(x, u)
+        #     y = h(x, u)
+        # Simplification for linear systems:
+        # x_dot = A*x + B*u
+        #     y = C*x + D*u
+        # --> therefore
+        # A = ∂f/∂x, B = ∂f/∂u, C = ∂h/∂x, D = ∂h/∂u each at stationary point 0
+
+        f: sp.Matrix = sp.zeros(n_states, 1)
+        for i, state_var in enumerate(self.state_vars):
+            state_deriv = sp.Derivative(state_var, "t")  # symbolic derivative dx/dt
+            f[i] = self.solution[state_deriv]
+
+        h: sp.Matrix = sp.zeros(n_outputs, 1)  # efforts then flows
+        for i, bond in enumerate(self.bonds):
+            h[i] = self.solution[bond.effort]
+            h[i + n_outputs // 2] = self.solution[bond.flow]
+
+        A = f.jacobian(self.state_vars)
+        B = f.jacobian(self.inputs)
+
+        C = h.jacobian(self.state_vars)
+        D = h.jacobian(self.inputs)
+        # alternatively could use sp.linear_eq_to_matrix(...)
+
+        return A, B, C, D, sp.Matrix(self.state_vars), n_states, n_inputs, n_outputs
+
+    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.
+
+        Parameters
+        ----------
+        layout : Callable[[nx.Graph, ...], dict], optional
+            `networkx` layout function for plotting the graph, by default `nx.spectral_layout`
+            This is only called if the graph is not a directed acyclic graph (DAG).
+            If the graph is a DAG, a `multipartite_layout` is used instead.
+
+        Returns
+        -------
+        tuple[plt.Figure, plt.Axes]
+            Matplotlib Figure and axes objects for the plot.
+        Raises
+        ------
+        ValueError
+            If an edge has no valid causality assigned.
+        """
+
+        G = nx.DiGraph()
+
+        for elem in self.elements:
+            G.add_node(elem.name, label=elem.name)
+
+        for bond in self.bonds:
+            G.add_edge(
+                bond.from_element.name,
+                bond.to_element.name,
+                label=bond.num,
+                causality=bond.causality,
+            )
+
+        # 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)
+
+        fig, ax = plt.subplots(figsize=(10, 8))
+        ax.set_axis_off()
+        nx.draw_networkx(
+            G,
+            pos,
+            ax=ax,
+            with_labels=True,
+            node_size=2000,
+            node_color="lightblue",
+            font_size=10,
+            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,
+        )
+
+        # Function to add a perpendicular line
+        def draw_causal_stroke(ax, p1, p2, at="head", length=20, node_size=2000, padding=2):
+            """Draw a causal stroke perpendicular to the edge (p1 -> p2).
+
+            Parameters
+            ----------
+            ax : matplotlib.axes.Axes
+                The axes to draw on.
+            p1 : tuple[float, float]
+                The (x, y) coordinates of the first node.
+            p2 : tuple[float, float]
+                The (x, y) coordinates of the second node.
+            at : str, optional
+                Where to draw the stroke, by default "head"
+            length : int, optional
+                The length of the stroke, by default 20
+            node_size : int, optional
+                The size of the nodes, by default 2000
+            padding : int, optional
+                The padding between the node and the stroke, by default 2
+
+            Raises
+            ------
+            ValueError
+                If the 'at' parameter is not "head" or "tail".
+            """
+
+            # --- Convert node size (points^2) to radius in pixels ---
+            radius_points = np.sqrt(node_size / np.pi)
+            radius_pixels = radius_points * ax.figure.dpi / 72.0  # 1 point = 1/72 inch
+            offset = radius_pixels + padding   # + padding (in px) so stroke sits outside node
+
+            # Transform points to display (pixel) coordinates
+            p1_disp = ax.transData.transform(p1)
+            p2_disp = ax.transData.transform(p2)
+
+            # Edge vector in display coords
+            vec = p2_disp - p1_disp
+            norm = np.linalg.norm(vec)
+            if norm == 0:
+                return
+            uvec = vec / norm
+
+            # Perpendicular in display coords
+            perp = np.array([-uvec[1], uvec[0]])
+
+            # Base point (head or tail), offset in pixels
+            if at == "head":
+                base_disp = p2_disp - uvec * offset
+            elif at == "tail":
+                base_disp = p1_disp + uvec * offset
+            else:
+                raise ValueError(f"Invalid value for 'at': {at}")
+
+            # Stroke endpoints in display coords
+            p_start_disp = base_disp - perp * (length / 2)
+            p_end_disp = base_disp + perp * (length / 2)
+
+            # Transform back to data coords for plotting
+            p_start = ax.transData.inverted().transform(p_start_disp)
+            p_end = ax.transData.inverted().transform(p_end_disp)
+
+            ax.plot([p_start[0], p_end[0]], [p_start[1], p_end[1]], color="k", lw=1.0)
+
+        # Add perpendicular lines to edges
+        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)
+            elif causality is Causality.FLOW_OUT:
+                draw_causal_stroke(ax, pos[u], pos[v], at="tail", padding=-2)
+            else:
+                raise ValueError(f"Edge {u}->{v} has no valid causality: {causality} --> this should never happen!")
+
+        return fig, ax

pyBondGraph/core.py

@@ -0,0 +1,188 @@
+from abc import ABC, abstractmethod
+from enum import Enum
+
+import sympy as sp
+
+
+class Causality(Enum):
+    """Enumeration for bond causality types.
+    This definition is always from the perspective of the `from_element`.
+    Therefore a `Bond(OneJunction(...), Inductor(...), "effort_out")` means that the
+    `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.
+    """
+
+    EFFORT_OUT = "effort_out"
+    FLOW_OUT = "flow_out"
+
+
+class StatefulElement(ABC):
+    """Base class for all stateful elements (capacitor, inductor) in the bond graph.
+    Requires implementation of a `state_var` property that returns the symbolic state variable associated with the element.
+    """
+
+    @property
+    @abstractmethod
+    def state_var(self) -> sp.Symbol:
+        """sp.Symbol: Returns the symbolic state variable associated with the stateful element."""
+        raise NotImplementedError("Subclasses should implement this method")
+
+
+class Node(ABC):
+    """Base class for all nodes in the bond graph."""
+
+    def __init__(self, name: str):
+        """Base class for all nodes in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the node. Will be shown on the bond graph plot.
+        """
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name})"
+
+
+class Bond:
+    """Represents a bond between two elements in the bond graph."""
+
+    counter = 0
+
+    def __init__(self, from_element: Node, to_element: Node, causality: str | Causality):
+        """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.
+
+        Parameters
+        ----------
+        from_element : Node
+            The element where the bond originates.
+        to_element : Node
+            The element where the bond terminates.
+        causality : str | Causality
+            The causality of the bond, either `effort_out` or `flow_out`.
+            If a string is provided, it is converted to the corresponding `Causality` enum.
+            This definition is always from the perspective of the `from_element`.
+            Therefore a `Bond(OneJunction(...), Inductor(...), "effort_out")` means that the
+            `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.
+
+        Raises
+        ------
+        ValueError
+            If the causality is not 'effort_out' or 'flow_out'.
+        """
+
+        self.from_element = from_element
+        self.to_element = to_element
+
+        if isinstance(causality, str):
+            causality = Causality(causality.lower()) # Convert string to Causality enum, case insensitive
+            # --> automatically raises ValueError if string is not valid
+
+        self.causality: Causality = causality
+
+        self.num = Bond.counter
+        Bond.counter += 1
+
+        self.effort = sp.Symbol(f"e_{self.num}", real=True)
+        self.flow = sp.Symbol(f"f_{self.num}", 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 __repr__(self) -> str:
+        return f"Bond(from={self.from_element}, to={self.to_element}, causality={self.causality})"
+
+
+class Junction(Node, ABC):
+    """Base class for all junctions in the bond graph."""
+
+    def __init__(self, name: str):
+        """Base class for all junctions in the bond graph.
+        Stores a list of associated bonds and a reference to the "strong" bond.
+
+        Parameters
+        ----------
+        name : str
+            The name of the junction. Will be shown on the bond graph plot.
+        """
+        super().__init__(name)
+        self.bonds: list[Bond] = []
+        self.strong_bond = None
+
+    @property
+    @abstractmethod
+    def equations(self) -> list[sp.Expr]:
+        """list[sp.Expr]: Returns the symbolic equations defining the behavior of the junction."""
+        raise NotImplementedError("Subclasses should implement this method")
+
+
+class ElementOnePort(Node, ABC):
+    """Base class for all one-port elements in the bond graph.
+    Requires implementation of an `equations` property that returns the list of symbolic equations defining the element's behavior.
+    This can also be just one equation.
+    """
+
+    def __init__(self, name: str, value: str):
+        """ABC for a one-port element. Acts as base class for all one-port elements like Inductor, Capacitor, Resistor, SourceEffort, SourceFlow.
+        Stores an associated bond and a symbolic value (real and positive) for its defining characteristics e.g. resistance, capacitance, etc.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Will be shown on the bond graph plot.
+        value : str
+            The name of the value associated with the element, is internally used for creating a `sympy.Symbol`.
+        """
+
+        super().__init__(name)
+        self.value = sp.Symbol(value, real=True, positive=True)  # Ensure value is a positive real number
+        self.bond: Bond = None  # bond that connects this element to a bond graph
+
+    @property
+    @abstractmethod
+    def equations(self) -> list[sp.Expr]:
+        """list[sp.Expr]: Returns the symbolic equations defining the behavior of the one-port element."""
+        raise NotImplementedError("Subclasses should implement this method")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name = {self.name}, value = {self.value})"
+
+
+class ElementTwoPort(Node, ABC):
+    """Base class for all two-port elements in the bond graph.
+    Requires implementation of an `equations` property that returns the list of symbolic equations defining the element's behavior.
+    """
+
+    def __init__(self, name: str, value: str):
+        """ABC for a two-port element. Acts as base class for all two-port elements like Transformer, Gyrator.
+        Stores two associated bonds and a symbolic value (real and positive) for its defining characteristics e.g. conversion factor, ratio, etc.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Will be shown on the bond graph plot.
+        value : str
+            The name of the value associated with the element, is internally used for creating a `sympy.Symbol`.
+        """
+
+        super().__init__(name)
+        self.value = sp.Symbol(value, real=True, positive=True)
+        self.bond1: Bond = None  # ElementOther   --(bond1)--> ElementTwoPort
+        self.bond2: Bond = None  # ElementTwoPort --(bond2)--> ElementOther
+
+    @property
+    @abstractmethod
+    def equations(self) -> list[sp.Expr]:
+        """list[sp.Expr]: Returns the symbolic equations defining the behavior of the two-port element."""
+        raise NotImplementedError("Subclasses should implement this method")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name = {self.name}, value = {self.value})"

pyBondGraph/elements.py

@@ -0,0 +1,359 @@
+from .core import Causality, StatefulElement, ElementOnePort, ElementTwoPort, Junction
+
+import sympy as sp
+
+
+class SourceEffort(ElementOnePort):
+    """Represents a source of effort in the bond graph.
+    A source of effort provides a constant effort to its port, the associated flow follows automatically."""
+
+    def __init__(self, name: str, value: str):
+        """Create a source of effort in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        value : str
+            The name of the element value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        # Source --> constant effort
+        return [self.bond.effort - self.value]
+
+
+class SourceFlow(ElementOnePort):
+    """Represents a source of flow in the bond graph.
+    A source of flow provides a constant flow to its port, the associated effort follows automatically.
+    """
+
+    def __init__(self, name: str, value: str):
+        """Create a source of flow in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        value : str
+            The name of the element value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        # Source --> constant flow
+        return [self.bond.flow - self.value]
+
+
+class Capacitor(ElementOnePort, StatefulElement):
+    """Represents a linear compliance/capacitance element in the bond graph.
+    A capacitance relates the effort of its port with the integral of its flow by a constant capacitance value.
+    """
+
+    def __init__(self, name: str, value: str):
+        """Create a linear compliance/capacitance element in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        value : str
+            The name of the element value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def state_var(self) -> sp.Symbol:
+        """Returns the symbolic state variable (generalized displacement) associated with the compliance/capacitance.
+
+        Returns
+        -------
+        sp.Symbol
+            The symbolic state variable representing the generalized displacement (q) of the compliance/capacitance.
+        """
+        return sp.Symbol(f"q_{self.name}", real=True)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the linear compliance/capacitance.
+        Formulated in the derivative of the internal state_var, stemming from integral causality.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the compliance/capacitance.
+        """
+
+        # Dynamic equation: f = dq/dt, e = q / C
+        return [
+            self.bond.flow - sp.Derivative(self.state_var, "t"),
+            self.bond.effort - self.state_var / self.value,
+        ]
+
+
+type Compliance = Capacitor  # Alias for Compliance element
+
+
+class Inductor(ElementOnePort, StatefulElement):
+    """Represents a linear inertia/inductance element in the bond graph.
+    An inductor relates the flow of its port with the integral of its effort by a constant inductance value.
+    """
+
+    def __init__(self, name: str, value: str):
+        """Create a linear inertia/inductance element in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        value : str
+            The name of the element value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def state_var(self) -> sp.Symbol:
+        """Returns the symbolic state variable (generalized momentum) associated with the inertia/inductance.
+
+        Returns
+        -------
+        sp.Symbol
+            The symbolic state variable representing the generalized momentum (p) of the inertia/inductance.
+        """
+        return sp.Symbol(f"p_{self.name}", real=True)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the linear inertia/inductance.
+        Formulated in the derivative of the internal state_var, stemming from integral causality.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the inertia/inductance.
+        """
+
+        # Dynamic equation: e = dp/dt, f = p / L
+        return [
+            self.bond.effort - sp.Derivative(self.state_var, "t"),
+            self.bond.flow - self.state_var / self.value,
+        ]
+
+
+type Inertance = Inductor  # Alias for Inertia element
+
+
+class Resistor(ElementOnePort):
+    """Represents a linear resistance/damper element in the bond graph.
+    A resistor relates the effort and flow of its port by a constant resistance value.
+    """
+
+    def __init__(self, name: str, value: str):
+        """Create a linear resistance element.
+
+        Parameters
+        ----------
+        name : str
+            The name of the resistance. Forwarded to the `Node` base class.
+        value : str
+            The name of the resistance value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the linear resistance.
+        The equation is formulated based on the causality of the associated bond.
+        This makes resolving causality issues easier, as there is no preferred one for resistors.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the resistance.
+        """
+
+        # Resistance: e = R * f
+        if self.bond.causality == Causality.EFFORT_OUT:
+            return [self.bond.flow - 1 / self.value * self.bond.effort]
+        elif self.bond.causality == Causality.FLOW_OUT:
+            return [self.bond.effort - self.value * self.bond.flow]
+
+
+type Resistance = Resistor  # Alias for Resistance element
+
+
+class Transformer(ElementTwoPort):
+    """Represents a transformer element in the bond graph.
+    A transformer relates the efforts of its two ports and the flows of its two ports by a constant ratio.
+    """
+
+    def __init__(self, name: str, value: str):
+        """Create a transformer element in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        value : str
+            The name of the element value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the transformer.
+        The equations are formulated based on the causality of the associated bonds.
+        This makes resolving causality issues easier, as there is no preferred causality for transformers.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the transformer.
+
+        Raises
+        ------
+        ValueError
+            If both bonds are not assigned or if they do not have the same causality.
+        """
+
+        if self.bond1 is None or self.bond2 is None:
+            raise ValueError("Both bonds must be assigned to the transformer element.")
+
+        if self.bond1.causality != self.bond2.causality:
+            raise ValueError("Both bonds must have the same causality for a transformer element.")
+
+        if self.bond1.causality == Causality.EFFORT_OUT:
+            return [
+                self.bond1.flow - 1 / self.value * self.bond2.flow,
+                self.bond2.effort - 1 / self.value * self.bond1.effort,
+            ]
+        elif self.bond1.causality == Causality.FLOW_OUT:
+            return [
+                self.bond1.effort - self.value * self.bond2.effort,
+                self.bond2.flow - self.value * self.bond1.flow,
+            ]
+
+
+class Gyrator(ElementTwoPort):
+    """Represents a gyrator element in the bond graph.
+    A gyrator relates the effort of one port with the flow of the other (and vice versa) by a constant ratio.
+    """
+
+    def __init__(self, name: str, value: str):
+        """Create a gyrator element in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        value : str
+            The name of the element value, is internally used for creating a `sympy.Symbol`.
+        """
+        super().__init__(name, value)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the gyrator.
+        The equations are formulated based on the causality of the associated bonds.
+        This makes resolving causality issues easier, as there is no preferred causality for gyrators.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the gyrator.
+
+        Raises
+        ------
+        ValueError
+            If both bonds are not assigned or if they have the same causality.
+        """
+
+        if self.bond1 is None or self.bond2 is None:
+            raise ValueError("Both bonds must be assigned to the gyrator element.")
+
+        if self.bond1.causality == self.bond2.causality:
+            raise ValueError("Both bonds must have the different causality for a gyrator element.")
+
+        if self.bond1.causality == Causality.EFFORT_OUT:
+            return [
+                self.bond1.flow - 1 / self.value * self.bond2.effort,
+                self.bond2.flow - 1 / self.value * self.bond1.effort,
+            ]
+        elif self.bond1.causality == Causality.FLOW_OUT:
+            return [
+                self.bond1.effort - self.value * self.bond2.flow,
+                self.bond2.effort - self.value * self.bond1.flow,
+            ]
+
+
+class OneJunction(Junction):
+    """Represents a one-junction element in the bond graph.
+    A one-junction enforces equal flow (current, velocity, etc.) on all connected bonds and the sum of efforts to be zero .
+    The sign convention is that efforts of bonds going into the junction are positive, efforts of bonds going out of the junction are negative.
+    """
+
+    def __init__(self, name: str):
+        """Create a one-junction element in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        """
+        super().__init__(name)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the one-junction.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the one-junction.
+        """
+
+        effort_eq = 0
+        for b in self.bonds:
+            dir = +1 if b.to_element == self else -1
+            effort_eq += dir * b.effort
+
+        flow_eq = [self.bonds[0].flow - b.flow for b in self.bonds[1:]]
+        return [effort_eq, *flow_eq]
+
+
+class ZeroJunction(Junction):
+    """Represents a zero-junction element in the bond graph.
+    A zero-junction enforces equal effort (voltage, force, etc.) on all connected bonds and the sum of flows to be zero .
+    The sign convention is that flows of bonds going into the junction are positive, flows of bonds going out of the junction are negative.
+    """
+
+    def __init__(self, name: str):
+        """Create a zero-junction element in the bond graph.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        """
+        super().__init__(name)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the zero-junction.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the zero-junction.
+        """
+
+        flow_eq = 0
+        for b in self.bonds:
+            dir = +1 if b.to_element == self else -1
+            flow_eq += dir * b.flow
+
+        effort_eq = [self.bonds[0].effort - b.effort for b in self.bonds[1:]]
+        return [flow_eq, *effort_eq]

pyBondGraph/sensors.py

@@ -0,0 +1,86 @@
+from .core import StatefulElement, ElementOnePort
+
+import sympy as sp
+
+
+class IntegratedEffortSensor(ElementOnePort, StatefulElement):
+    """Represents a sensor that integrates effort to its internal state variable."""
+
+    def __init__(self, name: str):
+        """Create a sensor that integrates effort to its internal state variable.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        """
+        super().__init__(name, "")
+
+    @property
+    def state_var(self) -> sp.Symbol:
+        """Returns the symbolic state variable (integrated effort) associated with the sensor.
+
+        Returns
+        -------
+        sp.Symbol
+            The symbolic state variable representing the integrated effort.
+        """
+        return sp.Symbol(f"e_int_{self.name}", real=True)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the sensor that integrates effort.
+        Formulated in the derivative of the internal state_var, stemming from integral causality.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the sensor.
+        """
+
+        # Dynamic equation: e = d(state_var)/dt, f = 0
+        return [
+            self.bond.effort - sp.Derivative(self.state_var, "t"),
+            self.bond.flow
+        ]
+
+class IntegratedFlowSensor(ElementOnePort, StatefulElement):
+    """Represents a sensor that integrates flow to its internal state variable."""
+
+    def __init__(self, name: str):
+        """Create a sensor that integrates effort to its internal state variable.
+
+        Parameters
+        ----------
+        name : str
+            The name of the element. Forwarded to the `Node` base class.
+        """
+        super().__init__(name, "")
+
+    @property
+    def state_var(self) -> sp.Symbol:
+        """Returns the symbolic state variable (integrated flow) associated with the sensor.
+
+        Returns
+        -------
+        sp.Symbol
+            The symbolic state variable representing the integrated flow.
+        """
+        return sp.Symbol(f"f_int_{self.name}", real=True)
+
+    @property
+    def equations(self) -> list[sp.Expr]:
+        """Returns the symbolic equations defining the behavior of the sensor that integrates flow.
+        Formulated in the derivative of the internal state_var, stemming from integral causality.
+
+        Returns
+        -------
+        list[sp.Expr]
+            A list of symbolic equations representing the behavior of the sensor.
+        """
+
+        # Dynamic equation: f = d(state_var)/dt, e = 0
+        return [
+            self.bond.flow - sp.Derivative(self.state_var, "t"),
+            self.bond.effort
+        ]

pybondgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: pyBondGraph
+Version: 0.1.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
+Project-URL: Homepage, https://github.com/MrP123/pyBondGraph
+Project-URL: Issues, https://github.com/MrP123/pyBondGraph/issues
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.14.0
+Requires-Dist: networkx>=3.5
+Requires-Dist: numpy>=2.3.0
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: control>=0.10.2
+Provides-Extra: streamlit
+Requires-Dist: streamlit>=1.47.0; extra == "streamlit"
+Requires-Dist: streamlit-flow-component>=1.6.1; extra == "streamlit"
+Dynamic: license-file
+
+# pyBondGraph
+**pyBondGraph** is a Python library for **modeling and analyzing linear bond graph systems** using symbolic computation.
+
+The library allows users to construct bond graph models programmatically, automatically derive the governing equations, and analyze the resulting dynamic systems using tools from control theory.
+
+Bond graphs provide a **domain-independent modeling framework** for physical systems. Using a unified representation of power exchange, the same modeling approach can be used for electrical, mechanical, hydraulic, and multi-domain systems.
+
+---
+
+# Features
+
+* Programmatic construction of **bond graph models**
+* Automatic **symbolic equation derivation** using SymPy
+* Conversion of models to **state-space systems**
+* Example models for electrical and mechanical systems
+
+---
+
+# Installation
+
+## Install directly from GitHub
+The easiest way to install the library is directly via pip:
+```bash
+pip install git+https://github.com/MrP123/pyBondGraph.git
+```
+This installs the latest version of the package from the repository.
+
+---
+
+## Development installation
+To work with the source code:
+```bash
+git clone https://github.com/MrP123/pyBondGraph.git
+cd pyBondGraph
+pip install -e .
+```
+
+---
+
+# Dependencies
+
+The main dependencies are:
+
+* `sympy`
+* `numpy`
+* `networkx`
+* `matplotlib`
+* `control` only needed for the examples
+
+Optional dependencies are used for experimental visualization tools.
+
+---
+
+# Basic Usage
+A bond graph model is constructed by creating elements and connecting them via bonds.
+
+Simple RC-Filter circuit:
+
+```python
+from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction, Bond, Causality
+
+bg = BondGraph()
+
+# create elements
+voltage_source = SourceEffort("U", "u_in")
+resistor = Resistor("R", "R")
+capacitor = Capacitor("C", "C")
+series_junction = OneJunction("J1")
+
+# connect elements
+# causalities need to be assigned manually 
+bg.add_bond(Bond(voltage_source, series_junction, Causality.EFFORT_OUT))
+bg.add_bond(Bond(series_junction, resistor, Causality.EFFORT_OUT))
+bg.add_bond(Bond(series_junction, capacitor, Causality.FLOW_OUT))
+
+# plot the resulting BondGraph
+bg.plot()
+
+# derive system equations in linear state space form
+A, B, C, D, x, n_states, n_inputs, n_outputs = bond_graph.get_state_space()
+```
+
+The library automatically derives the **symbolic system equations** describing the dynamics of the model.
+
+---
+
+
+# Core Concepts
+Bond graphs represent **power exchange between system components**, where power is the product of **effort** and **flow** associated with the following components:
+
+## Elements
+| Element | Meaning                                  |
+|---------|------------------------------------------|
+| R       | Dissipation                              |
+| C       | Energy storage (compliance, capacitance) |
+| I       | Energy storage (inertia, inductance)     |
+| Se      | Effort source                            |
+| Sf      | Flow source                              |
+
+## Junctions
+| Junction | Meaning       |
+|----------|---------------|
+|     0    | Common effort |
+|     1    | Common flow   |
+
+## Sensors
+| Sensor                 | Meaning                                     |
+|------------------------|---------------------------------------------|
+| IntegratedEffortSensor | Measures integral of the effort at its bond |
+| IntegratedFlowSensor   | Measures integral of the flow at its bond   |
+
+In mechanical bond graph models:
+* **flow** corresponds to **velocity**
+* **effort** corresponds to **force**
+
+An **integrated flow sensor** can therefore be used to compute **position**:
+
+---
+
+# Example Systems
+The repository contains example models illustrating typical applications of bond graphs.
+
+### RLC Circuit
+Demonstrates modeling of an electrical circuit using bond graph elements.
+
+### DC Motor
+A multi-domain electromechanical system coupling electrical and mechanical dynamics.
+
+### Transformer
+Example of energy transformation between two ports.
+
+### Two DOF Mass–Spring–Damper System
+Classical mass-spring-damper system with two degrees of freedom.
+
+---
+
+# Typical Applications
+Bond graph modeling is particularly useful for:
+
+* electromechanical systems
+* robotics and mechatronics
+* multi-domain energy systems
+* control system modeling
+* teaching system dynamics

pybondgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyBondGraph/__init__.py,sha256=-C74b1kF3iyVfMe9RwvsA0DzznMe1UQa8jopn-1cSAY,717
+pyBondGraph/bondgraph.py,sha256=5MqOFeNWEDSM6E5AD7TSfblAWF59IWeVwu3qOxAaP04,16656
+pyBondGraph/core.py,sha256=rDT82D6_1jUzrq1uJ3YLxHGUKfOKtr313vO2uaw-CiM,7851
+pyBondGraph/elements.py,sha256=yQu88NRoDbnG8r8gPZ5NoN7ydA0Oud7fzW1AiWBx3S8,13170
+pyBondGraph/sensors.py,sha256=p8HdCkClxslBuMsd46mQKn2uuufWGZLBh_iV5boZRZk,2891
+pybondgraph-0.1.0.dist-info/licenses/LICENSE,sha256=gVYUJmavXr6Y0lO28X9WXKiwuEz0HaTCAJRIVkXuXb8,202
+pybondgraph-0.1.0.dist-info/METADATA,sha256=WG1REhQcB4itvhGW-51VsXmm9dtVxrl_fgn79fqBZXo,5459
+pybondgraph-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pybondgraph-0.1.0.dist-info/top_level.txt,sha256=N3BmEIcuMU1Cqbc6ayds0jzxyZwyOA1MAy5sCO4qZ2o,12
+pybondgraph-0.1.0.dist-info/RECORD,,

pybondgraph-0.1.0.dist-info/WHEEL

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

pybondgraph-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1 @@
+This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.  To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/4.0/

pybondgraph-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyBondGraph