pathsim 0.28.0__tar.gz → 0.29.0__tar.gz

{pathsim-0.28.0 → pathsim-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pathsim
-Version: 0.28.0
+Version: 0.29.0
 Summary: A differentiable block based hybrid system simulation framework.
 Author-email: Milan Rother <milan.rother@gmx.de>
 License: MIT

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/__init__.py

@@ -8,5 +8,6 @@ except Exception:
 from .simulation import Simulation
 from .connection import Connection, Duplex
 from .subsystem import Subsystem, Interface
+from .utils.carrier import Carrier, Vector
 from .utils.logger import LoggerManager
 from .exceptions import StopSimulation

{pathsim-0.28.0 → pathsim-0.29.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.28.0'
-__version_tuple__ = version_tuple = (0, 28, 0)
+__version__ = version = '0.29.0'
+__version_tuple__ = version_tuple = (0, 29, 0)
 
-__commit_id__ = commit_id = 'ge34add612'
+__commit_id__ = commit_id = 'g220bc787c'

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/blocks/__init__.py

@@ -19,6 +19,7 @@ from .switch import *
 from .dynsys import *
 from .kalman import *
 from .adder import *
+from .splitter import *
 from .scope import *
 from .delay import *
 from .noise import *

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/blocks/_block.py

@@ -22,32 +22,6 @@ from ..optim.operator import DynamicOperator
 from ..exceptions import LinearizationError
 
 
-# HELPERS ===============================================================================
-
-def _labels_size(labels):
-    """Minimum register size required to hold all declared port labels.
-
-    Port labels map string aliases to integer port indices. The register has
-    to be large enough to address the highest declared index, otherwise blocks
-    with unconnected declared ports (e.g. a multi-input block placed without
-    connections) would default to the size 1 register and break positional
-    input access.
-
-    Parameters
-    ----------
-    labels : dict[str: int] | None
-        port label mapping (alias -> index)
-
-    Returns
-    -------
-    size : int | None
-        minimum register size, or None if no labels are declared
-    """
-    if not labels:
-        return None
-    return max(labels.values()) + 1
-
-
 # BASE BLOCK CLASS ======================================================================
 
 class Block:
@@ -123,14 +97,8 @@ class Block:
 
         #registers to hold input and output values, pre-sized to the declared
         #port labels so blocks with unconnected ports are still addressable
-        self.inputs = Register(
-            size=_labels_size(self.input_port_labels),
-            mapping=self.input_port_labels and self.input_port_labels.copy()
-            )
-        self.outputs = Register(
-            size=_labels_size(self.output_port_labels),
-            mapping=self.output_port_labels and self.output_port_labels.copy()
-            )
+        self.inputs = Register(mapping=self.input_port_labels)
+        self.outputs = Register(mapping=self.output_port_labels)
 
         #initialize integration engine as 'None' by default
         self.engine = None

pathsim-0.29.0/src/pathsim/blocks/splitter.py

@@ -0,0 +1,124 @@
+#########################################################################################
+##
+##                                  SPLITTER BLOCK
+##                               (blocks/splitter.py)
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+import numpy as np
+
+from ._block import Block
+from ..optim.operator import Operator
+from ..utils.carrier import Carrier, Vector
+from ..utils.mutable import mutable
+
+
+# SIMO BLOCKS ===========================================================================
+
+@mutable
+class Splitter(Block):
+    """Splits the input into multiple outputs, weighted with fractions (SIMO).
+
+    .. math::
+
+        y_i(t) = f_i \\cdot u(t)
+
+    The fractions have to sum up to one, so the splitter conserves what flows
+    through it, for example a mass or molar flow.
+
+    With a carrier, the input is a stream of multiple channels, for example
+    the flows of multiple species. Every output is a stream with the same
+    layout and each channel is split with the same fractions.
+
+
+    Example
+    -------
+    Split a flow into two outputs with 90 and 10 percent:
+
+    .. code-block:: python
+
+        S = Splitter([0.9, 0.1])
+
+    Split a stream of species flows, the ports 'in', 'out_0' and 'out_1'
+    have the layout of the carrier:
+
+    .. code-block:: python
+
+        class Species(Carrier):
+            keys = ("H", "D", "T")
+
+        S = Splitter([0.9, 0.1], carrier=Species())
+
+        C = Connection(S["out_1"], B["in"])
+
+
+    Note
+    ----
+    This block is purely algebraic and its operation (`op_alg`) will be called
+    multiple times per timestep, each time when `Simulation._update(t)` is
+    called in the global simulation loop.
+
+
+    Parameters
+    ----------
+    fractions : array_like
+        fractions of the input for each output, must sum up to one
+    carrier : Carrier | None
+        layout of the input and output streams, single channel if 'None'
+
+
+    Attributes
+    ----------
+    op_alg : Operator
+        internal algebraic operator
+    """
+
+    input_port_labels = {"in": 0}
+    output_port_labels = None
+
+    def __init__(self, fractions=None, carrier=None):
+
+        self.fractions = np.ones(1) if fractions is None else np.asarray(fractions, dtype=float)
+        self.carrier = carrier
+
+        #input validation
+        if not np.isclose(np.sum(self.fractions), 1.0):
+            raise ValueError(f"'fractions' must sum up to one but sum up to {np.sum(self.fractions)}!")
+
+        #ports with the layout of the carrier, placed one after another
+        n = 1 if carrier is None else len(carrier)
+
+        def _port(start):
+            if carrier is None:
+                return start
+            if carrier.keys:
+                return Carrier(start, keys=carrier.keys)
+            return Vector(n, start)
+
+        self.input_port_labels = {"in": _port(0)}
+        self.output_port_labels = {
+            f"out_{i}": _port(i * n) for i in range(len(self.fractions))
+            }
+
+        super().__init__()
+
+        #every channel of the input split with the same fractions
+        self.op_alg = Operator(
+            func=lambda u: np.kron(self.fractions, u),
+            jac=lambda u: np.kron(self.fractions.reshape(-1, 1), np.eye(len(u)))
+            )
+
+
+    def update(self, t):
+        """update system equation
+
+        Parameters
+        ----------
+        t : float
+            evaluation time
+        """
+        u = self.inputs.to_array()
+        y = self.op_alg(u)
+        self.outputs.update_from_array(y)

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/connection.py

@@ -138,9 +138,12 @@ class Connection:
     ----------
     _active : bool
         flag to set 'Connection' as active or inactive
+    _transfers : list[tuple[Block, int | np.ndarray, int | np.ndarray]] | None
+        resolved data transfers to the targets as tuples of target block,
+        target and source channel indices, built by 'resolve_ports'
     """
 
-    __slots__ = ["source", "targets", "_active"]
+    __slots__ = ["source", "targets", "_active", "_transfers"]
 
 
     def __init__(self, source, *targets):
@@ -153,6 +156,9 @@ class Connection:
 
         #flag to set connection active
         self._active = True
+
+        #resolved data transfers (lazily initialized)
+        self._transfers = None
         
         #validate port aliases
         self._validate_ports()
@@ -169,8 +175,10 @@ class Connection:
 
 
     def __len__(self):
-        """Returns the number of ports that are defined in the connection"""
-        return len(self.source)
+        """Returns the number of channels that are defined in the connection,
+        ports that are carriers count with all of their channels
+        """
+        return len(self.source.block.outputs._resolve(self.source.ports))
 
 
     def __bool__(self):
@@ -199,9 +207,9 @@ class Connection:
         """Check the dimensions of the source and target ports, 
         if they dont match, raises an exception.
         """
-        n_src = len(self.source)
+        n_src = len(self)
         for trg in self.targets:
-            if len(trg) != n_src:
+            if len(trg.block.inputs._resolve(trg.ports)) != n_src:
                 raise ValueError(f"Source and target have different number of ports!")
 
 
@@ -245,8 +253,12 @@ class Connection:
         """Transfers data from the source block output port 
         to the target block input port.
         """
-        for trg in self.targets:
-            self.source.to(trg)
+        if self._transfers is None:
+            self.resolve_ports()
+
+        _data = self.source.block.outputs._data
+        for block, i_trg, i_src in self._transfers:
+            block.inputs._data[i_trg] = _data[i_src]
 
 
     def resolve_ports(self):
@@ -267,10 +279,20 @@ class Connection:
         Calling ``resolve_ports`` once during graph assembly closes that
         gap. Idempotent. New register slots are zero-initialised through
         ``np.zeros`` in ``Register.resize``.
+
+        The resolved indices are stored as data transfers for ``update``,
+        transfers of a single channel use plain integer indices, which is
+        faster than fancy indexing with an index array.
         """
-        self.source._get_output_indices()
+        i_src = self.source._get_output_indices()
+
+        self._transfers = []
         for trg in self.targets:
-            trg._get_input_indices()
+            i_trg = trg._get_input_indices()
+            if len(i_trg) == 1:
+                self._transfers.append((trg.block, int(i_trg[0]), int(i_src[0])))
+            else:
+                self._transfers.append((trg.block, i_trg, i_src))
 
 
 @deprecated(version="1.0.0")

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/optim/linearization.py

@@ -69,28 +69,44 @@ def _state_labels(x_layout, keys):
     return labels
 
 
-def _port_labels(port_refs, keys):
-    """One label per resolved port across a list of 'PortReference', in the
+def _port_labels(port_refs, keys, inputs=True):
+    """One label per resolved channel across a list of 'PortReference', in the
     same order as the assembled 'B' columns or 'C' and 'D' rows.
 
+    Ports that are carriers get one label per channel, named by the channel
+    key or by the channel position for carriers without keys.
+
     Parameters
     ----------
     port_refs : list[PortReference]
         break points or tap points
     keys : dict[Block: str]
         canonical identifiers from '_block_keys'
+    inputs : bool
+        resolve the ports in the block inputs, otherwise in the block outputs
 
     Returns
     -------
     labels : list[str]
-        one label per port
+        one label per channel
     """
     labels = []
     for pr in port_refs:
-        if len(pr.ports) == 1:
+        register = pr.block.inputs if inputs else pr.block.outputs
+
+        #single channel -> block identifier only
+        if len(register._resolve(pr.ports)) == 1:
             labels.append(keys[pr.block])
-        else:
-            labels.extend(f"{keys[pr.block]}[{p}]" for p in pr.ports)
+            continue
+
+        for p in pr.ports:
+            carrier = register._carriers.get(p) if isinstance(p, str) else None
+            if carrier is None:
+                name = f"{p[0]}.{p[1]}" if isinstance(p, tuple) else p
+                labels.append(f"{keys[pr.block]}[{name}]")
+            else:
+                names = carrier.keys or range(len(carrier))
+                labels.extend(f"{keys[pr.block]}[{p}.{k}]" for k in names)
     return labels
 
 
@@ -305,6 +321,6 @@ def assemble_statespace(blocks, connections, inputs, outputs, t):
     return (
         A, B, C, D,
         _state_labels(x_layout, keys),
-        _port_labels(inputs, keys),
-        _port_labels(outputs, keys)
+        _port_labels(inputs, keys, inputs=True),
+        _port_labels(outputs, keys, inputs=False)
         )

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/simulation.py

@@ -1260,29 +1260,30 @@ class Simulation:
         #log message begin of steady state solver
         self.logger.info(f"STEADYSTATE -> STARTING (reset: {reset})")
 
-        #solve for steady state at current time
-        with Timer(verbose=False) as T:
-            success, evals, iters = self._solve(self.time, self.dt)
-
-        #catch non convergence
-        if not success:
-            details = self._solve_tracker.details(lambda b: b.__class__.__name__)
-            _msg = "STEADYSTATE -> FAILED (evals: {}, iters: {}, runtime: {})\n{}".format(
-                evals, iters, T, "\n".join(details))
-            self.logger.error(_msg)
-            raise RuntimeError(_msg)
-
-        #sample result
-        self._sample(self.time, self.dt)
-
-        #log message
-        self.logger.info(
-            "STEADYSTATE -> FINISHED (success: {}, evals: {}, iters: {}, runtime: {})".format(
-                success, evals, iters, T)
-            )
-
-        #switch back to original solver
-        self._set_solver(_solver)
+        try:
+            #solve for steady state at current time
+            with Timer(verbose=False) as T:
+                success, evals, iters = self._solve(self.time, self.dt)
+
+            #catch non convergence
+            if not success:
+                details = self._solve_tracker.details(lambda b: b.__class__.__name__)
+                _msg = "STEADYSTATE -> FAILED (evals: {}, iters: {}, runtime: {})\n{}".format(
+                    evals, iters, T, "\n".join(details))
+                self.logger.error(_msg)
+                raise RuntimeError(_msg)
+
+            #sample result
+            self._sample(self.time, self.dt)
+
+            #log message
+            self.logger.info(
+                "STEADYSTATE -> FINISHED (success: {}, evals: {}, iters: {}, runtime: {})".format(
+                    success, evals, iters, T)
+                )
+        finally:
+            #restore the transient solver even if solving or sampling fails
+            self._set_solver(_solver)
 
 
     # initial timestep estimation -------------------------------------------------

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/subsystem.py

@@ -786,6 +786,9 @@ class Subsystem(Block):
         if not _blocks_dyn:
             return None
 
+        #the parent may have supplied new inputs after evaluating our outputs
+        self.update(t)
+
         _derivatives = []
         for b in _blocks_dyn:
             _d = b.derivative(t)
@@ -928,6 +931,9 @@ class Subsystem(Block):
         max_error : float
             maximum error of implicit update equaiton
         """
+        #refresh internal inputs for the current implicit stage
+        self.update(t)
+
         max_error = 0.0
         for block in self._blocks_dyn:
             if not block: continue
@@ -963,6 +969,9 @@ class Subsystem(Block):
             rescale factor for timestep
         """
 
+        #refresh internal inputs for the current explicit stage
+        self.update(t)
+
         #initial timestep rescale and error estimate
         success, max_error_norm, min_scale = True, 0.0, None
 
@@ -1045,4 +1054,4 @@ class Subsystem(Block):
             evaluation time for buffering    
         """
         for block in self._blocks_dyn:
-            if block: block.buffer(dt)
+            if block: block.buffer(dt)

pathsim-0.29.0/src/pathsim/utils/carrier.py

@@ -0,0 +1,213 @@
+#########################################################################################
+##
+##                                   CARRIER CLASS
+##                               (utils/carrier.py)
+##
+##            This module defines the 'Carrier' class that groups multiple
+##          scalar channels of a block register into a single named entity
+##
+#########################################################################################
+
+# CLASSES ===============================================================================
+
+class Carrier:
+    """Named range of scalar channels of a block register.
+
+    A carrier describes a contiguous block of channels and gives each of them
+    a name. It is placed at an explicit position ('start') in the register of
+    a block and used as the value of a port label
+
+    .. code-block:: python
+
+        _in_1 = Carrier(keys=("F", "T"))
+        _in_2 = Carrier(_in_1.stop, keys=("F", "T"))
+
+        class Mixer(Block):
+            input_port_labels = {"in_1": _in_1, "in_2": _in_2}
+
+
+    The carrier only exists while the system graph is assembled. Component
+    access resolves to plain integer indices, either by attribute or by key
+
+    .. code-block:: python
+
+        _in_1.F     # -> 0
+        _in_1["T"]  # -> 1
+        _in_1[1]    # -> 1
+
+
+    so the values themselves stay in the flat float64 register of the block
+    and nothing carrier specific is left at runtime
+
+    .. code-block:: python
+
+        def func(u):
+            return u[_in_1.F] + u[_in_2.F]
+
+
+    Note
+    ----
+    Carriers are addressed as a whole when blocks are connected, a connection
+    to a carrier port transfers all its channels at once.
+
+
+    Parameters
+    ----------
+    start : int
+        index of the first channel in the register of the block
+    keys : tuple[str] | list[str] | None
+        names of the channels, overrides the class level 'keys'
+
+
+    Attributes
+    ----------
+    keys : tuple[str]
+        names of the channels
+    start : int
+        index of the first channel
+    stop : int
+        index after the last channel
+    """
+
+    keys = ()
+
+    #names that would collide with the carrier interface itself
+    _reserved = ("keys", "start", "stop", "size", "slice")
+
+    def __init__(self, start=0, keys=None):
+
+        #channel names, from the arguments or from the class
+        if keys is not None:
+            self.keys = tuple(keys)
+
+        #key validation
+        for key in self.keys:
+            if not isinstance(key, str):
+                raise ValueError(f"Key '{key}' must be str but is '{type(key)}'!")
+            if key in self._reserved or key.startswith("_"):
+                raise ValueError(f"Key '{key}' is reserved!")
+        if len(set(self.keys)) < len(self.keys):
+            raise ValueError("Keys must be unique!")
+
+        #position validation
+        if not isinstance(start, int) or start < 0:
+            raise ValueError(f"Start '{start}' must be a positive int!")
+
+        #size validation
+        if self.size < 1:
+            raise ValueError("Carrier must have at least one channel!")
+
+        self.start = start
+        self.stop = start + self.size
+
+        #channel indices as plain attributes, resolved once
+        for i, key in enumerate(self.keys):
+            setattr(self, key, start + i)
+
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self.start}, {self.keys})"
+
+
+    @property
+    def size(self):
+        """Number of channels covered by the carrier
+
+        Returns
+        -------
+        size : int
+            number of channels
+        """
+        return len(self.keys)
+
+
+    def __len__(self):
+        return self.size
+
+
+    def __getitem__(self, key):
+        """Index of a single channel of the carrier, by key or by position.
+
+        Parameters
+        ----------
+        key : int, str
+            channel name or channel position within the carrier
+
+        Returns
+        -------
+        index : int
+            index of the channel in the register of the block
+        """
+
+        if isinstance(key, str):
+            if key not in self.keys:
+                raise ValueError(f"Key '{key}' not defined for {self}!")
+            return getattr(self, key)
+
+        if isinstance(key, int):
+            if key < 0 or key >= self.size:
+                raise ValueError(f"Channel '{key}' outside of {self}!")
+            return self.start + key
+
+        raise ValueError(f"Key must be (int, str) but is '{type(key)}'!")
+
+
+    @property
+    def slice(self):
+        """All channels of the carrier as a slice, for direct access to the
+        flat register data, for example 'u[_in_1.slice]'
+
+        Returns
+        -------
+        slice : slice
+            slice covering all channels of the carrier
+        """
+        return slice(self.start, self.stop)
+
+
+class Vector(Carrier):
+    """Carrier for a fixed number of unnamed channels.
+
+    Channels are addressed by position only, which makes this the carrier
+    for values that have a size but no component names, such as a spatial
+    discretization
+
+    .. code-block:: python
+
+        v = Vector(3)
+        v[0]  # -> 0
+        v[2]  # -> 2
+
+
+    Parameters
+    ----------
+    size : int
+        number of channels
+    start : int
+        index of the first channel in the register of the block
+    """
+
+    def __init__(self, size, start=0):
+
+        #size validation
+        if not isinstance(size, int) or size < 1:
+            raise ValueError(f"Size '{size}' must be a positive int!")
+
+        self._size = size
+        super().__init__(start)
+
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self.size}, {self.start})"
+
+
+    @property
+    def size(self):
+        """Number of channels covered by the carrier
+
+        Returns
+        -------
+        size : int
+            number of channels
+        """
+        return self._size

{pathsim-0.28.0 → pathsim-0.29.0}/src/pathsim/utils/graph.py

@@ -115,16 +115,19 @@ class Graph:
     def _validate_connections(self):
         """Fast O(N) validation that no connections overwrite each other.
         
-        Checks that no two connections target the same (block, port) pair.
+        Checks that no two connections target the same (block, channel) pair.
+        Ports are resolved to channel indices first, so port names, ports that
+        are carriers and single carrier channels are compared on the channels
+        they actually cover.
         """
-        # {(block, port_idx): connection}
+        # {(block, channel_idx): connection}
         connected_targets = set()
         
         for connection in self.connections:
             for target in connection.targets:
                 target_block = target.block
-                for port_idx in target.ports:
-                    key = (target_block, port_idx)
+                for port_idx in target_block.inputs._resolve(target.ports):
+                    key = (target_block, int(port_idx))
                     if key in connected_targets:
                         raise ValueError(
                             f"Connection conflict detected"