Skip to content

Runnable Examples

This directory contains runnable Python scripts that demonstrate key features of the BatteryProc formula engine and programmatic API.

Each script is self-contained and includes comments explaining every step. The scripts use sample data files included in this directory.

How to Run

Ensure you have batteryproc installed in your Python environment (see Installation):

python docs/examples/example_script_name.py

Example Scripts

1. Basic Capacity (example_basic_capacity.py)

Demonstrates the most fundamental workflow: calculating per-cycle charge/discharge capacity and Coulombic Efficiency from raw data.

  • Data: sample_3cycles.csv
  • Output: A summary table (console) and basic_capacity_plot.png
python docs/examples/example_basic_capacity.py

2. Energy & Efficiency (example_energy_efficiency.py)

Shows how to compute per-cycle energy metrics: total energy (mWh), specific energy (Wh/kg), and energy efficiency.

  • Data: sample_3cycles.csv
  • Output: A summary table (console) and energy_efficiency_plot.png

3. Differential Capacity — dQ/dV (example_dqdv.py)

Demonstrates the differential capacity analysis workflow, including data smoothing and filtering.

  • Data: sample_cccv.xlsx
  • Output: dqdv_plot.png

4. Cycle Detection Methods (example_cycle_detection.py)

Illustrates the different cycle detection strategies (auto, step_type, current_sign) and how to inspect the metadata they produce.

  • Data: sample_cccv.xlsx
  • Output: Comparison of cycle indices (console)

5. Metric Tolerance Comparison (example_tolerance_comparison.py)

Shows the metric reconciliation feature in action. Demonstrates how tolerance settings affect whether BatteryProc trusts file-reported metrics or replaces them with recomputed values.

  • Data: sample_tolerance_test.csv (contains intentional errors)
  • Output: Reconciliation reports (console)

Using the Programmatic API

Beyond the formula engine, you can use the high-level batteryproc.api to process files exactly as the CLI does, but from Python. Here is a minimal example:

from pathlib import Path
from batteryproc.api import process_file, process_files
from batteryproc.batteryproc_types import ProcessOptions

# --- Process a single file ---
result = process_file(
    Path("data/cell_01.xlsx"),
    ProcessOptions(outdir=Path("output"), energy=True),
)
print(f"Status: {result.status}")  # "success", "skipped", or "failure"
if result.errors:
    print(f"Errors: {result.errors}")

# --- Process multiple files with averaging ---
batch = process_files(
    [Path("data/Cell_A1.xlsx"), Path("data/Cell_A2.xlsx")],
    ProcessOptions(
        outdir=Path("results"),
        average=True,
        csv_export=True,
    ),
)
print(f"{batch.success_count} succeeded, {batch.failure_count} failed")

# --- Inspect per-file results ---
for fr in batch.files:
    if not fr.ok:
        print(f"  ⚠ {fr.path.name}: {fr.error_category} — {fr.errors}")

Key differences from the CLI:

  • No sys.exit — errors are returned as structured FileResult objects.
  • Captured output — by default, stdout/stderr are captured into FileResult.stdout / FileResult.stderr instead of printing to the console.
  • ProcessOptions replaces argparse — all configuration is explicit and type-checked.

See the API Reference for full documentation of ProcessOptions, FileResult, and ProcessResult.