Skip to content

Guide: Cycle Detection in BatteryProc

A deep dive into how BatteryProc identifies charge/discharge cycles in messy, real-world experimental data.

Robustly identifying cycle boundaries is fundamental to all battery performance analysis. This guide explains the theory, techniques, and edge cases that the BatteryProc cycle detection engine handles to segment raw time-series data into discrete, meaningful cycles.

This document is for any researcher who needs to: - Understand how cycle indices are assigned, especially for data lacking explicit labels. - Confidently process complex experimental protocols (e.g., CC-CV, GITT, formation cycles). - Debug data quality issues related to cycle detection. - Tune the cycle detection algorithm for specific experimental needs using the CLI.

1. The Cycle Identification Problem

1.1. What is a Battery Cycle?

A battery cycle is typically defined as a sequence of charge and discharge events that returns the battery to its original state of charge. A common sequence is: 1. Charge Phase: Current flows into the battery (I > 0). 2. Optional Rest: Zero current (I ≈ 0) allows for voltage relaxation. 3. Discharge Phase: Current flows out of the battery (I < 0). 4. Optional Rest: Another zero-current period.

The primary challenge is to programmatically determine when one cycle ends and the next begins, especially when faced with noisy data, inconsistent labeling, and complex multi-step protocols.

1.2. Key Parameters for Detection

BatteryProc uses a combination of signals to identify cycles:

Parameter Role in Cycle Detection
step_type The most reliable signal when present; an explicit label from the instrument (e.g., "Charge", "Discharge").
current_a The primary data-driven signal; a sign change reliably indicates a transition between charge and discharge.
capacity_mAh A useful validation signal; a sudden reset or wrap in cumulative capacity often aligns with a new cycle.
voltage_v A secondary validation signal; voltage trends (increasing/decreasing) can confirm the current state.

2. The Tiered Detection Strategy (The AUTO Method)

BatteryProc employs a robust, tiered detection strategy that prioritizes the most reliable signals first and gracefully falls back to data-driven methods when metadata is missing or inconsistent. This is the default AUTO method.

Hierarchy of Reliability:

  1. Trust Existing cycle_index (if valid): If the input data already contains a cycle_index column, the engine first validates it. If the index is consistent (monotonic, no major gaps), it is used directly.
  2. Parse step_type Labels: If a step_type column is available, the engine uses regular expressions to identify "charge," "discharge," and "rest" steps. This is highly effective for clean, well-structured data from major cyclers.
  3. Analyze Current Sign: If step labels are unreliable or absent, the engine falls back to analyzing the sign of the current. It identifies transitions from positive (charge) to negative (discharge) to define cycle boundaries.
  4. Validate and Refine: The results from the primary methods can be cross-checked using capacity resets and voltage trends to flag anomalies and increase confidence.

This tiered approach ensures that BatteryProc can handle everything from pristine, instrument-generated files to raw, unlabeled CSV data.

3. Detection Methods in Detail

3.1. Method 1: Step Type Parsing

This method relies on pattern matching against the step_type string.

  • Algorithm: It flags rows as 'charge' or 'discharge' based on regex patterns (e.g., matching "chg", "charge", "dchg"). A new cycle is counted when the sequence transitions back to the initial active step (e.g., from discharge back to charge).
  • Strengths: Fast, deterministic, and highly accurate for standardized data.
  • Weaknesses: Brittle. It fails if step names are non-standard (e.g., "Formation", "Pulse") or if the column is missing.

3.2. Method 2: Current Sign Analysis

This is the primary data-driven method, using the physics of current flow.

  • Algorithm:
    1. Thresholding: The current is classified as charge (I > I_threshold), discharge (I < -I_threshold), or rest (|I| <= I_threshold). This filters out noise around zero.
    2. Transition Detection: The engine identifies points where the active current state changes (e.g., from charge to discharge).
    3. Filtering: To prevent noise or brief spikes from creating spurious cycles, a "debounce" filter is applied, requiring a state change to be sustained for a minimum duration or number of points.
    4. Cycle Assignment: A new cycle number is assigned at the start of each charge phase that follows a discharge phase.
  • Strengths: Instrument-agnostic and robust to inconsistent labeling.
  • Weaknesses: Requires careful selection of the current threshold and can be sensitive to spikes or dropouts in the current signal.

4. Handling Edge Cases and Challenges

Real-world battery data is beautifully messy. Here’s how BatteryProc handles the complexities.

4.1. Rest Periods

Rest periods (I ≈ 0) can occur between or within cycles. The engine's default strategy is to assign a rest period to the cycle of the preceding active step. This is achieved via a "forward-fill" logic, ensuring that rests don't incorrectly split a cycle.

4.2. Multi-Step Protocols (e.g., CC-CV)

A common protocol like a Constant-Current Constant-Voltage (CC-CV) charge consists of multiple steps (CC charge, then CV charge) that all belong to the same charge phase of a single cycle. The detection engine is designed to group these together. The Step Type parser recognizes "CC" and "CV" variants, and the Current Sign method sees a continuous positive current (though it tapers during the CV phase), correctly identifying them as part of one charge event.

4.3. Formation Cycles

Formation cycles often use different parameters than standard cycling. The current detection logic treats them as regular cycles (e.g., Cycle 1, 2, 3). Future enhancements may add a cycle_type column to explicitly label them as 'formation'.

4.4. Incomplete or Truncated Data

If a data file ends mid-cycle, the last cycle may be incomplete (e.g., containing a charge phase but no discharge). BatteryProc will detect this and flag the cycle as incomplete in its validation diagnostics. These partial cycles are often excluded from aggregate metrics like capacity fade.

4.5. Non-Monotonic Time

Concatenated files or instrument resets can cause time to jump backward. The engine detects these "time reversals" and splits the data into separate, continuous segments for processing, preventing errors in time-based calculations like integration.

4.6. Noisy Data

To handle current noise, the engine uses: - Thresholding: Ignoring small current values around zero. - Hysteresis/Debouncing: Requiring a state change to be sustained for a minimum duration before it is considered a valid transition.

5. Validation and Diagnostics

To provide insight into the quality of the cycle detection, BatteryProc includes a powerful validation function, validate_cycle_index(). This function returns a detailed report on the detected cycles, including: - The total number of cycles found. - Statistics on cycle length and duration. - A list of identified anomalies, such as short_cycle, time_reversal, or rest_misalignment. - A "capacity alignment score" that checks if cycle start points align with resets in the cumulative capacity data (if available).

This allows you to programmatically assess the quality of your data and the cycle detection process.

6. Configuration and Tuning

While the AUTO method works well for most cases, you can fine-tune the algorithm via CLI flags:

  • --cycle-detection METHOD: Force a specific detection method.
    • auto: The default tiered strategy.
    • step_type: Use only Step Type parsing. Fails if the column is missing.
    • current_sign: Use only current sign analysis.
  • --current-threshold VALUE: Set the current threshold (in Amperes) for distinguishing active current from rest. This is crucial for noisy data.
  • --autotune-current-threshold: Allows BatteryProc to automatically estimate an optimal current threshold based on the data's noise characteristics.
  • --validate-cycles: Enable detailed cycle validation diagnostics, which will be printed in the output.

Downstream consumers of configuration (new)

  • Metrics: metrics.dqdv calls the configuration-aware detection pipeline and attaches a cycle_detection metadata dict to the returned dQ/dV traces (including method, thresholds, and auto-threshold details when enabled).
  • Parsers & CLI: When Cycle Index is synthesized during ingestion, the parser and CLI mirror the same pipeline so indices, thresholds, and diagnostics remain consistent with the metrics layer.
  • Plots: plots.dqdv_plot preserves the cycle_detection attrs already present on the input DataFrames, enabling traceability in downstream analysis.

Practical Example

If you are processing a raw CSV file that has no step_type column and a noisy current signal, you might use: 

batteryproc my_data.csv --cycle-detection current_sign --current-threshold 0.05
This command forces the robust current-based method and sets a higher threshold to ignore the noise.

7. References and Further Reading

  • Cycle Identification Research: For comprehensive theory, algorithms, and implementation strategies, see the Cycle Identification Research deep dive.
  • Academic Literature:
    • Plett, G. L. (2004). "State-of-charge estimation for lithium-ion batteries". IEEE Transactions on Power Electronics.
    • Zhang, Y., et al. (2020). "Cycle life prediction of lithium-ion batteries based on data-driven methods". Applied Energy.