Skip to content

Project ChargedUp – Phase 2 Kickstart Guide

Quick-start guide for developers returning to BatteryProc Last Updated: 2025-11-07 | Phase 1 Complete

What is Phase 2?

Phase 2 focuses on user experience, performance, and distribution: - GUI Implementation: Simple desktop interface (Tkinter or PySimpleGUI) - Performance Optimization: Parallel processing, chunked reads, profiling - Metrics Expansion: Additional formula-based calculations based on user needs - Packaging: PyPI distribution with automated releases

What was Phase 1? Multi-format parsing, formula-driven metrics, extensible architecture (See Phase 1 Summary)

Quick Start (30 Minutes)

1. Environment Setup (10 min)

# Clone and setup
git clone https://github.com/nickbashian/batteryproc.git
cd batteryproc

# Create environment
conda env create -f environment-simple.yml
conda activate batteryproc

# Install in editable mode
pip install -e .
pip install -r requirements-dev.txt

# Verify
batteryproc --help
pytest  # Should pass all 711 tests

2. Read These First (15 min)

  1. Phase 1 Summary
  2. ChargedUp Roadmap
  3. Cheat Sheet

3. Try It Out (5 min)

# Process a test file
batteryproc tests/data/SAMPLE_TEST.xlsx -o ./test_output

# Try multi-format
batteryproc tests/data/ -r -o ./batch_output

# Check available parsers
python - << 'PY'
from batteryproc.parsers import ParserRegistry
print('Supported extensions:', ParserRegistry.supported_extensions())
PY

Architecture State

What Exists (Phase 1 Complete)

Parser System: - batteryproc/parsers.py: BaseParser, ParserRegistry - Parsers: Neware (.xlsx), CSV, TXT, BioLogic MPT - Config: batteryproc/config/column_mappings.yml

Metrics Engine: - Formula-based capacity/energy derivations - Cycle index synthesis from raw data - Coulombic efficiency validation - Bad cell detection with override (--force-process)

CLI: - Entry point: batteryproc/cli.py - Delegates to ParserRegistry for all file types - Flags: --mapping-file, --no-heuristic-map, --force-process, --average

Visualization: - Plot helpers in batteryproc/plots.py - Consistent styling via batteryproc/colours.py

What Doesn't Exist (Phase 2 Scope)

  • No GUI – CLI only
  • No parallel processing – Single-threaded
  • No PyPI package – Local install only
  • No database – File-based workflow only

Phase 2 Roadmap (Suggested)

Priority 1: GUI Foundation (Months 1–2)

Goal: Non-technical users can process files with clicks

  1. Refactor CLI core logic to callable functions: 
    # Target API
from batteryproc import process_file
results = process_file(path, output_dir, options)
  2. Build minimal GUI with Tkinter:
  3. File/folder selector
  4. Output directory picker
  5. Run button with progress bar
  6. Add basic error handling and user feedback

Starting Point: Refactor batteryproc/cli.py to separate argparse from business logic

Priority 2: Performance Optimization (Months 3–4)

Goal: 3–5x speedup for batch processing

  1. Profile current bottlenecks: 
    python -m cProfile -o profile.stats batteryproc large_file.xlsx
  2. Implement optimizations:
  3. Chunked DataFrame reads for large files
  4. Parallel processing for batch mode (multiprocessing)
  5. Selective column loading (only needed columns)
  6. Benchmark and validate against baseline

Starting Point: Create performance baseline with scripts/benchmark.py

Priority 3: Packaging & Distribution (Months 5–6)

Goal: pip install batteryproc works

  1. Finalize pyproject.toml (modern Python packaging)
  2. Define entry points for CLI and GUI
  3. Create GitHub Actions workflow for releases
  4. Test installation in clean environments

Starting Point: Review the Python Packaging User Guide

Open Questions for Phase 2

Q1: GUI Framework Choice - Options: Tkinter (stdlib), PySimpleGUI (easy), PyQt (powerful) - Trade-offs: Dependencies vs features vs learning curve - Recommendation: Start with Tkinter for minimal dependencies

Q2: Performance Priorities - Unknown: Which operations are slowest? (Need profiling data) - Candidates: Excel parsing, plot generation, metrics calculations - Action: Create baseline before optimizing

Q3: Metrics Expansion Scope - Question: What additional calculations do users need? - Depends on: User feedback during Phase 1 usage - See: deep dive on cycle identification research in docs

Quick Reference

Build Validation (Always Run Before Committing) 

pytest                    # All tests pass
ruff check .             # No lint errors
black --check .          # Code formatted
mypy batteryproc         # Type checks pass

Adding a New Parser (Example) 

from batteryproc.parsers import BaseParser, ParserRegistry
import pandas as pd
from pathlib import Path

@ParserRegistry.register_parser
class MyInstrumentParser(BaseParser):
    extensions = (".myext",)
    def parse(self, path: Path) -> pd.DataFrame:
        ...

Common Tasks 

# Run specific test
pytest tests/test_cli.py::test_basic_processing -v

# Generate coverage report
pytest --cov=batteryproc --cov-report=html
# Open htmlcov/index.html

Resources - Issues: https://github.com/nickbashian/batteryproc/issues?q=label%3Aphase-2 - Documentation: https://nickbashian.github.io/batteryproc/ - Discussions: https://github.com/nickbashian/batteryproc/discussions - Maintainer: @nickbashian

Ready to Start? Look for issues labeled phase-2 and good-first-issue.