pathsim 0.23.2__tar.gz → 0.25.0__tar.gz

pathsim-0.25.0/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- What does this change do, and why? Keep it short and factual. -->
+
+## Changes
+
+<!-- One line per file or logical change. -->
+
+## Test plan
+
+<!-- What did you run, and what was the result? -->
+
+- [ ] `pytest -m "slow or not slow"` passes
+- [ ] New code is covered by tests under `tests/pathsim/`
+
+---
+
+<!--
+Please see CONTRIBUTING.md. In particular: submit your work under your own name,
+without co-author trailers or generated-by footers for AI assistants or other
+tools.
+-->

pathsim-0.25.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to PathSim
+
+Thanks for your interest in PathSim. Bug reports, fixes, new blocks and
+documentation improvements are all welcome.
+
+## Before you start
+
+For anything beyond a bug fix, please open an issue or a
+[discussion](https://github.com/orgs/pathsim/discussions) first. PathSim has a
+deliberate architecture and a companion project ([fastsim](https://fastsim.dev))
+that it stays aligned with, so a short conversation up front saves everyone from
+building in a direction that won't be merged.
+
+Small, focused pull requests get reviewed and merged much faster than large ones.
+If you have found several unrelated things, please split them up — a bug fix that
+stands on its own should not have to wait for a design discussion about a feature.
+
+## Development setup
+
+```bash
+git clone https://github.com/pathsim/pathsim
+cd pathsim
+pip install -e ".[test]"
+```
+
+## Tests
+
+```bash
+pytest                       # default run, excludes slow tests
+pytest -m "slow or not slow" # everything
+```
+
+New code needs tests, and they belong in `tests/pathsim/` mirroring the source
+tree. `tests/evals/` is for long-running validation studies only — it is excluded
+from the default run, so regular unit tests placed there will not run in CI.
+
+## Code style
+
+PathSim follows a consistent style throughout. Please match the surrounding code
+rather than introducing new conventions:
+
+- NumPy-style docstrings with `Parameters` / `Returns` sections
+- comments start directly after the `#`, no leading space
+- section banners as used in the existing modules
+- no new dependencies in the core — it stays on `numpy`, `scipy`, `matplotlib`
+
+## Commits and pull requests
+
+- Keep commit messages short and factual, one line where possible.
+- Describe what the change does and why. Test results and open questions are
+  useful; marketing is not.
+- **Submit your work under your own name.** Please do not add co-author trailers,
+  attribution footers or generated-by signatures for AI assistants or other tools
+  in commit messages or pull request descriptions. Use whatever tools you like —
+  you are the author, and you are vouching for the code you submit.
+
+## Reporting bugs
+
+Please include the PathSim version, your Python and NumPy versions, and a minimal
+script that reproduces the problem.
+
+## License
+
+Contributions are made under the MIT License, the same terms as PathSim itself.

{pathsim-0.23.2 → pathsim-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pathsim
-Version: 0.23.2
+Version: 0.25.0
 Summary: A differentiable block based hybrid system simulation framework.
 Author-email: Milan Rother <milan.rother@gmx.de>
 License: MIT
@@ -119,6 +119,7 @@ scp.plot()
 - [Documentation](https://docs.pathsim.org) — tutorials, examples, and API reference
 - [Homepage](https://pathsim.org) — overview and getting started
 - [Contributing](https://docs.pathsim.org/pathsim/latest/contributing) — how to contribute
+- [Consulting & commercial support](https://milanrother.com/consulting/) — integration, custom blocks, migration from closed tools
 
 ## Citation
 

{pathsim-0.23.2 → pathsim-0.25.0}/README.md

@@ -89,6 +89,7 @@ scp.plot()
 - [Documentation](https://docs.pathsim.org) — tutorials, examples, and API reference
 - [Homepage](https://pathsim.org) — overview and getting started
 - [Contributing](https://docs.pathsim.org/pathsim/latest/contributing) — how to contribute
+- [Consulting & commercial support](https://milanrother.com/consulting/) — integration, custom blocks, migration from closed tools
 
 ## Citation
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.23.2'
-__version_tuple__ = version_tuple = (0, 23, 2)
+__version__ = version = '0.25.0'
+__version_tuple__ = version_tuple = (0, 25, 0)
 
-__commit_id__ = commit_id = 'g6079208a8'
+__commit_id__ = commit_id = 'g405501720'

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/_block.py

@@ -11,11 +11,15 @@
 # IMPORTS ===============================================================================
 
 import inspect
+import numpy as np
+
 from functools import lru_cache
 
 from ..utils.deprecation import deprecated
 from ..utils.register import Register
 from ..utils.portreference import PortReference
+from ..optim.operator import DynamicOperator
+from ..exceptions import LinearizationError
 
 
 # HELPERS ===============================================================================
@@ -103,11 +107,18 @@ class Block:
         internal callable operator for algebraic components of block
     op_dyn : DynamicOperator | None
         internal callable operator for dynamic (ODE) components of block
+    linearizable : bool
+        class level flag that declares whether the block has a valid linear
+        state space model, see 'to_statespace'
     """
 
     input_port_labels = None
     output_port_labels = None
 
+    #blocks with a switching, discontinuous or non deterministic characteristic
+    #set this to 'False' and are rejected by 'to_statespace'
+    linearizable = True
+
     def __init__(self):
 
         #registers to hold input and output values, pre-sized to the declared
@@ -353,18 +364,121 @@ class Block:
             event.reset()
 
 
+    def to_statespace(self, t):
+        """Return the local linear state space model of the block in its
+        current operating point.
+
+        .. math::
+
+            \\begin{align}
+            \\delta \\dot{x} &= \\mathbf{A} \\delta x + \\mathbf{B} \\delta u\\\\
+                   \\delta y &= \\mathbf{C} \\delta x + \\mathbf{D} \\delta u
+            \\end{align}
+
+
+        This is a pure query, the block is not modified and keeps evaluating
+        its original functions afterwards. The Jacobians come from the
+        'jac', 'jac_x' and 'jac_u' methods of the internal operators, which
+        prefer analytical Jacobians and fall back to numerical differentiation.
+
+        Blocks without operators define their linear model themselves and
+        override this method. Blocks without a valid linear model declare
+        this through the 'linearizable' class attribute.
+
+        Note
+        ----
+        This is the primitive that 'linearize' and the system level
+        linearization build on, not the other way around.
+
+        Parameters
+        ----------
+        t : float
+            evaluation time
+
+        Returns
+        -------
+        A, B, C, D : np.ndarray
+            local state space matrices of the block, shaped
+            (nx,nx), (nx,nu), (ny,nx), (ny,nu)
+
+        Raises
+        ------
+        LinearizationError
+            if the block has no valid linear model in this operating point
+        """
+
+        #block declares itself as not linearizable -> fail loudly
+        if not self.linearizable:
+            raise LinearizationError(
+                f"Block '{self.__class__.__name__}' has no linear state space "
+                "model (switching, discontinuous or non deterministic)!"
+                )
+
+        #get current state
+        u, y, x = self.get_all()
+
+        nu, ny = len(u), len(y)
+        nx = len(np.atleast_1d(x)) if self.engine else 0
+
+        #dynamics -> A, B
+        if not self.engine:
+            A, B = np.zeros((0, 0)), np.zeros((0, nu))
+        elif self.op_dyn is not None:
+            A = np.asarray(self.op_dyn.jac_x(x, u, t)).reshape(nx, nx)
+            B = np.asarray(self.op_dyn.jac_u(x, u, t)).reshape(nx, nu)
+        else:
+            #state without dynamic operator -> only the block knows its dynamics
+            raise LinearizationError(
+                f"Block '{self.__class__.__name__}' is dynamic but defines no "
+                "'op_dyn', it must override 'to_statespace'!"
+                )
+
+        #output map -> C, D
+        if self.op_alg is None:
+            if nx:
+                #state without algebraic operator -> implicit output map,
+                #only the block knows it (e.g. 'ODE' with 'y = x')
+                raise LinearizationError(
+                    f"Block '{self.__class__.__name__}' is dynamic but defines "
+                    "no 'op_alg', it must override 'to_statespace'!"
+                    )
+            #stateless without algebraic operator -> no input to output path
+            C, D = np.zeros((ny, 0)), np.zeros((ny, nu))
+
+        elif isinstance(self.op_alg, DynamicOperator):
+            #'DynamicOperator' is called with 'x=None' on stateless blocks
+            C = np.asarray(self.op_alg.jac_x(x, u, t)).reshape(ny, nx) if nx else np.zeros((ny, 0))
+            D = np.asarray(self.op_alg.jac_u(x if nx else None, u, t)).reshape(ny, nu)
+
+        else:
+            C = np.zeros((ny, nx))
+            D = np.asarray(self.op_alg.jac(u)).reshape(ny, nu)
+
+        return A, B, C, D
+
+
     def linearize(self, t):
         """Linearize the algebraic and dynamic components of the block.
 
-        This is done by linearizing the internal 'Operator' and 'DynamicOperator' 
-        instances in the current system operating point. The operators create 
-        1st order taylor approximations internally and use them on subsequent 
+        This is done by linearizing the internal 'Operator' and 'DynamicOperator'
+        instances in the current system operating point. The operators create
+        1st order taylor approximations internally and use them on subsequent
         calls after linearization.
 
+        Note
+        ----
+        Use 'to_statespace' if only the linear model is needed, it does not
+        switch the block over to its linear surrogate.
+
         Parameters
         ----------
-        t : float 
+        t : float
             evaluation time
+
+        Returns
+        -------
+        A, B, C, D : np.ndarray
+            local state space matrices of the block, see 'to_statespace'
         """
 
         #get current state
@@ -372,13 +486,20 @@ class Block:
 
         #no engine -> stateless
         if not self.engine:
-            #linearize only algebraic operator 
-            if self.op_alg: self.op_alg.linearize(u)
+            #linearize only algebraic operator
+            if self.op_alg:
+                if isinstance(self.op_alg, DynamicOperator):
+                    self.op_alg.linearize(None, u, t)
+                else:
+                    self.op_alg.linearize(u)
         else:
             #linearize algebraic and dynamic operators
             if self.op_alg: self.op_alg.linearize(x, u, t)
             if self.op_dyn: self.op_dyn.linearize(x, u, t)
 
+        #hand back the linear model the operators just computed
+        return self.to_statespace(t)
+
 
     def delinearize(self):
         """Revert the linearization of the blocks algebraic and dynamic components.

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/comparator.py

@@ -46,6 +46,9 @@ class Comparator(Block):
     input_port_labels = {"in": 0}
     output_port_labels = {"out":0}
 
+    #discontinuous switching characteristic -> no linear model
+    linearizable = False
+
 
     def __init__(self, threshold=0, tolerance=1e-4, span=[-1, 1]):
         super().__init__()

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/converters.py

@@ -64,6 +64,10 @@ class ADC(Block):
     input_port_labels = {"in": 0}
     output_port_labels = None
 
+    #quantization is discontinuous -> no linear model
+    linearizable = False
+
+
     def __init__(self, n_bits=4, span=[-1, 1], T=1, tau=0):
         super().__init__()
 
@@ -154,6 +158,10 @@ class DAC(Block):
     input_port_labels = None
     output_port_labels = {"out": 0}
 
+    #quantization is discontinuous -> no linear model
+    linearizable = False
+
+
     def __init__(self, n_bits=4, span=[-1, 1], T=1, tau=0):
         super().__init__()
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/counter.py

@@ -39,6 +39,9 @@ class Counter(Block):
 
     input_port_labels = {"in": 0}
     output_port_labels = {"out": 0}
+
+    #integer valued, discontinuous output -> no linear model
+    linearizable = False
     
 
     def __init__(self, start=0, threshold=0.0):

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/delay.py

@@ -89,6 +89,10 @@ class Delay(Block):
         internal ring buffer for N-sample delay (discrete mode)
     """
 
+    #time delay is not finite dimensional -> no linear model
+    linearizable = False
+
+
     def __init__(self, tau=1e-3, sampling_period=None):
         super().__init__()
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/discrete.py

@@ -48,6 +48,10 @@ class SampleHold(Block):
         internal scheduled event for periodic sampling
     """
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, T=1.0, tau=0.0):
         super().__init__()
 
@@ -111,6 +115,10 @@ class FirstOrderHold(Block):
         internal scheduled event for periodic sampling
     """
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, T=1.0, tau=0.0):
         super().__init__()
 
@@ -195,6 +203,10 @@ class FIR(Block):
         internal scheduled event for periodic filter evaluation
     """
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, coeffs=[1.0], T=1.0, tau=0.0):
         super().__init__()
 
@@ -293,6 +305,10 @@ class DiscreteIntegrator(Block):
         internal scheduled event for periodic update
     """
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, T=1.0, tau=0.0, initial_value=0.0):
         super().__init__()
 
@@ -353,6 +369,10 @@ class DiscreteDerivative(Block):
         internal scheduled event for periodic update
     """
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, T=1.0, tau=0.0):
         super().__init__()
 
@@ -421,6 +441,10 @@ class DiscreteStateSpace(Block):
         internal scheduled event for periodic update
     """
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, A=0.0, B=1.0, C=1.0, D=0.0, T=1.0, tau=0.0, initial_value=None):
         super().__init__()
 
@@ -548,6 +572,10 @@ class TappedDelay(Block):
 
     input_port_labels = {"in": 0}
 
+    #discrete time block -> no continuous time linear model
+    linearizable = False
+
+
     def __init__(self, N=2, T=1.0, tau=0.0):
         super().__init__()
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/dynsys.py

@@ -93,7 +93,8 @@ class DynamicalSystem(Block):
         alg_length : int
             length of algebraic path
         """
-        x, u = self.engine.state, self.inputs.to_array()
+        x = self.engine.state if self.engine else self.initial_value
+        u = self.inputs.to_array()
         has_passthrough = np.any(self.op_alg.jac_u(x, u, 0.0))
         return int(has_passthrough)
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/integrator.py

@@ -84,6 +84,46 @@ class Integrator(Block):
         self.outputs.update_from_array(self.engine.state)
 
 
+    def to_statespace(self, t):
+        """Local linear state space model of the integrator.
+
+        The integrator is already linear, so its model is exact and
+        independent of the operating point
+
+        .. math::
+
+            \\mathbf{A} = 0, \\quad \\mathbf{B} = \\mathbf{I}, \\quad
+            \\mathbf{C} = \\mathbf{I}, \\quad \\mathbf{D} = 0
+
+
+        Note
+        ----
+        The integrator carries no operators, so the generic implementation
+        of 'Block.to_statespace' cannot derive this and would reject it.
+
+        Parameters
+        ----------
+        t : float
+            evaluation time
+
+        Returns
+        -------
+        A, B, C, D : np.ndarray
+            local state space matrices of the integrator
+        """
+        #no engine assigned yet -> no state, same degradation as the base class
+        nx = len(np.atleast_1d(self.engine.state)) if self.engine else 0
+        nu = len(self.inputs.to_array())
+        ny = len(self.outputs.to_array())
+
+        return (
+            np.zeros((nx, nx)),
+            np.eye(nx, nu),
+            np.eye(ny, nx),
+            np.zeros((ny, nu))
+            )
+
+
     def derivative(self, t):
         """time derivative of the integrator state, which is just the input
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/logic.py

@@ -29,6 +29,10 @@ class Logic(Block):
 
     """
 
+    #boolean valued, discontinuous output -> no linear model
+    linearizable = False
+
+
     def __len__(self):
         """Purely algebraic block"""
         return 1

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/lti.py

@@ -72,6 +72,12 @@ class StateSpace(Block):
         real valued state space matrices
     initial_value : array_like, None
         initial state / initial condition
+    state_labels, input_labels, output_labels : list[str], None
+        optional identifiers for the states, inputs and outputs of the model.
+        Models assembled by 'Simulation.to_statespace' carry the block names
+        they were built from here. These are also exactly the 'states',
+        'inputs' and 'outputs' keyword arguments of 'control.StateSpace', so
+        the model hands over to python-control without an adapter.
 
     Attributes
     ----------
@@ -81,11 +87,17 @@ class StateSpace(Block):
         internal algebraic operator for mapping to outputs
     """
 
-    def __init__(self, 
-                 A=-1.0, B=1.0, C=-1.0, D=1.0, 
-                 initial_value=None):
+    def __init__(self,
+                 A=-1.0, B=1.0, C=-1.0, D=1.0,
+                 initial_value=None,
+                 state_labels=None, input_labels=None, output_labels=None):
         super().__init__()
 
+        #optional identifiers for the rows and columns of the matrices
+        self.state_labels = state_labels
+        self.input_labels = input_labels
+        self.output_labels = output_labels
+
         #statespace matrices with input shape validation
         self.A = np.atleast_2d(A)
         self.B = np.atleast_1d(B)

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/math.py

@@ -601,9 +601,9 @@ class Matrix(Math):
 
     Parameters
     ----------
-    A : np.ndarray
-        matrix, 2d array with dim=2
-        
+    A : array_like
+        matrix, 2d array-like (nested lists are accepted and converted)
+
     Attributes
     ----------
     op_alg : Operator
@@ -613,6 +613,10 @@ class Matrix(Math):
     def __init__(self, A=np.eye(1)):
         super().__init__()
 
+        # accept any array-like: a nested list is the natural way to write a
+        # small matrix inline, and every other block parameter takes one
+        A = np.asarray(A, dtype=float)
+
         # check matrix dimension and shape
         if not A.ndim == 2:
             raise ValueError("'A' must be dim 2")

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/ode.py

@@ -113,13 +113,13 @@ class ODE(Block):
 
 
     def update(self, t):
-        """update system equation for fixed point loop, 
+        """update system equation for fixed point loop,
         here just setting the outputs
-    
+
         Note
         ----
-        the ODE block has no direct passthrough, so the 
-        'update' method is optimized for this case        
+        the ODE block has no direct passthrough, so the
+        'update' method is optimized for this case
 
         Parameters
         ----------
@@ -129,6 +129,40 @@ class ODE(Block):
         self.outputs.update_from_array(self.engine.state)
 
 
+    def to_statespace(self, t):
+        """Local linear state space model of the ODE block.
+
+        The dynamics come from the Jacobians of 'op_dyn', the output map is
+        the implicit identity 'y = x' of this block.
+
+        Note
+        ----
+        The ODE block defines no algebraic operator, so the generic
+        implementation of 'Block.to_statespace' cannot derive the output map.
+
+        Parameters
+        ----------
+        t : float
+            evaluation time
+
+        Returns
+        -------
+        A, B, C, D : np.ndarray
+            local state space matrices of the ODE block
+        """
+        u, y, x = self.get_all()
+
+        nu, ny = len(u), len(y)
+        nx = len(np.atleast_1d(x))
+
+        return (
+            np.asarray(self.op_dyn.jac_x(x, u, t)).reshape(nx, nx),
+            np.asarray(self.op_dyn.jac_u(x, u, t)).reshape(nx, nu),
+            np.eye(ny, nx),
+            np.zeros((ny, nu))
+            )
+
+
     def solve(self, t, dt):
         """advance solution of implicit update equation of the solver
 

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/relay.py

@@ -60,6 +60,9 @@ class Relay(Block):
     input_port_labels = {"in":0}
     output_port_labels = {"out":0}
 
+    #discontinuous switching characteristic -> no linear model
+    linearizable = False
+
     def __init__(
         self, 
         threshold_up=1.0, 
@@ -95,12 +98,25 @@ class Relay(Block):
                 ),
             ]
 
+        # start in the lower relay state
+        self.outputs[0] = self.value_down
+
 
     def __len__(self):
         """This block has no direct passthrough"""
         return 0
 
 
+    def reset(self):
+        """Reset the block and return to the lower relay state.
+
+        The base reset zeroes the outputs, which is not a relay state -- the
+        output must land back on `value_down`, same as after construction.
+        """
+        super().reset()
+        self.outputs[0] = self.value_down
+
+
     def update(self, t):
         """update system equation for fixed point loop, 
         here just setting the outputs

{pathsim-0.23.2 → pathsim-0.25.0}/src/pathsim/blocks/rng.py

@@ -42,6 +42,9 @@ class RandomNumberGenerator(Block):
     input_port_labels = {}
     output_port_labels = {"out":0}
 
+    #non deterministic output -> no linear model
+    linearizable = False
+
     def __init__(self, sampling_period=None):
         super().__init__()