feat: modular sync architecture with accorr numba/torch optimizations

[Ramdam17]

Summary

• Modular sync architecture: Each connectivity metric (PLV, CCorr, ACCorr, Coh, ImCoh, PLI, wPLI, EnvCorr, PowCorr) is now a class inheriting from BaseMetric, in its own file under hypyp/sync/
• ACCorr optimizations: Integrates numba JIT and PyTorch GPU backends for Adjusted Circular Correlation, originally developed by @m2march as part of BrainHack Montreal 2026 (PR Optimization of accorr via pytorch #246)
• Unified optimization API: Single parameter (None, 'auto', 'numba', 'torch') flows through the entire chain: compute_sync() → get_metric() → ACCorr() → auto-detects GPU with graceful fallback and warnings

Optimization behavior

Value	Behavior	Fallback
None	Standard numpy (default)	—
'auto'	Best available: torch → numba → numpy	cascade with warnings
'numba'	Numba JIT compilation	warn + numpy if unavailable
'torch'	PyTorch with auto-detected GPU (MPS/CUDA)	warn + torch CPU if no GPU, warn + numpy if no torch

Usage

from hypyp.analyses import compute_sync
result = compute_sync(complex_signal, 'accorr', optimization='torch')

# Or directly
from hypyp.sync import ACCorr
metric = ACCorr(optimization='auto')

Optional dependencies

poetry install --with optim_torch    # PyTorch
poetry install --with optim_numba    # Numba

Test plan

• 172 tests pass, 0 failures
• ACCorr numpy vs reference implementation
• ACCorr numba vs reference implementation
• ACCorr torch (MPS) vs reference implementation
• Fallback warnings tested via mocking
• All 9 metrics work through compute_sync()
• Existing test suite (test_stats, test_fnirs, etc.) unaffected

🤖 Generated with Claude Code

Co-Authored-By: Martín A. Miguel [email protected]

[Ramdam17]

Hi @m2march,

This PR integrates your accorr optimizations (numba/torch) from PR #246 into the new modular sync architecture. Your work is credited via co-authorship on the commit and in the accorr.py docstring.

Main changes from your original PR:

• Unified API: single optimization parameter instead of backend + device
• Graceful fallback with warnings when backends are unavailable
• Optional dependency groups in pyproject.toml (poetry install --with optim_torch)
• Reference-based tests validating all 3 backends against the original implementation

Could you review the changes before we merge?

[m2march]

I've got one comment and then some less relevant notes:

Comment

• In testsync.py:89, the test is supposed to test the call through compute_sync, but the function is never called.

Notes

• There is no config of the device. I like that it makes the optimization interface simpler, but I am afraid this will bite back if there are reasons to select CUDA vs MPS.
• Also, nowhere in the documentation it is stated that if MPS is available, it goes over CUDA. I'm not sure if they are exclusive.
• In analysis.py:compute_sync, the math for the different sync methods is removed. I see that it's in every subclass of BaseMetric. I fear that trying to find that (along with the reference papers) might be too obscure for non-programmers. It is annoying to have documentation too far from the implementation, but might be worth the duplicate for clarity. Alternatively, there would be a wiki entry or README in the sync folder that could be referred to in the docstring of compute_sync.

[Ramdam17]

Thanks for the review @m2march! All three points addressed in branch fix/pr250-review (d93f582):

1. Test bug (line 89) — Fixed

TestAccorrViaComputeSync now properly calls compute_sync() for all tests. Added a complex_signal_raw fixture in conftest.py for the raw format expected by compute_sync() ((2, n_epoch, n_ch, n_freq, n_samp)), separate from the existing complex_signal fixture (internal metric format). Also added numba and torch variants to the class.

2. Device priority — Documented

_resolve_optimization() and _resolve_torch() in base.py now document:

• Fallback cascade: torch → numba → numpy for 'auto', requested → numpy + UserWarning for specific backends
• Device priority: MPS > CUDA > CPU (mutually exclusive, auto-selected by PyTorch)
• MPS float32 precision note with tolerance implications

3. Math documentation — Three layers

Since this is a scientific tool and you can never have too much documentation:

• hypyp/sync/README.md (new): full reference table — formula + citation for all 9 metrics
• compute_sync() docstring: new Modes section with short formula + paper reference per metric, plus See Also pointing to individual classes and the README
• accorr.py module docstring: Credits block for the precompute optimization

Acknowledgement

@m2march (Martín A. Miguel) is now credited in README.md, the new CONTRIBUTORS.md, and the accorr.py module docstring for the ACCorr optimization work done at BrainHack Montréal. It was the right thing to do and it was overdue.

---

Test results with all backends: 14/14 passed (numpy ✓, numba ✓, torch/MPS ✓)