pathsim 0.21.1__tar.gz → 0.22.1__tar.gz

{pathsim-0.21.1 → pathsim-0.22.1}/.github/workflows/pypi_deployment.yml

@@ -12,12 +12,12 @@ jobs:
   deploy:
     runs-on: ubuntu-latest  
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0 
     
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.x'
     

{pathsim-0.21.1 → pathsim-0.22.1}/.github/workflows/tests_codecov.yml

@@ -4,9 +4,9 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.x'
       - name: Install dependencies

{pathsim-0.21.1 → pathsim-0.22.1}/.github/workflows/urlchecker.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: urls-checker
       uses: urlstechie/urlchecker-action@master
       with:

{pathsim-0.21.1 → pathsim-0.22.1}/PKG-INFO

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

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim/__init__.py

@@ -9,3 +9,4 @@ from .simulation import Simulation
 from .connection import Connection, Duplex
 from .subsystem import Subsystem, Interface
 from .utils.logger import LoggerManager
+from .exceptions import StopSimulation

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.21.1'
-__version_tuple__ = version_tuple = (0, 21, 1)
+__version__ = version = '0.22.1'
+__version_tuple__ = version_tuple = (0, 22, 1)
 
-__commit_id__ = commit_id = 'g1f8538a26'
+__commit_id__ = commit_id = 'g33dfc7866'

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim/blocks/_block.py

@@ -18,6 +18,32 @@ from ..utils.register import Register
 from ..utils.portreference import PortReference
 
 
+# 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:
@@ -84,11 +110,14 @@ class Block:
 
     def __init__(self):
 
-        #registers to hold input and output values
+        #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()
             )
 

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim/connection.py

@@ -249,6 +249,30 @@ class Connection:
             self.source.to(trg)
 
 
+    def resolve_ports(self):
+        """Eagerly resolve source and target port indices, growing the
+        underlying ``Register`` instances to their final size.
+
+        Normally registers grow lazily on the first ``connection.update()``
+        via ``PortReference._get_input_indices``. In the DAG case that is
+        fine: the source-side connection fires before the target block's
+        ``update``, so by the time the block reads its inputs, the
+        register has the right size. Inside an algebraic loop the order
+        is reversed (``block.update()`` first, then ``connection.update()``
+        in the same iteration), so the first iteration sees a register
+        still at the ``Block.__init__`` default size and any block that
+        accesses inputs by position (e.g. ``Function`` splatting into a
+        multi-arg callable) raises ``TypeError``.
+
+        Calling ``resolve_ports`` once during graph assembly closes that
+        gap. Idempotent. New register slots are zero-initialised through
+        ``np.zeros`` in ``Register.resize``.
+        """
+        self.source._get_output_indices()
+        for trg in self.targets:
+            trg._get_input_indices()
+
+
 @deprecated(version="1.0.0")
 class Duplex(Connection):
     """Extension of the 'Connection' class, that defines bidirectional

pathsim-0.22.1/src/pathsim/exceptions.py

@@ -0,0 +1,44 @@
+#########################################################################################
+##
+##                              PATHSIM EXCEPTIONS
+##                               (exceptions.py)
+##
+##      This module defines custom exceptions for the PathSim simulation framework.
+##
+#########################################################################################
+
+
+class StopSimulation(Exception):
+    """Exception that can be raised by blocks or models to signal that the 
+    simulation should stop immediately.
+
+    This provides a clean mechanism for user-defined stopping conditions,
+    such as reaching a target state, detecting a fault, or satisfying 
+    a convergence criterion.
+
+    When raised inside a block's update, sample, or any other method 
+    called during the simulation loop, the 'Simulation' class will catch 
+    it gracefully and terminate the run as if 'stop()' had been called.
+
+    Parameters
+    ----------
+    message : str
+        optional message describing the stopping condition
+
+    Example
+    -------
+
+    Raise from inside a block to stop the simulation:
+
+    .. code-block:: python
+
+        from pathsim.exceptions import StopSimulation
+        from pathsim.blocks import Function
+
+        def check(x):
+            if x > 10.0:
+                raise StopSimulation(f"value exceeded threshold: {x:.4f}")
+            return x
+
+        blk = Function(check)
+    """

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim/simulation.py

@@ -47,6 +47,7 @@ from .blocks._block import Block
 from .events._event import Event
 
 from .connection import Connection
+from .exceptions import StopSimulation
 
 
 # TRANSIENT SIMULATION CLASS ============================================================
@@ -690,6 +691,12 @@ class Simulation:
         for block in self.blocks:
             block.inputs.reset()
 
+        #resolve all port indices so input/output registers are sized before
+        #graph assembly evaluates block passthrough via len(block) and before
+        #any block.update() runs (see Connection.resolve_ports)
+        for con in self.connections:
+            con.resolve_ports()
+
         #time the graph construction
         with Timer(verbose=False) as T:
             self.graph = Graph(self.blocks, self.connections)
@@ -1472,14 +1479,17 @@ class Simulation:
 
                     #implicit solver didn't converge
                     if not success:
-                        details = self._solve_tracker.details(lambda b: b.__class__.__name__)
                         if is_adaptive:
-                            self.logger.warning(
-                                "implicit solver not converged, reverting step at t={:.6f}\n{}".format(
-                                    time_stage, "\n".join(details)))
+                            #adaptive stepping: a non-converged solve is
+                            #the expected signal to halve the step and
+                            #retry. revert silently — same handling as the
+                            #LTE failure below. residuals stay available
+                            #via self._solve_tracker for diagnostics.
                             self._revert(self.time)
                             return False, 0.0, 0.5, total_evals + 1, total_solver_its
                         else:
+                            #fixed-step: user has no recovery path, log it
+                            details = self._solve_tracker.details(lambda b: b.__class__.__name__)
                             self.logger.warning(
                                 "implicit solver not converged at t={:.6f} (iters: {})\n{}".format(
                                     time_stage, solver_its, "\n".join(details)))
@@ -1623,16 +1633,22 @@ class Simulation:
         _dt = self.dt
 
         #initial system function evaluation
-        self._update(self.time)
+        try:
+            self._update(self.time)
 
-        #catch and resolve initial events
-        for event, *_ in self._detected_events(self.time):
+            #catch and resolve initial events
+            for event, *_ in self._detected_events(self.time):
 
-            #resolve events directly
-            event.resolve(self.time)
+                #resolve events directly
+                event.resolve(self.time)
 
-            #evaluate system function again -> propagate event
-            self._update(self.time)
+                #evaluate system function again -> propagate event
+                self._update(self.time)
+
+        except StopSimulation as e:
+            self.logger.info(f"STOP (StopSimulation: '{e}')")
+            self._active = False
+            return
 
         #sampling states and inputs at 'self.time == starting_time'
         self._sample(self.time, _dt)
@@ -1641,10 +1657,15 @@ class Simulation:
         while self.time < end_time and self._active:
 
             #advance the simulation by one (effective) timestep '_dt'
-            success, error_norm, scale, *_ = self.timestep(
-                dt=_dt,
-                adaptive=_adaptive
-                )
+            try:
+                success, error_norm, scale, *_ = self.timestep(
+                    dt=_dt,
+                    adaptive=_adaptive
+                    )
+            except StopSimulation as e:
+                self.logger.info(f"STOP (StopSimulation: '{e}')")
+                self._active = False
+                break
 
             #perform adaptive rescale
             if _adaptive:

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim.egg-info/PKG-INFO

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

{pathsim-0.21.1 → pathsim-0.22.1}/src/pathsim.egg-info/SOURCES.txt

@@ -256,6 +256,7 @@ src/pathsim/__init__.py
 src/pathsim/_constants.py
 src/pathsim/_version.py
 src/pathsim/connection.py
+src/pathsim/exceptions.py
 src/pathsim/simulation.py
 src/pathsim/subsystem.py
 src/pathsim.egg-info/PKG-INFO

{pathsim-0.21.1 → pathsim-0.22.1}/tests/pathsim/blocks/test_block.py

@@ -254,6 +254,33 @@ class TestBlock(unittest.TestCase):
         self.assertEqual(cache_info.misses, 1)
 
 
+    def test_register_sizing_from_port_labels(self):
+        """Registers are pre-sized to the declared port labels so blocks
+        with unconnected multi-port interfaces stay positionally addressable.
+        """
+
+        class _LabeledBlock(Block):
+            input_port_labels = {"a": 0, "b": 1}
+            output_port_labels = {"x": 0, "y": 1, "z": 2}
+
+        B = _LabeledBlock()
+
+        #registers sized to highest declared index + 1
+        self.assertEqual(len(B.inputs), 2)
+        self.assertEqual(len(B.outputs), 3)
+
+        #shape reflects declared ports even without connections
+        self.assertEqual(B.shape, (2, 3))
+
+        #all declared ports addressable and zero-initialized
+        self.assertEqual(B.inputs["b"], 0.0)
+        self.assertEqual(B.outputs["z"], 0.0)
+
+        #blocks without port labels keep the default size 1 registers
+        self.assertEqual(len(Block().inputs), 1)
+        self.assertEqual(len(Block().outputs), 1)
+
+
 # RUN TESTS LOCALLY ====================================================================
 
 if __name__ == '__main__':

{pathsim-0.21.1 → pathsim-0.22.1}/tests/pathsim/test_connection.py

@@ -141,7 +141,7 @@ class TestConnection(unittest.TestCase):
 
 
     def test_on_off_bool(self):
-        
+
         B1, B2 = Block(), Block()
 
         #default
@@ -159,6 +159,62 @@ class TestConnection(unittest.TestCase):
         self.assertTrue(C)
 
 
+    def test_resolve_ports_grows_input_register(self):
+        """resolve_ports must size the target input register so blocks
+        accessing inputs by position before any connection.update() runs
+        (e.g. inside an algebraic loop) see the correct number of slots.
+        """
+        B1, B2 = Block(), Block()
+
+        #fresh block has size-1 input register from Block.__init__
+        self.assertEqual(len(B2.inputs), 1)
+
+        C = Connection(B1[2], B2[3])
+
+        #ports validated but lazy resize not yet triggered
+        self.assertEqual(len(B2.inputs), 1)
+        self.assertEqual(len(B1.outputs), 1)
+
+        C.resolve_ports()
+
+        #both registers must accommodate the highest port index
+        self.assertEqual(len(B2.inputs), 4)
+        self.assertEqual(len(B1.outputs), 3)
+
+        #new slots are zero-initialised
+        self.assertEqual(B2.inputs[3], 0.0)
+
+
+    def test_resolve_ports_is_idempotent(self):
+        """Repeated calls must not change register size or contents."""
+        B1, B2 = Block(), Block()
+        C = Connection(B1[5], B2[7])
+
+        C.resolve_ports()
+        size_in = len(B2.inputs)
+        size_out = len(B1.outputs)
+
+        #seed a value so we can detect data loss on a second resolve
+        B2.inputs[7] = 42.0
+
+        C.resolve_ports()
+        self.assertEqual(len(B2.inputs), size_in)
+        self.assertEqual(len(B1.outputs), size_out)
+        self.assertEqual(B2.inputs[7], 42.0)
+
+
+    def test_resolve_ports_multi_target(self):
+        """All targets must be resolved, not just the first."""
+        B1, B2, B3 = Block(), Block(), Block()
+        C = Connection(B1[1], B2[4], B3[6])
+
+        C.resolve_ports()
+
+        self.assertEqual(len(B1.outputs), 2)
+        self.assertEqual(len(B2.inputs), 5)
+        self.assertEqual(len(B3.inputs), 7)
+
+
 
 class TestDuplex(unittest.TestCase):
     """

{pathsim-0.21.1 → pathsim-0.22.1}/tests/pathsim/test_simulation.py

@@ -21,9 +21,11 @@ from pathsim.connection import Connection
 #modules from pathsim for test case
 from pathsim.blocks import (
     Integrator,
-    Amplifier,  
-    Scope, 
-    Adder
+    Amplifier,
+    Scope,
+    Adder,
+    Function,
+    Constant,
     )
 
 from pathsim._constants import (
@@ -37,6 +39,7 @@ from pathsim._constants import (
 from pathsim.blocks import Source, Relay
 from pathsim.events.schedule import Schedule
 from pathsim.events._event import Event
+from pathsim.exceptions import StopSimulation
 
 
 # TESTS ================================================================================
@@ -754,6 +757,82 @@ class TestSimulationAdvanced(unittest.TestCase):
         self.assertLess(self.Sim.time, 5.0)
 
 
+    def test_stop_simulation_exception_stops_run(self):
+        """StopSimulation raised by a block stops run() without propagating"""
+
+        threshold = 0.5  # Int state starts at 1 and decays — stop when below this
+
+        def guard(x):
+            if x < threshold:
+                raise StopSimulation(f"value dropped below {threshold}")
+            return x
+
+        guard_block = Function(guard)
+        self.Sim.add_block(guard_block)
+        self.Sim.add_connection(Connection(self.Int, guard_block))
+
+        # should not raise, and should stop before duration=5
+        self.Sim.run(duration=5.0, reset=True)
+
+        self.assertFalse(self.Sim._active)
+        self.assertLess(self.Sim.time, 5.0)
+
+
+    def test_stop_simulation_at_first_step(self):
+        """StopSimulation raised immediately leaves sim.time at start"""
+
+        call_count = [0]
+
+        def always_stop(x):
+            call_count[0] += 1
+            raise StopSimulation("stop immediately")
+
+        guard_block = Function(always_stop)
+        self.Sim.add_block(guard_block)
+        self.Sim.add_connection(Connection(self.Int, guard_block))
+
+        start_time = self.Sim.time
+        self.Sim.run(duration=5.0, reset=False)
+
+        self.assertFalse(self.Sim._active)
+        self.assertEqual(self.Sim.time, start_time)
+
+
+    def test_stop_simulation_exception_stops_run_streaming(self):
+        """StopSimulation raised by a block terminates run_streaming cleanly"""
+
+        threshold = 0.5
+
+        def guard(x):
+            if x < threshold:
+                raise StopSimulation("streaming stop")
+            return x
+
+        guard_block = Function(guard)
+        self.Sim.add_block(guard_block)
+        self.Sim.add_connection(Connection(self.Int, guard_block))
+
+        results = list(self.Sim.run_streaming(
+            duration=5.0,
+            reset=True,
+            tickrate=100,
+            func_callback=lambda: self.Sim.time
+        ))
+
+        self.assertFalse(self.Sim._active)
+        self.assertLess(self.Sim.time, 5.0)
+        self.assertGreater(len(results), 0)
+
+
+    def test_stop_simulation_no_exception_normal_run(self):
+        """Regression: normal run without StopSimulation completes fully"""
+
+        self.Sim.run(duration=2.0, reset=True)
+
+        self.assertAlmostEqual(self.Sim.time, 2.0, 5)
+        self.assertTrue(self.Sim._active)
+
+
     def test_deprecated_timestep_methods(self):
         """Test deprecated timestep methods still work"""
 
@@ -1045,6 +1124,65 @@ class TestSimulationRuntimeMutation(unittest.TestCase):
         self.assertGreater(len(time), 0)
 
 
+class TestSimulationAlgebraicLoop(unittest.TestCase):
+    """Regression tests for algebraic-loop port resolution.
+
+    In an algebraic loop the iteration order is block.update() ->
+    connection.update(). Without eager port resolution during graph
+    assembly the first iteration would see input registers still at
+    their Block.__init__ default size, and any block accessing inputs
+    by position (Function splatting into a multi-arg lambda) would
+    raise TypeError.
+    """
+
+    def test_function_in_algebraic_loop_runs(self):
+        """Function with multi-arg lambda inside algebraic loop must run."""
+
+        c = Constant(value=1.0)
+        A = Function(lambda u, fb: u + 0.1 * fb)
+        B = Function(lambda x: 0.5 * x)
+
+        blocks = [c, A, B]
+        connections = [
+            Connection(c, A[0]),
+            Connection(A, B),
+            Connection(B, A[1]),    # closes the loop
+            ]
+
+        Sim = Simulation(blocks, connections, dt=0.01, log=False)
+
+        #without eager resolution this would raise TypeError on the first
+        #step ("missing 1 required positional argument: 'fb'")
+        Sim.run(duration=0.05)
+
+        #fixed point: A = 1 + 0.1 * 0.5 * A  ->  A = 1 / 0.95
+        self.assertAlmostEqual(float(A.outputs[0]), 1.0 / 0.95, 6)
+
+
+    def test_assemble_graph_resolves_all_connections(self):
+        """After Simulation init every connection's registers are sized."""
+
+        c = Constant(value=1.0)
+        A = Function(lambda u, fb: u + fb)
+        B = Function(lambda x: x)
+
+        blocks = [c, A, B]
+        connections = [
+            Connection(c, A[0]),
+            Connection(A, B),
+            Connection(B, A[1]),
+            ]
+
+        Simulation(blocks, connections, dt=0.01, log=False)
+
+        #all registers must reach their final size during _assemble_graph
+        self.assertGreaterEqual(len(A.inputs), 2)
+        self.assertGreaterEqual(len(B.inputs), 1)
+        self.assertGreaterEqual(len(c.outputs), 1)
+        self.assertGreaterEqual(len(A.outputs), 1)
+        self.assertGreaterEqual(len(B.outputs), 1)
+
+
 # RUN TESTS LOCALLY ====================================================================
 
 if __name__ == '__main__':