cellpycore 0.2.3__tar.gz → 0.2.5__tar.gz

{cellpycore-0.2.3/.issueflows/02-partly-solved-issues → cellpycore-0.2.5/.issueflows/03-solved-issues}/issue100_status.md

@@ -1,6 +1,6 @@
 # Issue #100 — status
 
-- [ ] Done
+- [x] Done
 
 ## What's done
 

cellpycore-0.2.5/.issueflows/03-solved-issues/issue138_original.md

@@ -0,0 +1,85 @@
+# Issue #138: Add a built-in utility for calculating Equivalent Full Cycles (EFC) from time-series data.
+
+Author: jepegit
+URL: https://github.com/cellpy/cellpy-core/issues/138
+
+Cellpy currently provides cycle-based summaries and performance metrics for cycling experiments. However, many battery datasets particularly operational, field, and BMS datasets do not contain well-defined charge/discharge cycles. Instead, they consist of continuous time-series measurements of voltage, current, temperature, and time.
+
+For these datasets, researchers and engineers often use Equivalent Full Cycles (EFC) as a throughput-based ageing metric. Currently, users must calculate EFC outside of cellpy and maintain custom implementations, leading to duplicated effort and inconsistent definitions across projects.
+
+As battery research increasingly incorporates operational and real-world datasets, the lack of a built-in EFC calculation makes it more difficult to compare ageing across datasets and integrate operational data into existing cellpy workflows.
+
+## Proposed Solution
+
+Add a built-in utility for calculating **Equivalent Full Cycles (EFC)** from time-series data.
+
+Example usage:
+
+```python
+cell.calculate_efc(nominal_capacity=300.0)
+````
+
+or
+
+```python
+cell.make_summary(add_efc=True)
+```
+
+The implementation could:
+
+* Calculate cumulative charge throughput from current and time:
+
+  $$
+  Q_{throughput} = \sum |I| \Delta t
+  $$
+
+* Compute EFC as:
+
+  $$
+  EFC = \frac{Q_{throughput}}{2Q_{nom}}
+  $$
+
+  where $$Q_{nom}$$ is the nominal capacity.
+
+* Optionally add:
+  * Instantaneous cumulative EFC to the raw dataframe.
+  * EFC columns to the summary dataframe.
+  * Energy-throughput-based equivalents (optional future extension).
+  * Support for SoC-based EFC calculations when SoC data is available.
+
+Suggested outputs:
+
+* `cumulative_ah_throughput`
+* `cumulative_energy_throughput`
+* `equivalent_full_cycles`
+
+This would provide a standardized and reproducible EFC implementation directly within the cellpy ecosystem.
+
+***
+
+**Describe alternatives you've considered**
+
+Current alternatives include:
+
+* Implementing custom EFC calculations in downstream analysis scripts.
+* Adding project-specific preprocessing steps prior to importing data into cellpy.
+
+While these approaches work, they lead to code duplication and make it harder to compare results across projects and users. A native cellpy implementation would provide a common reference method and improve reproducibility.
+
+***
+
+**Additional context**
+
+This feature would be particularly useful for:
+
+* Operational battery datasets.
+* BMS and field-monitoring data.
+* Fleet and stationary storage applications.
+* Machine learning pipelines where degradation progress is tracked using throughput-based metrics.
+* Continuous time-series datasets that do not contain explicit cycle boundaries.
+
+As cellpy expands beyond traditional cycling experiments and is increasingly used for large-scale battery data analysis, a standardized EFC utility would help bridge the gap between laboratory cycling data and real-world operational datasets.
+
+```
+```
+

cellpycore-0.2.5/.issueflows/03-solved-issues/issue138_plan.md

@@ -0,0 +1,18 @@
+# Issue #138 — Plan: Equivalent Full Cycles (EFC) utility
+
+Confirmed approach (user-approved 2026-07-18):
+
+- **Both surfaces**: raw-level current integration + summary-level per-cycle columns.
+- **Summary basis**: existing `test_cumulated_charge_capacity + test_cumulated_discharge_capacity` (unit-consistent with nom_cap, no conversion factor).
+- **Skipped**: energy throughput, SoC-based EFC (issue marks optional/future); `make_summary(add_efc=True)` wiring (standalone functions match `equivalent_cycles_to_summary` precedent); legacy-bridge columns (native-only feature).
+
+## Changes
+
+1. `summarizers.py`: two free functions next to `equivalent_cycles_to_summary`:
+   - `throughput_to_raw(data, schema=None, nom_cap_abs=1.0, conversion_factor=1.0, *, nom_cap=None)` — adds `test_cumulated_capacity_throughput` (= cum_sum(|current|·Δt·factor), windowed over test_id when present, negative Δt clipped to 0) and `equivalent_full_cycles` (= throughput / (2·nom_cap_abs)) to `data.raw`. `conversion_factor` converts current·time units to the capacity unit (e.g. A·s→mAh = 1000/3600), caller-supplied per codebase convention.
+   - `efc_to_summary(data, schema=None, nom_cap_abs=1.0, normalization_cycles=None, step_txt=None, *, nom_cap=None)` — same two columns on the summary, throughput = cumulated charge + discharge capacity; supports `normalization_cycles` like its sibling.
+2. `config.py` `CycleCols`: the two new column-name fields (raw function reuses the same names via `schema.cycle`).
+3. `docs/specifications/cycle-table.md`: two new spec rows (conformance-locked).
+4. `legacy/mapping.py`: names added to `NATIVE_ONLY_CYCLE` (no legacy counterpart).
+5. `tests/test_config_columns.py`: names added to `CYCLE_EXPECTED`.
+6. `tests/test_efc.py` (new): raw integration vs hand-computed Σ|I|Δt, rest-rows-add-nothing, monotonicity, conversion factor, pandas round-trip, summary identity vs cumulated capacities.

cellpycore-0.2.5/.issueflows/03-solved-issues/issue138_status.md

@@ -0,0 +1,26 @@
+# Issue #138 — Status
+
+- [x] Done
+
+## 2026-07-18
+
+- Implemented `throughput_to_raw` and `efc_to_summary` in `src/cellpycore/summarizers.py`.
+- Registered `test_cumulated_capacity_throughput` and `equivalent_full_cycles` on `CycleCols` (`config.py`), in `docs/specifications/cycle-table.md`, in `tests/test_config_columns.py`, and as `NATIVE_ONLY_CYCLE` in `legacy/mapping.py`.
+- Added `tests/test_efc.py` (4 tests). Full suite: 265 passed.
+- End-to-end sanity run on mock data with A·s→mAh factor verified by hand (≈194 mAh throughput → EFC ≈ 0.324 at nom_cap 300 mAh).
+
+## 2026-07-23 (revision after review)
+
+- **Integration fixed**: right-Riemann `|I_i|·dt` → trapezoidal `mean(|I|)·dt` in `throughput_to_raw`. The old rule charged a whole preceding rest to the first sample of a pulse — wrong for the irregularly sampled field/BMS data this targets.
+- **Silent failures now logged**: missing current values and negative time deltas are counted and emitted as `logger.warning` instead of passing as zero.
+- **Legacy names **: `equivalent_full_cycles` and `cumulated_capacity_throughput` added to legacy `HeadersSummary` + `CYCLE_PAIRS` + `LEGACY_ATTR_TO_SCHEMA`; removed from `NATIVE_ONLY_CYCLE`. EFC now reaches default-schema cellpy users, not only `native_schema=True`.
+- **Wired into `add_scaled_summary_columns`** (native + legacy bridge), unconditionally — no `add_efc` flag (`nom_cap_abs` is already resolved there, next to `equivalent_cycles_to_summary`).
+- **Units helper**: `calculate_throughput_conversion_factor(current_unit, time_unit)` in `units/converters.py` so cellpy computes the A·s→charge factor the pint way (mirrors `calculate_current_conversion_factor`), instead of hand-derived `1000/3600` at call sites.
+- **Docs**: raw derived-columns table in `harmonized-raw.md`; `cycle-table.md` notes `EFC = normalized_cycle_index·(1+CE)/2`.
+- **Tests**: analytic case (1 A × 3600 s → EFC 0.5), trapezoidal-vs-right-Riemann, bad-input warnings, native + legacy-bridge wiring, units factor. The old `_expected_raw_throughput` helper mirrored the implementation and could not fail; kept but now backed by the analytic + bridge cases. Full suite: **271 passed**.
+
+## Remaining
+
+- **Blocking cellpy PR**: bump `cellpycore==0.2.4` pin in cellpy `pyproject.toml`, add `helpers.add_efc` wrapper (mirrors `add_normalized_cycle_index`) for the `cell.calculate_efc(...)` API from the issue. Plot label (`plotutils.py:823`) stays as-is, `equivalent_full_cycles` gets no axis-label entry (falls back to column name).
+- Version bump to **0.3.0** on close (new spec columns = schema change).
+- Deferred (per approved plan): energy throughput, SoC-based EFC.

cellpycore-0.2.5/.issueflows/03-solved-issues/issue142_original.md

@@ -0,0 +1,48 @@
+# Issue #142: Harden cycle_mode unwrapping in OldCellpyCellCore / _cycle_mode_to_test_mode
+
+Source: https://github.com/cellpy/cellpy-core/issues/142
+
+## Original issue text
+
+## Context
+
+Found while working **jepegit/cellpy#668** (v1.x batch notebook): after a custom `update_cell` → `make_step_table()` → `make_summary()`, the legacy bridge crashes with:
+
+```text
+AttributeError: 'list' object has no attribute 'strip'
+```
+
+in `cellpycore.cell_core._cycle_mode_to_test_mode` when `OldCellpyCellCore.cycle_mode` is still list-shaped (often double-nested from cellpy-file meta, e.g. `[['anode']]`).
+
+### Why this is a core issue (not just v1.x)
+
+- `cellpy` **master** already mitigates on the **consumer load path** via recursive `test_meta._unwrap` after `meta_test_dependent.update(as_list=True, …)` (and has unit tests).
+- The **engine/bridge** still assumes a scalar string:
+  - `OldCellpyCellCore.cycle_mode` getter only does one-level `m[0]`
+  - setter **keeps** list values (`[x.lower() for x in cycle_mode]`) instead of storing a scalar
+  - `_cycle_mode_to_test_mode` calls `cycle_mode.strip()` with no list/tuple handling
+
+Any path that skips consumer unwrap (legacy loads, in-memory meta mutation, older cellpy pins) can still hit this. v1.x (#668) will add a consumer-side unwrap backport; core should still be defensive.
+
+## What to do
+
+1. **Getter** (`OldCellpyCellCore.cycle_mode`): recursively unwrap 1-element `list`/`tuple` to a scalar (same semantics as cellpy `test_meta._unwrap`).
+2. **Setter**: unwrap first, then store a **scalar** string (or `None`) — do not persist a list of lowered strings.
+3. **`_cycle_mode_to_test_mode`**: if given a list/tuple, unwrap before `.strip()`; keep existing string / `None` / unknown-spelling behaviour.
+4. **Tests** covering at least:
+   - `'anode'` / `'full_cell'`
+   - `['anode']`
+   - `[['anode']]`
+   - `None`
+   - make_summary / make_core_summary does not raise on nested list meta
+
+## Acceptance
+
+- Nested list `cycle_mode` no longer crashes summarization through the legacy bridge.
+- Existing CE / inverted-convention tests (issue #129 era) stay green.
+- No API break for callers that already pass a plain string.
+
+## Links
+
+- Downstream report: https://github.com/jepegit/cellpy/issues/668
+- Related consumer mitigation on master: unwrap in `cellpy.readers.cellpy_file.read` / `test_meta._unwrap`

cellpycore-0.2.5/.issueflows/03-solved-issues/issue142_plan.md

@@ -0,0 +1,86 @@
+# Issue #142 — plan: harden `cycle_mode` unwrapping
+
+## Goal
+
+Stop nested list-shaped `cycle_mode` (e.g. `[['anode']]`) from crashing
+`_cycle_mode_to_test_mode` / summarization on the legacy bridge; store and
+expose a scalar string (or `None`) from the `cycle_mode` property.
+
+## Constraints
+
+- Back-compat: plain string callers unchanged; issue #127 spelling tables and
+  issue #129 bridge CE polarity tests stay green.
+- KISS: no new package/module; private helper next to existing translator in
+  `cell_core.py`. No numpy dependency (cellpy’s `_unwrap` also peels numpy
+  scalars / NaN — out of scope here; meta on the bridge is Python
+  `list`/`tuple`/`str`/`None`).
+- Metadata boundary unchanged: still optional; only normalize this one field
+  at the property / translator edge.
+- Scope: getter, setter, `_cycle_mode_to_test_mode` (+ tests). No cellpy
+  consumer changes (jepegit/cellpy#668 stays separate).
+
+### Prior art
+
+- `cellpy.readers.test_meta._unwrap` — recursive peel of 1-element
+  `list`/`tuple`; multi-element left as-is. **Mirror** that rule in core
+  (list/tuple only).
+- `_cycle_mode_to_test_mode` + `#127` tests in `tests/test_schema.py` —
+  spelling / warning contract; **extend**, don’t rewrite.
+- `CellpyCellCore.cycle_mode` getter already does one-level `m[0]`; setter
+  wrongly keeps a lowered **list**. `OldCellpyCellCore` inherits this
+  property (no override).
+- `test_bridge_summary_respects_cycle_mode` (`tests/test_golden.py`) — CE
+  polarity regression for string `"anode"`; keep green; add a nested-list
+  smoke if cheap.
+- Toolbox: empty (nothing reusable). Graph: `cycle_mode` /
+  `_cycle_mode_to_test_mode` / `OldCellpyCellCore` communities confirm the
+  change set is `cell_core.py` + `test_schema.py`.
+
+## Approach
+
+1. Add `_unwrap_meta_scalar(value)` in `cell_core.py` (module-private):
+   while `list`/`tuple` and `len == 1`, recurse; else return value.
+2. **Getter:** unwrap `meta_test_dependent.cycle_mode`; if still
+   `list`/`tuple`, take `[0]` when non-empty else `None` (preserves today’s
+   first-element behaviour for multi-element placeholders).
+3. **Setter:** unwrap first; if still sequence, take first or `None`; then
+   store **scalar** `str.lower()` or `None` on both meta and `_cycle_mode`
+   (never a list of lowered strings). Handle `None` without calling `.lower()`.
+4. **`_cycle_mode_to_test_mode`:** unwrap (+ first-element if still sequence)
+   before `.strip()`; keep existing `None` / empty / known / unknown+warn
+   behaviour. Type hint can widen to `Optional[str | list | tuple]` or stay
+   loose — behaviour matters more than the annotation.
+5. No public API export of the helper.
+
+Multi-element lists (`['anode','cathode']`) are not a real cellpy-file shape
+today; taking `[0]` matches the old getter and avoids a new failure mode.
+
+## Files to touch
+
+| Path | Change |
+|------|--------|
+| [`src/cellpycore/cell_core.py`](../../src/cellpycore/cell_core.py) | `_unwrap_meta_scalar`; harden getter / setter / `_cycle_mode_to_test_mode` |
+| [`tests/test_schema.py`](../../tests/test_schema.py) | Parametrize unwrap cases next to `#127` block; nested-list → INVERTED; setter stores scalar; optional `make_core_summary` / `make_summary` smoke with nested meta |
+
+## Test strategy
+
+```bash
+uv run pytest tests/test_schema.py -k cycle_mode
+uv run pytest   # full suite before close
+uv run ruff check && uv run ruff format --check
+```
+
+New coverage (minimum from issue):
+
+- `_cycle_mode_to_test_mode`: `'anode'`, `'full_cell'`, `['anode']`,
+  `[['anode']]`, `None` (and keep existing spelling params green).
+- Getter/setter: set `[['anode']]` or assign list → property returns
+  `"anode"`; stored meta is a `str`, not a list.
+- Smoke: `OldCellpyCellCore` (or `CellpyCellCore`) with nested list on
+  `meta_test_dependent.cycle_mode` → `make_core_summary` / `make_summary`
+  does not raise.
+
+## Open questions
+
+None blocking — defaults above match the issue + cellpy `_unwrap`. Say if
+you want multi-element lists to warn instead of silently taking `[0]`.

cellpycore-0.2.5/.issueflows/03-solved-issues/issue142_status.md

@@ -0,0 +1,20 @@
+# Issue #142 — status
+
+- [x] Done
+
+## What's done
+
+- Plan confirmed (`issue142_plan.md`).
+- Added `_unwrap_meta_scalar` / `_as_cycle_mode_scalar` in `cell_core.py`.
+- Hardened `CellpyCellCore.cycle_mode` getter/setter to store/return scalar
+  (or `None`); nested lists no longer persist as lowered lists.
+- `_cycle_mode_to_test_mode` unwraps list/tuple before `.strip()`.
+- Tests in `tests/test_schema.py` (issue #142 block): translator shapes,
+  setter scalar store, getter unwrap, `OldCellpyCellCore.make_core_summary`
+  smoke with `[['anode']]` meta.
+- Full suite: 281 passed; ruff green.
+- `HISTORY.md` Unreleased bullet added.
+
+## Remaining work
+
+- None (close / PR).

{cellpycore-0.2.3 → cellpycore-0.2.5}/.issueflows/04-designs-and-guides/cellpy-core-integration-roadmap.md

@@ -46,7 +46,7 @@ Reconciled against the actual repo state on **2026-06-26**. Status legend: ✅ d
 | STEP-09 Harmonize headers | ✅ done | `config.Cols` + spec tests; `legacy/mapping.py` gives lossless/total `config.Cols` ↔ legacy `Headers*` round-trip (`tests/test_header_mapping.py`) (#34/#35) |
 | STEP-10 Metadata scaffolding | ✅ done | `cellpycore.metadata` (`models.py`/`io.py`); `TestMeta`/`CellMeta`/`TestMetaCollection` + (de)serialize/merge; graceful-degradation guard (`tests/test_metadata.py`) (#37) |
 | STEP-11 Timestamp representation | ✅ done | `epoch_time_utc` + `first/last_epoch_time_utc` are int64-ns UTC; `cellpycore.timestamps` conversion helpers + fixture regenerated (`tests/test_timestamps.py`) (#32, PR #38) |
-| STEP-12 Unit-handling boundary | 🟡 partly done | `CellpyUnits` schema in `units/spec.py` (#40/#112) + `units.py` tooling behind the optional `units` extra; factors cross the seam by value; `cellpy` still keeps duplicate converters (delegation pending) |
+| STEP-12 Unit-handling boundary | ✅ done | `CellpyUnits` schema in `units/spec.py` (#40/#112) + `units.py` tooling behind the optional `units` extra; factors cross the seam by value; `cellpy` now delegates `get_converter_to_specific` / `nominal_capacity_as_absolute` to `cellpycore.units` (jepegit/cellpy #451) — the duplicate converters are retired |
 
 Per-step `Status:` lines below repeat this for context; this table is the quick reference.
 The forward work beyond these twelve steps (STEP-13+) is enumerated in
@@ -266,12 +266,15 @@ Adopt the internal int64-ns timestamp representation.
 
 ## STEP-12 Unit-handling boundary (scaffolding/tooling in core; population & policy upstream)
 
-**Status:** 🟡 partly done — the `CellpyUnits` schema lives in `cellpycore.units.spec`
+**Status:** ✅ done — the `CellpyUnits` schema lives in `cellpycore.units.spec`
 (#40, #112) and the pint-based conversion tooling (`cellpycore.units`:
 `get_converter_to_specific`, `nominal_capacity_as_absolute`, `Q`, output-unit defaults)
-already exist behind the optional `units` extra, attached to the `OldCellpyCellCore`
-bridge, and conversion factors already cross the seam **by value**. Remaining on the
-**cellpy** side only: duplicate converter functions not yet delegated to core.
+exists behind the optional `units` extra, attached to the `OldCellpyCellCore`
+bridge, and conversion factors cross the seam **by value**. The final cellpy-side move
+has landed: `CellpyCell.get_converter_to_specific` / `nominal_capacity_as_absolute`
+(and `convert_value` / `calculate_scaler`) now delegate to `cellpycore.units`
+(jepegit/cellpy #451, unit plan Phase 2), guarded by converter-parity fixtures on both
+sides — the duplicated converters are retired.
 
 **Codebase:** `cellpy-core` (scaffolding/tooling — `legacy.py` + `units.py`); population
 (`raw_units` from loaders) and the decision to delegate are `cellpy`'s opt-in.
@@ -299,8 +302,9 @@ already did for headers and the step engine).
 
 ## Remaining work (STEP-13+) — finalized 2026-06-28 (issue #39)
 
-The original twelve steps are complete except for the two intentionally-continuous /
-partly-done ones (STEP-06 golden fixtures, STEP-12 unit boundary). Going through the
+The original twelve steps are complete except for the one intentionally-continuous
+one (STEP-06 golden fixtures); STEP-12 (unit boundary) closed once the cellpy-side
+converter delegation landed (jepegit/cellpy #451). Going through the
 roadmap and the companion design docs surfaced the remaining work below. Each item is now
 tracked as its own **cellpy-core** GitHub issue (the cellpy-side delegation work stays on
 jepegit/cellpy). Captured under issue #39.
@@ -339,12 +343,12 @@ flowchart TD
     S08 --> S09["STEP-09 Harmonize headers ✅"]
     S08 --> S10["STEP-10 Metadata scaffolding ✅"]
     S08 --> S11["STEP-11 Timestamp representation ✅"]
-    S03 --> S12["STEP-12 Unit-handling boundary 🟡"]
+    S03 --> S12["STEP-12 Unit-handling boundary ✅"]
     S07["STEP-07 Build-backend swap ✅"] -.independent.-> S08
 
     classDef done fill:#d4edda,stroke:#28a745,color:#155724;
     classDef partly fill:#fff3cd,stroke:#ffc107,color:#856404;
     classDef todo fill:#f8d7da,stroke:#dc3545,color:#721c24;
-    class S01,S02,S03,S04,S05,S07,S08,S09,S10,S11 done;
-    class S06,S12 partly;
+    class S01,S02,S03,S04,S05,S07,S08,S09,S10,S11,S12 done;
+    class S06 partly;
 ```

cellpycore-0.2.5/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python-envs.pythonProjects": [
+        {
+            "path": ".",
+            "envManager": "ms-python.python:venv",
+            "packageManager": "ms-python.python:pip"
+        }
+    ]
+}

{cellpycore-0.2.3 → cellpycore-0.2.5}/HISTORY.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+- Harden `cycle_mode` unwrapping in `OldCellpyCellCore` / `_cycle_mode_to_test_mode`. (#142)
+
+## [0.2.4] - 2026-07-23
+
+- Add Equivalent Full Cycles (EFC) utilities (#138). `summarizers.throughput_to_raw`
+  integrates `|current|` over test time (trapezoidal, windowed per `test_id`) to add
+  `test_cumulated_capacity_throughput` and `equivalent_full_cycles` to the raw frame —
+  for continuous / BMS / field data without cycle boundaries. `summarizers.efc_to_summary`
+  adds the same two columns to the per-cycle summary from the cumulated charge+discharge
+  capacities. Both use `EFC = throughput / (2 x nominal capacity)`. Missing current values
+  and negative time deltas contribute zero and are logged as warnings.
+- EFC is emitted unconditionally by `add_scaled_summary_columns` (native + legacy bridge),
+  so it reaches default-schema cellpy users; the legacy bridge renames the summary columns
+  to `cumulated_capacity_throughput` / `equivalent_full_cycles`.
+- New spec columns in `docs/specifications/cycle-table.md` (with the
+  `EFC = normalized_cycle_index x (1 + CE) / 2` relationship noted) and the raw
+  derived-columns table in `harmonized-raw.md`.
+- `units.calculate_throughput_conversion_factor(current_unit, time_unit)` computes the
+  current·time → charge factor (e.g. A·s → mAh) the pint way, mirroring
+  `calculate_current_conversion_factor`.
 ## [0.2.3] - 2026-07-19
 
 - Bridge legacy raw ``charge_energy`` / ``discharge_energy`` to

{cellpycore-0.2.3 → cellpycore-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cellpycore
-Version: 0.2.3
+Version: 0.2.5
 Summary: Core engine for cellpy: fast, thread-safe step and cycle summarization of battery-cycling raw data
 License-Expression: MIT
 License-File: LICENSE

{cellpycore-0.2.3 → cellpycore-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cellpycore"
-version = "0.2.3"
+version = "0.2.5"
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
 description = "Core engine for cellpy: fast, thread-safe step and cycle summarization of battery-cycling raw data"

{cellpycore-0.2.3 → cellpycore-0.2.5}/src/cellpycore/cell_core.py

@@ -1,7 +1,7 @@
 import datetime
 import logging
 import time
-from typing import Callable, Iterable, List, Optional, Sequence, TypeVar, Union
+from typing import Any, Callable, Iterable, List, Optional, Sequence, TypeVar, Union
 
 from cellpycore import config
 from cellpycore.exceptions import NoDataFound
@@ -24,7 +24,31 @@ _NORMAL_CYCLE_MODES = frozenset(
 )
 
 
-def _cycle_mode_to_test_mode(cycle_mode: Optional[str]) -> config.TestMode:
+def _unwrap_meta_scalar(value: Any) -> Any:
+    """Recursively peel 1-element ``list``/``tuple`` wrappers.
+
+    Mirrors cellpy's ``test_meta._unwrap`` for the shapes that show up in
+    cellpy-file meta (often nested once, e.g. ``[['anode']]``). Multi-element
+    sequences are left unchanged.
+    """
+    if isinstance(value, (list, tuple)) and len(value) == 1:
+        return _unwrap_meta_scalar(value[0])
+    return value
+
+
+def _as_cycle_mode_scalar(value: Any) -> Optional[str]:
+    """Normalize ``cycle_mode`` to a scalar string or ``None``.
+
+    Unwraps 1-element list/tuple nesting, then takes the first element of any
+    remaining multi-element sequence (legacy getter behaviour).
+    """
+    value = _unwrap_meta_scalar(value)
+    if isinstance(value, (list, tuple)):
+        return value[0] if value else None
+    return value
+
+
+def _cycle_mode_to_test_mode(cycle_mode: Any) -> config.TestMode:
     """Map a legacy ``cycle_mode`` string to a :class:`config.TestMode`.
 
     The inverted (anode half-cell) convention is selected by any of ``"anode"``
@@ -33,16 +57,19 @@ def _cycle_mode_to_test_mode(cycle_mode: Optional[str]) -> config.TestMode:
     ``None`` and the recognized normal-convention spellings map to
     ``TestMode.NORMAL``.
 
-    An *unrecognized* non-empty value also maps to ``NORMAL`` but logs a warning,
-    so a mistyped or unmapped mode fails loudly instead of silently flipping the
-    ``coulombic_efficiency`` / ``coulombic_difference`` sign conventions.
+    Nested 1-element ``list``/``tuple`` wrappers (cellpy-file meta shape) are
+    unwrapped before matching. An *unrecognized* non-empty value also maps to
+    ``NORMAL`` but logs a warning, so a mistyped or unmapped mode fails loudly
+    instead of silently flipping the ``coulombic_efficiency`` /
+    ``coulombic_difference`` sign conventions.
 
     Args:
-        cycle_mode: Legacy mode string, or ``None``.
+        cycle_mode: Legacy mode string, nested list/tuple wrappers, or ``None``.
 
     Returns:
         The corresponding ``TestMode`` for summary sign conventions.
     """
+    cycle_mode = _as_cycle_mode_scalar(cycle_mode)
     if cycle_mode is None:
         return config.TestMode.NORMAL
     key = cycle_mode.strip().lower()
@@ -370,23 +397,18 @@ class CellpyCellCore:
         # TODO: v2.0 edit this from scalar to list
         try:
             data = self.data
-            m = data.meta_test_dependent.cycle_mode
-            # cellpy saves this as a list (ready for v2.0),
-            # but we want to return a scalar for the moment
-            # Temporary fix to make sure that cycle_mode is a scalar:
-            if isinstance(m, (tuple, list)):
-                return m[0]
-            return m
+            # cellpy-file meta often stores 1-element (sometimes nested) lists;
+            # expose a scalar for the current engine.
+            return _as_cycle_mode_scalar(data.meta_test_dependent.cycle_mode)
         except NoDataFound:
             return self._cycle_mode
 
     @cycle_mode.setter
-    def cycle_mode(self, cycle_mode: str):
-        if isinstance(cycle_mode, (tuple, list)):
-            cycle_mode = [cycle_mode.lower() for cycle_mode in cycle_mode]
-        else:
-            cycle_mode = cycle_mode.lower()
+    def cycle_mode(self, cycle_mode: Any):
         # TODO: v2.0 edit this from scalar to list
+        cycle_mode = _as_cycle_mode_scalar(cycle_mode)
+        if cycle_mode is not None:
+            cycle_mode = cycle_mode.lower()
         logger.debug(f"-> cycle_mode: {cycle_mode}")
         try:
             data = self.data
@@ -621,6 +643,9 @@ class CellpyCellCore:
         data = summarizers.equivalent_cycles_to_summary(
             data, schema, nom_cap_abs, normalization_cycles, step_txt
         )
+        data = summarizers.efc_to_summary(
+            data, schema, nom_cap_abs, normalization_cycles, step_txt
+        )
 
         # Note: the C-rates are added by make_core_summary (using the step-table
         # rates, independent of nom_cap, matching legacy cellpy). Adding them again
@@ -1131,6 +1156,9 @@ class OldCellpyCellCore(CellpyCellCore):
         summarizers.equivalent_cycles_to_summary(
             nd, native_schema, nom_cap_abs, normalization_cycles, step_txt
         )
+        summarizers.efc_to_summary(
+            nd, native_schema, nom_cap_abs, normalization_cycles, step_txt
+        )
         specific_columns = native_schema.cycle.specific_columns
         for mode in specifics:
             factor = self._resolve_specific_conversion_factor(

{cellpycore-0.2.3 → cellpycore-0.2.5}/src/cellpycore/config.py

@@ -444,6 +444,10 @@ class CycleCols(Cols):
     # preserving single-value IR targets (the four ``ir_start/end_*`` columns
     # above remain reserved for the richer future IR model).
     normalized_cycle_index: str = "normalized_cycle_index"
+    # Throughput-based ageing metrics (issue #138). ``throughput_to_raw`` reuses
+    # these same names for the columns it adds to the raw frame.
+    test_cumulated_capacity_throughput: str = "test_cumulated_capacity_throughput"
+    equivalent_full_cycles: str = "equivalent_full_cycles"
     charge_c_rate: str = "charge_c_rate"
     discharge_c_rate: str = "discharge_c_rate"
     ir_charge: str = "ir_charge"

{cellpycore-0.2.3 → cellpycore-0.2.5}/src/cellpycore/legacy/headers.py

@@ -122,6 +122,8 @@ class HeadersSummary(BaseHeaders):
     cumulated_ric_sei: str = "cumulated_ric_sei"
     cumulated_ric: str = "cumulated_ric"
     normalized_cycle_index: str = "normalized_cycle_index"
+    cumulated_capacity_throughput: str = "cumulated_capacity_throughput"
+    equivalent_full_cycles: str = "equivalent_full_cycles"
     low_level: str = "low_level"
     high_level: str = "high_level"
 

{cellpycore-0.2.3 → cellpycore-0.2.5}/src/cellpycore/legacy/mapping.py

@@ -121,6 +121,9 @@ CYCLE_PAIRS = [
     ("charge_c_rate", "charge_c_rate"),
     ("discharge_c_rate", "discharge_c_rate"),
     ("normalized_cycle_index", "normalized_cycle_index"),
+    # Throughput-based ageing metrics (issue #138).
+    ("test_cumulated_capacity_throughput", "cumulated_capacity_throughput"),
+    ("equivalent_full_cycles", "equivalent_full_cycles"),
 ]
 
 # -----------------------------------------------------------------------------
@@ -366,6 +369,8 @@ LEGACY_ATTR_TO_SCHEMA = {
         "cumulated_coulombic_difference": "test_cumulated_coulombic_difference",
         "cumulated_discharge_capacity": "test_cumulated_discharge_capacity",
         "cumulated_discharge_capacity_loss": "test_cumulated_discharge_capacity_loss",
+        "cumulated_capacity_throughput": "test_cumulated_capacity_throughput",
+        "equivalent_full_cycles": "equivalent_full_cycles",
         "cycle_index": "cycle_num",
         "data_point": "datapoint_num_last",
         "discharge_c_rate": "discharge_c_rate",