Welcome to BatteryProc¶
BatteryProc is a command-line tool and Python library for battery researchers. It automates the processing of cycling data — turning raw instrument files into publication-quality plots and validated electrochemical metrics.
It reads Neware .xlsx, delimited text (.csv/.txt), and BioLogic .mpt files. For every input it calculates per-cycle capacity, energy, Coulombic efficiency, and (optionally) differential capacity (dQ/dV), then writes organized plots and data files to disk.
Why BatteryProc?¶
- Multi-format support — Process Neware, BioLogic, and generic CSV/Text files through a pluggable parser registry.
- Validated metrics — A physics-based formula engine recomputes metrics from raw data and reconciles them against file-reported values.
- Publication-ready output — Consistent, high-DPI plots and optional SVG vector graphics, all styled through a centralized theme.
- Batch processing — Handle one file or an entire directory tree with a single command.
- Programmatic API — Embed the full pipeline in Python scripts without
sys.exitor argparse.
Documentation Map¶
Getting Started¶
New to BatteryProc? Start here.
- Installation — Set up via Conda or pip.
- Quick Start — Process your first file, run a batch, and understand the outputs.
User Guides¶
Step-by-step instructions for common tasks.
- CLI Usage — The core guide to running BatteryProc from the command line.
- Input File Requirements — Supported formats and how to structure your data files.
- CSV Data Export — Export the data behind every plot as CSV files.
- Averaging Replicate Cells — Combine data from multiple cells tested under similar conditions.
- Cycle Detection — How BatteryProc identifies charge/discharge cycles.
- Cycle Detection Configuration — Tune cycle detection parameters with YAML config files.
- Debugging Flags — Troubleshoot tricky datasets with diagnostic flags.
- Formula Engine — The mathematical definitions of all computed metrics.
- Adding a Parser — Extend BatteryProc to support new instrument formats.
- Plot Style Guide — Visual conventions for BatteryProc plots.
Examples¶
Runnable Python scripts demonstrating key workflows.
- Examples Overview — Capacity, energy, dQ/dV, cycle detection, and metric tolerance examples.
Reference¶
Look-up tables and technical specifications.
- CLI Arguments — Complete list of command-line flags and options.
- API Reference — Python module documentation for
batteryproc.apiand core modules. - Plot Gallery — Visual catalogue of every plot type BatteryProc generates.
- Metric Comparison — How file-reported and recomputed metrics are reconciled.
- Glossary — Definitions of electrochemical and BatteryProc-specific terms.
Deep Dives¶
Understand the "why" and "how" for maintainers and advanced users.
- Architecture — The four-stage processing pipeline.
- Exception Handling — Error hierarchy and exit codes.
- Performance — Tips for large batch runs.
- Cycle Identification Research — Background research on cycle segmentation.
Support¶
- Troubleshooting & FAQ — Common problems and solutions.
Project Info¶
- Contributing — Dev setup, code style, testing, and PR process.
- Project ChargedUp — Internal project planning (Phases 1–4 complete).
Project Info¶
BatteryProc v3.6.0 · Python 3.10+ · BSD 3-Clause License