Skip to content

Guide: Cycle Detection Configuration

Overview

This guide is for battery scientists and engineers who need to fine-tune how batteryproc identifies charge/discharge cycles in their data. The --cycle-config flag allows you to override the default cycle detection parameters using a YAML file, giving you precise control for challenging datasets.

When to Use a Custom Configuration

While batteryproc's default auto detection works well for most standard galvanostatic cycling data, you may need a custom configuration for:

  • Low-Current Experiments: Testing small cells like coin cells, micro-batteries, or watch batteries where the current is close to the default noise threshold.
  • Noisy Data: Working with instruments that produce noisy current readings, which can confuse the default cycle detection logic.
  • Complex Protocols: Analyzing data from non-standard tests like Galvanostatic Intermittent Titration Technique (GITT), Potentiostatic Intermittent Titration Technique (PITT), or formation cycle protocols with unusual current profiles.

Config File Structure

The configuration is a YAML file with a top-level cycle_detection key. Here is an annotated example:

# my_cycle_config.yml
cycle_detection:
  # --- Key Parameters ---
  method: current_sign               # Detection strategy
  current_threshold: 0.0005          # Noise floor for current (Amps)
  auto_current_threshold: false      # Disable adaptive tuning
  validate_cycles: true              # Enable quality checks

  # --- Fine-Tuning Parameters ---
  validator:
    min_cycle_length: 3              # Min data points per cycle
    capacity_alignment_tolerance: 5.0 # Tolerance for capacity alignment (%)

  current_sign:
    # Settings for the 'current_sign' method
    smoothing_window: 5              # Rolling average window for smoothing
    zero_cross_padding: 2            # Points to ignore around zero-crossings

To use this file, you would run: 

batteryproc path/to/data.xlsx --cycle-config my_cycle_config.yml

Key Parameters for Scientists

  • method: Choose the primary detection strategy.

    • auto (default): Trusts the cycle index from the file, then falls back to step_type, then current_sign.
    • step_type: Uses the "Step Type" column (e.g., "Charge", "Discharge").
    • current_sign: Identifies cycles based on the sign of the current (positive for charge, negative for discharge).
    • legacy: Uses the older forward-fill logic.

  • current_threshold: The minimum current (in Amperes) to be considered active cycling. This is the most important parameter to adjust. Set it just above the noise floor of your instrument. For example, if your instrument has a noise level of ±0.1 mA, a good threshold would be 0.0002 (0.2 mA).

  • auto_current_threshold: When true, batteryproc will attempt to determine the current_threshold automatically from the data. This is useful for batches of files with varying noise levels, but should be disabled if you need precise control.

  • validate_cycles: When true, batteryproc will run a series of quality checks on the identified cycles and report any anomalies, such as short cycles or misaligned capacity.

  • validator: A dictionary of settings for fine-tuning the cycle quality validation.

    • min_cycle_length: The minimum number of data points a cycle must have to be considered valid.
    • capacity_alignment_tolerance: The allowed percent difference between the calculated capacity and the file-reported capacity.

  • current_sign: A dictionary of settings for the current_sign method, useful for noisy data.

    • smoothing_window: The size of the rolling average window to apply to the current data before detecting zero-crossings.
    • zero_cross_padding: The number of data points to ignore on either side of a zero-crossing to prevent noise from causing rapid cycling.

Common Use Cases & Example Configurations

1. Low-Current Testing (e.g., Coin Cells)

For coin cells, the current may be very low (e.g., < 1 mA). The default current_threshold might be too high, causing the tool to miss cycles.

Configuration (low_current_cells.yml): 

cycle_detection:
  method: current_sign
  current_threshold: 0.0001 # 0.1 mA
  auto_current_threshold: false

2. Noisy Instrumentation

If your instrument produces noisy current data, especially around zero, you can use smoothing to improve detection.

Configuration (noisy_data.yml): 

cycle_detection:
  method: current_sign
  current_threshold: 0.001 # 1 mA
  current_sign:
    smoothing_window: 11
    zero_cross_padding: 3

3. Formation Cycles

Formation cycles often have long rests and variable currents. It's often best to trust the step_type from the instrument file.

Configuration (formation_cycles.yml): 

cycle_detection:
  method: step_type
  validate_cycles: false # Disable validation for unusual formation steps

Using the Config File

To use your custom configuration, pass the path to your YAML file using the --cycle-config flag:

batteryproc path/to/your_data/ -r --cycle-config path/to/your/custom_config.yml -o path/to/results/

Validation and Testing

To verify that your configuration is working as expected:

  1. Run with --validate-cycles: This is the best way to get detailed feedback. The output will show the number of cycles found and any anomalies.
  2. Use --debug: This will provide even more verbose output about the detection process.
  3. Inspect the plots: The generated plots are the ultimate validation. If the capacity vs. cycle plot looks correct, your configuration is likely working well.