pathsim 0.2.0__py3-none-any.whl

pathsim/utils/funcs.py

@@ -0,0 +1,205 @@
+########################################################################################
+##
+##                                 UTILITY FUNCTIONS  
+##                                  (utils/funcs.py)
+##
+##                                Milan Rother 2023/24
+##
+########################################################################################
+
+# IMPORTS ==============================================================================
+
+from time import perf_counter
+
+import numpy as np
+
+
+# HELPERS ==============================================================================
+
+def timer(func):
+    """
+    shows the execution time in milliseconds of the 
+    function object passed for debugging purposes
+    """
+    def wrap_func(*args, **kwargs):
+        t1 = perf_counter()
+        result = func(*args, **kwargs)
+        t2 = perf_counter()
+        print(f"Function '{func.__name__!r}' executed in {(t2 - t1)*1e3:.2f}ms")
+        return result
+    return wrap_func
+
+
+def dB(x):
+    """
+    Compute clipped decibel value (for signals) where 
+    the minimum value is '-360dB'.
+    """
+    return 20.0*np.log10(np.clip(abs(x), 1e-18, None))
+
+
+# HELPERS FOR SIMULATION ===============================================================
+
+def dict_to_array(a):
+    return np.array([a[k] for k in sorted(a.keys())])
+
+
+def array_to_dict(a):
+    if np.isscalar(a): return {0:a}
+    else: return dict(enumerate(a))
+
+
+def rel_error(a, b):
+    """
+    Computes the relative error between two scalars.
+    It is robust to one of them being zero and falls 
+    back to the absolute error in this case.
+
+    NOTE : 
+        this is actually faster then inlining the 
+        branching into the return statement
+    """
+    if a == 0.0: return abs(b)
+    else: return abs((a - b)/a)
+
+
+def abs_error(a, b):
+    """
+    Computes the absolute error between two scalars.
+    """
+    return abs(a - b)
+
+
+def max_error(a, b):
+    """
+    Computes the maximum absolute error / deviation between two
+    iterables such as lists with numerical values. Returns a scalar 
+    value representing the maximum deviation.
+
+    NOTE:
+        this is actually faster then 'max' over a list comprehension
+    """
+    max_err = 0.0
+    for err in map(abs_error, a, b):
+        if err > max_err: 
+            max_err = err
+    return max_err
+
+
+def max_rel_error(a, b):
+    """
+    Computes the maximum relative error between two iterables 
+    such as lists with numerical values. It is robust to one of 
+    them being zero and falls back to the absolute error in this 
+    case. It returns a scalar value representing the maximum 
+    relative error. 
+
+    NOTE:
+        this is actually faster then 'max' over a list comprehension
+    """
+    max_err = 0.0
+    for err in map(rel_error, a, b):
+        if err > max_err: 
+            max_err = err
+    return max_err
+
+
+def max_error_dicts(a, b):
+    """
+    Computes the maximum absolute error between two dictionaries 
+    with numerical values. It returns a scalar value representing 
+    the maximum absolute error. 
+    """
+    return max_error(a.values(), b.values())
+
+
+def max_rel_error_dicts(a, b):
+    """
+    Computes the maximum relative error between two dictionaries 
+    with numerical values. It is robust to one of them being zero 
+    and falls back to the absolute error in this case. It returns 
+    a scalar value representing the maximum relative error. 
+    """
+    return max_rel_error(a.values(), b.values())
+
+
+# AUTOMATIC DIFFERENTIATION ============================================================
+
+def numerical_jacobian(func, x, h=1e-8):
+    """
+    Numerically computes the jacobian of the function 'func' by 
+    central differences with the stepsize 'h' which is set to 
+    a default value of 'h=1e-8' which is the point where the 
+    truncation error of the central differences balances with 
+    the machine accuracy of 64bit floating point numbers.    
+    
+    INPUTS : 
+        func : (function object) function to compute jacobian for
+        x    : (float or array) value for function at which the jacobian is evaluated
+        h    : (float) step size for central differences
+    """
+    
+    #catch scalar case (gradient)
+    if np.isscalar(x):
+        return 0.5 * (func(x+h) - func(x-h)) / h
+         
+    #perturbation matrix and jacobian
+    e = np.eye(len(x)) * h
+    return 0.5 * np.array([func(x_p) - func(x_m) for x_p, x_m in zip(x+e, x-e)]).T / h
+
+
+def auto_jacobian(func):
+    """
+    Wraps a function object such that it computes the jacobian 
+    of the function with respect to the first argument.
+
+    This is intended to compute the jacobian 'jac(x, u, t)' of 
+    the right hand side function 'func(x, u, t)' of numerical 
+    integrators with respect to 'x'.
+    """
+    def wrap_func(*args):
+        _x, *_args = args
+        return numerical_jacobian(lambda x: func(x, *_args), _x)
+    return wrap_func
+
+
+
+# PATH ESTIMATION ======================================================================
+
+def path_length_dfs(connections, starting_block, visited=set()):
+    """
+    Recursively compute the longest path (depth first search) 
+    in a directed graph from a starting node / block.
+    """
+
+    #node already visited -> break cycles
+    if starting_block in visited:   
+        return 0
+
+    #block without instant time component -> break cycles
+    if not len(starting_block):   
+        return 0
+
+    #add starting node to set of visited nodes
+    visited.add(starting_block)
+
+    #length of paths from the starting nodes
+    max_length = 0
+
+    #iterate connections and explore the path from the target node
+    for conn in connections:
+        
+        #find connections from starting block
+        src, _ = conn.source 
+        if src == starting_block:
+
+            #iterate connection target blocks
+            for trg, _ in conn.targets:
+
+                #recursively compute the new longest path
+                length = path_length_dfs(connections, trg, visited.copy())
+                if length > max_length: max_length = length
+
+    #add the contribution of the starting node to longest path
+    return max_length + len(starting_block)
+

pathsim/utils/gilbert.py

@@ -0,0 +1,110 @@
+########################################################################################
+##
+##                       METHODS FOR STATESPACE REALIZATIONS
+##                                (utils/gilbert.py)
+##
+##                                Milan Rother 2024
+##
+########################################################################################
+
+# IMPORTS ==============================================================================
+
+import numpy as np
+
+
+# STATESPACE REALIZATION ===============================================================
+
+def gilbert_realization(Poles=[], Residues=[], Const=0.0, tolerance=1e-9):
+        
+    """
+    Build real valued statespace model from transfer function 
+    in pole residue form by Gilberts method and an additional 
+    similarity transformation to get fully real valued matrices.
+
+    pole residue form:
+        H(s) = Const + sum( Residues / (s - Poles) )
+    
+    statespace form:
+        H(s) = C * (s*I - A)^-1 * B + D 
+    
+    NOTE :  
+        The resulting system is identical to the so-called 
+        'Modal Form' and is a minimal realization.
+
+    INPUTS : 
+        Poles     : (array) real and complex poles
+        Residues  : (array) array of real and complex residue matrices
+        Const     : (array) matrix for constant term
+        tolerance : (float) relative tolerance for checking real poles
+    """
+
+    #make arrays
+    Poles = np.atleast_1d(Poles)
+    Residues = np.atleast_1d(Residues)
+
+    #check validity of args
+    if not len(Poles) or  not len(Residues):
+        raise ValueError("No 'Poles' and 'Residues' defined!")
+
+    if len(Poles) != len(Residues):
+        raise ValueError("Same number of 'Poles' and 'Residues' have to be given!")
+
+    #check shape of residues for MIMO, etc
+    if Residues.ndim == 1:
+        N, m, n = Residues.size, 1, 1
+        Residues = np.reshape(Residues, (N, m, n))
+    elif Residues.ndim == 2:
+        N, m, n = *Residues.shape, 1
+        Residues = np.reshape(Residues, (N, m, n))
+    elif Residues.ndim == 3:
+        N, m, n = Residues.shape
+    else:
+        raise ValueError(f"shape mismatch of 'Residues': Residues.shape={Residues.shape}")
+
+    #initialize companion matrix
+    a = np.zeros((N, N))
+    b = np.zeros(N)
+        
+    #residues
+    C = np.ones((m, n*N))
+    
+    #go through poles and handle conjugate pairs
+    _Poles, _Residues = [], []
+    for p, R in zip(Poles, Residues):
+
+        #real pole
+        if np.isreal(p) or abs(np.imag(p) / np.real(p)) < tolerance:
+            _Poles.append(p.real)
+            _Residues.append(R.real)
+
+        #complex conjugate pair
+        elif np.imag(p) > 0.0:
+            _Poles.extend([p, np.conj(p)])
+            _Residues.extend([R, np.conj(R)])
+
+    #build real companion matrix from the poles
+    p_old = 0.0
+    for k, (p, R) in enumerate(zip(_Poles, _Residues)):
+        
+        #check if complex conjugate
+        is_cc = (p.imag != 0.0 and p == np.conj(p_old))
+        p_old = p
+        
+        a[k,k] = np.real(p)
+        b[k] = 1.0
+        if is_cc:
+            a[k, k-1] = - np.imag(p)
+            a[k-1, k] = np.imag(p)
+            b[k]   = 0.0
+            b[k-1] = 2.0
+            
+        #iterate columns of residue
+        for i in range(n):
+            C[:,k+N*i] = np.imag(R[:,i]) if is_cc else np.real(R[:,i])  
+                
+    #build block diagonal
+    A = np.kron(np.eye(n, dtype=float), a)
+    B = np.kron(np.eye(n, dtype=float), b).T
+    D = Const
+
+    return  A, B, C, D

pathsim/utils/progresstracker.py

@@ -0,0 +1,90 @@
+########################################################################################
+##
+##                             PROGRESS TRACKER CLASS DEFINITION 
+##                                (utils/progresstracker.py)
+##
+##                                   Milan Rother 2023/24
+##
+########################################################################################
+
+# IMPORTS ==============================================================================
+
+from time import perf_counter
+import logging
+
+
+# HELPER CLASS =========================================================================
+
+class ProgressTracker:
+    """
+    Class that manages progress tracking by providing a generator
+    interface that runs until an external condition is satisfied.
+    """
+
+    def __init__(self, logger=None, log_interval=10):
+
+        #set logger
+        self.logger = logger or logging.getLogger(__name__)
+        
+        #generation condition
+        self.condition = True
+        
+        #step counter
+        self.steps = 0
+        self.successful_steps = 0
+
+        #for progress display in percent
+        self.display_percentages = list(range(0, 101, log_interval))
+
+
+    def __iter__(self):
+
+        #starting progress tracker
+        if self.logger:
+            self.logger.info("STARTING progress tracker")
+
+        #computer time for performance estimate
+        starting_time = perf_counter()
+
+        #generate as long as 'self.condition' is 'True'
+        while self.condition: 
+            yield 
+
+        #compute tracker runtime
+        runtime = perf_counter() - starting_time
+
+        #log the runtime
+        if self.logger:
+            self.logger.info(f"FINISHED steps(total)={self.successful_steps}({self.steps}) runtime={runtime*1e3:.2f}ms")
+
+
+    def check(self, progress, success=False, msg=""):
+        """
+        Update the progress of the generator. 
+
+        This method needs to be called within the iteration loop 
+        to update the looping condition and the internal tracking.
+
+        INPUTS :
+            progress : (float) progress number between 0 and 1
+            success  : (bool) was the update step successful?
+            msg      : (string) additional logging message
+        """
+
+        #compute progress in percent (round to integer)
+        percentage = int(100 * progress)
+
+        #count successful steps
+        self.successful_steps += int(success)
+        
+        #count total steps
+        self.steps += 1
+
+        #generation condition is progress less then 1
+        self.condition = progress < 1.0
+
+        #check if percentage can be displayed
+        if percentage >= self.display_percentages[0]:
+            self.display_percentages.pop(0)
+            if self.logger:
+                self.logger.info(f"progress={percentage:.0f}%"+msg)

pathsim/utils/realtimeplotter.py

@@ -0,0 +1,230 @@
+#########################################################################################
+##
+##                              REALTIME PLOTTER CLASS 
+##                            (utils/realtimeplotter.py)
+##
+##                                Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import matplotlib.pyplot as plt
+import matplotlib.style as mplstyle
+mplstyle.use("fast")
+
+import numpy as np
+
+import time
+from collections import deque
+
+
+# PLOTTER CLASS =========================================================================
+
+
+class RealtimePlotter:
+    """
+    Class that manages a realtime plotting window that 
+    can stream in x-y-data and update accordingly
+        
+    INPUTS:
+        max_samples     : (int) maximum number of samples to plot
+        update_interval : (float) time in seconds between refreshs
+        labels          : (list of strings) labels for plot traces
+        x_label         : (str) label for x-axis
+        y_label         : (str) label for y-axis
+    """
+
+    def __init__(self, max_samples=None, update_interval=1, labels=[], x_label="", y_label=""):
+        
+        #plotter settings
+        self.max_samples = max_samples
+        self.update_interval = update_interval
+        self.labels = labels
+        self.x_label = x_label
+        self.y_label = y_label
+        
+        #figure initialization
+        self.fig, self.ax = plt.subplots(nrows=1, 
+                                         ncols=1, 
+                                         figsize=(8,4), 
+                                         tight_layout=True, 
+                                         dpi=120)
+        
+        #custom colors
+        self.ax.set_prop_cycle(color=["#e41a1c", 
+                                      "#377eb8", 
+                                      "#4daf4a", 
+                                      "#984ea3", 
+                                      "#ff7f00"])
+        
+        #plot settings
+        self.ax.set_xlabel(self.x_label)
+        self.ax.set_ylabel(self.y_label)
+        self.ax.grid(True)
+        
+        #data and lines (traces) for plotting
+        self.lines = []
+        self.data = []
+        
+        #tracking update time
+        self.last_update = time.time()
+        
+        #flag for running mode
+        self.is_running = True
+        
+        # Connect the close event to the on_close method
+        self.fig.canvas.mpl_connect("close_event", self.on_close)
+        
+        # Initialize legend
+        self.legend = None
+        self.lined = {}
+        
+        #show the plotting window
+        self.show()
+
+
+    def update_all(self, x, y):
+
+        #not running? -> quit early
+        if not self.is_running:
+            return False
+    
+        #no data yet? -> initialize lines
+        if not self.data:
+
+            #data initialization
+            for i, val in enumerate(y):
+                self.data.append({"x": [], "y": []})
+
+                #label selection and line (trace) initialization
+                label = self.labels[i] if i < len(self.labels) else f"port {i}"
+                line, = self.ax.plot([], [], lw=1.5, label=label)
+                self.lines.append(line)
+
+            # Create legend
+            self.legend = self.ax.legend(fancybox=False, ncols=int(np.ceil(len(y)/4)), loc="lower left")
+            self._setup_legend_picking()
+
+        #check if new update of plot is required
+        current_time = time.time()
+        if current_time - self.last_update > self.update_interval:        
+            
+            #replace the data
+            for i, val in enumerate(y):
+                self.data[i]["x"] = x
+                self.data[i]["y"] = val
+
+            self._update_plot()
+            self.last_update = current_time
+
+        return True
+
+
+    def update(self, x, y):
+        
+        #not running? -> quit early
+        if not self.is_running:
+            return False
+
+        #no data yet? -> initialize lines
+        if not self.data:
+
+            #vectorial data -> multiple traces
+            if np.isscalar(y):
+
+                #size of data
+                n = 1
+
+                #check if rolling window plot
+                if self.max_samples is None:
+                    self.data.append({"x": [], "y": []})
+                else:
+                    self.data.append({"x": deque(maxlen=self.max_samples), 
+                                      "y": deque(maxlen=self.max_samples)})
+
+                #label selection and line (trace) initialization
+                label = self.labels[0] if self.labels else "port 0"
+                line, = self.ax.plot([], [], lw=1.5, label=label)
+                self.lines.append(line)
+
+            else:
+                
+                #size of data
+                n = len(y)
+
+                for i in range(n):
+                    
+                    #check if rolling window plot
+                    if self.max_samples is None:
+                        self.data.append({"x": [], "y": []})
+                    else:
+                        self.data.append({"x": deque(maxlen=self.max_samples), 
+                                          "y": deque(maxlen=self.max_samples)})
+
+                    #label selection and line (trace) initialization
+                    label = self.labels[i] if i < len(self.labels) else f"port {i}"
+                    line, = self.ax.plot([], [], lw=1.5, label=label)
+                    self.lines.append(line)
+
+            # Create legend
+            self.legend = self.ax.legend(fancybox=False, ncols=int(np.ceil(n/4)), loc="lower left")
+            self._setup_legend_picking()
+
+        #add the data
+        if np.isscalar(y):
+            self.data[0]["x"].append(x)
+            self.data[0]["y"].append(y)
+        else:
+            for i, val in enumerate(y):
+                self.data[i]["x"].append(x)
+                self.data[i]["y"].append(val)
+
+        #check if new update of plot is required
+        current_time = time.time()
+        if current_time - self.last_update > self.update_interval:
+            self._update_plot()
+            self.last_update = current_time
+
+        return True
+
+
+    def _update_plot(self):
+
+        #set the data to the lines (traces) of the plot
+        for i, line in enumerate(self.lines):
+            line.set_data(self.data[i]["x"], self.data[i]["y"])
+
+        #rescale the window
+        self.ax.relim()
+        self.ax.autoscale_view()
+
+        #redraw the figure
+        self.fig.canvas.draw()
+        self.fig.canvas.flush_events()
+
+
+    def show(self):
+        plt.show(block=False)
+
+
+    def on_close(self, event):
+        self.is_running = False
+
+
+    def _setup_legend_picking(self):
+
+        #setup the picking for the legend lines
+        for legline, origline in zip(self.legend.get_lines(), self.lines):
+            legline.set_picker(5)  # 5 points tolerance
+            self.lined[legline] = origline
+
+        def on_pick(event):
+            legline = event.artist
+            origline = self.lined[legline]
+            visible = not origline.get_visible()
+            origline.set_visible(visible)
+            legline.set_alpha(1.0 if visible else 0.2)
+            self.fig.canvas.draw()
+
+        self.fig.canvas.mpl_connect("pick_event", on_pick)