{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Electrode balancing\n",
"\n",
"In this notebook we provide an example on how to perform electrode balancing for a half cell. The goal is to find the conversion from capacity to stoichiometry for a given measured electrode, by using a reference dataset for which voltage is known as a function of the stoichiometry.\n",
"\n",
"## Set the environment\n",
"We start by installing and importing the necessary libraries."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"/Users/engs2510/Documents/Git/PyBOP/.nox/notebooks-overwrite/bin/python3: No module named pip\r\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Note: you may need to restart the kernel to use updated packages.\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"/Users/engs2510/Documents/Git/PyBOP/.nox/notebooks-overwrite/bin/python3: No module named pip\r\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Note: you may need to restart the kernel to use updated packages.\n"
]
}
],
"source": [
"%pip install --upgrade pip ipywidgets -q\n",
"%pip install pybop -q\n",
"\n",
"# Import the necessary libraries\n",
"import numpy as np\n",
"import pandas as pd\n",
"import pybamm\n",
"\n",
"import pybop\n",
"\n",
"pybop.PlotlyManager().pio.renderers.default = \"notebook_connected\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Load the data\n",
"We start by loading the data, which is available in the [pybamm-param repository](https://www.github.com/paramm-team/pybamm-param). We load half cell data (which is the versus stoichiometry and thus the reference one) and the three-electrode data (which is the one we want to balance). The measurements are for an LGM50 cell, with a graphite and SiOx negative electrode and an NMC811 positive electrode."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# .csv files are uploaded for Anode\n",
"base_url = \"https://raw.githubusercontent.com/paramm-team/pybamm-param/develop/pbparam/input/data/\"\n",
"reference_data = pd.read_csv(\n",
" base_url + \"anode_OCP_2_lit.csv\"\n",
") # half cell lithiation data\n",
"measured_data = pd.read_csv(\n",
" base_url + \"anode_OCP_3_lit.csv\"\n",
") # three-electrode full cell lithiation data\n",
"\n",
"# Drop negative capacity values\n",
"measured_data = measured_data.drop(\n",
" measured_data[measured_data[\"Capacity [A.h]\"] < 0].index\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Setup model, parameters and data\n",
"\n",
"To perform the electrode balancing, we will use an ECM model consisting only of the OCV component. To achieve that, we will set the resistance to zero. We will also change the upper and lower voltage limits to ensure we do not hit them during the optimisation. For the OCV, we will use the reference data we just loaded."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"def ocv(sto):\n",
" return pybamm.Interpolant(\n",
" reference_data[\"Stoichiometry\"].to_numpy(),\n",
" reference_data[\"Voltage [V]\"].to_numpy(),\n",
" sto,\n",
" \"reference OCV\",\n",
" )\n",
"\n",
"\n",
"parameter_set = pybop.empirical.Thevenin().default_parameter_values\n",
"parameter_set.update(\n",
" {\n",
" \"Initial SoC\": 0,\n",
" \"Entropic change [V/K]\": 0,\n",
" \"R0 [Ohm]\": 0,\n",
" \"Lower voltage cut-off [V]\": 0,\n",
" \"Upper voltage cut-off [V]\": 5,\n",
" \"Open-circuit voltage [V]\": ocv,\n",
" }\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we can just assemble the model. We use the `Thevenin` model with no RC elements:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"model = pybop.empirical.Thevenin(\n",
" parameter_set=parameter_set, options={\"number of rc elements\": 0}\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We define the parameters we want to optimise. In this case, we need to optimise the initial SoC and the cell capacity, which will be needed to convert the capacity to stoichiometry."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"parameters = pybop.Parameters(\n",
" pybop.Parameter(\n",
" \"Initial SoC\",\n",
" prior=pybop.Uniform(0, 0.5),\n",
" bounds=[0, 0.5],\n",
" ),\n",
" pybop.Parameter(\n",
" \"Cell capacity [A.h]\",\n",
" prior=pybop.Uniform(0.01, 50),\n",
" bounds=[0.01, 50],\n",
" ),\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we need to assemble the dataset. This is a bit tricky, as we are doing an electrode balancing but in theory we are solving a discharge problem. However, we can use that if we impose a 1 A discharge, the time (in hours) will be the same as the capacity in (in Ah). Therefore, we can treat time as capacity, we just need to scale it to the correct units (as PyBaMM models take time in seconds). Note that in this case current is negative as we are lithiating the electrode."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Form dataset\n",
"dataset = pybop.Dataset(\n",
" {\n",
" \"Time [s]\": measured_data[\"Capacity [A.h]\"].to_numpy() * 3600,\n",
" \"Current function [A]\": -np.ones(len(measured_data[\"Capacity [A.h]\"])),\n",
" \"Voltage [V]\": measured_data[\"Voltage [V]\"].to_numpy(),\n",
" }\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Identifying the parameters\n",
"\n",
"Once we have defined the model, parameters and dataset, we can just proceed to the optimisation. We define the `FittingProblem` and the cost, for which we choose the sum squared error."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"problem = pybop.FittingProblem(model, parameters, dataset)\n",
"cost = pybop.SumSquaredError(problem)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We choose the `SciPyMinimize` optimiser and we solve the optimisation problem. We can then print and plot the results."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/Users/engs2510/Documents/Git/PyBOP/.nox/notebooks-overwrite/lib/python3.12/site-packages/pybamm/solvers/base_solver.py:762: SolverWarning:\n",
"\n",
"Explicit interpolation times not implemented for CasADi solver with 'safe' mode\n",
"\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Initial parameters: [2.31587786e-02 4.62292192e+01]\n",
"Estimated parameters: [0.00923318 4.9721263 ]\n"
]
}
],
"source": [
"optim = pybop.SciPyMinimize(cost, max_iterations=300)\n",
"x, final_cost = optim.run()\n",
"print(\"Initial parameters:\", optim.x0)\n",
"print(\"Estimated parameters:\", x)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"pybop.quick_plot(problem, problem_inputs=x, title=\"Optimised Comparison\");"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Converting capacity to stoichiometry\n",
"\n",
"However, the whole goal of the electrode balancing was to convert capacity to stoichiometry, so how can we do that? To convert capacity $Q$ to stoichiometry $x$, we can simply use the following equation:\n",
"\n",
"$$\n",
"x = \\pm \\frac{Q}{Q_{\\text{cell}}} + x_0.\n",
"$$\n",
"Here, the choice of plus and minus depends on whether we are lithiating or delithiating the electrode (it is related to whether the current in the data is positive or negative). $Q_{\\text{cell}}$ is the cell capacity and $x_0$ is the initial stoichiometry, which are the two parameters we fitted. We can now convert the measured data and plot it against the reference data to check that the electrode balancing was correct."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from plotly import graph_objects as go\n",
"\n",
"fig = go.Figure(\n",
" layout=go.Layout(title=\"OCP Balance\", width=800, height=600),\n",
")\n",
"\n",
"fig.add_trace(\n",
" go.Scatter(\n",
" x=reference_data[\"Stoichiometry\"],\n",
" y=reference_data[\"Voltage [V]\"],\n",
" mode=\"lines\",\n",
" name=\"reference\",\n",
" ),\n",
")\n",
"\n",
"Q = x[1]\n",
"sto_0 = x[0]\n",
"\n",
"sto = measured_data[\"Capacity [A.h]\"].to_numpy() / Q + sto_0\n",
"\n",
"fig.add_trace(\n",
" go.Scatter(x=sto, y=measured_data[\"Voltage [V]\"], mode=\"lines\", name=\"fitted\"),\n",
")\n",
"\n",
"# Update axes labels\n",
"fig.update_xaxes(title_text=\"Stoichiometry\")\n",
"fig.update_yaxes(title_text=\"Voltage [V]\")\n",
"\n",
"# Show figure\n",
"fig.show()"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "env",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.4"
}
},
"nbformat": 4,
"nbformat_minor": 2
}