pyBondGraph 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.2.0
+Version: 0.3.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
@@ -36,9 +36,15 @@ Bond graphs provide a **domain-independent modeling framework** for physical sys
 # Features
 
 * Programmatic construction of **bond graph models**
+* **Automatic causality assignment** via SCAP (Sequential Causality Assignment Procedure), with optional manual override or mixed mode
 * Automatic **symbolic equation derivation** using SymPy
-* Conversion of models to **state-space systems**
-* Example models for electrical and mechanical systems
+* Conversion of models to **linear state-space systems** ($\dot{x} = Ax + Bu$, $y = Cx + Du$)
+* **Composable sub-models** via `SubBondGraph` with deep-copy namespace isolation
+* **Two-port elements**: Transformer and Gyrator with automatic causality propagation
+* **Sensor elements**: `IntegratedEffortSensor` and `IntegratedFlowSensor` for measuring integrated generalized variables (e.g. position from velocity)
+* **Domain-neutral aliases**: `Compliance` = `Capacitor`, `Inertance` = `Inductor`, `Resistance` = `Resistor`
+* Example models for electrical and electromechanical systems
+* Integration with **python-control** for numerical simulation (step response, Bode plots, etc.)
 
 ---
 
@@ -81,12 +87,12 @@ Optional dependencies are used for experimental visualization tools.
 ---
 
 # Basic Usage
-A bond graph model is constructed by creating elements and connecting them via bonds.
+A bond graph model is constructed by creating elements and connecting them via the `connect()` convenience method, which creates bonds and adds them to the graph in one step.
 
-Simple RC-Filter circuit:
+## RC-Filter with automatic causality (SCAP)
 
 ```python
-from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction, Bond, Causality
+from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction
 
 bg = BondGraph()
 
@@ -96,19 +102,20 @@ 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))
+# connect elements --> causality is assigned automatically by SCAP
+bg.connect(voltage_source, series_junction)
+bg.connect(series_junction, resistor)
+bg.connect(series_junction, capacitor)
 
 # 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()
+A, B, C, D, x, n_states, n_inputs, n_outputs = bg.get_state_space()
 ```
 
+Causality can also be assigned **manually** by passing a `Causality` value to `connect()`, or in **mixed mode** where some bonds are fixed and SCAP resolves the rest.
+
 The library automatically derives the **symbolic system equations** describing the dynamics of the model.
 
 ---
@@ -126,6 +133,12 @@ Bond graphs represent **power exchange between system components**, where power
 | Se      | Effort source                            |
 | Sf      | Flow source                              |
 
+## Two-Port Elements
+| Element     | Meaning                                                    |
+|-------------|------------------------------------------------------------|
+| TF          | Transformer — same causality on both bonds                 |
+| GY          | Gyrator — opposite causality on both bonds                 |
+
 ## Junctions
 | Junction | Meaning       |
 |----------|---------------|
@@ -139,11 +152,9 @@ Bond graphs represent **power exchange between system components**, where power
 | IntegratedFlowSensor   | Measures integral of the flow at its bond   |
 
 In mechanical bond graph models:
-* **flow** corresponds to **velocity**
+* **flow** corresponds to **velocity**, i.e. an *IntegratedFlowSensor* can be used to compute **position**.
 * **effort** corresponds to **force**
 
-An **integrated flow sensor** can therefore be used to compute **position**:
-
 ---
 
 # Example Systems
@@ -153,7 +164,7 @@ The repository contains example models illustrating typical applications of bond
 Demonstrates modeling of an electrical circuit using bond graph elements.
 
 ### DC Motor
-A multi-domain electromechanical system coupling electrical and mechanical dynamics.
+A multi-domain electromechanical system coupling electrical and mechanical dynamics. Also demonstrates integration with the `python-control` package for numerical simulation (step response).
 
 ### Transformer
 Example of energy transformation between two ports.
@@ -163,6 +174,18 @@ Classical mass-spring-damper system with two degrees of freedom.
 
 ---
 
+# Causality Assignment
+
+pyBondGraph supports three modes for assigning causality:
+
+1. **Automatic (SCAP)** — omit causality in `connect()` calls; `assign_causality()` is called automatically when solving. The Sequential Causality Assignment Procedure assigns causality in priority order: sources, storage elements (integral causality), resistors, then propagation through junctions and two-port elements.
+2. **Manual** — pass `Causality.EFFORT_OUT` or `Causality.FLOW_OUT` explicitly to each `connect()` call.
+3. **Mixed** — fix causality on some bonds, let SCAP resolve the rest.
+
+If a storage element cannot receive integral causality (which would imply a DAE rather than an ODE), a `DerivativeCausalityError` is raised with a clear diagnostic message.
+
+---
+
 # Typical Applications
 Bond graph modeling is particularly useful for:
 
@@ -171,3 +194,11 @@ Bond graph modeling is particularly useful for:
 * multi-domain energy systems
 * control system modeling
 * teaching system dynamics
+
+---
+
+# Planned Features
+
+* **FMU Export**: export bond graph models as Functional Mock-up Units (FMI standard) for interoperability with Simulink, Dymola, OpenModelica, and other FMI-compliant tools
+* **Nonlinear element support**: general nonlinear constitutive laws with Jacobian linearization
+* **Convenience bridge to python-control**: `to_control_ss(params)` method wrapping the existing manual pattern

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

@@ -10,9 +10,15 @@ Bond graphs provide a **domain-independent modeling framework** for physical sys
 # Features
 
 * Programmatic construction of **bond graph models**
+* **Automatic causality assignment** via SCAP (Sequential Causality Assignment Procedure), with optional manual override or mixed mode
 * Automatic **symbolic equation derivation** using SymPy
-* Conversion of models to **state-space systems**
-* Example models for electrical and mechanical systems
+* Conversion of models to **linear state-space systems** ($\dot{x} = Ax + Bu$, $y = Cx + Du$)
+* **Composable sub-models** via `SubBondGraph` with deep-copy namespace isolation
+* **Two-port elements**: Transformer and Gyrator with automatic causality propagation
+* **Sensor elements**: `IntegratedEffortSensor` and `IntegratedFlowSensor` for measuring integrated generalized variables (e.g. position from velocity)
+* **Domain-neutral aliases**: `Compliance` = `Capacitor`, `Inertance` = `Inductor`, `Resistance` = `Resistor`
+* Example models for electrical and electromechanical systems
+* Integration with **python-control** for numerical simulation (step response, Bode plots, etc.)
 
 ---
 
@@ -55,12 +61,12 @@ Optional dependencies are used for experimental visualization tools.
 ---
 
 # Basic Usage
-A bond graph model is constructed by creating elements and connecting them via bonds.
+A bond graph model is constructed by creating elements and connecting them via the `connect()` convenience method, which creates bonds and adds them to the graph in one step.
 
-Simple RC-Filter circuit:
+## RC-Filter with automatic causality (SCAP)
 
 ```python
-from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction, Bond, Causality
+from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction
 
 bg = BondGraph()
 
@@ -70,19 +76,20 @@ 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))
+# connect elements --> causality is assigned automatically by SCAP
+bg.connect(voltage_source, series_junction)
+bg.connect(series_junction, resistor)
+bg.connect(series_junction, capacitor)
 
 # 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()
+A, B, C, D, x, n_states, n_inputs, n_outputs = bg.get_state_space()
 ```
 
+Causality can also be assigned **manually** by passing a `Causality` value to `connect()`, or in **mixed mode** where some bonds are fixed and SCAP resolves the rest.
+
 The library automatically derives the **symbolic system equations** describing the dynamics of the model.
 
 ---
@@ -100,6 +107,12 @@ Bond graphs represent **power exchange between system components**, where power
 | Se      | Effort source                            |
 | Sf      | Flow source                              |
 
+## Two-Port Elements
+| Element     | Meaning                                                    |
+|-------------|------------------------------------------------------------|
+| TF          | Transformer — same causality on both bonds                 |
+| GY          | Gyrator — opposite causality on both bonds                 |
+
 ## Junctions
 | Junction | Meaning       |
 |----------|---------------|
@@ -113,11 +126,9 @@ Bond graphs represent **power exchange between system components**, where power
 | IntegratedFlowSensor   | Measures integral of the flow at its bond   |
 
 In mechanical bond graph models:
-* **flow** corresponds to **velocity**
+* **flow** corresponds to **velocity**, i.e. an *IntegratedFlowSensor* can be used to compute **position**.
 * **effort** corresponds to **force**
 
-An **integrated flow sensor** can therefore be used to compute **position**:
-
 ---
 
 # Example Systems
@@ -127,7 +138,7 @@ The repository contains example models illustrating typical applications of bond
 Demonstrates modeling of an electrical circuit using bond graph elements.
 
 ### DC Motor
-A multi-domain electromechanical system coupling electrical and mechanical dynamics.
+A multi-domain electromechanical system coupling electrical and mechanical dynamics. Also demonstrates integration with the `python-control` package for numerical simulation (step response).
 
 ### Transformer
 Example of energy transformation between two ports.
@@ -137,6 +148,18 @@ Classical mass-spring-damper system with two degrees of freedom.
 
 ---
 
+# Causality Assignment
+
+pyBondGraph supports three modes for assigning causality:
+
+1. **Automatic (SCAP)** — omit causality in `connect()` calls; `assign_causality()` is called automatically when solving. The Sequential Causality Assignment Procedure assigns causality in priority order: sources, storage elements (integral causality), resistors, then propagation through junctions and two-port elements.
+2. **Manual** — pass `Causality.EFFORT_OUT` or `Causality.FLOW_OUT` explicitly to each `connect()` call.
+3. **Mixed** — fix causality on some bonds, let SCAP resolve the rest.
+
+If a storage element cannot receive integral causality (which would imply a DAE rather than an ODE), a `DerivativeCausalityError` is raised with a clear diagnostic message.
+
+---
+
 # Typical Applications
 Bond graph modeling is particularly useful for:
 
@@ -144,4 +167,12 @@ Bond graph modeling is particularly useful for:
 * robotics and mechatronics
 * multi-domain energy systems
 * control system modeling
-* teaching system dynamics
+* teaching system dynamics
+
+---
+
+# Planned Features
+
+* **FMU Export**: export bond graph models as Functional Mock-up Units (FMI standard) for interoperability with Simulink, Dymola, OpenModelica, and other FMI-compliant tools
+* **Nonlinear element support**: general nonlinear constitutive laws with Jacobian linearization
+* **Convenience bridge to python-control**: `to_control_ss(params)` method wrapping the existing manual pattern

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

@@ -1,4 +1,4 @@
-from .core import Bond, Causality
+from .core import Bond, Causality, CausalityError, DerivativeCausalityError, Port  # port is a type alias: dict[str, Node]
 from .elements import (
     SourceEffort,
     SourceFlow,
@@ -15,7 +15,6 @@ from .elements import (
 )
 from .sensors import IntegratedEffortSensor, IntegratedFlowSensor
 from .subbondgraph import SubBondGraph
-from .core import Port  # type alias: dict[str, Node]
 
 from .bondgraph import BondGraph
 
@@ -39,4 +38,6 @@ __all__ = [
     "IntegratedFlowSensor",
     "Port",
     "SubBondGraph",
+    "CausalityError",
+    "DerivativeCausalityError",
 ]

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

@@ -10,16 +10,8 @@ import matplotlib.pyplot as plt
 from collections.abc import Callable
 from typing import TYPE_CHECKING
 
-from .core import (
-    Causality,
-    Node,
-    StatefulElement,
-    Bond,
-    ElementOnePort,
-    ElementTwoPort,
-    Junction,
-)
-from .elements import SourceEffort, SourceFlow, OneJunction, ZeroJunction
+from .core import Causality, CausalityError, DerivativeCausalityError, Node, StatefulElement, Bond, ElementOnePort, ElementTwoPort, Junction
+from .elements import SourceEffort, SourceFlow, Capacitor, Inductor, Resistor, Transformer, Gyrator, OneJunction, ZeroJunction
 
 from .core import Port
 
@@ -94,58 +86,52 @@ class BondGraph:
     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.
-            """
+        Iterates over each bond and calls _handle_element() for both the from_element and to_element
+        """
 
+        # Reset element bond references so that repeated calls are safe
+        for el in self.elements:
+            if isinstance(el, ElementOnePort):
+                el.bond = None
+            elif isinstance(el, ElementTwoPort):
+                el.bond1 = None
+                el.bond2 = None
+            elif isinstance(el, Junction):
+                el.bonds = []
+                el.strong_bond = None
+        
+
+        def _handle_element(element: Node, bond: Bond) -> None:
+            """Assign bond to element according to the element's type."""
             if isinstance(element, ElementOnePort):
                 element.bond = bond
 
             elif isinstance(element, ElementTwoPort):
-                if bond.to_element == element:
+                # bond1 = bond INTO the element, bond2 = bond FROM the element
+                if bond.to_element is element:
                     element.bond1 = bond
-                elif bond.from_element == element:
+                elif bond.from_element is element:
                     element.bond2 = bond
+                else:
+                    raise ValueError(f"Bond {bond} is not connected to ElementTwoPort {element}. You have called this function incorrectly.")
 
             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
+                if bond not in element.bonds:
+                    element.bonds.append(bond)
+
+                if self._is_strong_for(bond, element):
+                    if element.strong_bond is None:
+                        element.strong_bond = bond
+                    else:
+                        raise ValueError(
+                            f"{type(element).__name__} {element} already has a strong bond: "
+                            f"{element.strong_bond}. Cannot assign {bond}."
+                        )
+
         for bond in self.bonds:
-            handle_bond_element(bond.from_element, bond)
-            handle_bond_element(bond.to_element, bond)
+            _handle_element(bond.from_element, bond)
+            _handle_element(bond.to_element, bond)
 
     def __handle_equations(self) -> None:
         """Accumulates the equations from all elements and junctions in the bond graph.
@@ -173,7 +159,7 @@ class BondGraph:
                 bond1 = element.bond1
                 bond2 = element.bond2
                 if bond1 is None or bond2 is None:
-                    raise ValueError(f"Element {element} has no connected bonds.")
+                    raise ValueError(f"Element {element} is not fully connected with bonds.")
 
                 # Add equations from the element to the bond graph
                 self.equations.extend(element.equations)
@@ -192,6 +178,10 @@ class BondGraph:
             The keys include the time derivatives of the state variables and the efforts and flows of all bonds.
         """
 
+        # Auto-assign causality if any bonds lack it
+        if any(b.causality is None for b in self.bonds):
+            self.assign_causality()
+
         self.__handle_bonds()
         self.__handle_equations()
         state_derivatives = [sp.Derivative(var, "t") for var in self.state_vars]
@@ -303,7 +293,7 @@ class BondGraph:
         self,
         node_a: Node,
         node_b: Node,
-        causality: Causality = Causality.EFFORT_OUT,
+        causality: Causality | None = None,
     ) -> Bond:
         """Connect two nodes by adding a bond between them.
 
@@ -331,9 +321,11 @@ class BondGraph:
             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``.
+        causality : Causality | None, optional
+            Causality of the connecting bond.  Defaults to ``None``,
+            meaning causality will be assigned later by
+            :meth:`assign_causality` (SCAP).  Pass a ``Causality``
+            value explicitly to override automatic assignment.
 
         Returns
         -------
@@ -362,6 +354,241 @@ class BondGraph:
         self.add_bond(bond)
         return bond
 
+    # --- shared helpers (used by both assign_causality and __handle_bonds) ---
+    def _elements_of_type(self, *types: type) -> list[Node]:
+        """Yield all elements that are instances of types."""
+        return [el for el in self.elements if isinstance(el, types)]
+
+    @staticmethod
+    def _is_strong_for(bond: Bond, junc: Junction) -> bool:
+        """Return True if bond is the strong bond at junc."""
+        if bond.causality is None:
+            return False
+        
+        if isinstance(junc, OneJunction):
+            return (
+                (bond.from_element is junc and bond.causality == Causality.EFFORT_OUT)
+                or (bond.to_element is junc and bond.causality == Causality.FLOW_OUT)
+            )
+        elif isinstance(junc, ZeroJunction):
+            return (
+                (bond.from_element is junc and bond.causality == Causality.FLOW_OUT)
+                or (bond.to_element is junc and bond.causality == Causality.EFFORT_OUT)
+            )
+        return False
+
+    @staticmethod
+    def _make_strong(bond: Bond, junc: Junction) -> Causality:
+        """Return the causality that makes bond the strong bond at junc."""
+        junc_is_from = bond.from_element is junc
+
+        if isinstance(junc, OneJunction):
+            return Causality.EFFORT_OUT if junc_is_from else Causality.FLOW_OUT
+        else:  # ZeroJunction
+            return Causality.FLOW_OUT if junc_is_from else Causality.EFFORT_OUT
+
+    @staticmethod
+    def _make_weak(bond: Bond, junc: Junction) -> Causality:
+        """Return the causality that makes bond a weak bond at junc.
+
+        This is the inverse of :meth:`_make_strong`.
+        """
+        # inverse mapping of strong to weak causality
+        strong_to_weak = {
+            Causality.EFFORT_OUT: Causality.FLOW_OUT,
+            Causality.FLOW_OUT: Causality.EFFORT_OUT,
+        }
+
+        strong = BondGraph._make_strong(bond, junc)
+
+        return strong_to_weak[strong]
+
+    def assign_causality(self) -> None:
+        """Run the Sequential Causality Assignment Procedure (SCAP).
+
+        Assigns causality to every bond that currently has
+        ``causality = None``.  Bonds whose causality was set explicitly
+        (manually or via ``add_bond`` / ``connect``) are respected as
+        fixed constraints.
+
+        The algorithm proceeds in priority order:
+
+        1. Sources: fixed causality (Se outputs effort, Sf outputs flow).
+        2. Storage elements: preferred integral causality (C outputs effort, I outputs flow).
+        3. Remaining bonds: assigned by propagation through junctions and two-port elements.
+
+        After each assignment the consequences are propagated through connected junctions
+        (exactly one strong bond each) and two-port elements
+        (transformer: same causality on both bonds; gyrator: opposite causality).
+
+        Raises
+        ------
+        DerivativeCausalityError
+            If a storage element cannot receive its preferred integral causality.
+            This indicates the system contains algebraic constraints (DAE instead of ODE) which are not supported.
+        CausalityError
+            If causality cannot be fully resolved (should not happen for a well-formed bond graph).
+        """
+
+        # Populate bond references on elements so we can use access them when assigning causality.
+        self.__handle_bonds()
+
+        # Track which bonds still need assignment
+        unassigned: set[Bond] = {b for b in self.bonds if b.causality is None}
+
+        if not unassigned:
+            return
+
+        def _assign(bond: Bond, causality: Causality) -> None:
+            """Assign causality to a bond and remove it from the unassigned set."""
+            bond.causality = causality
+            unassigned.discard(bond)
+
+        def _propagate() -> None:
+            """Propagate causality through junctions and two-port elements
+            until no further assignments can be made."""
+            if not unassigned:
+                return
+
+            changed = True
+            while changed:
+                changed = False
+
+                # Junctions: if any strong bond exists, all unassigned bonds must be weak
+                for junc in self._elements_of_type(Junction):
+                    assigned_bonds = [b for b in junc.bonds if b.causality is not None]
+                    unassigned_here = [b for b in junc.bonds if b.causality is None]
+                    if not unassigned_here:
+                        continue
+
+                    has_strong = any(self._is_strong_for(b, junc) for b in assigned_bonds)
+
+                    if has_strong:
+                        for b in unassigned_here:
+                            _assign(b, self._make_weak(b, junc))
+                            changed = True
+                    elif len(unassigned_here) == 1:
+                        _assign(unassigned_here[0], self._make_strong(unassigned_here[0], junc))
+                        changed = True
+
+                # Two-port elements: if one bond has causality, the other must be assigned accordingly
+                for tp_elem in self._elements_of_type(ElementTwoPort):
+                    b1, b2 = tp_elem.bond1, tp_elem.bond2
+                    if b1 is None or b2 is None:
+                        continue
+
+                    src, dst = None, None
+                    if b1.causality is not None and b2.causality is None:
+                        src, dst = b1, b2
+                    elif b2.causality is not None and b1.causality is None:
+                        src, dst = b2, b1
+                    else:
+                        continue
+
+                    if isinstance(tp_elem, Transformer):
+                        _assign(dst, src.causality)
+                    else:  # Gyrator — opposite causality
+                        opp = Causality.FLOW_OUT if src.causality == Causality.EFFORT_OUT else Causality.EFFORT_OUT
+                        _assign(dst, opp)
+                    changed = True
+
+                if not unassigned:
+                    return
+
+        def _desired_causality(element: ElementOnePort, bond: Bond) -> Causality:
+            """Return the causality the element wants (from from_element perspective)."""
+            el_is_from = bond.from_element is element
+            if isinstance(element, (SourceEffort, Capacitor)):
+                return Causality.EFFORT_OUT if el_is_from else Causality.FLOW_OUT
+            elif isinstance(element, (SourceFlow, Inductor)):
+                return Causality.FLOW_OUT if el_is_from else Causality.EFFORT_OUT
+            return None
+
+        def _would_conflict_with_junction(bond: Bond, causality: Causality) -> bool:
+            """Check if assigning *causality* to *bond* would create a
+            second strong bond at any connected junction."""
+            for el in bond.elements:
+                if not isinstance(el, Junction):
+                    continue
+                # Temporarily check what this would mean
+                old = bond.causality
+                bond.causality = causality
+                is_strong = self._is_strong_for(bond, el)
+                bond.causality = old
+                if is_strong:
+                    other_bonds = [b for b in el.bonds if b is not bond and b.causality is not None]
+                    if any(self._is_strong_for(ob, el) for ob in other_bonds):
+                        return True
+            return False
+
+        # --- Phase 1: Sources (fixed causality) -----------------------------
+        for elem in self._elements_of_type(SourceEffort, SourceFlow):
+            if elem.bond.causality is None:
+                _assign(elem.bond, _desired_causality(elem, elem.bond))
+        _propagate()
+
+        # --- Phase 2: Storage elements (integral causality) -----------------
+        for elem in self._elements_of_type(Capacitor, Inductor):
+            if elem.bond.causality is not None:
+                continue
+            desired = _desired_causality(elem, elem.bond)
+            if not _would_conflict_with_junction(elem.bond, desired):
+                _assign(elem.bond, desired)
+            else:
+                raise DerivativeCausalityError(
+                    f"Storage element '{elem.name}' ({type(elem).__name__}) "
+                    f"cannot receive its preferred integral causality "
+                    f"because a connected junction already has a strong bond. "
+                    f"This forces derivative causality, turning the system "
+                    f"into a DAE (differential-algebraic equation) which is "
+                    f"not supported.\n"
+                    f"Suggestion: insert a resistive element (R) between "
+                    f"conflicting storage elements, or restructure the model."
+                )
+        _propagate()
+
+        # --- Phase 3: Resistors and remaining bonds -------------------------
+        for elem in self._elements_of_type(Resistor):
+            if elem.bond.causality is not None:
+                continue
+            bond = elem.bond
+            # Determine from the connected junction what this bond needs
+            other_el = bond.to_element if bond.from_element is elem else bond.from_element
+            if isinstance(other_el, Junction):
+                assigned_bonds = [b for b in other_el.bonds if b.causality is not None]
+                has_strong = any(self._is_strong_for(b, other_el) for b in assigned_bonds)
+                if has_strong:
+                    _assign(bond, self._make_weak(bond, other_el))
+                elif len([b for b in other_el.bonds if b.causality is None]) == 1:
+                    # if this is the only unassigned bond at the junction, it must be strong
+                    _assign(bond, self._make_strong(bond, other_el))
+        _propagate()
+
+        # --- Validate: two-port causality consistency -----------------------
+        for tp_elem in self._elements_of_type(ElementTwoPort):
+            b1, b2 = tp_elem.bond1, tp_elem.bond2
+            if b1 is None or b2 is None:
+                continue
+            if isinstance(tp_elem, Transformer) and b1.causality != b2.causality:
+                raise CausalityError(
+                    f"Transformer '{tp_elem.name}' requires both bonds to have the "
+                    f"same causality, but bond1={b1.causality} and bond2={b2.causality}."
+                )
+            if isinstance(tp_elem, Gyrator) and b1.causality == b2.causality:
+                raise CausalityError(
+                    f"Gyrator '{tp_elem.name}' requires both bonds to have different "
+                    f"causality, but both are {b1.causality}."
+                )
+
+        # --- Validate: unassigned bonds -------------------------------------
+        if unassigned:
+            descriptions = [f"  Bond({b.from_element.name} -> {b.to_element.name})" for b in unassigned]
+            raise CausalityError(
+                f"SCAP could not assign causality to {len(unassigned)} bond(s):\n"
+                + "\n".join(descriptions)
+                + "\nCheck that the bond graph is fully connected and well-formed."
+            )
+
     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.
 
@@ -432,7 +659,7 @@ class BondGraph:
         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
+            # Vary the parameter t \in [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)
@@ -469,7 +696,7 @@ class BondGraph:
                 If the 'at' parameter is not "head" or "tail".
             """
 
-            # --- Convert node size (points^2) to radius in pixels ---
+            # Convert node size (points^2, i.e. area) 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
@@ -515,6 +742,8 @@ class BondGraph:
                 _stroke_specs.append((pos[u], pos[v], "head", -2))
             elif causality is Causality.FLOW_OUT:
                 _stroke_specs.append((pos[u], pos[v], "tail", -2))
+            elif causality is None:
+                pass  # No causality assigned yet — skip causal stroke
             else:
                 raise ValueError(f"Edge {u}->{v} has no valid causality: {causality} --> this should never happen!")
 

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

@@ -17,6 +17,20 @@ class Causality(Enum):
     FLOW_OUT = "flow_out"
 
 
+class CausalityError(Exception):
+    """Raised when automatic causality assignment (SCAP) fails."""
+    pass
+
+
+class DerivativeCausalityError(CausalityError):
+    """Raised when a storage element would require derivative causality.
+
+    Derivative causality turns the system into a DAE (differential-algebraic equation) which cannot directly be transformed into state-space representation.
+    Consider adding a small resistance (or the like) between conflicting storage elements or restructuring the model.
+    """
+    pass
+
+
 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.
@@ -51,7 +65,15 @@ class Bond:
 
     _counter = 0  # Global fallback counter; prefer BondGraph-scoped numbering
 
-    def __init__(self, from_element: Node, to_element: Node, causality: str | Causality, num: int | None = None, instance_name: str = "", is_prefix: bool = True):
+    def __init__(
+        self,
+        from_element: Node,
+        to_element: Node,
+        causality: str | Causality | None = None,
+        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.
@@ -62,7 +84,7 @@ class Bond:
             The element where the bond originates.
         to_element : Node
             The element where the bond terminates.
-        causality : str | Causality
+        causality : str | Causality | None, optional
             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`.
@@ -70,6 +92,7 @@ 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.
+            If None, the causality must be assigned later by calling (manually or automatically) the bond graph's causality assignment algorithm.
         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.
@@ -89,10 +112,11 @@ class Bond:
         self.to_element = to_element
 
         if isinstance(causality, str):
-            causality = Causality(causality.lower()) # Convert string to Causality enum, case insensitive
+            causality = Causality(causality.lower())
+            # Convert string to Causality enum, case insensitive
             # --> automatically raises ValueError if string is not valid
 
-        self.causality: Causality = causality
+        self.causality: Causality | None = causality
 
         if num is None:
             self.num = Bond._counter
@@ -114,7 +138,12 @@ class Bond:
         """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]:
+    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.
 
@@ -140,13 +169,12 @@ class Bond:
         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            
+            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)
 
@@ -198,7 +226,9 @@ class ElementOnePort(Node, ABC):
         """
 
         super().__init__(name)
-        self.value = sp.Symbol(value, real=True, positive=True)  # Ensure value is a positive real number
+        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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.2.0
+Version: 0.3.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
@@ -36,9 +36,15 @@ Bond graphs provide a **domain-independent modeling framework** for physical sys
 # Features
 
 * Programmatic construction of **bond graph models**
+* **Automatic causality assignment** via SCAP (Sequential Causality Assignment Procedure), with optional manual override or mixed mode
 * Automatic **symbolic equation derivation** using SymPy
-* Conversion of models to **state-space systems**
-* Example models for electrical and mechanical systems
+* Conversion of models to **linear state-space systems** ($\dot{x} = Ax + Bu$, $y = Cx + Du$)
+* **Composable sub-models** via `SubBondGraph` with deep-copy namespace isolation
+* **Two-port elements**: Transformer and Gyrator with automatic causality propagation
+* **Sensor elements**: `IntegratedEffortSensor` and `IntegratedFlowSensor` for measuring integrated generalized variables (e.g. position from velocity)
+* **Domain-neutral aliases**: `Compliance` = `Capacitor`, `Inertance` = `Inductor`, `Resistance` = `Resistor`
+* Example models for electrical and electromechanical systems
+* Integration with **python-control** for numerical simulation (step response, Bode plots, etc.)
 
 ---
 
@@ -81,12 +87,12 @@ Optional dependencies are used for experimental visualization tools.
 ---
 
 # Basic Usage
-A bond graph model is constructed by creating elements and connecting them via bonds.
+A bond graph model is constructed by creating elements and connecting them via the `connect()` convenience method, which creates bonds and adds them to the graph in one step.
 
-Simple RC-Filter circuit:
+## RC-Filter with automatic causality (SCAP)
 
 ```python
-from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction, Bond, Causality
+from pyBondGraph import BondGraph, SourceEffort, Resistor, Capacitor, OneJunction
 
 bg = BondGraph()
 
@@ -96,19 +102,20 @@ 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))
+# connect elements --> causality is assigned automatically by SCAP
+bg.connect(voltage_source, series_junction)
+bg.connect(series_junction, resistor)
+bg.connect(series_junction, capacitor)
 
 # 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()
+A, B, C, D, x, n_states, n_inputs, n_outputs = bg.get_state_space()
 ```
 
+Causality can also be assigned **manually** by passing a `Causality` value to `connect()`, or in **mixed mode** where some bonds are fixed and SCAP resolves the rest.
+
 The library automatically derives the **symbolic system equations** describing the dynamics of the model.
 
 ---
@@ -126,6 +133,12 @@ Bond graphs represent **power exchange between system components**, where power
 | Se      | Effort source                            |
 | Sf      | Flow source                              |
 
+## Two-Port Elements
+| Element     | Meaning                                                    |
+|-------------|------------------------------------------------------------|
+| TF          | Transformer — same causality on both bonds                 |
+| GY          | Gyrator — opposite causality on both bonds                 |
+
 ## Junctions
 | Junction | Meaning       |
 |----------|---------------|
@@ -139,11 +152,9 @@ Bond graphs represent **power exchange between system components**, where power
 | IntegratedFlowSensor   | Measures integral of the flow at its bond   |
 
 In mechanical bond graph models:
-* **flow** corresponds to **velocity**
+* **flow** corresponds to **velocity**, i.e. an *IntegratedFlowSensor* can be used to compute **position**.
 * **effort** corresponds to **force**
 
-An **integrated flow sensor** can therefore be used to compute **position**:
-
 ---
 
 # Example Systems
@@ -153,7 +164,7 @@ The repository contains example models illustrating typical applications of bond
 Demonstrates modeling of an electrical circuit using bond graph elements.
 
 ### DC Motor
-A multi-domain electromechanical system coupling electrical and mechanical dynamics.
+A multi-domain electromechanical system coupling electrical and mechanical dynamics. Also demonstrates integration with the `python-control` package for numerical simulation (step response).
 
 ### Transformer
 Example of energy transformation between two ports.
@@ -163,6 +174,18 @@ Classical mass-spring-damper system with two degrees of freedom.
 
 ---
 
+# Causality Assignment
+
+pyBondGraph supports three modes for assigning causality:
+
+1. **Automatic (SCAP)** — omit causality in `connect()` calls; `assign_causality()` is called automatically when solving. The Sequential Causality Assignment Procedure assigns causality in priority order: sources, storage elements (integral causality), resistors, then propagation through junctions and two-port elements.
+2. **Manual** — pass `Causality.EFFORT_OUT` or `Causality.FLOW_OUT` explicitly to each `connect()` call.
+3. **Mixed** — fix causality on some bonds, let SCAP resolve the rest.
+
+If a storage element cannot receive integral causality (which would imply a DAE rather than an ODE), a `DerivativeCausalityError` is raised with a clear diagnostic message.
+
+---
+
 # Typical Applications
 Bond graph modeling is particularly useful for:
 
@@ -171,3 +194,11 @@ Bond graph modeling is particularly useful for:
 * multi-domain energy systems
 * control system modeling
 * teaching system dynamics
+
+---
+
+# Planned Features
+
+* **FMU Export**: export bond graph models as Functional Mock-up Units (FMI standard) for interoperability with Simulink, Dymola, OpenModelica, and other FMI-compliant tools
+* **Nonlinear element support**: general nonlinear constitutive laws with Jacobian linearization
+* **Convenience bridge to python-control**: `to_control_ss(params)` method wrapping the existing manual pattern

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

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