fix(sync): check backend capability before granting it, and dispatch fail-closed

[Ramdam17]

What this fixes

Asking for the Metal backend on a metric that has no Metal kernel used to run in NumPy silently, while the metric object reported _backend == 'metal'. Only PLI, wPLI and ACCorr have a Metal kernel; for PLV, CCorr, Coh, ImCoh, EnvCorr and PowCorr, optimization='metal' and priority=['metal', ...] gave a NumPy computation with no warning. Two defects combined: the resolver never asked whether the metric implements the backend, and the per-metric if/elif dispatch ended in a bare return self._compute_numpy(...), so the mismatch stayed silent.

Closes #299. Addresses the Metal half of #300.

The rule this pull request follows

The 0.6 series changes no computed value. Every request that worked on master therefore still computes with the same method and gives the same result; what changes is that the silent cases now warn and that the metric object tells the truth about its backend. Making a request run a different backend than before is left to 0.7.0.

What changes

The first two commits are the work of July 2026, replayed on top of the formatted master. The following ones apply the adjustments asked for by the October audit and answer ten rounds of independent review.

• BaseMetric.supports(backend) tells whether a metric implements a backend, from the _compute_* methods that exist.
• optimization='metal' on a metric without a Metal kernel warns and reports numpy. A priority list that reaches Metal on such a metric, on a machine where Metal is available, also ends in NumPy with a warning, as it silently did before; it does not move on to the next backend of the list. When the backend can neither run on the machine nor be computed by the metric, and no other GPU backend of the list can be used, the warning names the backend the metric lacks instead of saying "No GPU backend available".
• The nine duplicated if/elif chains are replaced by one table-driven BaseMetric.compute. A _backend set to a known backend the metric does not implement computes in NumPy with a warning, where it did so silently; a _backend that is not the name of a backend raises a ValueError naming the metric and the backends it implements.
• The contract for writing a metric is explicit: implement _compute_numpy and the optional accelerated methods, and set _dispatch_via_table = True in the class. The nine built-in metrics set it.
• Tests: the six Metal tests that compared NumPy with NumPy are replaced by tests of the fallback itself (warning, backend and result). The capability of every metric is checked against a hand-written matrix, and compute is checked to route every metric to every backend it implements, with stubs and no GPU. The four tests that run a Metal kernel spy on the kernel function.

Compatibility

For the nine built-in metrics, an independent review compared the method actually called, its arguments and its device against master over 1,130,688 simulated combinations of metric, optimization value, priority list and available backends, and found no difference. The numerical methods and the kernels are unchanged.

Third-party subclasses written the earlier way, with their own compute and their own dispatch, are still granted the backend they request and are not capability-checked, whether they derive from BaseMetric or from a built-in metric; _compute_numpy is not abstract, so they still instantiate. A subclass of a built-in metric that overrides compute and delegates to super().compute() keeps its earlier results. A _compute_* method that a subclass adds for a backend its parent does not implement was never called before and is still not, unless the subclass sets _dispatch_via_table = True itself.

Left for later pull requests

Moving on to the next backend of a priority list when the metric does not implement one is planned with the GPU work of 0.7.0. compute_sync still rewords every ValueError as an unsupported metric (#306). 'auto' cannot reach Metal or CuPy without torch (#304), and 'numba' in a priority list is ignored (#305). The Numba, torch and CUDA tests do not yet assert which backend ran (#308).

Measured

On macOS arm64 (M4 Max), Python 3.12, commit 9e4d4fe:

• standard dev environment: 310 passed, 42 skipped, 0 failed on the whole suite;
• with torch, numba and PyObjC Metal installed: 160 passed, 9 skipped (the CuPy tests) on tests/test_sync.py, the four Metal tests entering a real kernel;
• real resolution on that machine: PLV(optimization='metal') gives NumPy with the warning, PLI(optimization='metal') gives Metal, PLV with priority=['metal', 'torch'] and with priority=['metal'] gives NumPy with the warning, ACCorr under 'auto' gives Metal and PLV under 'auto' gives torch on MPS.

On a node of four H100 (CUDA, with torch, CuPy and Numba), commit 9e4d4fe: 343 passed, 9 skipped, 0 failed on the whole suite; under 'auto' every metric resolves to its CUDA kernel, as on master.

🤖 Generated with Claude Code

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.