Skip to content

Glossary

This page defines key electrochemical and BatteryProc-specific terms used throughout the documentation.

Electrochemical Terms

Capacity : The amount of electric charge a battery can store or deliver, measured in milliampere-hours (mAh). Specific capacity is capacity normalized by the active material mass (mAh/g) — this allows meaningful comparison between cells of different sizes.

Coulombic Efficiency (CE) : The ratio of discharge capacity to charge capacity for a given cycle, expressed as a percentage. A healthy cell typically shows CE near 99–100% after formation cycles. Dips below this indicate side reactions, electrolyte decomposition, or measurement artifacts.

Specific Energy : The amount of energy a battery stores per unit mass, measured in watt-hours per kilogram (Wh/kg). Computed by integrating voltage × current over time, then normalizing by cell weight. Requires --energy flag or ProcessOptions(energy=True).

dQ/dV (Differential Capacity) : The derivative of capacity with respect to voltage. Peaks in a dQ/dV plot correspond to voltage plateaus, which represent electrochemical phase transitions in the electrode materials. Shifts or loss of peaks over cycling indicate degradation mechanisms. Generated with the --derivative flag.

Capacity Retention : The ratio of a cell's discharge capacity at a given cycle to its discharge capacity at Cycle 1, expressed as a percentage. A cell with 80% retention at Cycle 500 has lost 20% of its initial capacity.

Cycle : One complete charge–discharge sequence. In BatteryProc, a cycle typically includes a charge step, an optional rest, a discharge step, and an optional rest. The exact definition depends on the cycle detection method used.

Formation Cycle : The initial cycles of a new cell, often run at low rates, during which the solid-electrolyte interphase (SEI) forms. Formation cycles typically show lower Coulombic efficiency and may use different protocols than subsequent cycling.

BatteryProc Terms

Step Plan : The sequence of steps in a battery test protocol (e.g., constant-current charge → constant-voltage hold → rest → discharge → rest). BatteryProc currently extracts this from the optional test sheet in Neware .xlsx files; if that sheet is missing, the step plan (and its signature) may be unavailable. Step plans are used to group replicate cells for averaging.

Step Plan Signature : A SHA-1 hash computed from a cell's step plan content. BatteryProc uses this signature to identify cells that were tested with identical protocols. Only cells with matching signatures are grouped for averaging (unless --average-ignore-plan is used).

Bad Cell : A classification applied when a cell shows abnormally low capacity (e.g., below 1.0 mAh/g) in its early cycles, suggesting a manufacturing defect, assembly error, or testing problem. BatteryProc fails the file with a data-quality error by default; use --force-process to force processing anyway.

Active Material Mass : The mass (in grams) of the electrochemically active material in the electrode. Required to convert raw capacity (mAh) to specific capacity (mAh/g). BatteryProc reads this from the data file or prompts you to enter it. Override with --mass-g.

Parser Registry : The plug-in system that allows BatteryProc to support multiple file formats. Each format (Neware XLSX, CSV, TXT, BioLogic MPT) has a dedicated parser class registered in batteryproc.parsers. See Adding a Parser.

ProcessOptions : The frozen dataclass (batteryproc.batteryproc_types.ProcessOptions) that captures all runtime configuration for the programmatic API. It mirrors CLI flags without requiring argparse. See the API Reference.

FileResult / ProcessResult : Structured return types from the API. FileResult describes the outcome of processing a single file; ProcessResult aggregates results from a batch run. See the API Reference.