cellpycore 0.1.1__tar.gz → 0.1.2__tar.gz

cellpycore-0.1.2/.issueflows/03-solved-issues/issue44_status.md

@@ -0,0 +1,23 @@
+# Issue #44 status — Release: tag cellpy-core (and decide PyPI publish)
+
+- [x] Done
+
+## What has been done
+
+- User added `.github/workflows/release.yml`: on GitHub release publish → ruff + pytest → `uv build` → PyPI publish (trusted publishing via `pypi` environment, `id-token: write`).
+- User added a release alias (commit `06831f0`) to trigger releases, modeled on jepegit/issue-flow.
+- Release `v0.1.0` was published 2026-07-02, but its CI test job failed on ruff F401 — PyPI publish never ran. Fix landed via PR #53.
+- **2026-07-02 (evening): release verified end-to-end.** `v0.1.1` tagged, `release.yml` ran green, and `cellpycore 0.1.1` is live on PyPI. The release/tagging convention works.
+- Note: tag `v0.1.1` points at `63066bf`, which **pre-dates** the #45 selector removal (merged to `main` as `2da165e` after the tag). cellpy `master` is compatible with both (it no longer passes `selector=` and works against 0.1.1 and `main`). The next release will include the removal.
+
+## Remaining work
+
+- ~~Document the release procedure~~ — done 2026-07-02:
+  `.issueflows/04-designs-and-guides/release-procedure.md` (alias, workflow,
+  happy path, failure mode, per-release re-pin checklist).
+- ~~Execute the cellpy-side re-pin~~ — done 2026-07-02: cellpy PR
+  [jepegit/cellpy#400](https://github.com/jepegit/cellpy/pull/400)
+  (branch `core44-pin-cellpycore-release`): `cellpycore>=0.1.1` from PyPI,
+  editable `[tool.uv.sources]` override kept, `allow-direct-references`
+  removed, `uv.lock` refreshed, seam tests green.
+- ~~Merge PR #400~~ — merged 2026-07-02 17:21Z. **Issue fully resolved.**

cellpycore-0.1.2/.issueflows/03-solved-issues/issue45_original.md

@@ -0,0 +1,17 @@
+# Issue #45: Cleanup (blocked): remove create_selector/summary_selector_exluder once cellpy migrates off them
+
+Source: https://github.com/cellpy/cellpy-core/issues/45
+
+## Original issue text
+
+Tracking issue for the deferred dead-code removal documented in `.issueflows/04-designs-and-guides/selector-dead-code-deferral.md`.
+
+## Status: blocked (do not remove yet)
+
+`selectors.create_selector` is **still imported by the external cellpy repo** (`cellpy/readers/cellreader.py` via `core_selectors.create_selector(...)`, and `cellpy/tests/test_slim.py`). `selectors.summary_selector_exluder` is the pandas engine it wraps, so it must live as long as `create_selector` does. cellpy pins `cellpycore @ ...@main`, so removing now breaks cellpy at its next pin resolution.
+
+## Removal trigger (future work)
+
+Remove **both** functions only after cellpy stops importing `core_selectors.create_selector` (i.e. cellpy moves its summary selection onto the native `make_summary` path or its own helper). Then this is a small dead-code deletion in `src/cellpycore/selectors.py`.
+
+(The sibling pair `generate_absolute_summary_columns` / `end_voltage_to_summary` was already removed in issue #24.)

cellpycore-0.1.2/.issueflows/03-solved-issues/issue45_plan.md

@@ -0,0 +1,130 @@
+# Issue #45 plan: remove `create_selector` / `summary_selector_exluder` (two-repo cleanup)
+
+## Goal
+
+Migrate cellpy off `core_selectors.create_selector`, then delete both
+`create_selector` and `summary_selector_exluder` from cellpy-core
+(`src/cellpycore/selectors.py`), plus the dead `selector` parameter on
+`make_core_summary`.
+
+## Key finding (unblocks the issue)
+
+Both `make_core_summary` implementations in `src/cellpycore/cell_core.py`
+(native, line ~159; legacy bridge, line ~563) accept `selector` but **never use
+it** — the polars engine selects cycle-end rows via `final_data_points`
+internally. So the selector cellpy builds in `_make_summary`
+(`cellpy/readers/cellreader.py:5794-5805`) and passes at line 5917 is already a
+no-op, as are cellpy's public `selector` / `selector_type` / `exclude_types` /
+`exclude_steps` kwargs on `make_summary`. Migration is therefore a pure
+dead-code removal on the cellpy side too — no behavior replacement needed.
+
+## Constraints
+
+- **Merge order:** cellpy pins `cellpycore @ git+…@main`
+  (`cellpy/pyproject.toml:61`). The cellpy PR (stop importing) must merge
+  **before** the cellpy-core PR (delete functions), or cellpy breaks at its
+  next pin resolution.
+- **Branch, don't fork** (per `cellpy-core-migration.md`): cellpy work goes on
+  a dedicated branch of the existing cellpy repo, e.g.
+  `core45-drop-create-selector`. cellpy-core work stays on the existing
+  branch `45-cleanup-blocked-remove-create_selectorsummary_selector_exluder-once-cellpy-migrates-off-them`.
+- **Local dev wiring:** cellpy already has the editable
+  `[tool.uv.sources] cellpycore = { path = "../cellpy-core", editable = true }`
+  override, so both branches can be tested together locally.
+- **User decisions (2026-07-02):** keep cellpy's `selector*` / `exclude*`
+  kwargs but emit `DeprecationWarning` when supplied; also remove the dead
+  `selector` parameter from both `make_core_summary` signatures in core.
+
+### Prior art
+
+- `selector-dead-code-deferral.md` (04-designs-and-guides) — the deferral
+  decision this issue executes; update it when done.
+- `code-review-2026-07.md` — notes #45 covers only these two functions;
+  `get_step_numbers` / `get_cycle_numbers` / `get_rates` stay.
+- Issue #24 removed the sibling pair `generate_absolute_summary_columns` /
+  `end_voltage_to_summary`; `tests/test_schema.py::test_no_module_header_globals`
+  shows the "assert name gone" test pattern to mirror.
+- Toolbox (`.issueflows/00-tools/`) and graph checked: no relevant helper.
+
+## Approach
+
+### Phase 1 — cellpy (branch `core45-drop-create-selector`)
+
+1. Create the branch from cellpy's default branch.
+2. `cellpy/readers/cellreader.py`:
+   - Remove `from cellpycore import selectors as core_selectors` (line 73).
+   - In `_make_summary`: delete the selector-building block (lines 5794-5805)
+     and stop passing `selector=selector` to `self.core.make_core_summary`
+     (line 5917).
+   - Emit `DeprecationWarning` when `selector`, `selector_type`,
+     `exclude_types`, or `exclude_steps` is supplied (non-None) to
+     `make_summary` — they have been no-ops since the core seam.
+3. `tests/test_slim.py`: drop the `core_selectors` import; update
+   `test_direct_core_make_core_summary` to call
+   `make_core_summary(data, find_ir=True, find_end_voltage=True)` without a
+   selector.
+4. Run cellpy tests (conda `cellpy_dev_313`): at least `pytest tests/test_slim.py`
+   plus summary-related tests (`-k summary`).
+
+### Phase 2 — cellpy-core (existing branch for #45)
+
+1. `src/cellpycore/selectors.py`: delete `create_selector` and
+   `summary_selector_exluder`; remove now-unused imports/constants
+   (`functools`, `FIRST`/`LAST`/`DELTA` if unused elsewhere — verify).
+2. `src/cellpycore/cell_core.py`: remove the unused `selector` parameter from
+   both `make_core_summary` signatures + docstrings.
+3. `tests/test_schema.py`: extend the dead-code assertions with
+   `create_selector` / `summary_selector_exluder` gone from `selectors`
+   (mirror `test_no_module_header_globals`).
+4. Docs: update `selector-dead-code-deferral.md` (resolved, date, link #45)
+   and flip #45 in `cellpy-core-integration-roadmap.md` from blocked to done.
+5. Run `uv run pytest`; rerun cellpy's `test_slim.py` against the edited core
+   via the editable path source.
+
+### Merge sequencing
+
+cellpy PR merges first → then cellpy-core PR. Local editable wiring keeps both
+testable during development.
+
+## Files to touch
+
+- `cellpy/cellpy/readers/cellreader.py` — remove import + selector block, add
+  deprecation warnings.
+- `cellpy/tests/test_slim.py` — drop selector usage.
+- `cellpy-core/src/cellpycore/selectors.py` — delete the two functions.
+- `cellpy-core/src/cellpycore/cell_core.py` — drop dead `selector` param (2 sites).
+- `cellpy-core/tests/test_schema.py` — add removed-name assertions.
+- `cellpy-core/.issueflows/04-designs-and-guides/selector-dead-code-deferral.md`,
+  `cellpy-core-integration-roadmap.md` — status updates.
+
+## Test strategy
+
+- cellpy-core: `uv run pytest` (top dir) — includes `tests/test_golden.py`
+  (golden parquet fixtures: 103 steps / 18 cycles / cycle-1 `data_point` 1457),
+  which is the core-side parity oracle.
+- cellpy: activate conda `cellpy_dev_313`, run `pytest tests/test_slim.py` and
+  `pytest -k summary`.
+
+### End-to-end verification (both branches together, before either PR)
+
+With the cellpy branch checked out and the editable
+`[tool.uv.sources]` path resolving `cellpycore` to the edited
+`../cellpy-core` working copy (branch for #45):
+
+1. Full seam pipeline via `tests/test_slim.py` — covers raw load
+   (`arbin_res` `from_raw`) → `make_step_table` → `make_summary` →
+   golden value (`summary.loc[1, data_point] == 1457`) → `save(.h5)`
+   roundtrip, now without any selector import.
+2. Full cellpy test suite: `pytest` (conda `cellpy_dev_313`) — catches any
+   other path that indirectly relied on the removed functions or the
+   `selector` kwarg plumbing.
+3. Deprecation check: call `make_summary(selector_type="non-cv")` (e.g. in a
+   test with `pytest.warns(DeprecationWarning)`) to verify the warning fires
+   and the summary still builds.
+4. Sanity import check against edited core:
+   `uv run python -c "import cellpycore.selectors as s; assert not hasattr(s, 'create_selector')"`.
+
+## Open questions
+
+- None — kwargs handling, core-param removal, and cellpy branching resolved by
+  user 2026-07-02.

cellpycore-0.1.2/.issueflows/03-solved-issues/issue45_status.md

@@ -0,0 +1,56 @@
+# Issue #45 status: remove `create_selector` / `summary_selector_exluder`
+
+- [x] Done
+
+## What was done (2026-07-02)
+
+### cellpy (branch `core45-drop-create-selector`, off `master`)
+
+- `cellpy/readers/cellreader.py`:
+  - Removed `from cellpycore import selectors as core_selectors`.
+  - `make_summary`: kept the `selector` / `selector_type` / `exclude_types` /
+    `exclude_steps` kwargs but they now emit a `DeprecationWarning` when
+    supplied (they have been no-ops since the core seam); docstring updated.
+  - `_make_summary`: dropped the four dead kwargs, the `create_selector`
+    block, and the `selector=` forwarding to `make_core_summary`.
+- `tests/test_slim.py`: removed `core_selectors` usage in
+  `test_direct_core_make_core_summary`; added
+  `test_make_summary_selector_kwargs_deprecated` (asserts warning + summary
+  still builds).
+
+### cellpy-core (branch `45-cleanup-blocked-...`)
+
+- `src/cellpycore/selectors.py`: deleted `create_selector` and
+  `summary_selector_exluder`, plus now-unused imports (`functools`,
+  `Callable`, `Iterable`, `List`, `StepCols`, `RawCols`) and the
+  `FIRST`/`LAST`/`DELTA` constants.
+- `src/cellpycore/cell_core.py`: removed the never-used `selector` parameter
+  from both `make_core_summary` signatures (native + legacy bridge).
+- `tests/test_schema.py`: added `test_no_legacy_selector_functions`.
+- Docs: `selector-dead-code-deferral.md` marked resolved;
+  `cellpy-core-integration-roadmap.md` #45 row flipped to done.
+
+## Test results
+
+- cellpy-core: `uv run pytest` — **95 passed** (includes golden fixtures).
+- cellpy (conda `cellpy_dev_313`, editable core via `[tool.uv.sources]`):
+  - `tests/test_slim.py` — 6 passed (incl. new deprecation test).
+  - `pytest -k summary` — 79 passed, 1 skipped, 1 xfailed.
+  - Full suite (excluding `test_ica.py`, `test_ocv_relax.py`,
+    `test_plotutils_summary_plot.py`) — **428 passed, 17 skipped, 11 xfailed**.
+
+### Pre-existing environment crash (not caused by this change)
+
+`test_ica.py`, `test_ocv_relax.py`, and `test_plotutils_summary_plot.py`
+abort the interpreter with `Windows fatal exception: code 0xc06d007f` inside
+scipy/numpy LAPACK (`lstsq` / `inv`). A standalone
+`python -c "from scipy.signal import savgol_filter; ..."` (no cellpy imports)
+crashes the same way in `cellpy_dev_313`, so this is a broken scipy/BLAS DLL
+situation in that conda env on this machine, unrelated to the selector
+removal. Should be fixed separately (e.g. reinstall scipy/numpy in the env).
+
+## Remaining work
+
+- Commit + push both branches, open PRs.
+- **Merge order:** cellpy PR first (cellpy pins `cellpycore @ git+…@main`),
+  then the cellpy-core PR.

cellpycore-0.1.2/.issueflows/03-solved-issues/issue54_original.md

@@ -0,0 +1,45 @@
+# Issue #54: Native exclude-types summary support (replace removed create_selector exclusion feature)
+
+Source: https://github.com/cellpy/cellpy-core/issues/54
+
+## Original issue text
+
+## Context
+
+Issue #45 removed the legacy pandas selector pair (`create_selector` / `summary_selector_exluder`). The default row selection (one cycle-end datapoint per cycle) was already native in `summarizers.make_summary`, so nothing was lost there.
+
+But the old selector had a second, distinct capability that was never ported to the polars engine (and has been silently a no-op since the core seam landed): **exclude-types summaries** (`selector_type="non-cv" / "non-rest" / "non-ocv" / "only-cv"`). Because capacities are cycle-cumulative, this is not row selection — it subtracts the excluded steps' deltas (`last - first` per step, summed per cycle) from the cycle-end values, producing a summary "as if" those steps never happened.
+
+cellpy's `make_summary(selector_type=...)` kwargs currently emit a `DeprecationWarning` and do nothing.
+
+## Proposed design (concrete first, KISS)
+
+Add an option to the native engine:
+
+```python
+summarizers.make_summary(data, schema, exclude_step_types=["cv_"], ...)
+```
+
+Implementation sketch:
+
+1. Filter the step table by excluded `step_type` prefix(es).
+2. Compute per-step deltas from the existing `*_first` / `*_last` stat columns (charge, discharge, current, voltage).
+3. Group by cycle (and `test_id` when present), sum.
+4. Subtract the per-cycle correction from the selected cycle-end summary rows.
+
+No new protocol/abstraction yet. If a second variant appears (custom exclusion logic, different correction policy), promote it to a pluggable `SummaryAdjuster` mirroring `extractors.SummaryExtractor` — giving the clean vocabulary: *selectors* pick rows, *extractors* derive columns, *adjusters* correct values.
+
+## Testing
+
+- Parity test against the removed pandas implementation (resurrect `summary_selector_exluder` from git history as a test oracle on a fixture with CV steps).
+- Guard: `exclude_step_types=None` must stay byte-identical to the current summary (golden fixtures).
+
+## Follow-up on the cellpy side
+
+Once this lands, cellpy can wire `selector_type` / `exclude_types` / `exclude_steps` to the new argument instead of warning, or keep the deprecation and expose the new API directly.
+
+## Links
+
+- #45 (dead-code removal that surfaced this)
+- #13 (polars summary rewrite that deliberately skipped the exclusion machinery)
+- `.issueflows/04-designs-and-guides/selector-dead-code-deferral.md`

cellpycore-0.1.2/.issueflows/03-solved-issues/issue54_plan.md

@@ -0,0 +1,53 @@
+# Plan — Issue #54: Native exclude-types summary support
+
+## Goal
+
+Add native exclude-types summary support to the polars engine: `summarizers.make_summary(..., exclude_step_types=["cv_"])` subtracts the excluded steps' per-cycle deltas from the cycle-end summary values, replacing the capability lost when `create_selector` / `summary_selector_exluder` were removed (issue #45).
+
+## Constraints
+
+- KISS: concrete kwarg first, no `SummaryAdjuster` protocol yet (issue explicitly defers it until a second variant appears).
+- `exclude_step_types=None` (default) must be **byte-identical** to today's summary — no join, no extra columns, golden fixtures untouched.
+- Engine stays schema-injected, polars-native, thread-safe; no module-level state.
+- cellpy-side wiring (`selector_type` → this kwarg) is a follow-up in the cellpy repo, out of scope here (per migration guide: core PR first).
+- Google-style docstrings.
+
+### Prior art
+
+- **Oracle:** removed pandas `summary_selector_exluder` recovered from `git show 2da165e^:src/cellpycore/selectors.py`. Math: filter steps whose `step_type` starts with any excluded prefix; per step compute `last - first` for current, voltage, charge, discharge; group by cycle, sum; left-merge onto selected cycle-end raw rows, `fillna(0.0)`, subtract.
+- **Deviations to document:** (1) old code also corrected current and voltage on the raw rows — the native summary's base subset carries only capacities (end potentials come from step-table joins), so the native correction targets `charge_capacity` / `discharge_capacity` only; (2) old `exclude_steps` matched step *numbers* against the step **type** column (`steps[t_st_txt].isin(exclude_steps)`) — a latent bug; we do not port `exclude_steps` at all; (3) old `create_selector` mapped `"non-rest"` → prefix `"rest_"` which never matched label `"rest"` — mapping strings stay in cellpy's follow-up, core takes explicit prefixes.
+- **Siblings/conventions to mirror:** `_group_keys` / `use_tid` composite-key handling and `join ... how="left"` + `fill_null` pattern already used by `_add_end_potentials`, `c_rates_to_summary`, `ir_to_summary` in [summarizers.py](../../src/cellpycore/summarizers.py). Step table provides `charge_capacity_first/_last`, `discharge_capacity_first/_last` stat columns (native names). Do **not** reuse `_delta_expr` (it is percent-based); the correction needs plain `last - first`.
+- Toolbox `.issueflows/00-tools/`: empty — nothing to reuse.
+- Graph: Community 50 (`make_summary`, `_group_keys`, `_add_end_potentials`) and 53 (step table) confirm the touch points; no surprises.
+
+## Approach
+
+1. **`summarizers.make_summary`** gains `exclude_step_types: Optional[Sequence[str]] = None`.
+   - When `None`: current code path, untouched.
+   - Else, right after the base `summary = selected.select(...)` and **before** the CE / coulombic-difference / loss / cumulated `with_columns` (so every derived column reflects corrected capacities, mirroring the oracle which corrected raw rows before summary derivation):
+     - Filter steps: `pl.any_horizontal(pl.col(shdr.step_type).str.starts_with(p) for p in exclude_step_types)`.
+     - Aggregate per `(test_id?, cycle)` (via `_group_keys`): `(charge_capacity_last - charge_capacity_first).sum()` and same for discharge, into temp `__excl_charge` / `__excl_discharge` columns.
+     - Left-join onto summary (same `use_tid` join-key logic as `_add_end_potentials`), `fill_null(0.0)` (oracle's `replace_nan=True`), subtract from `chdr.charge_capacity` / `chdr.discharge_capacity`, drop temp columns.
+2. **`CellpyCellCore.make_core_summary`** in [cell_core.py](../../src/cellpycore/cell_core.py) gains the same kwarg and passes it through (native entry point). Legacy bridge `OldCellpyCellCore` untouched for now — see open questions.
+3. Docstrings updated; short note added to `.issueflows/04-designs-and-guides/selector-dead-code-deferral.md` marking #54 resolved once merged (done at close, not plan).
+
+## Files to touch
+
+- `src/cellpycore/summarizers.py` — new kwarg + correction block in `make_summary` (~30 lines).
+- `src/cellpycore/cell_core.py` — pass-through kwarg on `CellpyCellCore.make_core_summary`.
+- `tests/test_schema.py` (or new `tests/test_exclude_types.py` if cleaner) — new tests, see below.
+
+## Test strategy
+
+Command: `uv run pytest` (project venv).
+
+- **Parity vs oracle:** synthetic native-named raw with CV steps (extend the `_build_cumulative_raw`-style builders; golden Arbin fixture has *no* CV steps, so it can't drive parity). Inline a small pandas oracle in the test file — the resurrected `summary_selector_exluder` math ported to native column names, capacities only — and assert the native `exclude_step_types=["cv_"]` summary capacities match.
+- **Guard:** `exclude_step_types=None` output equals current summary frame exactly (and existing golden tests `test_golden.py` stay green).
+- **Edge:** cycle without any excluded step gets zero correction (fill_null path); merged two-test frame keeps corrections isolated per `test_id` (reuse `_build_merged_raw` pattern).
+- **`only-cv` analogue:** `exclude_step_types=["charge", "discharge"]` excludes the plain `charge` / `discharge` steps but keeps `cv_charge` / `cv_discharge` (neither starts with those prefixes) — a test locks this `startswith` semantics, matching the oracle.
+
+## Open questions
+
+1. **Legacy bridge:** should `OldCellpyCellCore.make_core_summary` also accept/forward `exclude_step_types` now (making cellpy's follow-up wiring trivial), or stay untouched until the cellpy-side issue? Recommendation: add the pass-through now — it is ~3 lines and the bridge is the path cellpy actually calls.
+2. **Correction scope:** confirm capacities-only is acceptable (old code also adjusted the raw current/voltage of the selected row; those adjusted values fed nothing that survives in the native summary). Recommendation: capacities only, documented.
+3. Branch: create `54-exclude-types-summary` off up-to-date `main` at `/iflow-start`.

cellpycore-0.1.2/.issueflows/03-solved-issues/issue54_status.md

@@ -0,0 +1,19 @@
+# Issue #54 status — Native exclude-types summary support
+
+- [x] Done
+
+## What's done
+
+- 2026-07-02: plan accepted (`issue54_plan.md`); branch `54-exclude-types-summary` created off up-to-date `main`.
+- 2026-07-02: implemented per plan:
+  - `summarizers.make_summary` gained `exclude_step_types: Optional[Sequence[str]] = None`; new helper `_subtract_excluded_step_deltas` subtracts excluded steps' per-cycle `last - first` capacity deltas (prefix match on `step_type`, `_group_keys`-aware, `fill_null(0.0)`) from the cycle-end capacities **before** CE / loss / cumulated columns are derived.
+  - Pass-through kwarg on `CellpyCellCore.make_core_summary` and `OldCellpyCellCore.make_core_summary` (legacy bridge, per accepted open question 1).
+  - Capacities-only correction (accepted open question 2); documented in the helper docstring.
+  - New `tests/test_exclude_types.py` (7 tests): parity vs inline pandas oracle (resurrected `summary_selector_exluder` math), derived-column correctness, `None`/`[]` guard, unmatched-prefix zero correction, cycle-without-excluded-step, `startswith` ("only-cv") semantics lock, merged two-test isolation.
+- Full suite green: 107 passed (golden fixtures untouched → `None` path byte-identical).
+
+## Remaining work
+
+- None in this repo. Cellpy-side follow-up (wire `selector_type` / `exclude_types`
+  to the new kwarg instead of the bare `DeprecationWarning`) is a separate issue in
+  jepegit/cellpy. `selector-dead-code-deferral.md` note updated at close.

cellpycore-0.1.2/.issueflows/03-solved-issues/issue55_original.md

@@ -0,0 +1,47 @@
+# Issue #55: Add validating front door for raw frames (Data.from_raw_frame)
+
+Source: https://github.com/cellpy/cellpy-core/issues/55
+
+## Original issue text
+
+## Context
+
+The slim-consumer story (a user who builds a polars DataFrame in the native `config.RawCols` schema themselves and wants step/cycle summaries straight from cellpy-core, without cellpy) currently has no validating entry point:
+
+```python
+core = CellpyCellCore(initialize=True)
+core.data.raw = df   # accepts anything
+```
+
+A wrong column name or dtype only fails deep inside a polars expression in `summarizers`, with an error message that does not point back at the actual problem (the input frame not matching the schema).
+
+## Proposal
+
+Add a small validating constructor on `Data` (in `src/cellpycore/cell_core.py`):
+
+```python
+data = Data.from_raw_frame(df, validate=True)
+```
+
+Behavior:
+
+- Wraps the frame in a fresh `Data` (with the usual `MockMetaTestDependent`, so the graceful-degradation metadata guarantee is untouched).
+- When `validate=True` (default), checks the frame against `config.RawCols`:
+  - required columns present (clear error listing missing ones);
+  - dtype sanity for the load-bearing columns, in particular `epoch_time_utc` must be int64 (ns, UTC — the STEP-11 contract) and datapoint/cycle/step numbers integer;
+  - optional columns (`test_id`, `internal_resistance`, …) allowed absent.
+- Fails fast with a single actionable error message instead of a deep polars stack trace.
+
+Keep it KISS: one classmethod + one module-level validation helper, no schema-validation framework.
+
+## Tests
+
+- Happy path: valid native frame round-trips through `make_step_table` + `make_summary` identically to plain `data.raw = df`.
+- Missing column → error naming the missing column(s).
+- Wrong dtype on `epoch_time_utc` → error mentioning the int64-ns contract.
+- `validate=False` skips checks entirely.
+
+## Links
+
+- Raised while discussing the future slim-consumer / cellpy v2 interaction pattern (roadmap doc `cellpy-core-integration-roadmap.md`).
+- Related: #42 (reset-granularity normalization is the other half of "arbitrary external raw frames").

cellpycore-0.1.2/.issueflows/03-solved-issues/issue55_plan.md

@@ -0,0 +1,95 @@
+# Plan — Issue #55: Add validating front door for raw frames (`Data.from_raw_frame`)
+
+## Goal
+
+Give slim consumers a validating entry point for native-schema polars raw frames:
+`Data.from_raw_frame(df, validate=True)` fails fast with one actionable error
+instead of a deep polars stack trace inside `summarizers`.
+
+## Constraints
+
+- KISS (per issue): one classmethod + one module-level validation helper in
+  `src/cellpycore/cell_core.py`. No schema-validation framework, no new deps.
+- Graceful-degradation metadata guarantee untouched: `Data()` already attaches
+  `MockMetaTestDependent`; `from_raw_frame` reuses the plain constructor.
+- `validate=False` must skip all checks entirely (zero cost).
+- Google-style docstrings.
+
+### Prior art
+
+- `tests/test_harmonized_fixture.py::_rawcols_names()` — derives the full
+  `RawCols` name set via `vars(RawCols)`; the helper mirrors the idea but only
+  needs the explicit required subset (coexist, no migration).
+- `summarizers._ensure_test_id` — engine already auto-adds `test_id`; validator
+  must therefore treat `test_id` as optional.
+- `summarizers.make_step_table` signal resolution (lines ~360-375) — engine
+  skips absent `internal_resistance` / `ref_potential` / `step_time`; validator
+  treats these as optional too.
+- `_helpers.create_raw_data()` + `mock_data_with_raw` fixture — valid native
+  frame for tests (reuse, no new fixture needed).
+- Toolbox (`.issueflows/00-tools/`) empty; graph report checked — nothing else relevant.
+
+## Approach
+
+1. **Module-level helper** `validate_raw_frame(raw, raw_cols=None)` in
+   `cell_core.py` (public, so cellpy v2 can call it directly later):
+   - `raw_cols` defaults to `config.RawCols()`.
+   - Type check: must be a `polars.DataFrame` (the slim-consumer story is
+     polars-native) — clear `TypeError` otherwise.
+   - **Required columns** (the engine's load-bearing set):
+     `datapoint_num`, `cycle_num`, `step_num`, `epoch_time_utc`, `test_time`,
+     `current`, `potential`, `cumulative_charge_capacity`,
+     `cumulative_discharge_capacity`. Missing ones → single `ValueError`
+     listing all of them.
+   - **Dtype sanity** (collected, reported together with missing-column errors
+     in one message):
+     - `epoch_time_utc` must be exactly `pl.Int64` — error text mentions the
+       int64 nanoseconds-since-epoch UTC (STEP-11) contract.
+     - `datapoint_num`, `cycle_num`, `step_num` must be integer dtypes.
+     - `test_time`, `current`, `potential`, `cumulative_*_capacity` must be
+       numeric.
+   - **Optional columns** (`test_id`, `internal_resistance`, `ref_potential`,
+     `step_time`, `mask`, `source_*`, aux columns, …): allowed absent, not
+     dtype-checked (KISS).
+2. **Classmethod** on `Data`:
+
+   ```python
+   @classmethod
+   def from_raw_frame(cls, raw, validate=True, raw_cols=None) -> "Data":
+       if validate:
+           validate_raw_frame(raw, raw_cols)
+       data = cls()
+       data.raw = raw
+       return data
+   ```
+
+3. Run `graphify update .` after the code change (project rule).
+
+## Files to touch
+
+- [src/cellpycore/cell_core.py](c:\scripting\cellpy-core\src\cellpycore\cell_core.py)
+  — add `validate_raw_frame()` helper + `Data.from_raw_frame()` classmethod
+  (imports `polars` lazily inside the helper, matching module style).
+- [tests/test_creation.py](c:\scripting\cellpy-core\tests\test_creation.py)
+  — add the new tests (creation-themed file already exists; no new test module).
+
+## Test strategy
+
+Command: `uv run pytest` (project default).
+
+New tests in `tests/test_creation.py`:
+
+- **Happy path / round-trip**: `Data.from_raw_frame(create_raw_data())` runs
+  through `CellpyCellCore.make_core_step_table` + `make_core_summary` and the
+  resulting steps/summary frames equal those from plain `data.raw = df`.
+- **Missing columns**: drop e.g. `cycle_num` + `current` → `ValueError` naming
+  both.
+- **Wrong dtype**: cast `epoch_time_utc` to `pl.Float64` → error mentioning
+  int64-ns contract.
+- **`validate=False`**: same broken frame passes without error.
+- **Not a polars frame**: pandas frame → `TypeError`.
+
+## Open questions
+
+- None — polars-only input is assumed (the issue's slim-consumer story);
+  pandas users go through the legacy bridge instead.

cellpycore-0.1.2/.issueflows/03-solved-issues/issue55_status.md

@@ -0,0 +1,34 @@
+# Issue #55 status — validating front door for raw frames
+
+Branch: `55-from-raw-frame`
+
+## Done
+
+- 2026-07-02: Added `validate_raw_frame()` module-level helper and
+  `Data.from_raw_frame(raw, validate=True, raw_cols=None)` classmethod in
+  `src/cellpycore/cell_core.py` (per confirmed `issue55_plan.md`):
+  - `TypeError` on non-polars input (pandas users -> legacy bridge).
+  - Single `ValueError` collecting all problems: missing required columns
+    (`datapoint_num`, `cycle_num`, `step_num`, `epoch_time_utc`, `test_time`,
+    `current`, `potential`, `cumulative_charge_capacity`,
+    `cumulative_discharge_capacity`), `epoch_time_utc` must be Int64
+    (STEP-11 int64-ns UTC contract named in the message), datapoint/cycle/step
+    integer, rest numeric.
+  - Optional columns (`test_id`, `internal_resistance`, `ref_potential`,
+    `step_time`, `source_*`, `aux_*`, …) allowed absent, not dtype-checked.
+  - `validate=False` skips all checks; fresh `Data()` keeps the
+    `MockMetaTestDependent` graceful-degradation guarantee.
+- 5 new tests in `tests/test_creation.py`: round-trip parity vs plain
+  `data.raw = df` through `make_core_step_table` + `make_core_summary`,
+  missing columns all named, wrong epoch dtype mentions int64-ns,
+  `validate=False` skip, pandas `TypeError`.
+- Test suite green: `uv run pytest` -> 100 passed.
+- `graphify update .` run after the code change.
+
+## Remaining
+
+- Nothing (ready for `/iflow-close`).
+
+## Status
+
+- [x] Done

cellpycore-0.1.2/.issueflows/03-solved-issues/issue56_original.md

@@ -0,0 +1,64 @@
+# Issue #56: Document standalone use of cellpy-core (slim-consumer guide)
+
+Source: https://github.com/cellpy/cellpy-core/issues/56
+
+## Original issue text
+
+## Context
+
+cellpy-core is designed to be usable on its own: anyone who can produce a polars DataFrame in the native `config.RawCols` schema should be able to get step tables and per-cycle summaries without pulling in full cellpy. That story currently lives only in design docs and code docstrings — there is no user-facing documentation for it.
+
+## Proposal
+
+Add a "Using cellpy-core standalone" guide to `docs/` covering:
+
+### 1. The recommended entry point
+
+Native `CellpyCellCore` (not the `OldCellpyCellCore` legacy bridge, which exists only to serve legacy cellpy headers):
+
+```python
+from cellpycore.cell_core import CellpyCellCore, Data
+
+core = CellpyCellCore(initialize=True)
+core.data.raw = my_polars_frame          # native config.RawCols schema
+core.cycle_mode = "anode"                # only for half-cells; default "standard"
+
+data = core.make_core_step_table(
+    core.data,
+    nom_cap=my_nom_cap_abs,              # absolute Ah, for the per-step C-rate
+    raw_limits=my_instrument_limits,     # optional; DEFAULT_RAW_LIMITS otherwise
+)
+data = core.make_core_summary(
+    data,
+    current_conversion_factor=1.0,       # raw-current -> output-current, by value
+)
+# optional: specific / normalized columns
+data = core.add_scaled_summary_columns(
+    data,
+    nom_cap_abs=my_nom_cap_abs,
+    normalization_cycles=None,
+    specific_converters={"gravimetric": f_g, "areal": f_a, "absolute": f_abs},
+)
+
+steps, summary = data.steps, data.summary  # polars frames (StepCols / CycleCols)
+```
+
+Also mention the class-free alternative (`summarizers.make_step_table(data)` + `summarizers.make_summary(data)` with the default schema) and when the class is worth it (cycle-mode -> TestMode handling, IR/C-rate orchestration).
+
+### 2. The contract the caller must honor
+
+- **Order matters:** step table before summary (`make_summary` reads `data.steps`).
+- **No metadata required:** `Data()` ships `MockMetaTestDependent`; only `cycle_mode` changes the math (CE direction).
+- **Units by value:** core never sees unit objects — the caller precomputes floats (`nom_cap`, `current_conversion_factor`, `specific_converters`); pint fallback only via the optional `units` extra.
+- **Raw shape assumptions:** `epoch_time_utc` is int64 ns UTC; capacities are cycle-cumulative per direction (point at `normalize_capacity_granularity` for step-/test-cumulative inputs); `test_id` optional, defaults to 0.
+- **Legacy cruft absent by design:** native summary is the clean `CycleCols` subset + C-rate/IR; cumulated CE / shifted / RIC columns exist only on the legacy bridge.
+
+### 3. Housekeeping
+
+- Link the guide from the README.
+- Once #55 (`Data.from_raw_frame`) lands, switch the example to use it.
+
+## Links
+
+- Raised together with #55 while discussing the future slim-consumer / cellpy v2 interaction pattern.
+- Background: `.issueflows/04-designs-and-guides/cellpy-core-integration-roadmap.md`, `cellpy-core-migration.md` §4 (metadata/units boundaries).

cellpycore-0.1.2/.issueflows/03-solved-issues/issue56_plan.md

@@ -0,0 +1,48 @@
+# Issue #56 — plan
+
+## Goal
+
+Add a user-facing "Using cellpy-core standalone" guide to `docs/` so slim consumers
+(anyone with a polars frame in the native `config.RawCols` schema) can get step
+tables and per-cycle summaries without full cellpy. Link it from the README.
+
+## Approach
+
+- New `docs/standalone-use.md` covering:
+  - Recommended entry point: native `CellpyCellCore` + `Data.from_raw_frame`
+    (#55 landed, so the example uses the validating front door, not bare
+    `core.data.raw = ...`).
+  - Full pipeline example: `make_core_step_table` (nom_cap, raw_limits) →
+    `make_core_summary` (current_conversion_factor, exclude_step_types) →
+    optional `add_scaled_summary_columns` (specific_converters).
+  - Class-free alternative: `summarizers.make_step_table` + `summarizers.make_summary`
+    with the default schema, and when the class is worth it (cycle_mode → TestMode,
+    IR/C-rate orchestration).
+  - Caller contract: step table before summary; no metadata required; units by
+    value (pint only via the optional `units` extra); raw-shape assumptions
+    (`epoch_time_utc` int64 ns UTC, cycle-cumulative capacities →
+    `normalize_capacity_granularity` for step-/test-cumulative inputs, `test_id`
+    optional); legacy cruft only on the `OldCellpyCellCore` bridge.
+  - Links to `docs/data_format_specifications/harmonized_raw.md` and
+    `docs/data-object-definition.md`.
+- README: add a short Documentation section linking the guide (and install note —
+  package is on PyPI as `cellpycore` since v0.1.1, README still says GitHub-only;
+  fix that line while touching it).
+
+## Files to touch
+
+- `docs/standalone-use.md` (new)
+- `README.md` (link + install line)
+- `.issueflows/01-current-issues/issue56_*.md` (tracking)
+- `HISTORY.md`, `pyproject.toml` (at close: patch bump + promote)
+
+## Test strategy
+
+Docs-only change — no engine code touched. Re-run `uv run pytest` (107 tests) to
+confirm the suite stays green; verify the example snippets against the real
+signatures in `cell_core.py` / `summarizers.py` (done while writing).
+
+## Design docs consulted
+
+`cellpy-core-integration-roadmap.md`, `cellpy-core-migration.md` §4,
+`release-procedure.md` (for the close/release steps).