pathsim 0.1.0__tar.gz

pathsim-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Milan Rother
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pathsim-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: pathsim
+Version: 0.1.0
+Summary: A block based time domain system simulation framework.
+Home-page: https://github.com/milanofthe/PathSim
+Author: Milan Rother
+Author-email: milan.rother@gmx.de
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+
+# PathSim: A Time-Domain System Simulation Framework
+
+
+## Overview
+
+PathSim is a minimalistic and flexible block-based time-domain system simulation framework in Python. It provides a modular and intuitive approach to modeling and simulating complex dynamical systems using a directed computational graph. It is similar to Matlab Simulink in spirit but works very differently under the hood.
+
+Key features of PathSim include:
+
+- Decentralized architecture where each dynamical block has their own numerical integration engine. 
+- The system is solved directly on the computational graph instead of compiling a unified differetial algebraic system.
+- This has some advantages such as hot-swappable blocks during simulation and reading simulation results directly from the scopes.
+- The block execution is decoupled from the data transfer, which enables parallelization (future) and linear computational complexity scaling for sparsely connected systems.
+- Support for MIMO (Multiple Input, Multiple Output) blocks, enabling the creation of complex interconnected system topologies.
+- Fixed-point iteration approach with path length estimation to efficiently resolve algebraic loops.
+- Wide range of numerical solvers, including implicit and explicit multi-stage, and adaptive Runge-Kutta methods such as `RKDP54` or `ESDIRK54`.
+- Modular and hierarchical modeling with (nested) subsystems.
+- Library of pre-defined blocks, including mathematical operations, integrators, delays, transfer functions, and more.
+- Easy extensibility, allowing users to define custom blocks by subclassing the base `Block` class and implementing just a handfull of methods. 
+
+
+There are many example simulations in the `examples` directory that cover most of the functionalities of the pathsim package.
+
+## Getting Started
+
+To get started with PathSim, you need to import the necessary modules and classes. The main components of the package are:
+
+- `Simulation`: The main class that handles the blocks, connections, and the simulation loop.
+- `Connection`: The class that defines the connections between blocks.
+- Various block classes from the `blocks` module, such as `Integrator`, `Amplifier`, `Adder`, `Scope`, etc.
+
+Here's an example that demonstrates how to create a basic simulation. 
+In this example, we create a simulation of the harmonic oscillator (a spring mass damper 2nd order system) initial value problem. The ODE that defines it is give by
+
+$$
+\ddot{x} + \frac{c}{m} \dot{x} + \frac{k}{m} x = 0
+$$
+
+where $c$ is the damping, $k$ the spring constant and $m$ the mass.
+
+It can be translated to a block diagram using integrators, amplifiers and adders in the following way:
+
+![png](README_files/harmonic_oscillator_blockdiagram.png)
+
+The topology of the block diagram above can be directly defined as blocks and connections in the pathsim framework. First we initialize the blocks needed to represent the dynamical systems with their respective arguments such as initial conditions and gain values, then the blocks are connected using `Connection` objects, forming two feedback loops. The `Simulation` instance manages the blocks and connections and advances the system in time with the timestep (`dt`). The `log` flag for logging the simulation progress is also set. Finally, we run the simulation for some number of seconds and plot the results using the `plot()` method of the scope block.
+
+
+
+```python
+from pathsim import Simulation
+from pathsim import Connection
+from pathsim.blocks import Integrator, Amplifier, Adder, Scope
+from pathsim.solvers import SSPRK22  # 2nd order fixed timestep, this is also the default
+
+#initial position and velocity
+x0, v0 = 2, 5
+
+#parameters (mass, damping, spring constant)
+m, c, k = 0.8, 0.2, 1.5
+
+# Create blocks 
+I1 = Integrator(v0)   # integrator for velocity
+I2 = Integrator(x0)   # integrator for position
+A1 = Amplifier(c)
+A2 = Amplifier(k)
+A3 = Amplifier(-1/m)
+P1 = Adder()
+Sc = Scope(labels=["velocity", "position"])
+
+blocks = [I1, I2, A1, A2, A3, P1, Sc]
+
+# Create connections
+connections = [
+    Connection(I1, I2, A1, Sc),   # one to many connection
+    Connection(I2, A2, Sc[1]),
+    Connection(A1, P1),           # default connection to port 0
+    Connection(A2, P1[1]),        # specific connection to port 1
+    Connection(P1, A3),
+    Connection(A3, I1)
+    ]
+
+# Create a simulation instance from the blocks and connections
+Sim = Simulation(blocks, connections, dt=0.05, log=True, Solver=SSPRK22)
+
+# Run the simulation for 50 seconds
+Sim.run(duration=50.0)
+
+# Plot the results directly from the scope
+Sc.plot()
+
+# Read the results from the scope for further processing
+time, data = Sc.read()
+```
+
+    2024-08-11 21:08:32,152 - INFO - LOGGING enabled
+    2024-08-11 21:08:32,152 - INFO - SOLVER SSPRK22 adaptive=False implicit=False
+    2024-08-11 21:08:32,153 - INFO - PATH LENGTH ESTIMATE 3, 'iterations_min' set to 3
+    2024-08-11 21:08:32,154 - INFO - RESET
+    2024-08-11 21:08:32,154 - INFO - RUN duration=50.0
+    2024-08-11 21:08:32,155 - INFO - STARTING progress tracker
+    2024-08-11 21:08:32,155 - INFO - progress=0%
+    2024-08-11 21:08:32,179 - INFO - progress=10%
+    2024-08-11 21:08:32,202 - INFO - progress=20%
+    2024-08-11 21:08:32,226 - INFO - progress=30%
+    2024-08-11 21:08:32,251 - INFO - progress=40%
+    2024-08-11 21:08:32,277 - INFO - progress=50%
+    2024-08-11 21:08:32,302 - INFO - progress=60%
+    2024-08-11 21:08:32,325 - INFO - progress=70%
+    2024-08-11 21:08:32,347 - INFO - progress=80%
+    2024-08-11 21:08:32,371 - INFO - progress=90%
+    2024-08-11 21:08:32,393 - INFO - progress=100%
+    2024-08-11 21:08:32,393 - INFO - FINISHED steps(total)=1001(1001) runtime=238.25ms
+    
+
+
+    
+![png](README_files/README_3_1.png)
+    
+
+
+## Examples
+There are many examples of dynamical system simulations in the `examples` directory. They cover almost all the blocks currently available in PathSim as well as different solvers.
+
+

pathsim-0.1.0/README.md

@@ -0,0 +1,124 @@
+# PathSim: A Time-Domain System Simulation Framework
+
+
+## Overview
+
+PathSim is a minimalistic and flexible block-based time-domain system simulation framework in Python. It provides a modular and intuitive approach to modeling and simulating complex dynamical systems using a directed computational graph. It is similar to Matlab Simulink in spirit but works very differently under the hood.
+
+Key features of PathSim include:
+
+- Decentralized architecture where each dynamical block has their own numerical integration engine. 
+- The system is solved directly on the computational graph instead of compiling a unified differetial algebraic system.
+- This has some advantages such as hot-swappable blocks during simulation and reading simulation results directly from the scopes.
+- The block execution is decoupled from the data transfer, which enables parallelization (future) and linear computational complexity scaling for sparsely connected systems.
+- Support for MIMO (Multiple Input, Multiple Output) blocks, enabling the creation of complex interconnected system topologies.
+- Fixed-point iteration approach with path length estimation to efficiently resolve algebraic loops.
+- Wide range of numerical solvers, including implicit and explicit multi-stage, and adaptive Runge-Kutta methods such as `RKDP54` or `ESDIRK54`.
+- Modular and hierarchical modeling with (nested) subsystems.
+- Library of pre-defined blocks, including mathematical operations, integrators, delays, transfer functions, and more.
+- Easy extensibility, allowing users to define custom blocks by subclassing the base `Block` class and implementing just a handfull of methods. 
+
+
+There are many example simulations in the `examples` directory that cover most of the functionalities of the pathsim package.
+
+## Getting Started
+
+To get started with PathSim, you need to import the necessary modules and classes. The main components of the package are:
+
+- `Simulation`: The main class that handles the blocks, connections, and the simulation loop.
+- `Connection`: The class that defines the connections between blocks.
+- Various block classes from the `blocks` module, such as `Integrator`, `Amplifier`, `Adder`, `Scope`, etc.
+
+Here's an example that demonstrates how to create a basic simulation. 
+In this example, we create a simulation of the harmonic oscillator (a spring mass damper 2nd order system) initial value problem. The ODE that defines it is give by
+
+$$
+\ddot{x} + \frac{c}{m} \dot{x} + \frac{k}{m} x = 0
+$$
+
+where $c$ is the damping, $k$ the spring constant and $m$ the mass.
+
+It can be translated to a block diagram using integrators, amplifiers and adders in the following way:
+
+![png](README_files/harmonic_oscillator_blockdiagram.png)
+
+The topology of the block diagram above can be directly defined as blocks and connections in the pathsim framework. First we initialize the blocks needed to represent the dynamical systems with their respective arguments such as initial conditions and gain values, then the blocks are connected using `Connection` objects, forming two feedback loops. The `Simulation` instance manages the blocks and connections and advances the system in time with the timestep (`dt`). The `log` flag for logging the simulation progress is also set. Finally, we run the simulation for some number of seconds and plot the results using the `plot()` method of the scope block.
+
+
+
+```python
+from pathsim import Simulation
+from pathsim import Connection
+from pathsim.blocks import Integrator, Amplifier, Adder, Scope
+from pathsim.solvers import SSPRK22  # 2nd order fixed timestep, this is also the default
+
+#initial position and velocity
+x0, v0 = 2, 5
+
+#parameters (mass, damping, spring constant)
+m, c, k = 0.8, 0.2, 1.5
+
+# Create blocks 
+I1 = Integrator(v0)   # integrator for velocity
+I2 = Integrator(x0)   # integrator for position
+A1 = Amplifier(c)
+A2 = Amplifier(k)
+A3 = Amplifier(-1/m)
+P1 = Adder()
+Sc = Scope(labels=["velocity", "position"])
+
+blocks = [I1, I2, A1, A2, A3, P1, Sc]
+
+# Create connections
+connections = [
+    Connection(I1, I2, A1, Sc),   # one to many connection
+    Connection(I2, A2, Sc[1]),
+    Connection(A1, P1),           # default connection to port 0
+    Connection(A2, P1[1]),        # specific connection to port 1
+    Connection(P1, A3),
+    Connection(A3, I1)
+    ]
+
+# Create a simulation instance from the blocks and connections
+Sim = Simulation(blocks, connections, dt=0.05, log=True, Solver=SSPRK22)
+
+# Run the simulation for 50 seconds
+Sim.run(duration=50.0)
+
+# Plot the results directly from the scope
+Sc.plot()
+
+# Read the results from the scope for further processing
+time, data = Sc.read()
+```
+
+    2024-08-11 21:08:32,152 - INFO - LOGGING enabled
+    2024-08-11 21:08:32,152 - INFO - SOLVER SSPRK22 adaptive=False implicit=False
+    2024-08-11 21:08:32,153 - INFO - PATH LENGTH ESTIMATE 3, 'iterations_min' set to 3
+    2024-08-11 21:08:32,154 - INFO - RESET
+    2024-08-11 21:08:32,154 - INFO - RUN duration=50.0
+    2024-08-11 21:08:32,155 - INFO - STARTING progress tracker
+    2024-08-11 21:08:32,155 - INFO - progress=0%
+    2024-08-11 21:08:32,179 - INFO - progress=10%
+    2024-08-11 21:08:32,202 - INFO - progress=20%
+    2024-08-11 21:08:32,226 - INFO - progress=30%
+    2024-08-11 21:08:32,251 - INFO - progress=40%
+    2024-08-11 21:08:32,277 - INFO - progress=50%
+    2024-08-11 21:08:32,302 - INFO - progress=60%
+    2024-08-11 21:08:32,325 - INFO - progress=70%
+    2024-08-11 21:08:32,347 - INFO - progress=80%
+    2024-08-11 21:08:32,371 - INFO - progress=90%
+    2024-08-11 21:08:32,393 - INFO - progress=100%
+    2024-08-11 21:08:32,393 - INFO - FINISHED steps(total)=1001(1001) runtime=238.25ms
+    
+
+
+    
+![png](README_files/README_3_1.png)
+    
+
+
+## Examples
+There are many examples of dynamical system simulations in the `examples` directory. They cover almost all the blocks currently available in PathSim as well as different solvers.
+
+

pathsim-0.1.0/pathsim/__init__.py

@@ -0,0 +1,3 @@
+from .simulation import Simulation
+from .connection import Connection
+from .subsystem import Subsystem, Interface

pathsim-0.1.0/pathsim/blocks/__init__.py

@@ -0,0 +1,14 @@
+from .differentiator import *
+from .integrator import *
+from .amplifier import *
+from .function import *
+from .spectrum import *
+from .sources import *
+from .multiplier import *
+from .adder import*
+from .scope import *
+from .delay import *
+from .lti import *
+from .ode import *
+from .rng import *
+

pathsim-0.1.0/pathsim/blocks/_block.py

@@ -0,0 +1,217 @@
+#########################################################################################
+##
+##                                     BASE BLOCK 
+##                                  (blocks/_block.py)
+##
+##            This module defines the base 'Block' class that is the parent 
+##         to all other blocks and can serve as a base for new or custom blocks
+##                                
+##
+##                                  Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+#for unique identifiers of blocks
+import uuid
+
+
+# BASE BLOCK CLASS ======================================================================
+
+class Block:
+    """
+    Base 'Block' object that defines the inputs, outputs and the connect method.
+
+    Block interconnections are handeled via the io interface of the blocks. 
+    It is realized by dicts for the 'inputs' and for the 'outputs', where 
+    the key of the dict is the input/output channel and the corresponding 
+    value is the input/output value. 
+    
+    NOTE : 
+        This block is not intended to be used directly and serves as a base 
+        class definition for other blocks to be inherited.
+    """
+
+    def __init__(self):
+
+        #dicts to hold input and output values
+        self.inputs  = {0:0.0}  
+        self.outputs = {0:0.0} 
+
+        #initialiye integration engine as 'None' by default
+        self.engine = None
+
+        #unique block identifier
+        self.id = uuid.uuid4()
+
+
+    def __str__(self):
+        return self.__class__.__name__
+
+
+    def __len__(self):
+        """
+        The '__len__' method of the block is used to compute the length of the 
+        pass-throuh path of the block. For instant time blocks or blocks with 
+        pass-through components (adders, amplifiers, etc.) it returns 1, 
+        otherwise (integrator, buffer, etc.) it returns 0.
+        """
+        return 1
+
+
+    def __getitem__(self, key):
+        """
+        This method is intended to make connection creation more convenient 
+        and therefore just returns the block itself and the key directly after 
+        doing some basic checks.
+        """
+        if not isinstance(key, int):
+            raise ValueError(f"Port has to be of type 'int' but is '{type(key)}'!")
+        return (self, key)
+        
+
+    def reset(self):
+        """
+        Reset the blocks inputs and outputs and also its internal solver, if the 
+        block has a solver instance.
+        """
+        #reset inputs and outputs while maintaining ports
+        self.inputs  = {k:0.0 for k in sorted(self.inputs.keys())}  
+        self.outputs = {k:0.0 for k in sorted(self.outputs.keys())}
+
+        #reset engine if block has solver
+        if self.engine is not None:
+            self.engine.reset()
+
+
+    # methods for blocks with integration engines ---------------------------------------
+
+    def initialize_solver(self, Solver, tolerance_lte=1e-6):
+        """
+        Initialize the numerical integration engine with local truncation error 
+        tolerance if required.
+        If the block doesnt require an integration engine, this method just passes.
+        """
+        pass
+
+
+    def change_solver(self, Solver):
+        """
+        Changes the solver type of the integration engine of the block, if the 
+        block has a solver instance.
+        """
+        if self.engine is not None:
+            self.engine = self.engine.change(Solver)
+
+
+    def revert(self):
+        """
+        Revert the block to the state of the previous timestep, if the 
+        block has a solver instance indicated by the 'has_engine' flag.
+        This is required for adaptive solvers to revert the state to the 
+        previous timestep.
+        """
+        if self.engine is not None:
+            self.engine.revert()
+
+
+    def buffer(self):
+        """
+        Buffer current internal state of the block, if the block has 
+        a solver instance (is stateful).
+        This is required for multistage and implicit solvers.
+        """
+        if self.engine is not None:
+            self.engine.buffer()
+    
+
+    # methods for sampling data ---------------------------------------------------------
+    
+    def sample(self, t):
+        """
+        Samples the data of the blocks inputs or internal state when called. 
+        This can record block parameters after a succesful timestep such as 
+        for the 'Scope' and 'Delay' blocks but also for sampling from a random 
+        distribution in the 'RNG' and the noise blocks.
+        """
+        pass
+
+
+    # methods for inter-block data transfer ---------------------------------------------
+
+    def set(self, port, value):
+        """
+        Set the value of an input port of the block.
+        """        
+        self.inputs[port] = value
+
+
+    def get(self, port):
+        """
+        Get the value of an output port of the block.
+        Uses the 'get' method of 'outputs' dict with default value '0.0'.
+        """
+        return self.outputs.get(port, 0.0)
+
+
+    # methods for block output and state updates ----------------------------------------
+
+    def update(self, t):
+        """
+        The 'update' method is called iteratively for all blocks BEFORE the timestep 
+        to resolve algebraic loops (fixed-point iteraion). 
+
+        It is meant for instant time blocks (blocks that dont have a delay due to the 
+        timestep, such as Amplifier, etc.) and updates the 'outputs' of the block 
+        directly based on the 'inputs' and possibly internal states. 
+
+        It computes and returns the relative difference between the new output and 
+        the previous output (before the step) to track convergence of the fixed-point 
+        iteration.
+
+        RETURNS : 
+            error : (float) relative error to previous iteration for convergence control
+        """
+        return 0.0 
+
+
+    def solve(self, t, dt):
+        """
+        The 'solve' method performes one iterative solution step that is required 
+        to solve the implicit update equation of the solver if an implicit solver 
+        (numerical integrator) is used.
+
+        It returns the relative difference between the new updated solution 
+        and the previous iteration of the solution to track convergence within 
+        an outer loop.
+
+        This only has to be implemented by blocks that have an internal 
+        integration engine with an implicit solver.
+
+        RETURNS : 
+            error : (float) solver residual norm
+        """
+        return 0.0 
+
+
+    def step(self, t, dt):
+        """
+        The 'step' method is used in transient simulations and performs an action 
+        (numeric integration timestep, recording data, etc.) based on the current 
+        inputs and the current internal state. 
+
+        It performes one timestep for the internal states. For instant time blocks, 
+        the 'step' method does not has to be implemented specifically. 
+        
+        The method handles timestepping for dynamic blocks with internal states
+        such as 'Integrator', 'StateSpace', etc.
+
+        RETURNS : 
+            success : (bool) step was successful
+            error   : (float) local truncation error from adaptive integrators
+            scale   : (float) timestep rescale from adaptive integrators
+        """
+
+        #by default no error estimate
+        return True, 0.0, 1.0

pathsim-0.1.0/pathsim/blocks/adder.py

@@ -0,0 +1,33 @@
+#########################################################################################
+##
+##                          REDUCTION BLOCKS (blocks/adder.py)
+##
+##                       This module defines static 'Adder' block 
+##
+##                                   Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numpy as np
+
+from ._block import Block
+
+from ..utils.funcs import (
+    rel_error,
+    dict_to_array
+    )
+
+
+# MISO BLOCKS ===========================================================================
+
+class Adder(Block):
+    """
+    summs / adds all input signals (MISO)
+    """
+
+    def update(self, t):
+        prev_output = self.outputs[0]
+        self.outputs[0] = np.sum(dict_to_array(self.inputs), axis=0)
+        return rel_error(prev_output, self.outputs[0])

pathsim-0.1.0/pathsim/blocks/amplifier.py

@@ -0,0 +1,34 @@
+#########################################################################################
+##
+##                              IDEAL AMPLIFIER BLOCK 
+##                              (blocks/amplifier.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+from ._block import Block
+
+from ..utils.funcs import rel_error
+
+# SISO BLOCKS ===========================================================================
+
+class Amplifier(Block):
+    """
+    amplifies the input signal by 
+    multiplication with a constant gain term 
+
+    INPUTS : 
+        gain : (float) amplifier gain
+    """
+
+    def __init__(self, gain=1.0):
+        super().__init__()
+        self.gain = gain
+
+    def update(self, t):
+        prev_output = self.outputs[0]
+        self.outputs[0]  = self.gain * self.inputs[0]
+        return rel_error(prev_output, self.outputs[0])

pathsim-0.1.0/pathsim/blocks/delay.py

@@ -0,0 +1,70 @@
+#########################################################################################
+##
+##                        TIME DOMAIN DELAY BLOCK (blocks/delay.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numpy as np
+
+from ._block import Block
+from ..utils.adaptivebuffer import AdaptiveBuffer
+
+
+# BLOCKS ================================================================================
+
+class Delay(Block):
+    """
+    delays the input signal by a time constant 'tau' in seconds
+    using an adaptive rolling buffer
+
+    INPUTS : 
+        tau : (float) delay time constant for 
+    """
+
+    def __init__(self, tau=1e-3):
+        super().__init__()
+
+        #time delay in seconds 
+        self.tau = tau
+
+        #create adaptive buffer
+        self._buffer = AdaptiveBuffer(self.tau)
+
+
+    def __len__(self):
+        #no passthrough by definition
+        return 0
+
+
+    def reset(self):
+        #reset inputs and outputs
+        self.inputs  = {0:0.0}  
+        self.outputs = {0:0.0}
+
+        #clear the buffer
+        self._buffer.clear()
+
+
+    def update(self, t):
+        """
+        Evaluation of the buffer at different times.
+        """
+
+        #retrieve value from buffer
+        self.outputs[0] = self._buffer.get(t)
+
+        return 0.0
+
+
+    def sample(self, t):
+        """
+        Sample input values and time of sampling 
+        and add them to the buffer.
+        """
+
+        #add new value to buffer
+        self._buffer.add(t, self.inputs[0])