v2 pre-flip: adopt cellpycore CurveCols as the canonical capacity-curve schema

[jepegit]

Context

Phase-3 flip prerequisite (native-headers plan Phase 0, item 3; hardcoded-column-headers-report §5): the get_cap output frame ("capacity", "voltage", "cycle", "direction") is an implicit contract hard-coded by the producer in capacity_curves.py and by ~125 consumer sites (easyplot, collectors, ica, plotutils). The report recommended defining canonical names once.

The decision is already made on the core side: cellpycore ships config.CurveCols (cycle_num, potential, capacity, direction) and OcvCurveCols (cycle_num, step_num, step_time, potential) with an authoritative spec (docs/specifications/curve-table.md, core #118). The legacy frame maps 1:1: voltage → potential, cycle → cycle_num; capacity / direction are identical. cellpy should adopt, not invent.

Work

1. Producer: cellpy.readers.capacity_curves builds its frames from CurveCols / OcvCurveCols attributes. Decide the compat surface for the v2 line pre-flip: keep emitting the legacy names by renaming at the boundary (mirroring the raw/steps/summary bridge pattern), or emit native names under the native_schema flag only.
2. Consumers: migrate easyplot, collectors, ica, plotutils curve-frame sites onto the same objects (blocked on 1).
3. Also cover the "q" / "v" (collect_capacity_curves) and "dq" (ica) names — map onto CurveCols or document as deliberate derived-frame names.

Not labeled for hands-off mode: step 1 contains the compat-surface decision.

Refs

Report §5/§8-4; core #118 / #126; cellpy #511 (native_schema flag as a possible gate).

🤖 Generated with Claude Code

[jepegit]

Decision (2026-07-17): emit native CurveCols always

get_cap (and the curve/collector frames built on it) will emit the native CurveCols / OcvCurveCols names unconditionally on the v2 line — no legacy-name default, no per-flag branch. This is a documented v2 breaking change to the get_cap frame schema.

Legacy → native column mapping (only two names actually change):

legacy	native (CurveCols)
voltage	potential
cycle	cycle_num
capacity	capacity (unchanged)
direction	direction (unchanged)

OCV frames follow OcvCurveCols (cycle_num, step_num, step_time, potential).

Scoping (measured on master, 2026-07-17)

Producer — cellpy/readers/capacity_curves.py hand-builds the frame with literal "voltage"/"capacity"/"cycle"/"direction" (it does not currently delegate to cellpycore's curves module, which already emits CurveCols). ~40 get_cap-family call sites in-repo.

Consumers to migrate:

module	curve-column refs	notes
utils/plotutils.py	~35	includes false positives (raw/summary "voltage"/"cycle")
utils/collectors.py	~28	thin test coverage — migrate carefully
utils/ica.py	~20	"dq" derived name also here
exporters/tabular.py	2	export_cycles df["capacity"]/df["voltage"]
utils/easyplot.py (~51)	excluded	deprecated (introduced 1.1, removal 2.0 — DEPRECATIONS.md); it should be deleted before the 2.0 flip, not migrated

~69 test references to the curve columns; migration-guide breaking-change entry required.

Constraints discovered

• Atomic: the moment the producer emits potential/cycle_num, every consumer still reading "voltage"/"cycle" breaks. No safe partial landing.
• Raw-vs-curve ambiguity: many of the consumer "voltage"/"cycle" references are raw/steps/summary access that must not be touched — per-site judgment, not find-replace (the reverse of the v2 pre-flip: replace hardcoded raw/steps/summary column literals in utils and filters #538 problem).
• Centralize on the CurveCols object (single source of truth) rather than new literals.

Recommendation

Fold this into the flip PR rather than landing standalone. The native-headers plan already treats the flip as "one migration, not two" riding with the polars container change; the curve frame going native belongs in that same atomic, value-parity-oracled, golden-regenerated pass. As a standalone change it can't be partial and spends the migration risk twice. Prerequisite: delete the deprecated easyplot module first (its removal is already scheduled for 2.0).

[jepegit]

Blocker found while implementing Stage 1 (2026-07-18)

The producer change is done and verified (get_cap now emits ['cycle_num','potential','capacity','direction']), and the tested consumers migrate cleanly (exporters/tabular.export_cycles, ica.dqdv). But the main consumer surface — the collector/plot functions — is untested and CI never runs it:

• plotly / seaborn are optional extras ([project.optional-dependencies] batch/all), and CI's full job runs plain uv sync — so the plotting deps are never installed in CI.
• No test references capacity_collector / ica_collector / sequence_plotter / cycles_plotter / summary_plotter. Locally plotly/seaborn aren't installed either.
• collectors.py mixes three frame schemas behind one shared sequence_plotter (curve x=capacity,y=voltage,z=cycle; summary x=cycle,y=mean; ica x=voltage,z=cycle), so the curve-vs-summary-vs-ica "voltage"/"cycle" disambiguation is per-branch. A wrong call silently produces broken/wrong plots.

Migrating ~40 delicate sites there with zero test net, on a change that's atomic with the producer, is unsafe.

Recommendation: a test-net prerequisite (new Stage 0)

Before the curve-consumer migration:

1. Add plotly/seaborn to the CI test environment (uv sync --extra batch in the full job, or a plotting-deps test group) so the collector/plotter code actually executes under test.
2. Add characterization/smoke tests driving capacity_collector → sequence_plotter/cycles_plotter and ica_collector → ica_plotter on the canonical fixture (assert output frame columns + that the plotters run).
3. Then land v2 pre-flip: adopt cellpycore CurveCols as the canonical capacity-curve schema #540 (producer + all curve consumers) atomically against that net.

This de-risks not just #540 but every consumer-migration stage of the flip. The producer + safe-consumer work is parked on branch 540-native-curvecols (not pushed).