dual-water-tank-aging-identification-mcp

# 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 不会改变这些外部参考资料的权属或许可状态。