Architecture: How BatteryProc Works¶

Understanding the data pipeline from raw file to final plot.

BatteryProc is built on a modular "pipeline" architecture. It treats battery data analysis as a series of transformation steps, moving from raw, messy instrument files to clean, standardized metrics and visualizations.

1. The Processing Pipeline¶

The system operates in four distinct stages:

graph LR
    A[Raw File] -->|Parser| B[Canonical Data]
    B -->|Normalization| C[Standardized Record]
    C -->|Metrics Engine| D[Analysis Results]
    D -->|Plotting| E[Figures & Reports]

Stage 1: Ingestion (Parsers)¶

The entry point is the Parser Registry. When you provide a file, BatteryProc checks its extension and dispatches it to the appropriate parser (e.g., NewareParser for .xlsx, CSVParser for .csv).

Goal: Read the file into memory.
Challenge: Every instrument uses different column names ("Current(mA)", "I/mA", "Amps") and structures.
Solution: Parsers extract the raw tables and identify metadata (like step plans or mass), but they don't change the data values yet.

Stage 2: Normalization¶

Once loaded, the data is transformed into a Canonical Record. This is a standardized Pandas DataFrame where: * Current is always in Amperes (Charge > 0, Discharge < 0). * Voltage is in Volts. * Time is in Seconds (and strictly monotonic). * Columns have standard internal names (current_a, voltage_v, time_s).

This stage also handles Cycle Detection. If the file lacks cycle numbers, or if they are unreliable, the Cycle Detection engine analyzes the current/step-type traces to synthesize a correct cycle_index.

Stage 3: The Metrics Engine¶

Now that the data is clean and uniform, the Formulas Engine takes over. It calculates key performance indicators: * Integration: Capacity (Ah) and Energy (Wh). * Differentiation: dQ/dV (Differential Capacity). * Aggregation: Per-cycle summaries (Coulombic Efficiency, Retention).

This engine is instrument-agnostic. It doesn't care if the data came from a $50,000 cycler or a text file; the math is identical.

Stage 4: Visualization¶

Finally, the plots module generates the standard suite of figures. It uses a centralized Style Manager (batteryproc.colours) to ensuring all plots—whether single-cell or multi-cell averages—share a consistent, publication-ready look.

2. Key Components¶

The CLI Orchestrator (`cli.py`)¶

The Command Line Interface is the "conductor." It doesn't do the math; it: 1. Finds files (handling recursion). 2. Loads configuration (thresholds, tolerances). 3. Loops through files, calling the API. 4. Manages error reporting and progress bars.

The Metrics Core (`metrics/`, `formulas.py`)¶

formulas.py: Contains pure mathematical functions (e.g., trapezoidal integration, dQ/dV smoothing). These are stateless and easy to test.
metrics/: A package (capacity.py, energy.py, cycle_detection.py, averaging.py, bad_cell.py) that orchestrates these formulas to build summaries (e.g., "Calculate capacity for every cycle and return a DataFrame"). metrics/__init__.py re-exports the public names, so batteryproc.metrics.<name> import paths are unchanged.

The Parser Registry (`parsers.py`)¶

A plug-in system that allows BatteryProc to support new file formats without changing the core engine. Adding a new format is as simple as writing a class that inherits from BaseParser and registering it.

3. Design Philosophy¶

Fail Gracefully: If a file is missing energy data, we skip energy plots but still produce capacity plots. We don't crash.
Trust, but Verify: We default to using the instrument's reported metrics (like capacity) if available, but we validate them against our own recalculations. If they differ significantly, we warn the user or override them.
User-Centric: We prioritize "Physical Units" (Amps, Volts) internally but expose "Battery Units" (mAh, Wh/kg) in inputs/outputs to match researcher intuition.
CLI and API parity: The programmatic API (batteryproc.api) mirrors CLI behaviour exactly, returning structured results instead of calling sys.exit. See the API Reference.