pathsim 0.2.0__py3-none-any.whl

pathsim/__init__.py

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

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/blocks/_block.py

@@ -0,0 +1,209 @@
+#########################################################################################
+##
+##                                     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} 
+
+        #initialize 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 set_solver(self, Solver, tolerance_lte=1e-6):
+        """
+        Initialize the numerical integration engine with local truncation error 
+        tolerance if required.
+        If the block already has an integration engine, it is changed, 
+        if it does not require an integration engine, this method just passes.
+        """
+        pass
+
+
+    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/blocks/adder.py

@@ -0,0 +1,30 @@
+#########################################################################################
+##
+##                          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 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 abs(prev_output - self.outputs[0])

pathsim/blocks/amplifier.py

@@ -0,0 +1,34 @@
+#########################################################################################
+##
+##                              IDEAL AMPLIFIER BLOCK 
+##                              (blocks/amplifier.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+from ._block import Block
+
+
+# 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 abs(prev_output - self.outputs[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])

pathsim/blocks/differentiator.py

@@ -0,0 +1,70 @@
+#########################################################################################
+##
+##                        DIFFERENTIATOR BLOCK (blocks/differentiator.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numpy as np
+
+from ._block import Block
+
+
+# BLOCKS ================================================================================
+
+class Differentiator(Block):
+    """
+    Differentiates the input signal (SISO) using a first order transfer function 
+    with a pole at the origin which implements a high pass filter. 
+
+        H_diff(s) = s / (1 + s/f_max)
+
+    The approximation holds for signals up to a frequency of approximately f_max.
+
+    NOTE :
+        Depending on 'f_max', the resulting system might become stiff or ill conditioned!
+        As a practical choice set f_max to 3x the highest expected signal frequency.
+
+    INPUTS :
+        f_max : (float) highest expected signal frequency
+    """
+
+    def __init__(self, f_max=1e2):
+        super().__init__()
+
+        #maximum frequency for differentiator approximation
+        self.f_max = f_max
+
+    def __len__(self):
+        return 1
+
+
+    def set_solver(self, Solver, tolerance_lte=1e-6):
+        #change solver if already initialized
+        if self.engine is not None:
+            self.engine = self.engine.change(Solver, tolerance_lte)
+            return #quit early
+        #initialize the numerical integration engine with kernel
+        def _f(x, u, t): return - self.f_max * (x - u) 
+        def _jac(x, u, t): return - self.f_max
+        self.engine = Solver(0.0, _f, _jac, tolerance_lte)
+
+
+    def update(self, t):
+        #compute implicit balancing update
+        prev_output = self.outputs[0]
+        self.outputs[0] = -self.f_max * (self.engine.get() - self.inputs[0])
+        return abs(prev_output - self.outputs[0])
+
+
+    def solve(self, t, dt):
+        #advance solution of implicit update equation
+        return self.engine.solve(self.inputs[0], t, dt)
+
+
+    def step(self, t, dt):
+        #compute update step with integration engine
+        return self.engine.step(self.inputs[0], t, dt)

pathsim/blocks/function.py

@@ -0,0 +1,82 @@
+#########################################################################################
+##
+##                       GENERIC MIMO FUNCTION BLOCK (blocks/function.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numpy as np
+
+from ._block import Block
+
+from ..utils.funcs import (
+    max_error_dicts, 
+    array_to_dict,
+    dict_to_array
+    )
+
+
+# MIMO BLOCKS ===========================================================================
+
+class Function(Block):
+    """
+    Arbitrary MIMO function block, defined by a callable object, 
+    i.e. function or lambda expression.
+
+    The function can have multiple arguments that are then provided 
+    by the input channels of the function block.
+
+    Form multi input, the function has to specify multiple arguments
+    and for multi output, the aoutputs have to be provided as a 
+    tuple or list. 
+
+    INPUTS : 
+        func : (callable) MIMO function that defines block IO behaviour
+
+    NOTE :
+        If the outputs are provided as a single numpy array,
+        they are considered a single output
+    
+    EXAMPLE :
+        consider the function: 
+            func = lambda a, b, c : (a**2, a*b, b/c)
+        then the input channels of the block are assigned 
+        to the function arguments following this scheme:
+            inputs[0] -> a
+            inputs[1] -> b
+            inputs[2] -> c
+        and the function outputs are assigned to the 
+        output channels of the block in the same way:
+            a**2 -> outputs[0]
+            a*b  -> outputs[1]
+            b/c  -> outputs[2]
+    """
+
+    def __init__(self, func=lambda x: x):
+        super().__init__()
+
+        #some checks to ensure that function works correctly
+        if not callable(func):  
+            raise ValueError(f"'{func}' is not callable")
+        
+        #function defining the block update
+        self.func = func
+
+
+    def update(self, t):
+
+        #compute function output
+        output = self.func(*dict_to_array(self.inputs))
+
+        #check if the output is scalar
+        if np.isscalar(output):
+            prev_output = self.outputs[0]
+            self.outputs[0] = output
+            return abs(prev_output - self.outputs[0])
+        else:
+            prev_outputs = self.outputs.copy()
+            self.outputs = array_to_dict(output)
+            return max_error_dicts(prev_outputs, self.outputs)

pathsim/blocks/integrator.py

@@ -0,0 +1,66 @@
+#########################################################################################
+##
+##                             STANDARD INTEGRATOR BLOCK 
+##                              (blocks/integrator.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numpy as np
+
+from ._block import Block
+
+from ..utils.funcs import (
+    dict_to_array, 
+    array_to_dict
+    )
+
+
+# BLOCKS ================================================================================
+
+class Integrator(Block):
+    """
+    Integrates the input signal using a numerical integration engine. 
+    The block is inherently MIMO capable.
+
+    INPUTS : 
+        initial_value : (float or array) initial value of integrator
+    """
+
+    def __init__(self, initial_value=0.0):
+        super().__init__()
+
+        #save initial value
+        self.initial_value = initial_value
+
+
+    def __len__(self):
+        return 0
+
+
+    def set_solver(self, Solver, tolerance_lte=1e-6):
+        #change solver if already initialized
+        if self.engine is not None:
+            self.engine = self.engine.change(Solver, tolerance_lte)
+            return #quit early
+        #initialize the integration engine
+        def _f(x, u, t): return u
+        self.engine = Solver(self.initial_value, _f, None, tolerance_lte)
+        
+
+    def update(self, t):
+        self.outputs = array_to_dict(self.engine.get())
+        return 0.0
+
+
+    def solve(self, t, dt):
+        #advance solution of implicit update equation and update block outputs
+        return self.engine.solve(dict_to_array(self.inputs), t, dt)
+
+
+    def step(self, t, dt):
+        #compute update step with integration engine and update block outputs
+        return self.engine.step(dict_to_array(self.inputs), t, dt)