cellpycore 0.2.2__tar.gz → 0.2.3__tar.gz

cellpycore-0.2.3/.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.3/.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.3/.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.3/.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.3}/HISTORY.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellpycore
-Version: 0.2.2
+Version: 0.2.3
 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.3}/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",