Skip to content

ChargedUp Cheat Sheet (1-Pager)

Quick reference for engineers ramping onto the redesign.

Vision

A faster, more flexible, and maintainable BatteryProc that reliably parses multi-instrument data, derives consistent metrics, and improves usability (CLI + simple GUI) so analysis scales with our organization’s growth.

Core Objectives

  • Robust, extensible ingestion: tolerate header/sheet variation; add CSV/TXT/MPT and other instruments via modular parsers.
  • Formula-driven consistency: compute capacity/energy and related metrics from base variables; auto-detect/flag anomalies.
  • Better UX & engineering hygiene: decouple CLI from processing; prototype a lightweight GUI; strengthen docs, packaging, and CI.

Key Architectural Changes

Area Current Target Benefit
Parsing Monolithic Plugin/registry parsers Extensible across file types/instruments.
Metrics Embedded logic Centralized formula engine Consistent, testable results.
Plots Imperative Config + adaptive layouts Clear visuals at high cycle counts; reuse.

Milestone update: The formula engine and cycle detection logic are now comprehensively documented. See the Formulas Engine Guide and Cycle Detection Guide for full details.

Phase 1 (v3.4.0) Highlights

  • Multi-Format Ingestion: ParserRegistry now supports XLSX, CSV, TXT, and BioLogic MPT files.
  • Config-Driven Mapping: Handle format variations with YAML-based column standardization.
  • Validated Metrics: Compare file-reported values against recomputed metrics with configurable tolerances.
  • See the Phase 1 Summary for complete details.

Issue Taxonomy / Labels

  • ChargedUp – top-level project label (apply to all EPICs + tasks)
  • type: epic, type: task – hierarchy
  • Areas: area: parsing, area: metrics, area: plotting, area: cli, area: gui, area: packaging, area: docs, area: database

Workflow

  1. Create EPIC (template) from task statements + roadmap; keep high-level and outcome-oriented.
  2. Break into tasks (sub-issue template), each linking back to its EPIC. Use GitHub Issues/Boards for tracking.
  3. Branch naming: cu/<area>/<short-desc>; PRs target dev.
  4. Keep PRs small, link task + EPIC, and follow repo standards (tests/type/lint).
  5. When touching batteryproc/, follow the typed-core vs legacy policy (see Contributing → Typing Policy) and update the mypy overrides if a module graduates.

Definition of Done (Task Level)

  • Tests green (unit + affected integration) and CI passes.
  • Docs updated when user-visible behavior changes.
  • No new lint/type issues; local quality gates pass.
  • Linked EPIC & milestone updated; labels applied per area.

Quick Commands

# Run tests, linter, and type checker
pytest -q
ruff check .
mypy batteryproc
black --check .

# Build and serve documentation locally
mkdocs serve

CLI Tips

  • Use a custom mapping file to standardize sheet/column names and units:
    • batteryproc input.xlsx --mapping-file my_mappings.yml
  • Toggle heuristic column mapping (for mapping debug/strict mode):
    • batteryproc input.xlsx --mapping-file my_mappings.yml --no-heuristic-map (default is --heuristic-map)
  • Control metric reconciliation tolerances and source preference:
    • batteryproc input.xlsx --recompute-all --metric-tolerance 0.02
    • batteryproc input.xlsx --prefer-file-metrics --metric-tolerance-abs 0.1
  • Tune cycle detection behaviour and diagnostics from the CLI:
    • batteryproc input.xlsx --cycle-detection step_type --current-threshold 0.02 --validate-cycles
    • batteryproc input.xlsx --cycle-config overrides.yml --no-validate-cycles
  • Progress UX: multi-file runs surface a tqdm bar automatically when stdout is interactive. Pass --no-progress to suppress it, and rely on exit codes (2 parse, 3 data quality, 4 wrong data type, 13 permission, 1 unexpected) for scripting.

dQ/dV and Parser Integration (new)

  • dQ/dV respects cycle config: The --cycle-detection method and thresholds (including --autotune-current-threshold) are honored by metrics.dqdv and plots.dqdv_plot. The resulting DataFrames include attrs["cycle_detection"] with method/threshold provenance.
  • Parser synthesis uses the same pipeline: When a file is missing Cycle Index, the parser and CLI fallback synthesize indices via the shared detection flow so results match the metrics pathway, including auto-threshold metadata when enabled.

For a deep dive on these flags, see the Guide to Debugging Flags.

See Also