pyBondGraph 0.2.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyBondGraph
-Version: 0.2.1
+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.
 
 ---
@@ -36,10 +39,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
-* Capaility to **store** and **load** bond graph models in JSON format construct bond graphs from loaded sub bond graphs
+* 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.)
 
 ---
 
@@ -82,12 +90,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()
 
@@ -97,19 +105,22 @@ resistor = Resistor("R", "R")
 capacitor = Capacitor("C", "C")
 series_junction = OneJunction("J1")
 
-# connect elements
-# causalities need to be assigned manually ^
-bg.connect(voltage_source, series_junction, Causality.EFFORT_OUT)
-bg.connect(series_junction, resistor, Causality.EFFORT_OUT)
-bg.connect(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()
+
+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.
+
 The library automatically derives the **symbolic system equations** describing the dynamics of the model.
 
 ---
@@ -127,6 +138,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       |
 |----------|---------------|
@@ -140,11 +157,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
@@ -154,7 +169,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.
@@ -164,6 +179,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:
 
@@ -172,3 +199,9 @@ Bond graph modeling is particularly useful for:
 * multi-domain energy systems
 * control system modeling
 * teaching system dynamics
+
+---
+
+# Planned Features
+
+* **Nonlinear element support**: general nonlinear constitutive laws with Jacobian linearization

{pybondgraph-0.2.1 → 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.
 
 ---
@@ -10,10 +12,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
-* Capaility to **store** and **load** bond graph models in JSON format construct bond graphs from loaded sub bond graphs
+* 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.)
 
 ---
 
@@ -56,12 +63,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()
 
@@ -71,19 +78,22 @@ resistor = Resistor("R", "R")
 capacitor = Capacitor("C", "C")
 series_junction = OneJunction("J1")
 
-# connect elements
-# causalities need to be assigned manually ^
-bg.connect(voltage_source, series_junction, Causality.EFFORT_OUT)
-bg.connect(series_junction, resistor, Causality.EFFORT_OUT)
-bg.connect(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()
+
+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.
+
 The library automatically derives the **symbolic system equations** describing the dynamics of the model.
 
 ---
@@ -101,6 +111,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       |
 |----------|---------------|
@@ -114,11 +130,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
@@ -128,7 +142,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.
@@ -138,6 +152,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:
 
@@ -145,4 +171,10 @@ 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
+
+* **Nonlinear element support**: general nonlinear constitutive laws with Jacobian linearization

{pybondgraph-0.2.1 → pybondgraph-0.4.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,10 +15,13 @@ 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
 
+from .numerics import to_numpy, to_control_ss
+
+from .fmu_export import to_fmu
+
 __all__ = [
     "Bond",
     "Causality",
@@ -39,4 +42,9 @@ __all__ = [
     "IntegratedFlowSensor",
     "Port",
     "SubBondGraph",
+    "CausalityError",
+    "DerivativeCausalityError",
+    "to_numpy",
+    "to_control_ss",
+    "to_fmu",
 ]