Add frequency-domain coherence estimation with resolution mapping

[Copilot]

Overview

Implements frequency-domain coherence path alongside existing time-domain modulation for A/B verification. Fixes critical bugs in alpha selection, frequency resolution handling, and bin mapping that caused IndexError crashes and poor performance.

Implementation

New coherence method (coherence_manager.py):

• compute_coherence_freq_shifted(): Computes coherence via frequency shifts instead of time-domain modulation
• Transform modes: High-res STFT (configurable nfft) or full-file DFT
• Interpolation: none (nearest), linear, or 8-point Lagrange on complex bins
• Frame-start phase correction for STFT windowing

Configuration (default.yaml):

cyclic:
  use_freq_coherence_method: false       # Enable freq-domain
  use_stft_for_freq_coherence: true      # false = DFT
  freq_coherence_nfft: null              # Optional high-res size
  freq_coherence_interpolation: 'lagrange'
  freq_coherence_apply_phase_correction: true

Bug Fixes

1. Alpha ordering mismatch

Time-domain sorts alphas via Modulator.unique_with_relative_tolerance_fast(), freq-domain was using input order. Now both sort identically (correlation: -0.39 → 0.87).

2. Wrong max_bin calculation

DFT was using STFT's delta_f instead of its own, analyzing 3× too much data. Now calculates method-specific delta_f (70% fewer bins for DFT).

3. Alpha=0 exclusion from unstable sort

When 6+ alphas have coherence=1.0 and P_max_cfg=5, numpy's argsort could arbitrarily exclude alpha=0. Now explicitly reserves first slot for alpha=0.

4. Frequency bin resolution mismatch (IndexError)

Coherence computed at high-res (e.g., 2048 FFT → 1025 bins), but beamforming uses low-res (512 FFT → 257 bins). Indexing harmonic_sets[1036] crashed. Now maps via frequency:

freq_hz = k_highres * delta_f_coherence
k_lowres = round(freq_hz / delta_f_beamforming)
if k_lowres < nfft_real_beamforming:
    harmonic_bins_.append(k_lowres)  # Skip out-of-range bins

Test Coverage

27 new tests covering interpolation modes, resolution mapping, alpha selection edge cases, and method equivalence. All 100 tests passing.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.