feat: add phi_hat delay tracking to BasebandReplayChannel

[Yugam2508]

What this does

Brings the Julia BasebandReplayChannel to parity with the MATLAB/Python
reference implementations in the uwa-channels
project, so it works with current channel-library files.

Changes

• Delay tracking (phi_hat). Implements the previously-stubbed
  (# TODO: apply drift) delay-tracking mode: re-inserts both the phase
  (via cis.(φ)) and the delay drift (Δτ = φ / 2πfc, applied by
  re-interpolating on a time-shifted grid), matching the reference.
• File reader. Loads phi_hat, theta_hat, or neither (pure
  convolution), plus the optional f_resamp passband factor, per the
  UACR file-format spec.
  Previously theta_hat was mandatory.
• Phase-index fix. Corrects a pre-existing one-step offset in the
  phase-vector indexing (start * step → (start-1) * step + 1) that
  affected both phi_hat and theta_hat modes.
• Precision. Promotes the phase fields and fc to Float64 (delay-grid
  and long-signal carrier accuracy) while keeping h as ComplexF32 to
  preserve the memory characteristics for large channels.
• Tests. Adds test/test_replay.jl (physics, zero-phase identity,
  constant-phase recovery), resolving the open # TODO: add test cases.

Validation

• New tests pass; full suite green (511/511).
• Cross-validated against the Python reference on a real delay-tracking
  channel (black.mat): per-receiver correlation 0.9997, lag 0,
  power ratio 1.0 across all 8 receivers.

Implementation note: interpolation differences

This is a port to Julia-native primitives, not a line-by-line translation, so
it is not expected to be bit-identical to the Python reference. Two sites use
different (but equivalent-in-the-interior) interpolation:

• IR over time: the reference interpolates the impulse response across the
  time axis with scipy CubicSpline; this PR uses DSP.resample (polyphase
  FIR), consistent with how transmit already resamples the baseband signal.
• Delay drift: the reference re-interpolates the drifted output with scipy
  CubicSpline (not-a-knot boundaries); this PR uses
  Interpolations.BSpline(Cubic(Line())) with linear extrapolation outside
  the grid.

Both schemes are cubic and agree in the signal interior, differing most at the
edges due to the different boundary conditions. This is what accounts for the
residual in the cross-validation (0.9997 rather than 1.0): the two
implementations agree on the physics and diverge only at the level of numerical
interpolation, not algorithm. If bit-level parity with the reference is
preferred, the drift interpolation can be switched to a not-a-knot cubic to
match — happy to do so on request.

Notes

• Commit scope is pm (channel models are closely related to
  data-driven propagation models).
• UACR noise-model support remains out of scope here and is still
  marked # TODO: support UACR noise models. Will work on it next.

[mchitre]

@Yugam2508 there seem to be a merge conflict. Would you like to resolve it before I review?

[Yugam2508]

@Yugam2508 there seem to be a merge conflict. Would you like to resolve it before I review?

Apologies, resolved.

[mchitre]

Scope can be pm. Channel models are closely related to data-driven propagation models.

[mchitre]

Should we add a test that checks the whole replayed impulse response against a Python version (can be a stored version so we don't have to call Python)? We need to cover various cases with phi, theta, etc, so we may need more than one channels in the tests?

[Yugam2508]

working on this, will update it soon.

[Copilot]

Pull request overview

Adds full phi_hat (delay-tracking) support and updated UACR .mat parsing to BasebandReplayChannel, bringing the Julia replay channel in line with the referenced channel-library formats and behavior.

Changes:

• Implement phi_hat phase reinsertion + delay-drift (time-grid) re-interpolation in transmit, plus f_resamp passband resampling support.
• Update .mat loader to accept phi_hat, theta_hat, or neither (pure convolution), and validate phase/IR duration.
• Add replay-focused tests and include SignalAnalysis as a test dependency; ignore large channel/noise data artifacts via .gitignore.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 5 comments.

File	Description
src/replay.jl	Implements phi_hat drift handling, updates file loading logic, adds f_resamp, and adjusts phase indexing.
test/test_replay.jl	Adds physics/identity/constant-phase replay tests for the updated replay channel behavior.
test/Project.toml	Adds SignalAnalysis dependency needed by the new replay tests.
.gitignore	Ignores large binary channel/noise data files (*.mat, *.bin).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.