# Dual Water Tank MCP for Battery Aging Mechanism Identification

[English](#dual-water-tank-mcp-for-battery-aging-mechanism-identification) | [中文](#dual-water-tank-mcp-for-battery-aging-mechanism-identification-中文)

This project is an MCP server for fitting a lithium-ion full-cell dual-water-tank model from charge/discharge voltage-capacity data. It is designed for battery aging mechanism identification, including parameter fitting, charge/discharge sign handling, capacity-bound adaptation, and batch processing.

The project keeps a two-layer structure:

- `dual_water_tank_mcp/`: core model code, including data loading, column detection, charge/discharge detection, model calculation, GA fitting, batch output, and CLI.
- `dual_water_tank_mcp/server.py`: a thin MCP interface layer that exposes the core functions as MCP tools.

If you need to fix or improve the model later, edit the core code under `dual_water_tank_mcp/`, then restart the MCP server.

## Features

- Reads `.xlsx`, `.xls`, `.csv`, `.txt`, and `.tsv` battery test data.
- Automatically detects voltage and capacity columns.
- Automatically detects charge or discharge from the voltage trend.
- Applies charge/discharge signs for electrode stoichiometry `y` and `x`.
- Automatically tests both `+I*R` and `-I*R`, then keeps the lower-RMSE result.
- Automatically adapts GA capacity bounds from the dataset capacity span.
- Supports single-file fitting and batch fitting.
- Writes final results to a desktop output folder by default.
- Runs as an MCP server with ready-to-call tools.

## From GitHub To Installation

Clone the repository:

```powershell
git clone <your GitHub repository URL>
cd dual-water-tank-mcp
```

If you already have the source code locally, enter the project root directly, for example:

```powershell
cd "D:\desktop\PSG\1.1 github\dual-water-tank-mcp"
```

Python 3.10 or newer is required. Git is also recommended.

Check:

```powershell
python --version
git --version
```

You can use the bundled one-click MCP launcher. On first run, it creates `.venv` and installs dependencies:

```powershell
.\run_mcp.cmd
```

The same launcher is what MCP clients should call. Users do not need to edit model code, Python files, or MCP server code.

Command-line preview example:

```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

Command-line fitting example:

```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

## Start MCP

Add this project as an MCP server in Codex, Claude Desktop, Claude Code, or another MCP client.

Windows MCP configuration:

```json
{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "C:\\path\\to\\dual-water-tank-mcp\\run_mcp.cmd",
      "args": []
    }
  }
}
```

macOS/Linux MCP configuration:

```json
{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "/path/to/dual-water-tank-mcp/run_mcp.sh",
      "args": []
    }
  }
}
```

On macOS/Linux, make the scripts executable once:

```bash
chmod +x run_mcp.sh dual-water-tank.sh
```

Reusable config examples are also provided:

- `examples/mcp_config_windows.json`
- `examples/mcp_config_macos_linux.json`

After configuring the client, refresh or restart the MCP connection. If `dual-water-tank-model` appears as an available MCP server, the connection is ready.

## How To Use After MCP Is Connected

Once connected, you do not need to manually run Python or command-line scripts. Ask your MCP client to call the tools exposed by this project.

Recommended workflow:

1. If the input format is uncertain, call `preview_dual_water_tank_data` first.
2. For one file, call `fit_dual_water_tank`.
3. For many files, call `batch_fit_dual_water_tank`.
4. Open `result.json`, `fitted_curve.csv`, or `batch_summary.csv` in the desktop output folder.

By default, final results are written to the desktop:

```text
Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/
```

On this author's Windows machine, the default desktop path is usually:

```text
D:\desktop\dual water tank output\
```

The MCP response also includes output paths such as `output_dir`, `curve_csv`, and `result_json`.

Example user requests:

```text
Use the dual-water-tank MCP to preview test_cases/25C_0.1C/25C_0.1C.xlsx.
```

```text
Use the dual-water-tank MCP to fit test_cases/25C_0.1C/25C_0.1C.xlsx and save the final result to the desktop.
```

```text
Use the dual-water-tank MCP to batch fit all Excel files in D:\my_battery_data.
Write the final results to the desktop dual water tank output folder.
```

```text
Use the dual-water-tank MCP to fit D:\data\cell.xlsx.
Use D:\data\anode.txt as anode_path and D:\data\cathode.txt as cathode_path.
Automatically detect charge/discharge direction and I*R sign.
```

## MCP Tools

The server exposes these tools:

- `preview_dual_water_tank_data`: preview one dataset and return inferred columns, charge/discharge direction, capacity span, voltage range, and current estimate.
- `fit_dual_water_tank`: fit one file or one workbook sheet and write `result.json` plus `fitted_curve.csv`.
- `batch_fit_dual_water_tank`: fit all supported files in a folder, or fit a supplied file list, and write per-file outputs plus batch summaries.

## Tool Examples

Example MCP call for `preview_dual_water_tank_data`:

```json
{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx"
}
```

Example MCP call for `fit_dual_water_tank`:

```json
{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx",
  "direction": "auto",
  "resistance_sign": "auto"
}
```

Optional inputs for `fit_dual_water_tank`:

```json
{
  "data_file": "D:/data/cell.xlsx",
  "anode_path": "D:/data/anode.txt",
  "cathode_path": "D:/data/cathode.txt",
  "current": 65,
  "direction": "auto",
  "resistance_sign": "auto",
  "voltage_col": "B",
  "capacity_col": "C",
  "output_dir": "D:/desktop/dual water tank output/my_run"
}
```

Example MCP call for `batch_fit_dual_water_tank`:

```json
{
  "input_dir": "D:/my_battery_data",
  "direction": "auto",
  "resistance_sign": "auto"
}
```

## Model Sign Convention

The model keeps the original five parameters:

```text
[y0, Cp, x0, Cn, R]
```

Charge:

```text
y = y0 - Q / Cp
x = x0 + Q / Cn
V = Upos(y) - Uneg(x) + I * R
```

Discharge:

```text
y = y0 + Q / Cp
x = x0 - Q / Cn
V = Upos(y) - Uneg(x) - I * R
```

`I` is treated as a positive current magnitude. By default, `resistance_sign` is `auto`, so the tool fits both `+I*R` and `-I*R` for the detected direction and keeps the lower full-data RMSE. The selected sign and both candidate RMSE values are written to `resistance_sign_selection` in `result.json`.

Available resistance-sign modes:

```text
auto | physics | positive | negative | matlab
```

- `auto`: fit both `+I*R` and `-I*R`, then choose the lower full-data RMSE.
- `physics`: charge uses `+I*R`; discharge uses `-I*R`.
- `positive`: force `+I*R`.
- `negative`: force `-I*R`.
- `matlab`: always use `+I*R`, matching the executed objective function in the original MATLAB file.

The original MATLAB target function uses `+I*R` for the provided charge example, while one MATLAB comment says charge should use `-I*R`. Because the code and comment conflict, the MCP default is data-driven sign selection.

## Input Data Rules

Recommended full-cell data columns:

| Voltage | Capacity |
| --- | --- |
| `voltage_V` | `capacity_Ah` |

Headerless files are supported. The program scores numeric columns by whether they look like voltage and capacity:

- voltage-like columns usually have median values in a common battery voltage range and a reasonable voltage span;
- capacity-like columns usually have a meaningful span and are mostly monotonic;
- adjacent voltage/capacity columns get a bonus because this is common in cycler exports.

Charge/discharge detection normalizes capacity to move forward from zero, then compares the median voltage near the end against the median voltage near the beginning:

- voltage rising means `charge`;
- voltage falling means `discharge`;
- near-flat data falls back to a linear voltage-capacity slope.

The current magnitude can be provided explicitly with `current`. If it is omitted, the tool tries to parse C-rate from the file name. For example, `25C_0.1C.xlsx` is interpreted as `0.1C`; the temperature-like `25C` is ignored when a more plausible C-rate is present.

## Electrode OCV Files

The bundled test case includes matching electrode OCV files:

```text
test_cases/25C_0.1C/anode.txt
test_cases/25C_0.1C/cathode.txt
```

By default, the MCP uses these test-case electrode files so that a new user can immediately run the demo. For real experiments, pass `anode_path` and `cathode_path` if you want to use a different pair of half-cell OCV curves.

## Output Files

Each single-file fitting job outputs:

- `result.json`: fitted parameters, RMSE, sign selection, stoichiometry ranges, and derived values.
- `fitted_curve.csv`: capacity, measured voltage, modeled voltage, residual, electrode potentials, and `x/y` stoichiometry.

Batch jobs also output:

- `batch_summary.csv`: one-row summary for each fitted file.
- `batch_summary.json`: full batch summary with errors, if any.

If `output_dir` is not provided, final results are written to:

```text
Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/
```

The input data folder stays clean by default.

## Test Case

The repository includes one test case:

```text
test_cases/25C_0.1C/
```

Files:

- `25C_0.1C.xlsx`: full-cell voltage-capacity test data.
- `anode.txt`: anode half-cell OCV curve.
- `cathode.txt`: cathode half-cell OCV curve.

Quick preview:

```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

Quick fit:

```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

## Repository Layout

```text
dual_water_tank_mcp/          Python package and MCP server
test_cases/25C_0.1C/          Example full-cell dataset plus anode/cathode OCV files
references/original_resource/ Original MATLAB scripts, notes, and source references
examples/                     MCP configuration examples
Desktop/dual water tank output/ Generated results outside the repository
```

## Local Debugging

Run a quick preview:

```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

Run a quick fit without saving files:

```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx" --no-save --population-size 20 --generations 1 --max-points 100
```

Run the sign-diagnosis script:

```powershell
python scripts\diagnose_parameter_gap.py
```

Developer installation, only if you want to modify the code:

```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .
```

## License

The Python code in this repository is released under the Apache License 2.0. See `LICENSE`. Project attribution is listed in `NOTICE`.

Apache License 2.0 includes an explicit patent license and patent termination language. Reference materials under `references/original_resource/` may have their own copyright, patent, or usage terms. The Apache License 2.0 for this repository code does not change the ownership or licensing of those external/reference files.

---

# Dual Water Tank MCP for Battery Aging Mechanism Identification 中文

[English](#dual-water-tank-mcp-for-battery-aging-mechanism-identification) | [中文](#dual-water-tank-mcp-for-battery-aging-mechanism-identification-中文)

这是一个用于锂离子电池双水箱模型参数辨识的 MCP 服务。输入为充电/放电电压-容量数据，输出为双水箱模型参数、拟合曲线、误差、符号选择结果和批量汇总。它主要面向电池老化机理识别，例如容量损失、锂库存变化、正负极容量变化等参数分析。

项目保持两层结构：

- `dual_water_tank_mcp/`：核心模型代码，包括数据读取、列识别、充放电识别、模型计算、遗传算法拟合、批量输出和 CLI。
- `dual_water_tank_mcp/server.py`：MCP 薄接口层，只负责把核心函数暴露成 MCP 工具。

后续如果需要修正或改进模型，直接改 `dual_water_tank_mcp/` 下的核心代码，然后重启 MCP 服务即可。

## 功能

- 读取 `.xlsx`、`.xls`、`.csv`、`.txt`、`.tsv` 电池测试数据。
- 自动识别电压列和容量列。
- 根据电压趋势自动识别充电或放电。
- 自动处理正负极化学计量比 `y/x` 的充放电符号。
- 自动分别尝试 `+I*R` 和 `-I*R`，选择全数据 RMSE 更低的结果。
- 根据数据容量范围自动适配遗传算法容量上下限。
- 支持单文件拟合和批量拟合。
- 默认把最终结果输出到桌面文件夹。
- 可以作为 MCP server 被 Codex、Claude 等 agent 调用。

## 从 GitHub 到安装

如果项目已经上传到 GitHub，先克隆仓库：

```powershell
git clone <你的 GitHub 仓库地址>
cd dual-water-tank-mcp
```

如果已经有本地源码，直接进入项目根目录，例如：

```powershell
cd "D:\desktop\PSG\1.1 github\dual-water-tank-mcp"
```

需要 Python 3.10 或更高版本，建议同时安装 Git。

检查版本：

```powershell
python --version
git --version
```

可以直接使用仓库自带的一键 MCP 启动脚本。第一次运行会自动创建 `.venv` 并安装依赖：

```powershell
.\run_mcp.cmd
```

MCP 客户端也应该调用这个脚本。用户不需要修改模型代码、Python 文件或 MCP server 文件。

命令行预览示例：

```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

命令行拟合示例：

```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

## 启动 MCP

在 Codex、Claude Desktop、Claude Code 或其他 MCP 客户端中添加这个 MCP server。

Windows MCP 配置示例：

```json
{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "C:\\path\\to\\dual-water-tank-mcp\\run_mcp.cmd",
      "args": []
    }
  }
}
```

macOS/Linux MCP 配置示例：

```json
{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "/path/to/dual-water-tank-mcp/run_mcp.sh",
      "args": []
    }
  }
}
```

macOS/Linux 需要先给脚本执行权限：

```bash
chmod +x run_mcp.sh dual-water-tank.sh
```

仓库里也提供了可复制修改的配置文件：

- `examples/mcp_config_windows.json`
- `examples/mcp_config_macos_linux.json`

配置完成后，在 MCP 客户端中刷新或重启连接。看到 `dual-water-tank-model` 可用，就说明已经连上。

## MCP 已连接后怎么用

连接成功以后，不需要手动运行 Python 或命令行脚本。你只需要在支持 MCP 的客户端里提出需求，客户端会调用本项目暴露的 MCP 工具。

推荐流程：

1. 如果不确定输入数据格式，先调用 `preview_dual_water_tank_data`。
2. 单文件拟合调用 `fit_dual_water_tank`。
3. 批量拟合调用 `batch_fit_dual_water_tank`。
4. 打开桌面输出目录里的 `result.json`、`fitted_curve.csv` 或 `batch_summary.csv` 查看结果。

最终结果默认输出到桌面：

```text
Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/
```

在作者的 Windows 电脑上，通常是：

```text
D:\desktop\dual water tank output\
```

MCP 返回结果里也会包含 `output_dir`、`curve_csv`、`result_json` 等路径。

用户可以这样对 MCP 客户端说：

```text
请使用 dual-water-tank MCP 预览 test_cases/25C_0.1C/25C_0.1C.xlsx。
```

```text
请使用 dual-water-tank MCP 拟合 test_cases/25C_0.1C/25C_0.1C.xlsx，并把最终结果保存到桌面。
```

```text
请使用 dual-water-tank MCP 批量拟合 D:\my_battery_data 里面的所有 Excel 文件。
最终结果输出到桌面的 dual water tank output 文件夹。
```

```text
请使用 dual-water-tank MCP 拟合 D:\data\cell.xlsx。
anode_path 使用 D:\data\anode.txt，cathode_path 使用 D:\data\cathode.txt。
自动判断充放电方向和 I*R 符号。
```

## MCP 工具

MCP server 暴露这些工具：

- `preview_dual_water_tank_data`：预览一个数据集，返回自动识别到的列、充放电方向、容量范围、电压范围和电流估计。
- `fit_dual_water_tank`：拟合一个文件或一个工作表，输出 `result.json` 和 `fitted_curve.csv`。
- `batch_fit_dual_water_tank`：拟合一个文件夹或文件列表，输出每个文件的结果和批量汇总。

## 工具调用示例

`preview_dual_water_tank_data` 示例：

```json
{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx"
}
```

`fit_dual_water_tank` 示例：

```json
{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx",
  "direction": "auto",
  "resistance_sign": "auto"
}
```

`fit_dual_water_tank` 可选参数示例：

```json
{
  "data_file": "D:/data/cell.xlsx",
  "anode_path": "D:/data/anode.txt",
  "cathode_path": "D:/data/cathode.txt",
  "current": 65,
  "direction": "auto",
  "resistance_sign": "auto",
  "voltage_col": "B",
  "capacity_col": "C",
  "output_dir": "D:/desktop/dual water tank output/my_run"
}
```

`batch_fit_dual_water_tank` 示例：

```json
{
  "input_dir": "D:/my_battery_data",
  "direction": "auto",
  "resistance_sign": "auto"
}
```

## 模型符号约定

模型保留原始五个参数：

```text
[y0, Cp, x0, Cn, R]
```

充电：

```text
y = y0 - Q / Cp
x = x0 + Q / Cn
V = Upos(y) - Uneg(x) + I * R
```

放电：

```text
y = y0 + Q / Cp
x = x0 - Q / Cn
V = Upos(y) - Uneg(x) - I * R
```

`I` 按正的电流大小输入。默认 `resistance_sign` 为 `auto`，工具会对检测到的方向分别拟合 `+I*R` 和 `-I*R`，选择全数据 RMSE 更低的结果。最终选择的符号和两个候选的 RMSE 会写入 `result.json` 的 `resistance_sign_selection` 字段。

可选的电阻符号模式：

```text
auto | physics | positive | negative | matlab
```

- `auto`：同时拟合 `+I*R` 和 `-I*R`，选择全数据 RMSE 更低的结果。
- `physics`：充电用 `+I*R`，放电用 `-I*R`。
- `positive`：强制 `+I*R`。
- `negative`：强制 `-I*R`。
- `matlab`：始终使用 `+I*R`，对应原 MATLAB 目标函数实际执行的公式。

原 MATLAB 目标函数在给定充电示例中实际使用 `+I*R`，但脚本注释中有一处写成充电 `-I*R`。因为代码和注释冲突，所以本 MCP 默认使用数据驱动的符号选择。

## 输入数据规则

推荐全电池数据至少包含两列：

| 电压 | 容量 |
| --- | --- |
| `voltage_V` | `capacity_Ah` |

没有表头也可以。程序会根据数值特征识别电压列和容量列：

- 电压列通常在常见电池电压范围内，并且有合理电压跨度。
- 容量列通常有明显跨度，并且大体单调。
- 相邻的电压/容量列会获得额外评分，因为这符合常见测试设备导出格式。

充放电识别会先把容量归一化为从零向前增加，再比较末端电压和起始电压：

- 电压整体上升：`charge`
- 电压整体下降：`discharge`
- 近似平坦：退回到线性电压-容量斜率判断

电流大小可以通过 `current` 显式传入。如果不传，工具会尝试从文件名解析 C-rate。例如 `25C_0.1C.xlsx` 会识别为 `0.1C`，温度含义的 `25C` 不会被当成倍率。

## 半电池 OCV 文件

自带测试案例包含匹配的半电池 OCV 文件：

```text
test_cases/25C_0.1C/anode.txt
test_cases/25C_0.1C/cathode.txt
```

默认情况下，MCP 使用这套测试案例里的电极文件，方便新用户下载后立刻跑通 demo。真实实验中，如果要使用自己的半电池 OCV 曲线，请传入 `anode_path` 和 `cathode_path`。

## 输出文件

单文件拟合会输出：

- `result.json`：拟合参数、RMSE、符号选择、化学计量比范围和派生参数。
- `fitted_curve.csv`：容量、实测电压、模型电压、残差、正负极电势和 `x/y`。

批量任务额外输出：

- `batch_summary.csv`：每个拟合文件一行摘要。
- `batch_summary.json`：完整批量结果和错误信息。

如果不传 `output_dir`，最终结果会写到：

```text
Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/
```

默认不会污染输入数据文件夹。

## 测试案例

仓库包含一个测试案例：

```text
test_cases/25C_0.1C/
```

文件：

- `25C_0.1C.xlsx`：全电池电压-容量测试数据。
- `anode.txt`：负极半电池 OCV 曲线。
- `cathode.txt`：正极半电池 OCV 曲线。

快速预览：

```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

快速拟合：

```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

## 仓库结构

```text
dual_water_tank_mcp/          Python package and MCP server
test_cases/25C_0.1C/          Example full-cell dataset plus anode/cathode OCV files
references/original_resource/ Original MATLAB scripts, notes, and source references
examples/                     MCP configuration examples
Desktop/dual water tank output/ Generated results outside the repository
```

## 本地调试

快速预览：

```powershell
.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"
```

快速拟合但不保存文件：

```powershell
.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx" --no-save --population-size 20 --generations 1 --max-points 100
```

运行符号诊断脚本：

```powershell
python scripts\diagnose_parameter_gap.py
```

开发者安装方式，仅在需要修改代码时使用：

```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .
```

## 许可证

本仓库 Python 代码使用 Apache License 2.0，见 `LICENSE`。项目署名见 `NOTICE`。

Apache License 2.0 包含明确的专利授权和专利终止条款。`references/original_resource/` 中的参考资料可能有其原始版权、专利或使用限制。本仓库代码使用 Apache License 2.0 不会改变这些外部参考资料的权属或许可状态。