cellpycore 0.2.2__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.4/.issueflows/03-solved-issues/issue139_original.md

@@ -0,0 +1,61 @@
+# Issue #139: legacy mapping: no entries for the energy columns (charge_energy_txt -> cumulative_charge_energy)
+
+Source: https://github.com/cellpy/cellpy-core/issues/139
+
+## Original issue text
+
+## Summary
+
+`cellpycore.legacy.mapping.LEGACY_ATTR_TO_SCHEMA["raw"]` has no entries for the
+energy columns, although both sides exist:
+
+- native schema defines `cumulative_charge_energy` and
+  `cumulative_discharge_energy`;
+- cellpy's loader configurations declare `charge_energy_txt` and
+  `discharge_energy_txt`, and vendor files carry the data (Maccor `Watt-hr`,
+  Neware energy columns, …).
+
+```python
+>>> from cellpycore.legacy import mapping
+>>> {k: v for k, v in mapping.LEGACY_ATTR_TO_SCHEMA["raw"].items() if "energy" in k}
+{}
+```
+
+## Why it matters now
+
+Found while porting loaders to the `harmonize()` framework
+(jepegit/cellpy#559 → #560). Consequences today:
+
+1. On the native runtime, `to_native()` passes the unmapped columns through
+   under their **legacy** names, so a native frame carries `charge_energy`
+   while the schema says the column should be `cumulative_charge_energy`.
+   Asking `c.schema.raw` for energy finds nothing.
+2. `harmonize()` drops undeclared columns by design, so a ported loader would
+   silently lose energy data unless it declares a passthrough — which is the
+   wrong long-term answer for a column the schema already has a name for.
+
+## Ask
+
+Add the mapping entries:
+
+| legacy attribute | native column |
+|---|---|
+| `charge_energy_txt` | `cumulative_charge_energy` |
+| `discharge_energy_txt` | `cumulative_discharge_energy` |
+
+Please confirm the reset-granularity convention for the energy columns matches
+the capacity one (cycle-cumulative per direction, per the harmonized-raw spec's
+*Capacity convention*) — the cellpy side will normalise them the same way.
+
+## Also unmapped (for a decision, not necessarily this issue)
+
+These native raw columns have no legacy attribute mapped to them. Several are
+correctly framework-owned or native-only, but `datetime_txt → epoch_time_utc`
+looks like a genuine omission of the same kind:
+
+`epoch_time_utc`, `step_type`, `step_mode`, `step_type_detail`, `cycle_type`,
+`ref_potential`, `step_charge_power`, `step_discharge_power`, `aux_*`,
+`source_*`, `mask`, `test_id`.
+
+Cross-repo order per the cellpy 2 release plan §3: core PR → core release →
+cellpy re-pin → cellpy consumes.

cellpycore-0.2.4/.issueflows/03-solved-issues/issue139_plan.md

@@ -0,0 +1,119 @@
+# Plan — issue #139 (legacy raw energy mapping)
+
+## Goal
+
+Bridge legacy raw energy columns through the authoritative header map so
+`charge_energy` / `discharge_energy` rename to
+`cumulative_charge_energy` / `cumulative_discharge_energy` (same pattern as
+capacity), enabling `to_native()` / `harmonize()` consumers to find them under
+the native schema names.
+
+## Constraints
+
+- Keep change to `mapping.py` + its existing totality / spot-check tests.
+  No loader work, no engine changes, no cycle/step energy columns.
+- Totality discipline (#116): every legacy attr / column value is either mapped
+  or in an exception set — never both, never neither.
+- Value-level pairs (`RAW_PAIRS`) drive DataFrame renames; attribute table
+  (`LEGACY_ATTR_TO_SCHEMA`) must stay in sync (`test_legacy_attr_matches_value_mapping`).
+- Out of scope (issue itself): `datetime_txt → epoch_time_utc` and the other
+  unmapped native-only list — track separately if wanted.
+- Cross-repo: core PR → core release → cellpy re-pin → cellpy consumes
+  (cellpy #560). This issue is the core PR only.
+- Spec already states the reset convention (see Approach); record that as the
+  answer to the issue's ask — do not invent a new convention here.
+
+### Prior art
+
+- `RAW_PAIRS` / `LEGACY_ATTR_TO_SCHEMA["raw"]` / exception sets —
+  [`src/cellpycore/legacy/mapping.py`](src/cellpycore/legacy/mapping.py).
+  Mirror capacity entries (`charge_capacity_txt` →
+  `cumulative_charge_capacity`).
+- Totality + spot-check tests —
+  [`tests/test_header_mapping.py`](tests/test_header_mapping.py)
+  (`test_raw_*_totality`, `test_known_translations`,
+  `test_legacy_attr_*`).
+- Spec Capacity convention —
+  [`docs/specifications/harmonized-raw.md`](docs/specifications/harmonized-raw.md)
+  (§ Capacity convention): energy columns share cycle-cumulative / per-direction
+  semantics with capacity.
+- Issue #42 (solved): engine reset-granularity normalizer already covers
+  `cumulative_*_energy` when source granularity differs.
+- Fixture helper already assumes the rename —
+  [`dev/make_harmonized_raw.py`](dev/make_harmonized_raw.py)
+  (`charge_energy` → `cumulative_charge_energy`).
+- Issue #116 (solved): attribute-table + `LEGACY_ATTR_UNMAPPED` discipline.
+- Toolbox: none relevant.
+- Graph: community 87 (`mapping.py`) / 82 (legacy headers) — no extra modules.
+
+**Note vs architecture-plan D3:** `cellpy2-native-headers-migration-plan.md`
+still lists raw energy as passthrough ("not synthesized — different reset
+semantics"). That is **stale relative to the harmonized-raw Capacity
+convention + #42**. Mapping is a rename of already-supplied columns, not
+synthesis. After Accept, add a one-line correction in
+`.issueflows/04-designs-and-guides/` (or a comment in the plan status) so
+future agents do not re-block the bridge; updating the architecture-plan
+doc can be a tiny follow-up outside this PR if desired.
+
+## Approach
+
+1. **Confirm convention (recorded decision):** energy matches capacity —
+   cumulative per cycle, per direction, reset at cycle boundary
+   (`harmonized-raw.md` Capacity convention). Cellpy loaders normalize the
+   same way; if a source is step-cumulative, #42's normalizer is the path,
+   not leaving the columns unmapped.
+
+2. **Value map** — add to `RAW_PAIRS` (next to the capacity pairs):
+   ```python
+   ("cumulative_charge_energy", "charge_energy"),
+   ("cumulative_discharge_energy", "discharge_energy"),
+   ```
+
+3. **Exception sets** — remove from the raw exceptions so totality stays
+   exact:
+   - `LEGACY_ONLY_RAW`: drop `"charge_energy"`, `"discharge_energy"`
+   - `NATIVE_ONLY_RAW`: drop `"cumulative_charge_energy"`,
+     `"cumulative_discharge_energy"`
+
+4. **Attribute map** — add to `LEGACY_ATTR_TO_SCHEMA["raw"]`:
+   ```python
+   "charge_energy_txt": "cumulative_charge_energy",
+   "discharge_energy_txt": "cumulative_discharge_energy",
+   ```
+   and remove those attrs from `LEGACY_ATTR_UNMAPPED["raw"]`.
+
+5. **Do not touch** step/cycle maps (`NATIVE_ONLY_STEP` still has
+   `charge_energy` / `discharge_energy` as *step-table* base signals — different
+   columns).
+
+6. **Behavior:** `legacy_to_native_raw()` / bridge renames will translate
+   energy instead of leaving it as a passthrough extra. That is the intended
+   fix for native-schema lookup and `harmonize()`.
+
+## Files to touch
+
+| Path | Change |
+|------|--------|
+| `src/cellpycore/legacy/mapping.py` | `RAW_PAIRS` + attr table + raw exception sets |
+| `tests/test_header_mapping.py` | Extend `test_known_translations` expected dict with the two energy renames |
+| `.issueflows/04-designs-and-guides/` (short note) | Optional: "raw energy bridged like capacity (#139)" so D3 staleness is local |
+
+## Test strategy
+
+```bash
+uv run pytest tests/test_header_mapping.py
+uv run ruff check && uv run ruff format --check
+```
+
+Existing totality / attr-sync tests should go green once exceptions and pairs
+move together. No new fixture goldens expected (energy was not in
+`RAW_PAIRS` before; bridge goldens that omit energy columns stay unaffected).
+
+## Open questions
+
+1. **Energy reset convention = capacity?** **Recommended: yes** (spec + #42
+   already say so). Accepting this plan accepts that answer for the GitHub
+   issue ask.
+2. **Update architecture-plan D3 in this PR?** **Recommended: no** — keep
+   core PR small; optional local design-guide note only. Say if you want the
+   architecture-plan edit bundled.

cellpycore-0.2.4/.issueflows/03-solved-issues/issue139_status.md

@@ -0,0 +1,18 @@
+# Issue #139 status
+
+- [x] Done
+
+## What's done
+
+- Plan accepted (energy reset = capacity convention).
+- `RAW_PAIRS` + `LEGACY_ATTR_TO_SCHEMA["raw"]` energy entries added.
+- Dropped energy from `LEGACY_ONLY_RAW` / `NATIVE_ONLY_RAW` /
+  `LEGACY_ATTR_UNMAPPED["raw"]`.
+- `test_known_translations` updated.
+- Design note: `.issueflows/04-designs-and-guides/legacy-raw-energy-mapping.md`.
+- `uv run pytest` — 261 passed; ruff clean.
+- Version bump `0.2.2` → `0.2.3`; `HISTORY.md` promoted.
+
+## Remaining work
+
+- None (ship via PR).

cellpycore-0.2.4/.issueflows/04-designs-and-guides/legacy-raw-energy-mapping.md

@@ -0,0 +1,24 @@
+# Legacy raw energy mapping (#139)
+
+**Context.** Raw `charge_energy` / `discharge_energy` used to sit in
+`LEGACY_ONLY_RAW` (passthrough). Architecture-plan D3 still says that and
+claims different reset semantics vs native cumulative energy.
+
+**Decision.** Bridge them like capacity via `RAW_PAIRS` /
+`LEGACY_ATTR_TO_SCHEMA["raw"]`:
+
+| legacy value | native |
+|---|---|
+| `charge_energy` | `cumulative_charge_energy` |
+| `discharge_energy` | `cumulative_discharge_energy` |
+
+Reset convention matches capacity: cycle-cumulative, per direction
+(`docs/specifications/harmonized-raw.md` Capacity convention). Wrong source
+granularity → issue #42 normalizer, not leaving columns unmapped.
+
+**Alternatives.** Keep passthrough (rejected — breaks `to_native()` /
+`harmonize()` schema lookup). Synthesize energy from other signals (rejected —
+rename only).
+
+**Refs.** #139; cellpy #560; supersedes architecture-plan D3 for these two
+columns only.

{cellpycore-0.2.2 → cellpycore-0.2.4}/HISTORY.md

@@ -4,6 +4,31 @@ 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
+  ``cumulative_charge_energy`` / ``cumulative_discharge_energy`` via
+  ``RAW_PAIRS`` and ``LEGACY_ATTR_TO_SCHEMA``, matching the capacity
+  cycle-cumulative convention. (#139)
+
 ## [0.2.2] - 2026-07-17
 
 - Legacy bridge carries ``test_id`` through step and summary frames (identity

{cellpycore-0.2.2 → cellpycore-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellpycore
-Version: 0.2.2
+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.2 → cellpycore-0.2.4}/graphify-out/.graphify_labels.json

@@ -322,7 +322,6 @@
   "320": "Community 320",
   "321": "Community 321",
   "322": "Community 322",
-  "323": "Community 323",
   "324": "Community 324",
   "325": "Community 325",
   "326": "Community 326",
@@ -351,14 +350,11 @@
   "349": "Community 349",
   "350": "Community 350",
   "351": "Community 351",
-  "352": "Community 352",
   "353": "Community 353",
   "354": "Community 354",
-  "355": "Community 355",
   "356": "Community 356",
   "357": "Community 357",
   "358": "Community 358",
-  "359": "Community 359",
   "360": "Community 360",
   "361": "Community 361",
   "362": "Community 362",