Development environment setup

[SebastianJiroSchlecht]

Implement native arbitrary z-plane probing and autograd derivatives for FLAMO modules to enable advanced transfer-matrix analysis.

---

  

---

Note

Medium Risk
Adds new probe/probe_w APIs and matrix-composition logic across DSP building blocks; while runtime processing paths are largely unchanged, incorrect probe implementations or None-returning modules can lead to shape/dtype issues in transfer-matrix analysis.

Overview
Adds native arbitrary z-plane transfer-matrix probing across FLAMO DSP modules by introducing probe(z)/probe_w(w) on the DSP base and implementing concrete evaluations for key blocks (e.g. Gain, Filter/parallelFilter, SOSFilter variants, and Delay variants using H(z)=\gamma^m z^{-m}).

Extends system containers to compose these probes: Series now multiplies per-module transfer matrices, Recursion can probe the closed-loop transfer and exposes characteristic-matrix probing (probe_recursion*), Parallel combines branch transfer matrices, and Shell can optionally include input/output layer probes; Transform/FFT/iFFT add no-op probe stubs for compatibility.

^{Written by Cursor Bugbot for commit c0897ba. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[cursor]

Cursor Bugbot has reviewed your changes and found 4 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 4 issues found in the latest run.

• ✅ Fixed: Recursion.probe doesn't split ext_param for branches
  • Modified Recursion.probe to call _split_ext_param and pass the split parameters to feedforward and feedback branches.
• ✅ Fixed: Parallel.probe doesn't split ext_param for branches
  • Modified Parallel.probe to split ext_param by 'branchA' and 'branchB' keys before passing to each branch.
• ✅ Fixed: probe_w fallback to probe gives wrong z-transform
  • Removed incorrect fallback to probe in Series.probe_w and Recursion._eval_characteristic_w to prevent wrong z-transform computation.
• ✅ Fixed: Inherited Gain.probe crashes for HouseholderMatrix subclass
  • Added probe and probe_w overrides to HouseholderMatrix to correctly compute I - 2uu^T transfer matrix and avoid calling to_complex on already-complex tensor.

Or push these changes by commenting:

@cursor push e0aa132c68

Preview (e0aa132c68)

diff --git a/flamo/processor/dsp.py b/flamo/processor/dsp.py
--- a/flamo/processor/dsp.py
+++ b/flamo/processor/dsp.py
@@ -776,6 +776,26 @@
                 f"parameter shape = {self.size} not compatible with input signal of shape = ({x.shape})."
             )
 
+    def probe(self, z: torch.Tensor, ext_param=None):
+        r"""
+        Evaluate the Householder transfer matrix H(z) at arbitrary complex z.
+
+        For a frequency-independent Householder matrix, H(z) = I - 2*u*u^T.
+
+            **Returns**:
+                torch.Tensor: ``(N, N)`` complex transfer matrix.
+        """
+        param = ext_param if ext_param is not None else self.param
+        u = self.map(param)
+        N = u.shape[0]
+        I = torch.eye(N, dtype=u.dtype, device=u.device)
+        uuT = torch.matmul(u, u.transpose(0, 1))
+        return I - 2 * uuT
+
+    def probe_w(self, w: torch.Tensor, ext_param=None):
+        r"""Evaluate at :math:`w = z^{-1}`; Householder matrix is constant, so same as :meth:`probe`."""
+        return self.probe(w, ext_param)
+
     def get_io(self):
         r"""
         Computes the number of input and output channels based on the size parameter.

diff --git a/flamo/processor/system.py b/flamo/processor/system.py
--- a/flamo/processor/system.py
+++ b/flamo/processor/system.py
@@ -326,11 +326,11 @@
     def probe_w(self, w: torch.Tensor, ext_param=None):
         r"""
         Evaluate the series transfer matrix at :math:`w = z^{-1}`.
-        Uses each module's :meth:`probe_w` if present, else :meth:`probe(w)`.
+        Uses each module's :meth:`probe_w` if present.
         """
         H = None
         for module in self:
-            probe_fn = getattr(module, 'probe_w', None) or getattr(module, 'probe', None)
+            probe_fn = getattr(module, 'probe_w', None)
             if probe_fn is None:
                 continue
             Hi = probe_fn(w, ext_param)
@@ -538,8 +538,9 @@
             **Returns**:
                 torch.Tensor: Transfer matrix ``(N_out, N_in)`` (complex).
         """
-        F = self.feedforward.probe(z, ext_param)
-        B = self.feedback.probe(z, ext_param)
+        ext_param_ff, ext_param_fb = self._split_ext_param(ext_param)
+        F = self.feedforward.probe(z, ext_param_ff)
+        B = self.feedback.probe(z, ext_param_fb)
         N = F.shape[0]
         I = torch.eye(N, dtype=F.dtype, device=F.device)
         A = I - F @ B
@@ -643,8 +644,10 @@
         Used for numerical stability when :math:`|z| < 1` (evaluate in w-plane).
         """
         ext_param_ff, ext_param_fb = self._split_ext_param(ext_param)
-        probe_ff = getattr(self.feedforward, 'probe_w', None) or self.feedforward.probe
-        probe_fb = getattr(self.feedback, 'probe_w', None) or self.feedback.probe
+        probe_ff = getattr(self.feedforward, 'probe_w', None)
+        probe_fb = getattr(self.feedback, 'probe_w', None)
+        if probe_ff is None or probe_fb is None:
+            raise NotImplementedError("probe_w not implemented for feedforward or feedback branches")
         F = probe_ff(w, ext_param_ff)
         B = probe_fb(w, ext_param_fb)
         N = F.shape[0]
@@ -868,8 +871,16 @@
             **Returns**:
                 torch.Tensor: Transfer matrix (complex).
         """
-        H_A = self.branchA.probe(z, ext_param)
-        H_B = self.branchB.probe(z, ext_param)
+        ext_param_brA = None
+        ext_param_brB = None
+        if ext_param is not None:
+            for key, param in ext_param.items():
+                if 'branchA' in key:
+                    ext_param_brA = param
+                elif 'branchB' in key:
+                    ext_param_brB = param
+        H_A = self.branchA.probe(z, ext_param_brA)
+        H_B = self.branchB.probe(z, ext_param_brB)
         if self.sum_output:
             return H_A + H_B
         else:

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Docstring claims wrong matrix multiplication order in probe

High Severity

The probe_recursion docstring states P(z) = I - B(z) F(z) and references "delays on columns," but the code actually computes I - F @ B (i.e., I - feedforward @ feedback). This is consistent with Recursion.forward and Recursion.probe (which both use I - F @ B), but the documented formula has the matrix multiplication order swapped. Since the docstring explicitly says callers (e.g., pyFDN) will use this for JVP/grad-based derivatives of P(z), the mismatch between documented and actual matrix structure will lead to incorrect results for any caller relying on the documented convention. The same issue appears in probe_recursion_w.

Additional Locations (1)

• flamo/processor/system.py#L553-L565

 

[cursor]

Unused parameter include_shell_io in probe_recursion

Low Severity

probe_recursion accepts an include_shell_io parameter and **kwargs, but neither is used in the method body. A caller passing include_shell_io=True would expect behavior similar to Shell.probe, but the argument is silently ignored. This is misleading dead code.