pathsim 0.2.0__py3-none-any.whl

pathsim/subsystem.py

@@ -0,0 +1,267 @@
+#########################################################################################
+##
+##                                 SUBSYSTEM DEFINITION 
+##                                    (subsystem.py)
+##
+##              This module contains the 'Subsystem' and 'Interface' classes 
+##         that manage subsystems that can be embedded within a larger simulation
+##
+##                                  Milan Rother 2024
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+from .blocks._block import Block
+from .utils.funcs import path_length_dfs
+
+
+# IO CLASS ==============================================================================
+
+class Interface(Block):
+    """
+    Bare-bone block that serves as a data interface for the 'Subsystem' class.
+
+    It works like this:
+    - Internal blocks of the subsystem are connected to the inputs and outputs 
+      of this Interface block via the internal connections.
+    - It behaves like a normal block (inherits the main 'Block' class methods).
+    - It implements some special methods to get and set the inputs and outputs 
+      of the blocks, that are used to translate between the internal blocks of the 
+      subsystem and the inputs and outputs of the subsystem.
+    - Handles data transfer to and from the internal subsystem blocks 
+      to and from the inputs and outputs of the subsystem.
+    """
+    
+    def set_output(self, port, value): 
+        self.outputs[port] = value
+    
+    def get_input(self, port): 
+        return self.inputs.get(port, 0.0)
+
+
+# MAIN SUBSYSTEM CLASS ==================================================================
+
+class Subsystem(Block):
+    """
+    Subsystem class that holds its own blocks and connecions and 
+    can natively interface with the main simulation loop. 
+
+    IO interface is realized by a special 'Interface' block, that has extra 
+    methods for setting and getting inputs and outputs and serves 
+    as the interface of the internal blocks to the outside. 
+
+    The subsystem doesnt use its 'inputs' and 'outputs' dicts directly. 
+    It exclusively handles data transfer via the 'Interface' block. 
+
+    This class can be used just like any other block during the simulation, 
+    since it implements the required methods 'update' for the fixed-point 
+    iteration (resolving algebraic loops with instant time blocks), 
+    the 'step' method that performs timestepping (especially for dynamic 
+    blocks with internal states) and the 'solve' method for solving the 
+    implicit update equation for implicit solvers. 
+
+    INPUTS : 
+        blocks      : (list of 'Block' objects) internal blocks of the subsystem
+        connections : (list of 'Connection' objects) internal connections of the subsystem
+    """
+
+    def __init__(self, blocks=None, connections=None):
+        super().__init__()
+
+        #internal connecions
+        self.connections = [] if connections is None else connections
+        
+        #collect and organize internal blocks
+        self.blocks, self.interface = [], None
+
+        if blocks is not None:
+            for block in blocks:
+                if isinstance(block, Interface): self.interface = block
+                else: self.blocks.append(block)
+
+        #check if interface is defined
+        if self.interface is None:
+            raise ValueError("Subsystem 'blocks' list needs to contain 'Interface' block!")
+
+        #validate the internal connections upon initialization
+        self._check_connections()
+
+
+    def __str__(self):
+        _b = "\n".join(["    " + str(block) for block in self.blocks])
+        return f"Subsystem\n" + _b
+
+
+    def __len__(self):
+        """
+        Recursively compute the longest signal path in the subsytem by 
+        depth first search, leveraging the '__len__' methods of the blocks. 
+        This enables the path length computation even for nested subsystems.
+
+        Iterate internal blocks and compute longest path from each block 
+        as starting block.
+
+        Basically the same as in the 'Simulation' class.
+        """
+        max_path_length = 0
+        for block in self.blocks:
+            path_length = path_length_dfs(self.connections, block)
+            if path_length > max_path_length:
+                max_path_length = path_length
+        return max_path_length + 1 #longer due to 'Interface' block
+
+
+    def _check_connections(self):
+        """
+        Check if connections are valid and if there is no input port that recieves 
+        multiple outputs and could be overwritten unintentionally.
+
+        If multiple outputs are assigned to the same input, an error is raised.
+        """
+
+        #iterate connections and check if they are valid
+        for i, conn_1 in enumerate(self.connections):
+
+            #check if connections overwrite each other and raise exception
+            for conn_2 in self.connections[(i+1):]:
+                if conn_1.overwrites(conn_2):
+                    _msg = f"{conn_1} overwrites {conn_2}"
+                    raise ValueError(_msg)
+
+
+    def reset(self):
+
+        #reset interface
+        self.interface.reset()
+
+        #reset internal blocks
+        for block in self.blocks:
+            block.reset()
+
+
+    # methods for inter-block data transfer -------------------------------------------------
+
+    def set(self, port, value):
+        """
+        The 'set' method of the 'Subsystem' sets the output 
+        values of the 'Interface' block.
+        """
+        self.interface.set_output(port, value)
+
+
+    def get(self, port):
+        """
+        The 'get' method of the 'Subsystem' retrieves the input 
+        values of the 'Interface' block.
+        """
+        return self.interface.get_input(port)
+
+
+    # methods for data recording ------------------------------------------------------------
+
+    def sample(self, t):
+
+        """
+        Update the internal connections again and sample data from 
+        the internal blocks that implement the 'sample' method.
+        """
+
+        #update internal connenctions (data transfer)
+        for connection in self.connections:
+            connection.update()
+
+        #record data if required
+        for block in self.blocks:
+            block.sample(t)
+
+
+    # methods for block output and state updates --------------------------------------------
+
+    def update(self, t):
+        """
+        Update the instant time components of the internal blocks 
+        to evaluate the (distributed) system equation.
+        """
+
+        #update internal connections (data transfer)
+        for connection in self.connections:
+            connection.update()
+
+        #update internal blocks
+        max_error = 0.0
+        for block in self.blocks:
+            error = block.update(t)
+            if error > max_error:
+                max_error = error
+
+        #return subsystem convergence error
+        return max_error
+
+
+    def solve(self, t, dt):
+        """
+        Advance solution of implicit update equation for internal blocks.
+        """
+        max_error = 0.0
+        for block in self.blocks:
+            error = block.solve(t, dt)
+            if error > max_error:
+                max_error = error
+        return max_error
+
+
+    def step(self, t, dt):
+        """
+        Explicit component of timestep for internal blocks including error propagation.
+        """
+
+        #initial timestep rescale and error estimate
+        success, max_error, scale = True, 0.0, 1.0
+
+        #step blocks and get error estimates if available
+        for block in self.blocks:
+            ss, error, scl = block.step(t, dt)
+            if not ss: success = False
+            if error > max_error:
+                max_error, scale = error, scl      
+
+        return success, max_error, scale
+
+
+    # methods for blocks with integration engines -------------------------------------------
+
+    def set_solver(self, Solver, tolerance_lte=1e-6):
+        """
+        Initialize all blocks with solver for numerical integration
+        and tolerance for local truncation error 'tolerance_lte'.
+
+        If blocks already have solvers, change the numerical integrator
+        to the 'Solver' class.
+        
+        INPUTS:
+            Solver : ('Solver' class) numerical solver definition
+            tolerance_lte : (float) tolerance for local truncation error
+        """
+
+        #iterate all blocks and set integration engines
+        for block in self.blocks:
+            block.set_solver(Solver, tolerance_lte)
+
+
+    def revert(self):
+        """
+        revert the internal blocks to the state 
+        of the previous timestep 
+        """
+        for block in self.blocks:
+            block.revert()
+
+
+    def buffer(self):
+        """
+        buffer internal states of blocks with 
+        internal integration engines 
+        """
+        for block in self.blocks:
+            block.buffer()

pathsim/utils/adaptivebuffer.py

@@ -0,0 +1,87 @@
+
+########################################################################################
+##
+##                         ADAPTIV BUFFER CLASS DEFINITION 
+##                            (utils/adaptivebuffer.py)
+##
+##                                Milan Rother 2024
+##
+########################################################################################
+
+# IMPORTS ==============================================================================
+
+from collections import deque
+from bisect import bisect_left
+
+
+# HELPER CLASS =========================================================================
+
+class AdaptiveBuffer:
+    """
+    A class that manages an adaptive buffer for delay modeling which is primarily 
+    used in the pathsim 'Delay' block. It implements a linear interpolation for 
+    arbitraty time lookup.
+
+    INPUTS : 
+        delay : (float) time delay in seconds
+    """
+
+    def __init__(self, delay):
+
+        #the buffer uses a double ended queue
+        self.buffer = deque()
+        self.delay = delay
+
+        #for buffer cleanup every 100 lookups
+        self.clean_every = 100
+        self.counter = 0
+
+
+    def __len__(self):
+        return len(self.buffer)
+
+
+    def add(self, t, value):
+
+        #add the time-value tuple
+        self.buffer.append((t, value))
+        
+        #clean up the buffer
+        if self.counter > self.clean_every:
+            self.counter = 0
+            while len(self.buffer) > 1 and t > self.delay + self.buffer[0][0] :
+                self.buffer.popleft()
+        else:
+            self.counter += 1
+
+    
+    def get(self, t):
+
+        #default 0
+        if not self.buffer:
+            return 0.0
+        
+        #interpolation
+        target_time = t - self.delay
+
+        #requested time too small -> return first value
+        if target_time <= self.buffer[0][0]:
+            return self.buffer[0][1]
+        
+        #requested time too large -> return last value
+        if target_time >= self.buffer[-1][0]:
+            return self.buffer[-1][1]
+
+        #find buffer index for requested time
+        i = bisect_left(self.buffer, (target_time,))
+        t0, y0 = self.buffer[i-1]
+        t1, y1 = self.buffer[i]
+        
+        #linear interpolation
+        return y0 + (y1 - y0) * (target_time - t0) / (t1 - t0)
+
+
+    def clear(self):
+        #reset everything
+        self.buffer = deque()
+        self.counter = 0

pathsim/utils/anderson.py

@@ -0,0 +1,180 @@
+########################################################################################
+##
+##                               ANDERSON ACCELERATION 
+##                                (utils/anderson.py)
+##
+##                                 Milan Rother 2024
+##
+########################################################################################
+
+# IMPORTS ==============================================================================
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+# CLASS ================================================================================
+
+class AndersonAcceleration:
+    """
+    Class for accelerated fixed-point iteration through anderson acceleration. 
+    Solves a nonlinear set of equations given in the fixed-point form:
+
+        x = g(x)
+
+    Anderson Accelerstion tracks the evolution of the solution from the previous 
+    iterations. The next step in the iteration is computed as a linear combination 
+    of the previous iterates. The coefficients are computed to minimize the least 
+    squares error of the fixed-point problem.
+
+    INPUTS : 
+        m       : (int) buffer length
+        restart : (bool) clear buffer when full
+    """
+
+    def __init__(self, m=1, restart=True):
+
+        #length of buffer for next estimate
+        self.m = m
+
+        #restart after buffer length is reached?
+        self.restart = restart
+
+        #rolling buffers
+        self.x_buffer = []
+        self.f_buffer = []
+
+        #iteration counter for debugging
+        self.counter = 0
+
+
+    def reset(self):
+        """
+        reset the anderson accelerator
+        """
+
+        #clear buffers
+        self.x_buffer = []
+        self.f_buffer = []
+
+        #reset iteration counter
+        self.counter = 0
+
+
+    def step(self, x, g):
+        """
+        Perform one iteration on the fixed-point solution.
+
+        INPUTS : 
+            x : (float or array) current solution
+            g : (float or array) current evaluation of g(x)
+        """
+
+        #increment counter
+        self.counter += 1
+
+        #residual (this gets minimized)
+        f = g - x
+        
+        #fallback to regular fpi if 'm == 0'
+        if self.m == 0:
+            return g, np.linalg.norm(f)
+
+        #make x vectorial if g is vector
+        if np.isscalar(x) and not np.isscalar(g):
+            x *= np.ones_like(g)
+    
+        #append to buffer
+        self.x_buffer.append(x)
+        self.f_buffer.append(f)
+
+        #total buffer length
+        k = len(self.f_buffer)
+
+        #if no buffer, regular fixed-point update
+        if k == 1:
+            return g, np.linalg.norm(f)
+
+        #if buffer size 'm' reached, restart or truncate
+        elif self.m is not None and k > self.m + 1:
+            if self.restart:
+                self.x_buffer = []
+                self.f_buffer = []
+                return g, np.linalg.norm(f)
+            else:
+                self.x_buffer.pop(0)
+                self.f_buffer.pop(0)
+
+        #get deltas 
+        dX = np.diff(self.x_buffer, axis=0)
+        dF = np.diff(self.f_buffer, axis=0)
+
+        #exit for scalar values
+        if np.isscalar(f):
+
+            #delta squared norm
+            dF2 = np.linalg.norm(dF)**2
+
+            #catch division by zero
+            if dF2 <= 1e-14:
+                return g, abs(f)
+
+            #new solution and residual
+            return x - f * sum(dF * dX) / dF2, abs(f)
+
+        #compute coefficients from least squares problem
+        C, *_ = np.linalg.lstsq(dF.T, f, rcond=None)
+
+        #new solution and residual
+        return x - C @ dX, np.linalg.norm(f)
+
+
+
+class NewtonAndersonAcceleration(AndersonAcceleration):
+    """
+    Modified class for hybrid anderson acceleration that can use a jacobian 'jac' of 
+    the function 'g' for a newton step before the fixed point step for the initial 
+    estimate before applying the anderson acceleration.
+
+    If a jacobian 'jac' is available, this significantly improves the convergence 
+    (speed and robustness) of the solution.
+    """
+
+    def _newton(self, x, g, jac):
+        """
+        Newton step on solution, where 'f=g-x' is the 
+        residual and 'jac' is the jacobian of 'g'.
+        """
+
+        #compute residual
+        f = g - x
+
+        #early exit for scalar or purely vectorial values
+        if np.isscalar(f) or np.ndim(jac) == 1:
+            return x - f / (jac - 1.0), abs(f)
+
+        #vectorial values (newton raphson)
+        jac_f = jac - np.eye(len(f))
+        return x - np.linalg.solve(jac_f, f), np.linalg.norm(f)
+
+
+    def step(self, x, g, jac=None):
+        """
+        Perform one iteration on the fixed-point solution. 
+        If the jacobian of g 'jac' is provided, a newton step 
+        is performed previous to anderson acceleration.
+        """
+
+        #newton step if jacobian available
+        if jac is None: 
+
+            #regular anderson step with residual
+            return super().step(x, g)
+        else: 
+            #newton step with residual
+            _x, res = self._newton(x, g, jac)
+
+            #anderson step with no residual
+            y, _ = super().step(_x, g)
+
+            return y, res