Skip to content

Troubleshooting and FAQ

Solutions to common problems when using BatteryProc.

Installation Problems

batteryproc command not found

The CLI entry point is not on your PATH.

Solutions:

  1. Make sure your virtual environment is activated (your terminal prompt should show (batteryproc) or (.venv)).
  2. Re-run pip install -e . inside the activated environment.
  3. As a fallback, run python -m batteryproc.cli --help from the project root.

ImportError: No module named ...

A dependency is missing.

Solution: Activate your environment and run pip install -e . again. If the error mentions batteryproc itself, confirm you are inside the correct environment.

Processing Problems

File is skipped as incomplete

BatteryProc skips files with very little data (e.g., only a partial cycle) to avoid generating misleading plots.

Solution: If you want to process the file anyway, add --force-process. Otherwise, inspect the file to ensure it contains the data you expect.

Excel format issues

Neware .xlsx files are expected to contain sheets named record, cycle, and unit. Files missing these sheets will be skipped.

Solution: Verify your file has the required sheets. For non-Neware files, see the Input File Requirements guide.

Access denied or permission errors

BatteryProc cannot read the input file or write to the output directory.

Solution: Ensure the file is not open in another program (e.g., Excel). Verify you have write permissions for the output directory. Avoid system-protected folders.

Mass prompt appears repeatedly

BatteryProc prompts for the active material mass when it detects a placeholder value (e.g., 1 g) in the data file.

Solution: Provide the mass upfront with --mass-g 0.523 to skip the interactive prompt entirely. For batch processing, this is especially useful.

Plot Problems

Plots look strange or are blank

Missing curves or unusual values usually indicate anomalies in the source data.

Solutions:

  • Check the console output for WARNING messages — BatteryProc often detects issues and prints diagnostics.
  • Use --debug for verbose output to see exactly what data was extracted.
  • Use --quiet to suppress non-critical warnings if the output is too noisy.

dQ/dV plot is empty or noisy

The dQ/dV calculation requires sufficient data points within a charge or discharge step. Short cycles or low logging resolution may not provide enough points.

Solution: BatteryProc prints a warning when it skips dQ/dV for a cycle. There is no fix other than ensuring the source data has adequate resolution.

Averaging Problems

Averaging not working as expected

You used --average, but no average plots were generated for cells you expected to be grouped.

Cause: BatteryProc groups cells by step plan signature (a hash of the test protocol). Cells with different protocols are not averaged together.

Solutions:

  1. Use --debug-signatures to print each file's step plan signature and see why cells are in different groups.
  2. Use --average-ignore-plan to force averaging by filename only (ignoring protocol differences). When used alone, it auto-enables capacity averaging.
  3. Combine --average-ignore-plan --average-energy if you also want energy averages while ignoring plan compatibility.

Warning

Averaging cells with different test protocols may produce misleading results. Use --average-ignore-plan with caution.

Console Output Problems

Console shows lots of benign warnings

When reconciling instrument metrics against recomputed values, BatteryProc may print informational warnings for each out-of-tolerance row.

Solution: Add --quiet to suppress non-critical warnings from the console. They remain available in logs and in the warnings metadata attached to results.

Debugging general issues

If the output directory is empty or the tool does not seem to run, use the --debug flag for verbose output that reveals file discovery problems, parsing errors, and data issues.

Unmapped Columns

After applying explicit column mappings, BatteryProc uses a conservative heuristic to map remaining columns based on token overlap with known standardized names. This helps when an instrument exports slightly different column headers.

Control: Heuristics are enabled by default. Use --no-heuristic-map to disable them when debugging mappings.

Adding permanent mappings: If columns remain unmapped, add explicit entries to a mapping file and pass it with --mapping-file path/to/your.yml. See batteryproc/config/column_mappings.yml for the expected structure:

instruments:
  default:
    columns:
      "Volt_reading": "Voltage (V)"

Heuristics never override explicit mappings.

Frequently Asked Questions

Q: What operating systems does BatteryProc support? : BatteryProc is platform-independent and works on Windows, macOS, and Linux.

Q: How long does processing take? : Most files process in seconds. Very large datasets (hundreds of thousands of rows) may take a few minutes per file. A progress bar is displayed for batch operations (disable with --no-progress).

Q: How can I get the numeric data, not just plots? : Use --csv to export CSV files alongside plots, or --csv-only for CSV files without rendering plots. See the CSV Data Export Guide for column definitions.

Q: How can I use BatteryProc from Python scripts? : Use the programmatic API in batteryproc.api. See the API Reference for examples and documentation.

Q: How can I change the plot style? : Plot styling is centralized in batteryproc/colours.py and the batteryproc/plots/_style.py styling component (with plot builders in batteryproc/plots/builders.py). Since the package is installed in editable mode (-e), changes take effect immediately. See the Style Guide.