# LiXX Cell Pack Matcher

A web-based tool for finding the optimal cell configuration in lithium battery packs. It matches cells based on capacity and internal resistance to maximize pack performance and longevity.

![License](https://img.shields.io/badge/license-MIT-blue.svg)

## Features

- **Pack Configuration**: Support for any SxP configuration (e.g., 6S2P, 4S3P, 12S4P)
- **Cell Matching**: Optimize by capacity (mAh) and internal resistance (mΩ)
- **Multiple Algorithms**:
  - Exhaustive Search (optimal for small configurations)
- **Surplus Cell Support**: Use more cells than needed; the algorithm selects the best subset
- **Live Progress**: Watch the optimization in real-time
- **Visual Pack Layout**: Color-coded visualization of the matched pack
- **Export Options**: JSON, CSV, and clipboard support
- **Keyboard Accessible**: Full keyboard navigation support
- **No Dependencies**: Pure HTML/CSS/JavaScript, no build step required

## Scientific Background

This tool implements cell matching algorithms based on research findings about lithium-ion battery pack assembly:

> **Internal resistance matching for parallel-connected lithium-ion cells and impacts on battery pack cycle life**
> 
> Wang et al., Journal of Power Sources (2013)
> DOI: [10.1016/j.jpowsour.2013.11.064](https://doi.org/10.1016/j.jpowsour.2013.11.064)

Key findings:
- A 20% difference in internal resistance between parallel-connected cells can reduce cycle life by approximately 40%
- Resistance mismatch causes uneven current distribution
- Uneven current leads to higher operating temperatures and accelerated capacity fade

## Usage

### Quick Start

1. Open `index.html` in a web browser
2. Set your pack configuration (e.g., 6S2P)
3. Enter cell data (label, capacity, and optionally internal resistance)
4. Click "Load Example" to see sample data
5. Adjust weights for capacity vs. IR matching
6. Click "Start Matching"
7. Review results and export if needed

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Alt + A` | Add new cell |
| `Alt + S` | Start matching |
| `Alt + E` | Load example data |
| `Esc` | Stop matching / Close dialog |
| `?` | Show keyboard shortcuts |

### Cell Data Format

Each cell requires:
- **Label**: Unique identifier (e.g., "B01", "Cell-A")
- **Capacity**: Measured capacity in mAh
- **Internal Resistance** (optional): Measured IR in mΩ

### Matching Weights

- **Capacity Weight**: Importance of matching parallel group capacities
- **IR Weight**: Importance of matching internal resistance within parallel groups

For current high-rate applications (e.g., power tools, EVs), increase IR weight.
For capacity-focused applications, increase capacity weight.

## Project Structure

```
lixx_cell_pack_matcher/
├── index.html          # Main application
├── css/
│   └── styles.css      # Application styles
├── js/
│   ├── app.js          # Main application logic
│   └── matching-algorithms.js  # Matching algorithms
├── data/
│   └── favicon.svg     # Application icon
├── README.md           # This file
└── LICENSE             # MIT License
```

## Technical Details

### Scoring Algorithm

The match quality score is calculated as:

```
score = (capacityWeight × capacityCV) + (irWeight × avgWithinGroupIRCV)
```

Where:
- `capacityCV`: Coefficient of variation of parallel group capacities
- `avgWithinGroupIRCV`: Average coefficient of variation of IR within each parallel group
- Lower score = better match

### Coefficient of Variation

```
CV = (σ / μ) × 100%
```

Where σ is the standard deviation and μ is the mean.

## License

MIT License - see [LICENSE](LICENSE) for details.