Merge pull request #203 from pathsim/feature/mutable-parameter-decorator

milanofthe · web-flow · commit c579dd7569e7 · 2026-02-26T10:51:58.000+01:00
Add mutable decorator for runtime parameter reinitialization
diff --git a/src/pathsim/blocks/converters.py b/src/pathsim/blocks/converters.py
@@ -12,10 +12,12 @@
 from ._block import Block
 from ..utils.register import Register
 from ..events.schedule import Schedule
+from ..utils.mutable import mutable
 
 
 # MIXED SIGNAL BLOCKS ===================================================================
 
+@mutable
 class ADC(Block):
     """Models an ideal Analog-to-Digital Converter (ADC).
 
@@ -104,6 +106,7 @@ def __len__(self):
         return 0
 
 
+@mutable
 class DAC(Block):
     """Models an ideal Digital-to-Analog Converter (DAC).
 
diff --git a/src/pathsim/blocks/ctrl.py b/src/pathsim/blocks/ctrl.py
@@ -14,10 +14,12 @@
 from .dynsys import DynamicalSystem
 
 from ..optim.operator import Operator, DynamicOperator
+from ..utils.mutable import mutable
 
 
 # LTI CONTROL BLOCKS (StateSpace subclasses) ============================================
 
+@mutable
 class PT1(StateSpace):
     """First-order lag element (PT1).
 
@@ -65,6 +67,7 @@ def __init__(self, K=1.0, T=1.0):
             )
 
 
+@mutable
 class PT2(StateSpace):
     """Second-order lag element (PT2).
 
@@ -124,6 +127,7 @@ def __init__(self, K=1.0, T=1.0, d=1.0):
             )
 
 
+@mutable
 class LeadLag(StateSpace):
     """Lead-Lag compensator.
 
@@ -180,6 +184,7 @@ def __init__(self, K=1.0, T1=1.0, T2=1.0):
             )
 
 
+@mutable
 class PID(StateSpace):
     """Proportional-Integral-Differentiation (PID) controller.
 
@@ -253,6 +258,7 @@ def __init__(self, Kp=0, Ki=0, Kd=0, f_max=100):
             )
 
 
+@mutable
 class AntiWindupPID(PID):
     """Proportional-Integral-Differentiation (PID) controller with anti-windup mechanism (back-calculation).
 
diff --git a/src/pathsim/blocks/delay.py b/src/pathsim/blocks/delay.py
@@ -12,10 +12,12 @@
 from ._block import Block
 
 from ..utils.adaptivebuffer import AdaptiveBuffer
+from ..utils.mutable import mutable
 
 
 # BLOCKS ================================================================================
 
+@mutable
 class Delay(Block):
     """Delays the input signal by a time constant 'tau' in seconds. 
 
diff --git a/src/pathsim/blocks/divider.py b/src/pathsim/blocks/divider.py
@@ -15,13 +15,15 @@
 from ._block import Block
 from ..utils.register import Register
 from ..optim.operator import Operator
+from ..utils.mutable import mutable
 
 
 # MISO BLOCKS ===========================================================================
 
 _ZERO_DIV_OPTIONS = ("warn", "raise", "clamp")
 
 
+@mutable
 class Divider(Block):
     """Multiplies and divides input signals (MISO).
 
diff --git a/src/pathsim/blocks/filters.py b/src/pathsim/blocks/filters.py
@@ -14,10 +14,12 @@
 
 from .lti import StateSpace
 from ..utils.register import Register
+from ..utils.mutable import mutable
 
 
 # FILTER BLOCKS =========================================================================
 
+@mutable
 class ButterworthLowpassFilter(StateSpace):
     """Direct implementation of a low pass butterworth filter block.
 
@@ -52,6 +54,7 @@ def __init__(self, Fc=100, n=2):
         super().__init__(omega_c*A, omega_c*B, C, D)
 
 
+@mutable
 class ButterworthHighpassFilter(StateSpace):
     """Direct implementation of a high pass butterworth filter block.
 
@@ -85,6 +88,7 @@ def __init__(self, Fc=100, n=2):
         super().__init__(omega_c*A, omega_c*B, C, D)
 
 
+@mutable
 class ButterworthBandpassFilter(StateSpace):
     """Direct implementation of a bandpass butterworth filter block.
 
@@ -119,6 +123,7 @@ def __init__(self, Fc=[50, 100], n=2):
         super().__init__(*tf2ss(num, den))
 
 
+@mutable
 class ButterworthBandstopFilter(StateSpace):
     """Direct implementation of a bandstop butterworth filter block.
 
@@ -153,6 +158,7 @@ def __init__(self, Fc=[50, 100], n=2):
         super().__init__(*tf2ss(num, den))
 
 
+@mutable
 class AllpassFilter(StateSpace):
     """Direct implementation of a first order allpass filter, or a cascade 
     of n 1st order allpass filters
diff --git a/src/pathsim/blocks/fir.py b/src/pathsim/blocks/fir.py
@@ -10,13 +10,15 @@
 import numpy as np
 from collections import deque
 
-from ._block import Block    
+from ._block import Block
 from ..utils.register import Register
-from ..events.schedule import Schedule 
+from ..events.schedule import Schedule
+from ..utils.mutable import mutable
 
 
 # FIR FILTER BLOCK ======================================================================
 
+@mutable
 class FIR(Block):
     """Models a discrete-time Finite-Impulse-Response (FIR) filter.
 
diff --git a/src/pathsim/blocks/lti.py b/src/pathsim/blocks/lti.py
@@ -22,6 +22,7 @@
 from ..utils.deprecation import deprecated
 
 from ..optim.operator import DynamicOperator
+from ..utils.mutable import mutable
 
 
 # LTI BLOCKS ============================================================================
@@ -169,6 +170,7 @@ def step(self, t, dt):
         return self.engine.step(f, dt)
 
 
+@mutable
 class TransferFunctionPRC(StateSpace):
     """This block defines a LTI (MIMO for pole residue) transfer function.
 
@@ -227,6 +229,7 @@ class TransferFunction(TransferFunctionPRC):
     pass
 
 
+@mutable
 class TransferFunctionZPG(StateSpace):
     """This block defines a LTI (SISO) transfer function.
 
@@ -281,6 +284,7 @@ def __init__(self, Zeros=[], Poles=[-1], Gain=1.0):
         super().__init__(sp_SS.A, sp_SS.B, sp_SS.C, sp_SS.D)
 
 
+@mutable
 class TransferFunctionNumDen(StateSpace):
     """This block defines a LTI (SISO) transfer function.
 
diff --git a/src/pathsim/blocks/samplehold.py b/src/pathsim/blocks/samplehold.py
@@ -9,10 +9,12 @@
 
 from ._block import Block
 from ..events.schedule import Schedule
+from ..utils.mutable import mutable
 
 
 # MIXED SIGNAL BLOCKS ===================================================================
 
+@mutable
 class SampleHold(Block):
     """Samples the inputs periodically and produces them at the output.
     
diff --git a/src/pathsim/blocks/sources.py b/src/pathsim/blocks/sources.py
@@ -14,6 +14,7 @@
 from ._block import Block
 from ..utils.register import Register
 from ..utils.deprecation import deprecated
+from ..utils.mutable import mutable
 from ..events.schedule import Schedule, ScheduleList
 from .._constants import TOLERANCE
 
@@ -169,6 +170,7 @@ def update(self, t):
 
 # SPECIAL CONTINUOUS SOURCE BLOCKS ======================================================
 
+@mutable
 class TriangleWaveSource(Source):
     """Source block that generates an analog triangle wave
         
@@ -214,6 +216,7 @@ def _triangle_wave(self, t, f):
         return 2 * abs(t*f - np.floor(t*f + 0.5)) - 1
 
 
+@mutable
 class SinusoidalSource(Source):
     """Source block that generates a sinusoid wave
         
@@ -289,6 +292,7 @@ def _gaussian(self, t, f_max):
         return np.exp(-(t/tau)**2)
 
 
+@mutable
 class SinusoidalPhaseNoiseSource(Block):
     """Sinusoidal source with cumulative and white phase noise.
     
@@ -703,6 +707,7 @@ class ChirpSource(ChirpPhaseNoiseSource):
 
 # SPECIAL DISCRETE SOURCE BLOCKS ========================================================
 
+@mutable
 class PulseSource(Block):
     """Generates a periodic pulse waveform with defined rise and fall times.
 
@@ -909,6 +914,7 @@ class Pulse(PulseSource):
     pass
 
 
+@mutable
 class ClockSource(Block):
     """Discrete time clock source block.
     
@@ -970,6 +976,7 @@ class Clock(ClockSource):
 
 
 
+@mutable
 class SquareWaveSource(Block):
     """Discrete time square wave source.
     
diff --git a/src/pathsim/blocks/spectrum.py b/src/pathsim/blocks/spectrum.py
@@ -15,12 +15,14 @@
 
 from ..utils.realtimeplotter import RealtimePlotter
 from ..utils.deprecation import deprecated
+from ..utils.mutable import mutable
 
 from .._constants import COLORS_ALL
 
 
 # BLOCKS FOR DATA RECORDING =============================================================
 
+@mutable
 class Spectrum(Block):
     """Block for fourier spectrum analysis (spectrum analyzer).
 
diff --git a/src/pathsim/utils/__init__.py b/src/pathsim/utils/__init__.py
@@ -1 +1,2 @@
 from .deprecation import deprecated
+from .mutable import mutable
diff --git a/src/pathsim/utils/mutable.py b/src/pathsim/utils/mutable.py
diff --git a/tests/pathsim/utils/test_mutable.py b/tests/pathsim/utils/test_mutable.py

Original file line number	Diff line number	Diff line change
`@@ -14,10 +14,12 @@`
`14`	`14`	`from .dynsys import DynamicalSystem`
`15`	`15`
`16`	`16`	`from ..optim.operator import Operator, DynamicOperator`
	`17`	`+from ..utils.mutable import mutable`
`17`	`18`
`18`	`19`
`19`	`20`	`# LTI CONTROL BLOCKS (StateSpace subclasses) ============================================`
`20`	`21`
	`22`	`+@mutable`
`21`	`23`	`class PT1(StateSpace):`
`22`	`24`	`"""First-order lag element (PT1).`
`23`	`25`
`@@ -65,6 +67,7 @@ def __init__(self, K=1.0, T=1.0):`
`65`	`67`	`)`
`66`	`68`
`67`	`69`
	`70`	`+@mutable`
`68`	`71`	`class PT2(StateSpace):`
`69`	`72`	`"""Second-order lag element (PT2).`
`70`	`73`
`@@ -124,6 +127,7 @@ def __init__(self, K=1.0, T=1.0, d=1.0):`
`124`	`127`	`)`
`125`	`128`
`126`	`129`
	`130`	`+@mutable`
`127`	`131`	`class LeadLag(StateSpace):`
`128`	`132`	`"""Lead-Lag compensator.`
`129`	`133`
`@@ -180,6 +184,7 @@ def __init__(self, K=1.0, T1=1.0, T2=1.0):`
`180`	`184`	`)`
`181`	`185`
`182`	`186`
	`187`	`+@mutable`
`183`	`188`	`class PID(StateSpace):`
`184`	`189`	`"""Proportional-Integral-Differentiation (PID) controller.`
`185`	`190`
`@@ -253,6 +258,7 @@ def __init__(self, Kp=0, Ki=0, Kd=0, f_max=100):`
`253`	`258`	`)`
`254`	`259`
`255`	`260`
	`261`	`+@mutable`
`256`	`262`	`class AntiWindupPID(PID):`
`257`	`263`	`"""Proportional-Integral-Differentiation (PID) controller with anti-windup mechanism (back-calculation).`
`258`	`264`