#566: one pure ICA core, IcaOptions, a specced output frame, and dvdq

[jepegit]

Closes #566.

Replaces four entry points × three ways of passing the same ~20 options with two verbs over one stateless core.

cellpy/ica.py	new home; cellpy.utils.ica re-exports it
IcaOptions	one frozen recipe object, validated at construction
transform_half_cycle(voltage, capacity, options, derivative=...)	the pure core — public, since it is the honest replacement for dqdv_np
dqdv() / dvdq()	same sources (cell / curve frame / two arrays), same options, symmetric signatures
to_wide()	wide format as an explicit conversion, not an entry-point mode

dvdq is new capability

cellpy could not compute differential voltage analysis at all. Some loaders ingested a dv_dq column when the cycler exported one, but nothing derived it from the curves. It needs no q(V) inversion — it differentiates the smoothed V(q) representation the pipeline already builds — so it is the simpler of the two derivatives, about 30 lines on the existing machinery.

The specced frame is why this is a 2.0 item

Users index the returned columns directly, so the output schema is a data contract:

dqdv -> cycle, direction, voltage, capacity, dqdv
dvdq -> cycle, direction, capacity, voltage, dvdq

direction is now spelled "charge"/"discharge". It used to be the raw ±1 code from get_cap, whose meaning flips with cycle_mode — the reader was left to reconstruct it. dq is kept as a duplicate of dqdv for one release.

Fixed on the way through

• from scipy.ndimage.filters import ... — deprecated alias, already warning on scipy 1.18 → scipy.ndimage.
• inspect_data wrote the derived normalizing factor back onto the converter, so a reused converter carried one half-cycle's normalization into the next. The core returns it instead; there is a determinism test for exactly this.
• A failing half-cycle was replaced by empty arrays and a log line — a cycle could lose a whole branch with no sign but a missing line on a plot. Failures are now collected, warned about, and recorded in frame.attrs; strict=True raises.
• The ValueError-retry-without-post-smoothing was copy-pasted per half-cycle; one path now.
• The Savitzky-Golay window arithmetic existed twice, identically.

Numerics are unchanged, and that is checked

The 1.x entry points are reimplemented on the new core, not kept as a second copy of the math — which is what makes the oracles meaningful. All eight golden suites recorded against the 1.x code reproduce bit-for-bit, split path and wide path included:

uv run python dev/regenerate_goldens.py --verify   # 23 suites byte-identical

Those goldens landed first, in their own commit, and I checked they bite: raising the default voltage_fwhm from 0.01 to 0.02 turns 10 of 16 red.

Test changes

The 19 characterization tests still pass. Three needed updating, and each is a real contract change rather than a test fixup:

• dqdv_np(None, None) now raises NullData instead of a TypeError from an assert len(...).
• The specced frame has one row fewer per cycle: 1.x inserted a NaN "splitter" row between the two half-cycles so a naive line plot would not join them, which the direction column makes unnecessary.

New: 42 API-contract tests. dvdq is verified against closed-form derivatives of a line and a parabola (no shared implementation), plus a reciprocity check against dqdv on a real half-cycle.

Deliberately not done

ica_collector still builds the 1.x frame. ica_plotter selects direction < 0 and calls it "charge", but get_cap gives -1 to the first half-cycle, which for cellpy's default cycle_mode="anode" is the cell discharge. Electrode-centric vs cell-centric — both defensible, and picking one silently flips the labels on every batch ICA plot. That wants a maintainer decision, so the collector calls the private legacy builder (no user-facing warning from inside a collector) with a comment explaining why.

Also still open from the plan's §6: the fate of the never-finished "hist" binning method (quarantined in the deprecated Converter; the new IcaOptions rejects it), normalize="nom_cap", and full-cell support.

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[jepegit]

Correction to the PR description above. I claimed the shims reproduce the 1.x numbers "bit-for-bit". That is true only on a single machine — regenerate_goldens.py --verify, which regenerates twice locally and compares bytes. It is not true across platforms, and CI caught me twice on it:

1. The metrics file rounds each column sum to six decimals, and I compared those exactly. Linux produced 122.614595 against a golden of 122.614594.
2. Fixing that, I tightened the frame comparison to rtol=1e-8 on the basis that per-value noise was "~5e-10" — a number I had derived from how much the sums moved. Sums average errors out; individual values do not. All 16 went red.

Measured properly from the CI log: scipy's interpolation and filtering differ between Windows and Linux by 1e-7 to 5e-7 relative on this data (258.2250118395604 vs 258.2250426021722 at the first point). The comparison now uses pandas' 1e-5 default, which leaves 20–100× headroom.

This also retires the sensitivity check I quoted in the second commit: the 1.0000001 perturbation I used to "prove" the oracle was sharp sat inside the platform noise band, and only failed because I ran it on the machine the goldens came from. Re-verified above the tolerance at 1e-4: all 16 red.

So the accurate claim is: byte-identical on one machine, and equal to within ~1e-5 relative across platforms — which is still far tighter than any change to the recipe would produce.