pyBondGraph 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.3.0
+Version: 0.4.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
@@ -19,6 +19,7 @@ Requires-Dist: networkx>=3.5
 Requires-Dist: numpy>=2.3.0
 Requires-Dist: matplotlib>=3.10.3
 Requires-Dist: control>=0.10.2
+Requires-Dist: pythonfmu3>=0.3.4
 Provides-Extra: streamlit
 Requires-Dist: streamlit>=1.47.0; extra == "streamlit"
 Requires-Dist: streamlit-flow-component>=1.6.1; extra == "streamlit"
@@ -29,6 +30,8 @@ Dynamic: license-file
 
 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.
 
+`pyBondGraph` can also export FMUs [(Functional Mock-up Units)](https://fmi-standard.org/) based on FMI 3.0 for Model Exchange, enabling interoperability with other simulation tools such as Simulink.
+
 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.
 
 ---
@@ -112,6 +115,8 @@ bg.plot()
 
 # derive system equations in linear state space form
 A, B, C, D, x, n_states, n_inputs, n_outputs = bg.get_state_space()
+
+bg.to_fmu("rc_filter")
 ```
 
 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.
@@ -199,6 +204,4 @@ Bond graph modeling is particularly useful for:
 
 # 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.3.0 → pybondgraph-0.4.0}/README.md

@@ -3,6 +3,8 @@
 
 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.
 
+`pyBondGraph` can also export FMUs [(Functional Mock-up Units)](https://fmi-standard.org/) based on FMI 3.0 for Model Exchange, enabling interoperability with other simulation tools such as Simulink.
+
 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.
 
 ---
@@ -86,6 +88,8 @@ bg.plot()
 
 # derive system equations in linear state space form
 A, B, C, D, x, n_states, n_inputs, n_outputs = bg.get_state_space()
+
+bg.to_fmu("rc_filter")
 ```
 
 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.
@@ -173,6 +177,4 @@ Bond graph modeling is particularly useful for:
 
 # 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
+* **Nonlinear element support**: general nonlinear constitutive laws with Jacobian linearization

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

@@ -18,6 +18,10 @@ from .subbondgraph import SubBondGraph
 
 from .bondgraph import BondGraph
 
+from .numerics import to_numpy, to_control_ss
+
+from .fmu_export import to_fmu
+
 __all__ = [
     "Bond",
     "Causality",
@@ -40,4 +44,7 @@ __all__ = [
     "SubBondGraph",
     "CausalityError",
     "DerivativeCausalityError",
+    "to_numpy",
+    "to_control_ss",
+    "to_fmu",
 ]

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

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from pathlib import Path
+
 import sympy as sp
 import networkx as nx
 import numpy as np
@@ -14,6 +16,8 @@ from .core import Causality, CausalityError, DerivativeCausalityError, Node, Sta
 from .elements import SourceEffort, SourceFlow, Capacitor, Inductor, Resistor, Transformer, Gyrator, OneJunction, ZeroJunction
 
 from .core import Port
+from .numerics import to_numpy, to_control_ss
+from .fmu_export import to_fmu
 
 if TYPE_CHECKING:
     from .subbondgraph import SubBondGraph
@@ -265,6 +269,127 @@ class BondGraph:
 
         return A, B, C, D, sp.Matrix(self.state_vars), n_states, n_inputs, n_outputs
 
+    def get_substitution_dict(self, overrides: dict[sp.Symbol, float] | None = None) -> dict[sp.Symbol, float]:
+        """Build a substitution dictionary from elements that have a ``numeric_value`` set.
+
+        Iterates over all :class:`ElementOnePort` and :class:`ElementTwoPort` elements
+        in the bond graph and maps each element's symbolic ``value`` to its ``numeric_value``.
+        Elements without a ``numeric_value`` (i.e. ``None``) are silently skipped.
+
+        Parameters
+        ----------
+        overrides : dict[sp.Symbol, float] | None, optional
+            Additional or overriding entries merged into the result.
+            This is useful for parameter sweeps or for supplying values
+            that are not stored on the elements (e.g. external inputs).
+
+        Returns
+        -------
+        dict[sp.Symbol, float]
+            Mapping from symbolic parameter to numeric value.
+
+        Raises
+        ------
+        ValueError
+            If any element with a ``numeric_value`` would overwrite an
+            already-collected symbol with a *different* value (duplicate
+            symbols with the same numeric value are fine).
+        """
+        subs: dict[sp.Symbol, float] = {}
+
+        for elem in self.elements:
+
+            if isinstance(elem, (ElementOnePort, ElementTwoPort)) and elem.numeric_value is not None:
+                if elem.value in subs and subs[elem.value] != elem.numeric_value:
+                    raise ValueError(
+                        f"Conflicting numeric values for symbol '{elem.value}': "
+                        f"{subs[elem.value]} vs {elem.numeric_value} (element '{elem.name}')."
+                    )
+                
+                subs[elem.value] = elem.numeric_value
+
+        # update dict with manually provded overrides (if any)
+        if overrides:
+            subs.update(overrides)
+
+        return subs
+
+    def get_numeric_state_space(
+        self,
+        subs: dict[sp.Symbol, float] | None = None,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        """Return the numeric (numpy) state-space matrices ``(A, B, C, D)``.
+
+        This is a convenience wrapper around :meth:`get_state_space` that
+        substitutes numeric parameter values and converts the resulting
+        symbolic matrices to :class:`numpy.ndarray`.
+
+        Parameters
+        ----------
+        subs : dict[sp.Symbol, float] | None, optional
+            Explicit substitution dictionary.  If ``None``,
+            :meth:`get_substitution_dict` is called to collect the values
+            stored on the elements.  If provided, it is used as-is (no
+            merging with element values).
+
+        Returns
+        -------
+        tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]
+            Numeric matrices ``(A, B, C, D)``.
+
+        Raises
+        ------
+        ValueError
+            If the symbolic state-space cannot be computed, or if free
+            symbols remain after substitution (i.e. some parameters have
+            no numeric value).
+        """
+        A, B, C, D, _x, _ns, _ni, _no = self.get_state_space()
+
+        if subs is None:
+            subs = self.get_substitution_dict()
+
+        # Check for remaining free symbols before conversion
+        free = set()
+        for M in (A, B, C, D):
+            free |= M.free_symbols
+        remaining = free - set(subs.keys())
+
+        if remaining:
+            raise ValueError(
+                f"The following symbols have no numeric value: {remaining}. "
+                f"Set numeric_value on the corresponding elements or pass them via the subs parameter."
+            )
+
+        return tuple(to_numpy(M, subs) for M in (A, B, C, D))
+    
+    def to_control_ss(self):
+        """Generate a control.StateSpace object from the bond graph's numeric state-space matrices.
+
+        Returns
+        -------
+        control.StateSpace
+            The :class:`control.StateSpace` object representing the bond graph's linear dynamics.
+
+        Raises
+        ------
+        ValueError
+            Raises a value error through :meth:`get_numeric_state_space` if not all numerical values required are set beforehand in the bondgraph elements            
+        """
+
+        matrices = self.get_numeric_state_space()
+        return to_control_ss(*matrices)
+
+
+
+    def to_fmu(self, model_name: str = "BondGraphExport", dest: str | Path = ".", author_name: str = "MtP", description: str = "A bond graph model.", keep_slave_python_code: bool = False) -> None:
+        # if default class name is used, use the bondgraph name if it is set
+        if model_name == "BondGraphExport" and self.name:
+            model_name = self.name
+
+        to_fmu(self, dest=dest, class_name=model_name, author_name=author_name, description=description, keep_slave_python_code=keep_slave_python_code)
+
+
     def add_subbondgraph(self, sub_bondgraph: SubBondGraph, instance_name: str | None = None, is_prefix: bool = True) -> Port:
         """Instantiate a SubBondGraph into this bond graph.
 

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

@@ -213,7 +213,7 @@ class ElementOnePort(Node, ABC):
     This can also be just one equation.
     """
 
-    def __init__(self, name: str, value: str):
+    def __init__(self, name: str, value: str, numeric_value: float | None = None):
         """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.
 
@@ -223,12 +223,16 @@ class ElementOnePort(Node, ABC):
             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`.
+        numeric_value : float | None, optional
+            Numeric value for the element parameter. If provided, it is used
+            when building substitution dictionaries for numeric evaluation.
         """
 
         super().__init__(name)
         self.value = sp.Symbol(
             value, real=True, positive=True
         )  # Ensure value is a positive real number
+        self.numeric_value: float | None = numeric_value
         self.bond: Bond = None  # bond that connects this element to a bond graph
 
     @property
@@ -246,7 +250,7 @@ class ElementTwoPort(Node, ABC):
     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):
+    def __init__(self, name: str, value: str, numeric_value: float | None = None):
         """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.
 
@@ -256,10 +260,14 @@ class ElementTwoPort(Node, ABC):
             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`.
+        numeric_value : float | None, optional
+            Numeric value for the element parameter. If provided, it is used
+            when building substitution dictionaries for numeric evaluation.
         """
 
         super().__init__(name)
         self.value = sp.Symbol(value, real=True, positive=True)
+        self.numeric_value: float | None = numeric_value
         self.bond1: Bond = None  # ElementOther   --(bond1)--> ElementTwoPort
         self.bond2: Bond = None  # ElementTwoPort --(bond2)--> ElementOther
 

{pybondgraph-0.3.0 → pybondgraph-0.4.0}/pyBondGraph/elements.py

@@ -53,7 +53,7 @@ class Capacitor(ElementOnePort, StatefulElement):
     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):
+    def __init__(self, name: str, value: str, numeric_value: float = None):
         """Create a linear compliance/capacitance element in the bond graph.
 
         Parameters
@@ -62,8 +62,10 @@ class Capacitor(ElementOnePort, StatefulElement):
             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`.
+        numeric_value : float, optional
+            The numeric value of the capacitance, used for numerical simulations.
         """
-        super().__init__(name, value)
+        super().__init__(name, value, numeric_value)
 
     @property
     def state_var(self) -> sp.Symbol:
@@ -102,7 +104,7 @@ class Inductor(ElementOnePort, StatefulElement):
     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):
+    def __init__(self, name: str, value: str, numeric_value: float = None):
         """Create a linear inertia/inductance element in the bond graph.
 
         Parameters
@@ -111,8 +113,10 @@ class Inductor(ElementOnePort, StatefulElement):
             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`.
+        numeric_value : float, optional
+            The numeric value of the inductance, used for numerical simulations.
         """
-        super().__init__(name, value)
+        super().__init__(name, value, numeric_value)
 
     @property
     def state_var(self) -> sp.Symbol:
@@ -151,7 +155,7 @@ class Resistor(ElementOnePort):
     A resistor relates the effort and flow of its port by a constant resistance value.
     """
 
-    def __init__(self, name: str, value: str):
+    def __init__(self, name: str, value: str, numeric_value: float = None):
         """Create a linear resistance element.
 
         Parameters
@@ -160,8 +164,10 @@ class Resistor(ElementOnePort):
             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`.
+        numeric_value : float, optional
+            The numeric value of the resistance, used for numerical simulations.
         """
-        super().__init__(name, value)
+        super().__init__(name, value, numeric_value)
 
     @property
     def equations(self) -> list[sp.Expr]:
@@ -190,7 +196,7 @@ class Transformer(ElementTwoPort):
     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):
+    def __init__(self, name: str, value: str, numeric_value: float = None):
         """Create a transformer element in the bond graph.
 
         Parameters
@@ -199,8 +205,10 @@ class Transformer(ElementTwoPort):
             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`.
+        numeric_value : float, optional
+            The numeric value of the transformer ratio, used for numerical simulations.
         """
-        super().__init__(name, value)
+        super().__init__(name, value, numeric_value)
 
     @property
     def equations(self) -> list[sp.Expr]:
@@ -242,7 +250,7 @@ class Gyrator(ElementTwoPort):
     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):
+    def __init__(self, name: str, value: str, numeric_value: float = None):
         """Create a gyrator element in the bond graph.
 
         Parameters
@@ -251,8 +259,10 @@ class Gyrator(ElementTwoPort):
             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`.
+        numeric_value : float, optional
+            The numeric value of the gyrator ratio, used for numerical simulations.
         """
-        super().__init__(name, value)
+        super().__init__(name, value, numeric_value)
 
     @property
     def equations(self) -> list[sp.Expr]:

pybondgraph-0.4.0/pyBondGraph/numerics.py

@@ -0,0 +1,57 @@
+import numpy as np
+import sympy as sp
+
+
+def to_numpy(
+    M: sp.Matrix,
+    subs: dict[sp.Symbol, float],
+) -> np.ndarray:
+    """Convert a symbolic SymPy matrix to a numeric NumPy array.
+
+    Parameters
+    ----------
+    M : sp.Matrix
+        Symbolic matrix.
+    subs : dict[sp.Symbol, float]
+        Substitution dictionary mapping symbols to numeric values.
+
+    Returns
+    -------
+    np.ndarray
+        Float64 array.
+    """
+    return np.array(M.subs(subs), dtype=np.float64)
+
+
+def to_control_ss(A: sp.Matrix | np.ndarray, B: sp.Matrix | np.ndarray, C: sp.Matrix | np.ndarray, D: sp.Matrix | np.ndarray, subs: dict[sp.Symbol, float] | None = None):
+    """Convert state-space matrices to a :class:`control.StateSpace` object.
+
+    Parameters
+    ----------
+    A, B, C, D : sp.Matrix or np.ndarray
+        State-space matrices (symbolic or already numeric).
+    subs : dict, optional
+        Substitution dictionary.  If provided the symbolic matrices are
+        substituted and converted to NumPy arrays first.
+
+    Returns
+    -------
+    control.StateSpace
+
+    Raises
+    ------
+    ImportError
+        If the ``control`` package is not installed.
+    """
+    try:
+        import control
+    except ImportError:
+        raise ImportError(
+            "python-control is required for to_control_ss(). "
+            "Install it with: pip install control"
+        )
+
+    if subs is not None:
+        A, B, C, D = (to_numpy(M, subs) for M in (A, B, C, D))
+
+    return control.ss(A, B, C, D)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.3.0
+Version: 0.4.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
@@ -19,6 +19,7 @@ Requires-Dist: networkx>=3.5
 Requires-Dist: numpy>=2.3.0
 Requires-Dist: matplotlib>=3.10.3
 Requires-Dist: control>=0.10.2
+Requires-Dist: pythonfmu3>=0.3.4
 Provides-Extra: streamlit
 Requires-Dist: streamlit>=1.47.0; extra == "streamlit"
 Requires-Dist: streamlit-flow-component>=1.6.1; extra == "streamlit"
@@ -29,6 +30,8 @@ Dynamic: license-file
 
 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.
 
+`pyBondGraph` can also export FMUs [(Functional Mock-up Units)](https://fmi-standard.org/) based on FMI 3.0 for Model Exchange, enabling interoperability with other simulation tools such as Simulink.
+
 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.
 
 ---
@@ -112,6 +115,8 @@ bg.plot()
 
 # derive system equations in linear state space form
 A, B, C, D, x, n_states, n_inputs, n_outputs = bg.get_state_space()
+
+bg.to_fmu("rc_filter")
 ```
 
 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.
@@ -199,6 +204,4 @@ Bond graph modeling is particularly useful for:
 
 # 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.3.0 → pybondgraph-0.4.0}/pyBondGraph.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ pyBondGraph/__init__.py
 pyBondGraph/bondgraph.py
 pyBondGraph/core.py
 pyBondGraph/elements.py
+pyBondGraph/numerics.py
 pyBondGraph/sensors.py
 pyBondGraph/subbondgraph.py
 pyBondGraph.egg-info/PKG-INFO

{pybondgraph-0.3.0 → pybondgraph-0.4.0}/pyBondGraph.egg-info/requires.txt

@@ -3,6 +3,7 @@ networkx>=3.5
 numpy>=2.3.0
 matplotlib>=3.10.3
 control>=0.10.2
+pythonfmu3>=0.3.4
 
 [streamlit]
 streamlit>=1.47.0

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

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

{pybondgraph-0.3.0 → pybondgraph-0.4.0}/requirements.txt

@@ -2,4 +2,5 @@ sympy>=1.14.0
 networkx>=3.5
 numpy>=2.3.0
 matplotlib>=3.10.3
-control>=0.10.2
+control>=0.10.2
+pythonfmu3>=0.3.4