cellpycore 0.2.3__tar.gz → 0.2.4__tar.gz

cellpycore-0.2.4/.issueflows/01-current-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.4/.issueflows/01-current-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.4/.issueflows/01-current-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.3 → cellpycore-0.2.4}/HISTORY.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellpycore
-Version: 0.2.3
+Version: 0.2.4
 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.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cellpycore"
-version = "0.2.3"
+version = "0.2.4"
 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.4}/src/cellpycore/cell_core.py

@@ -621,6 +621,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 +1134,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.4}/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.4}/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.4}/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",

{cellpycore-0.2.3 → cellpycore-0.2.4}/src/cellpycore/summarizers.py

@@ -1001,6 +1001,174 @@ def equivalent_cycles_to_summary(
     return data
 
 
+def throughput_to_raw(
+    data: Data,
+    schema: Optional[Schema] = None,
+    nom_cap_abs: float = 1.0,
+    conversion_factor: float = 1.0,
+    *,
+    nom_cap: Optional[float] = None,
+) -> Data:
+    """Add cumulative capacity throughput and equivalent full cycles to the raw frame.
+
+    Polars-native. Integrates the absolute current over test time
+    (trapezoidal ``sum(|current| * dt)``, cumulated per test) and derives the
+    equivalent full cycles (EFC) from it (issue #138):
+
+    - ``test_cumulated_capacity_throughput = cum_sum(mean(|I|) * dt * conversion_factor)``
+    - ``equivalent_full_cycles = test_cumulated_capacity_throughput / (2 * nom_cap_abs)``
+
+    Works on continuous time-series data (e.g. BMS / field datasets) without
+    any step table, summary, or cycle boundaries. Negative time deltas (file
+    seams, timer resets) and missing current values contribute zero; both are
+    logged as warnings rather than passing silently.
+
+    Args:
+        data (Data): The data object (only ``data.raw`` is used).
+        schema: The column-header schema to use. Defaults to the native
+            cellpy-core schema when not provided.
+        nom_cap_abs (float): The absolute nominal capacity, in the unit that
+            ``conversion_factor`` converts the throughput into (default: 1.0).
+        conversion_factor (float): Precomputed factor converting
+            ``current_unit * time_unit`` to the capacity unit of ``nom_cap_abs``
+            (by value; default 1.0 = no conversion, e.g. ``1000 / 3600`` for
+            A·s -> mAh).
+        nom_cap (float): Deprecated alias for ``nom_cap_abs``.
+
+    Returns:
+        Data: The data object with the two columns added to ``data.raw``.
+    """
+    nom_cap_abs = _resolve_nom_cap_abs(nom_cap_abs, nom_cap)
+    if schema is None:
+        schema = default_schema()
+    hdr_raw = schema.raw
+    hdr_out = schema.cycle
+
+    # The engine is polars-native; accept a pandas frame for convenience.
+    raw = data.raw
+    was_pandas = not isinstance(raw, pl.DataFrame)
+    if was_pandas:
+        raw = pl.from_pandas(raw)
+
+    # Window per test when the frame carries a test_id (merged objects); a
+    # plain single-test / BMS time-series frame without one is fine too.
+    per_test = hdr_raw.test_id in raw.columns
+
+    def _over(expr: pl.Expr) -> pl.Expr:
+        return expr.over(hdr_raw.test_id) if per_test else expr
+
+    current_abs = pl.col(hdr_raw.current).abs()
+    diff_t = _over(pl.col(hdr_raw.test_time).diff())
+
+    # Both failure modes are silent otherwise: a gap in the current trace would
+    # contribute zero, and an unsorted / reset time column would be swallowed by
+    # the clip below. Count them once and say so.
+    n_missing, n_backwards = raw.select(
+        current_abs.is_null().sum().alias("missing"),
+        (diff_t < 0.0).sum().alias("backwards"),
+    ).row(0)
+    if n_missing:
+        logger.warning(
+            f"{n_missing} missing current value(s) counted as zero current in the "
+            "throughput integral"
+        )
+    if n_backwards:
+        logger.warning(
+            f"{n_backwards} negative time delta(s) contributed zero throughput "
+            "(unsorted rows, file seam, or timer reset?)"
+        )
+
+    prev_current = _over(current_abs.shift(1))
+    dt = diff_t.fill_null(0.0).clip(lower_bound=0.0)
+
+    # Trapezoidal. A right-hand rule (|I_i| * dt) charges the whole preceding
+    # rest to the first sample of a pulse, which matters on the irregularly
+    # sampled field / BMS data this is meant for.
+    mean_current = (current_abs.fill_null(0.0) + prev_current.fill_null(0.0)) / 2.0
+    increment = mean_current * dt * conversion_factor
+    throughput_col = hdr_out.test_cumulated_capacity_throughput
+    raw = (
+        raw.with_columns(increment.alias(throughput_col))
+        .with_columns(_over(pl.col(throughput_col).cum_sum()).alias(throughput_col))
+        .with_columns(
+            (pl.col(throughput_col) / (2.0 * nom_cap_abs)).alias(
+                hdr_out.equivalent_full_cycles
+            )
+        )
+    )
+
+    data.raw = raw.to_pandas() if was_pandas else raw
+    return data
+
+
+def efc_to_summary(
+    data: Data,
+    schema: Optional[Schema] = None,
+    nom_cap_abs: float = 1.0,
+    normalization_cycles: Union[Sequence, int, None] = None,
+    step_txt: Optional[str] = None,
+    *,
+    nom_cap: Optional[float] = None,
+) -> Data:
+    """Add capacity throughput and equivalent full cycles (EFC) to the summary.
+
+    Polars-native (issue #138):
+
+    - ``test_cumulated_capacity_throughput = test_cumulated_charge_capacity +
+      test_cumulated_discharge_capacity``
+    - ``equivalent_full_cycles = test_cumulated_capacity_throughput / (2 * nom_cap_abs)``
+
+    The throughput is capacity-based (same unit as the summary capacities, so
+    ``nom_cap_abs`` must be in that unit); for raw current-integration on
+    time-series data without cycles, see ``throughput_to_raw``.
+
+    Args:
+        data (Data): The data object.
+        schema: The column-header schema to use. Defaults to the native
+            cellpy-core schema when not provided.
+        nom_cap_abs (float): The absolute nominal capacity (default: 1.0).
+        normalization_cycles (Union[Sequence, int, None]): The cycles for
+            normalization; when given, ``nom_cap_abs`` is derived from them.
+        step_txt (str): The summary capacity column used to derive
+            ``nom_cap_abs`` from ``normalization_cycles`` (defaults to the
+            native cycle charge-capacity column).
+        nom_cap (float): Deprecated alias for ``nom_cap_abs``.
+
+    Returns:
+        Data: The data object with the two columns added to the summary.
+    """
+    nom_cap_abs = _resolve_nom_cap_abs(nom_cap_abs, nom_cap)
+    if schema is None:
+        schema = default_schema()
+    headers_summary = schema.cycle
+
+    if step_txt is None:
+        step_txt = headers_summary.charge_capacity
+
+    # The engine is polars-native; accept a pandas frame for convenience.
+    summary = data.summary
+    if not isinstance(summary, pl.DataFrame):
+        summary = pl.from_pandas(summary)
+
+    if normalization_cycles is not None:
+        nom_cap_abs = _calculate_nominal_capacity_from_cycles(
+            summary, schema, normalization_cycles, step_txt
+        )
+
+    data.summary = summary.with_columns(
+        (
+            pl.col(headers_summary.test_cumulated_charge_capacity)
+            + pl.col(headers_summary.test_cumulated_discharge_capacity)
+        ).alias(headers_summary.test_cumulated_capacity_throughput)
+    ).with_columns(
+        (
+            pl.col(headers_summary.test_cumulated_capacity_throughput)
+            / (2.0 * nom_cap_abs)
+        ).alias(headers_summary.equivalent_full_cycles)
+    )
+    return data
+
+
 def c_rates_to_summary(
     data: Data,
     schema: Optional[Schema] = None,

{cellpycore-0.2.3 → cellpycore-0.2.4}/src/cellpycore/units/__init__.py

@@ -7,6 +7,7 @@ from cellpycore.units.converters import (
     calculate_scaler,
     calculate_specific_conversion_factors,
     calculate_specific_converters,
+    calculate_throughput_conversion_factor,
     convert_value,
     get_cellpy_units,
     get_converter_to_specific,
@@ -24,6 +25,7 @@ __all__ = [
     "calculate_scaler",
     "calculate_specific_conversion_factors",
     "calculate_specific_converters",
+    "calculate_throughput_conversion_factor",
     "convert_value",
     "get_cellpy_units",
     "get_converter_to_specific",

{cellpycore-0.2.3 → cellpycore-0.2.4}/src/cellpycore/units/converters.py

@@ -559,6 +559,36 @@ def calculate_current_conversion_factor(
     return factor.to_reduced_units().m
 
 
+def calculate_throughput_conversion_factor(
+    raw_current_unit: str,
+    raw_time_unit: str,
+    *,
+    to_units: Optional[CellpyUnits] = None,
+) -> float:
+    """Compute the factor converting ``current * time`` to the charge unit.
+
+    The returned float is suitable for ``conversion_factor`` in
+    ``summarizers.throughput_to_raw``: the raw current integral is in
+    ``current_unit * time_unit`` (e.g. A·s) and the nominal capacity it is
+    divided by is a charge (e.g. mAh), so the integral needs scaling first
+    (issue #138).
+
+    Args:
+        raw_current_unit: Pint-compatible unit string for the raw current
+            column (e.g. ``"A"``).
+        raw_time_unit: Pint-compatible unit string for the raw test-time
+            column (e.g. ``"s"``).
+        to_units: Output unit spec; defaults to ``CellpyUnits()``.
+
+    Returns:
+        Dimensionless conversion factor (raw current·time → output charge).
+    """
+    output_units = to_units or get_cellpy_units()
+    return calculate_scaler(
+        f"{raw_current_unit}*{raw_time_unit}", output_units["charge"]
+    )
+
+
 # Per-property aliases for spec labels whose bare string means something else
 # (or nothing) to pint. The spec keeps the legacy label; conversion/validation
 # uses the pint-parsable form. Decision recorded on issue #115:

{cellpycore-0.2.3 → cellpycore-0.2.4}/uv.lock

@@ -73,7 +73,7 @@ css = [
 
 [[package]]
 name = "cellpycore"
-version = "0.2.3"
+version = "0.2.4"
 source = { editable = "." }
 dependencies = [
     { name = "pandas" },