Adopt the ezmsg-sigproc 3.0 channel-grouping API

[cboulay]

Tracks the ezmsg-sigproc 3.0.0 channel-grouping API (ezmsg-org/ezmsg-sigproc#212), fixes an unrelated correctness bug in LRR, and makes the lint job deterministic.

Requires ezmsg-sigproc>=3.0.0, now released.

---

⚠️ Breaking changes to ezmsg-learn's own API

These affect anyone constructing LRRSettings / SelfSupervisedRegressionSettings. There is no deprecation period — upstream removed the settings these forwarded to, so the old spellings could not keep working.

1. channel_clusters + cluster_by_field → one channel_groups

Two settings that did the same job through different spellings collapse into a single ChannelGroupSpec, mirroring upstream. All of these are now the same setting:

before	after
channel_clusters=[[0, 1], [2, 3]]	channel_groups=[[0, 1], [2, 3]]
cluster_by_field="bank"	channel_groups="bank"
(not expressible)	channel_groups=("array", "bank") — group by the field tuple
(not expressible)	channel_groups=fn(message, axis) — callable

block_size is unchanged and remains the fallback when channel_groups is None or resolves to nothing (e.g. a field spec the incoming axis doesn't carry).

Precedence changed. Previously explicit channel_clusters silently won over cluster_by_field when both were set. With one setting there is nothing to arbitrate, so that rule is gone along with the test that pinned it. If you set both before, keep the one you actually wanted.

2. min_cluster_size → kernel

min_cluster_size tuned a block-merge threshold that no longer exists — upstream now chooses the matmul kernel from a cost model over the weights. Replaced by a passthrough:

LRRSettings(kernel="auto")    # default; library picks dense vs. block-diagonal
LRRSettings(kernel="dense")   # force dense
LRRSettings(kernel="blocks")  # force block-diagonal

min_cluster_size=1 (the old "just use blocks" idiom) becomes kernel="blocks". min_cluster_size > n_channels (the old "force dense" idiom) becomes kernel="dense".

This exists because upstream documents the cost model as mispredicting above ~2000 channels, picking up to ~40% off the best blocking — squarely LRR's regime. kernel is the supported escape hatch; without it that tuning would be unreachable from this package.

3. cluster → group rename

So that one vocabulary spans both packages:

before	after
MIN_REREF_CLUSTER_SIZE	MIN_REREF_GROUP_SIZE
state.resolved_clusters	state.resolved_groups
_get_channel_clusters()	_get_channel_groups()
_validate_clusters()	_validate_groups()

MIN_REREF_CLUSTER_SIZE is the only public one. Note resolved_groups now holds np.ndarray groups rather than list[int] — inherited from upstream's resolver.

Migration at a glance

# before
LRRSettings(channel_clusters=[[0, 1, 2], [3, 4, 5]], min_cluster_size=1)
LRRSettings(cluster_by_field="bank")
# after
LRRSettings(channel_groups=[[0, 1, 2], [3, 4, 5]], kernel="blocks")
LRRSettings(channel_groups="bank")

---

Upstream renames tracked

• channel_clusters_from_field / validate_channel_clusters → channel_groups_from_field / validate_channel_groups. We now call the higher-level resolve_channel_groups() instead, which handles every spec form and validates in-range and pairwise disjoint — overlapping groups used to pass silently here.
• rereference_matrix(clusters=) → groups=
• AffineTransformSettings.channel_clusters → channel_groups, min_cluster_size removed
• set_weights(recalc_clusters=) → recalc_structure=. No call-site change: LRRTransformer passes weights positionally and relies on the default, which is still what we want — refitting changes weight values, not the sparsity pattern.

Dropped the channel_clusters=None workaround

#20 pinned channel_clusters=None on the internal affine so a grouping finer than W's true blocks couldn't corrupt the apply. Upstream removed that failure mode outright — block structure is always read off the weight matrix now — so the workaround is deleted. Neither affine gets a grouping at all: LRR always supplies an explicit weight matrix, and grouping only builds kind/callable weights.

The regression test from #20 stays, re-pointed at the guarantee from this side (TestApplyFollowsWeightBlocks).

Independent bug fix: stale weights when refit before the first message

Separate commit (a643df8); not caused by the migration. LRRUnit takes training on INPUT_SAMPLE and signal on a separate stream, so several partial_fit calls routinely land before the first message is processed. In that window the transform silently applied the first fit forever:

p = LRRTransformer(LRRSettings(incremental=False))
p.partial_fit(msg(X1))
p.partial_fit(msg(X2))   # no message processed in between
p.send(msg(X2))          # -> X2 @ (I - W1), not (I - W2)

_on_weights_updated built the affine eagerly, passing I - W as AffineTransformSettings.weights. The affine's _reset_state — which doesn't run until a message arrives — rebuilds state from those settings, so every set_weights() in between updated state that was about to be discarded. Wrong output of correct shape and plausible magnitude, no warning.

Construction moves to _process, building from LRRState.effective (the latest I - W). The in-place set_weights path is unchanged and still the common case. Covered by TestRefitBeforeFirstMessage on both paths.

Also here

• _solve_weights: the "group is every channel, skip the scatter" shortcut now also requires the indices to be in order. A callable spec may return all n channels permuted, which still needs scattering back.
• Lint (527feb0): the Lint job called uv tool run ruff, which resolves ruff independently and honoured neither the lint dependency-group pin nor .pre-commit-config.yaml. CI silently tracked whatever ruff was newest, so a future release could turn it red with no change here. Switched to uv run ruff. Also cleared two pre-existing violations (an unsorted import block in tests/, one ruff format diff in src/) so pre-commit run --all-files is green; neither was failing CI, which only lints src and doesn't check formatting.

Performance

Inference speedup from the upstream kernel work, measured here at 512 channels in 8×64 groups, median of 200 iterations after 20 warmup, before = ezmsg-learn@dev + sigproc 2.34.0:

chunk	NumPy		Torch MPS		MLX
20	64.5 → 19.7 µs	3.3×	816 → 217	3.8×	292 → 156	1.9×
100	330.6 → 52.0	6.4×	765 → 191	4.0×	296 → 138	2.2×
300	983.6 → 131.6	7.5×	627 → 202	3.1×	309 → 150	2.1×

Torch MPS at chunk=20 was over the 30 kHz real-time budget (816 µs against 667) and is now at 217 µs. partial_fit is unchanged — it doesn't go through the affine.

Testing

Against released sigproc 3.0.0: 339 passed / 2 skipped (tests/unit tests/dim_reduce), 6 passed (tests/integration), lint exit 0, pre-commit run --all-files green.

🤖 Generated with Claude Code