{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"# Part I: Introduction to Battery Modelling with BattMo\n",
"\n",
" **Dr. Sridevi Krishnamurthi** and **Dr. Simon Clark,** *SINTEF AS, Battery Technology, Trondheim, Norway*\n",
"\n",
"\n",
"This guide provides an introductory resource for readers who would like to learn about lithium\\-ion batteries, battery modelling, or both! Starting from the basics of how a Li\\-ion battery works, we go step\\-by\\-step, introducing new modelling concepts at each level. After completing this guide, readers should have a working knowledge of Li\\-ion battery design principles and be able to simulate a variety of designs under different conditions.\n",
"\n",
"\n",
"The guide is divided into four parts:\n",
"\n",
"- **Part I: Introduction to Battery Modelling with BattMo** introduces the basic concepts of Li\\-ion battery design and operation. This part introduces the types of simulations that BattMo can perform and provides some examples demonstrating simple design modifications\n",
"- **Part II: The DFN Model overview** explains how the model operates and examines how the model parameters influence cell capacities.\n",
"- **Part III: Engineering** use cases delves into the cell design problems such as electrode balancing, rate capability analysis\n",
"- **Part IV: Ageing mechanisms and cell engineering** discusses the SEI and Lithium plating issues as part of the ageing mechanism, we also intoduce P4D models for dealing with complex geometries.\n",
"\n",
"*Please run 'startupBattMo.M' present in the home folder before running this notebook, this loads all the neccessary modules for running the simulations.*\n",
"\n",
"\n",
"\n",
"## Part I: Table of Contents\n",
" [**1. Lithium\\-Ion Battery Basics**](#-textbf-1-lithium-ion-battery-basics-)\n",
"\n",
" [**1.1 Cell Components**](#-textbf-1-1-cell-components-)\n",
"\n",
" [**1.2 Working Principle**](#-textbf-1-2-working-principle-)\n",
"\n",
" [1.3 Battery Properties](#1-3-battery-properties)\n",
"\n",
" [**1.4 Operational Protocols**](#-textbf-1-4-operational-protocols-)\n",
"\n",
" [**2. Modelling with BattMo**](#-textbf-2-modelling-with-battmo-)\n",
"\n",
" [**2.1 P2D/P3D/P4D Models**](#-textbf-2-1-p2d-p3d-p4d-models-)\n",
"\n",
" [**Example 1. Build and Visualize the Battery Grid in 3D**](#-textbf-example-1-build-and-visualize-the-battery-grid-in-3d-)\n",
"\n",
" [**Example 2. Constant Current Discharging of a Gr\\-NMC Battery Cell in 1D geometry**](#-textbf-example-2-constant-current-discharging-of-a-gr-nmc-battery-cell-in-1d-geometry-)\n",
"\n",
" [**Example 3. Post\\-Processing Voltage Curves**](#-textbf-example-3-post-processing-voltage-curves-)\n",
"\n",
" [**2.2 Influence of structural and material parameters on the capacity**](#-textbf-2-2-influence-of-structural-and-material-parameters-on-the-capacity-)\n",
"\n",
" [**Example 4. Increasing the thickness of the negative electrode / positive electrode**](#-textbf-example-4-increasing-the-thickness-of-the-negative-electrode-positive-electrode-)\n",
"\n",
" [**Example 5. Increasing the effective density of electrode coating**](#-textbf-example-5-increasing-the-effective-density-of-electrode-coating-)\n",
"\n",
" [**Example 6. Influence of material chemistry on capacity**](#-textbf-example-6-influence-of-material-chemistry-on-capacity-)\n",
"\n",
" [3. Summary](#3-summary)\n",
"\n",
" [**4. References**](#-textbf-4-references-)\n",
"\n",
"\n",
"\n",
"Rechargeable Li\\-ion batteries have transformed our lives. With the current focus on electrifying the mobility sector and the growing need to support intermittent renewable energy sources, there is much to learn about batteries and the materials that make them. The goal is to develop batteries with higher energy density and improved safety, manufactured in a sustainable manner.\n",
"\n",
"\n",
"BattMo is a powerful tool for conducting battery simulations, aiding in the understanding and optimization of battery performance. It utilizes continuum scale PXD (pseudo\\-X\\-dimensional) simulations based on the Doyle\\-Fuller\\-Newman (DFN) model. By providing material and design parameters for the various components of the battery, BattMo can simulate how key quantities like voltage, current, concentration, and temperature change in the battery as it is operated. When simulated over many charge\\-discharge cycles, BattMo can also predict capacity losses that occur due to degradation. It supports simulations from simple 1D grids to complex multi\\-layer pouch cells and jelly rolls, incorporating thermal effects and degradation mechanisms. Its modular design facilitates easy switching between different cell chemistries, making BattMo versatile for applications in battery research and development.\n",
"\n",
"\n",
"For a detailed overview of the modelling approach and the DFN model, please refer to **Part II** of this modelling guide.\n",
"\n",
"## **1. Lithium\\-Ion Battery Basics**\n",
"\n",
"Let's begin by exploring some lithium\\-ion (Li\\-ion) battery basics. The battery cell consists of three main components: **a negative electrode**, **a positive electrode**, and **an electrolyte**.\n",
"\n",
"\n",
"Each electrode contains an **active material** that stores energy by incorporating lithium into its chemical structure through an electrochemical reaction like intercalation or alloying. There are a variety of materials that could be used for active materials, but typical Li\\-ion batteries use graphite for the negative electrode and a lithiated transition metal oxide for the positive electrode. The active materials act as a stable host structure for storing Li\\-ions. You can think of them like shelves and the Li\\-ions like boxes. Boxes can be moved from one shelf to another, but the shelf itself remains stable.\n",
"\n",
"\n",
"The electrodes are linked by an electrolyte that serves as a type of \"highway\" for transporting Li+ ions, and it typically consists of a lithium salt like LiPF6 dissolved in a carbonate\\-based solvent. The electrolyte must support the fast transport of ions, while also blocking the transport of electrons. The electronically insulating nature of the electrolyte forces the electrons through an external circuit, providing electrical energy to connected devices. We will look at the exact types of materials used for these components later.\n",
"\n",
"\n",
"A schematic overview of this process for a graphite \\- lithium cobalt oxide (LCO) cell is shown in **Figure 1**. The basic operating principle of the Li\\-ion battery is sometimes refered to as a \"rocking\\-chair\" mechanism, because the rock back\\-and\\-forth between the positive and negative electrodes. When the Li\\-ion battery cell is charged, an externally applied voltage drives Li+ to de\\-intercalate from the positive electrode into the electrolyte where they are transported via diffusion\\-migration to the negative electrode. Electrons are released from the oxidation of cobalt in the positive electrode (Co3+ \\-> Co4+), travel through the external circuit, and recombine with lithium in the negative electrode \\[1\\]. When the Li\\-ion battery cell is discharged, the process is reversed. Driven by the change in the Gibbs Free Energy, Li is oxidized in the negative electrode and is transported across the electrolyte where it combines with electrons from the external circuit and is intercalated back into the positive electrode active material.\n",
"\n",
"
\n",
" \n",
"
\n",
"\n",
"\n",
" **Figure 1: A schematic representation of a typical Li\\-ion cell during charging.** *The Li\\-ion cell is a stack of a negative electrode, a positive electrode, and a Li+ containing electrolyte. The Li\\-ion cell works on the principle of intercalation, where Li+ ions are inserted into vacant sites in the electrode active materials. While a variety of active materials could be used for the electrodes, typical Li\\-ion batteries use graphite for the negative electrode and a lithiated transition metal oxide like LiCoO2 for the positive electrode \\[1\\].*\n",
"\n",
"### **1.1 Cell Components**\n",
"\n",
"Lithium\\-ion battery electrodes are porous composite structures that consist of a mixture of **active material**, **binder**, and **conducting additives** applied as a coating on a foil **current collector**. When the cell is assembled, the electrolyte is injected into the device and fills up the pores in the electrode, creating interfaces with the active materials where the electrochemical reactions can take place.\n",
"\n",
"
\n",
" \n",
"
\n",
"\n",
"\n",
"**Figure 2:** **Cross\\-sectional layout of a LIB with two porous electrodes and a porous separator.** *The active materials in the anode (negative electrode) and cathode (positive electrode) are simplified to spherical particles with gray and orange colors. The conducting additives are simplified to black small particles \\[6\\].*\n",
"\n",
"\n",
"**Positive Electrode**\n",
"\n",
"\n",
"Active materials for positive electrodes in Li\\-ion batteries are lithium transition metal oxides, which come in a variety of different compositions and crystal structures. The most common oxides NMC (lithium nickel manganese cobalt oxide), LFP (lithium iron phosphate), LMO (Llithium manganese oxide), LNO (lithium nickel oxide) LCO (lithium cobalt oxide) and NCA (lithium nickel cobalt aluminium oxide). Because these materials differ in energy density, cycling stability, commercial availability, and environmental impact, selecting the appropriate one for each application is crucial. For a thorough review of positive electrode materials, the reader can refer [here](https://www.nature.com/articles/s41467-020-15355-0).\n",
"\n",
"
\n",
" \n",
"
\n",
"\n",
"\n",
" **Fig. 3:** .**Crystal structures of transition metal oxides used as positive electrode active materials:** *(a) layered LiMO2 (M = Co, Ni, Mn, etc.), (b) spinel LiMn2O4, (c) NASICON\\-type Li3Fe2(PO4)3, and (d) olivine LiFePO4. The transition metal octahedra, MO6, are represented in blue, while the polyanion tetrahedra, XO4, are represented in brown. Li\\-ions are shown in turquoise\\[7\\].*\n",
"\n",
"\n",
"**Negative Electrode**\n",
"\n",
"\n",
"Graphite is the most common active material for the negative electrode in Li\\-ion cells, although alternative materials like silicon (Si) and lithium titanate (LTO) are used for some specialty applications. Early versions of rechargeable lithium batteries used lithium metal as the negative electrode active material due to its high specific capacity. However, ltihium metal can form dendritic or needle\\-like structures during charging, which can cause to safety\\-critical internal short\\-circuits. Nonetheless, research and development of lithium metal systems with advanced electrolytes continues as a way to increase the specific energy / energy density of rechargeable batteries. For a review on on carbon based negative electrode materials, one can refer [here](https://www.sciencedirect.com/science/article/pii/S2352152X23001135).\n",
"\n",
"\n",
"**Electrolyte**\n",
"\n",
"\n",
"The electrolyte serves as the medium for Li\\-ion conduction and can be either solid or liquid. Liquid electrolytes typically consist of lithium salts dissolved in an organic solvent, with common examples being LiPF6, LiBF4, and LiClO4. Commonly used solvents are ethylene carbonate, dimethyl carbonate, and diethyl carbonate. A good electrolyte, whether solid or liquid must possess high ionic conductivity, low electronic conductivity, support high voltages, and remain stable across a wide temperature range. For a review on liquid electrolytes, one can refer [here](https://onlinelibrary.wiley.com/doi/full/10.1002/smll.202205315).\n",
"\n",
"\n",
"**Separator**\n",
"\n",
"\n",
"The separator is typically made from polymer materials such as polyethylene (PE) or polypropylene (PP). It serves as a porous medium allowing lithium ions to move between the positive and negative electrodes. While the separator itself does not participate in the electrochemical reactions, it can influence the safety, power density, and cycle life of the battery.\n",
"\n",
"### **1.2 Working Principle**\n",
"\n",
"During charging, lithium ions (Li+) are deintercalated from the positive electrode (in this example, NMC) and migrate to the negative electrode (in this example, graphite) through the electrolyte. Concurrently, electrons are driven through the external circuit from NMC to graphite. During discharging, the reverse process occurs: lithium ions migrate back from the negative electrode (graphite) to the positive electrode (NMC) through the electrolyte, while electrons flow from graphite to NMC through the external circuit.\n",
"\n",
"\n",
" **At the positive electrode:**\n",
"\n",
"\n",
" $\\textrm{Li}{\\textrm{[NiMnCo]O}}_2 \\overset{\\textrm{charge}}{\\underset{\\textrm{discharge}}{\\rightleftharpoons} } {\\textrm{Li}}_{(1-x)} {\\textrm{[NiMnCo]O}}_2 +x{\\textrm{Li}}^+ +x{\\textrm{e}}^-$ (1.1)\n",
"\n",
"\n",
"**At the negative electrode:**\n",
"\n",
"\n",
" ${\\textrm{C}}_6 +y{\\textrm{Li}}^+ +{\\textrm{e}}^- \\overset{\\textrm{charge}}{\\underset{\\textrm{discharge}}{\\rightleftharpoons} } {\\textrm{Li}}_y {\\textrm{C}}_6$ (1.2)\n",
"\n",
"\n",
"**The overall cell reaction:**\n",
"\n",
"\n",
" ${\\textrm{[LiNiMnCo]O}}_2 +{\\textrm{C}}_6 \\overset{\\textrm{charge}}{\\underset{\\textrm{discharge}}{\\rightleftharpoons} } +{\\textrm{Li}}_{1-x} {\\textrm{[NiMnCo]O}}_2 +{\\textrm{Li}}_y {\\textrm{C}}_6$ (1.3)\n",
"\n",
"\n",
"The system is at its lowest energy when the Li\\-ions are in the positive electrode, during discharge, the Li ions migrate from the negative electrode to the positive electrode and the potential difference is released as energy. A detailed thermodynamic description will be presented in part 2 of the guide.\n",
"\n",
"### 1.3 Battery Properties\n",
"\n",
"A good battery should posess high energy density, ensuring it can store a significant amount of energy relative to its size and weight. Additionally, it should maintain a long cycle life, allowing it to endure numerous charge and discharge cycles without significant degradation. Minimal energy loss during these cycles is crucial, ensuring efficient energy usage and prolonged operational efficiency.\n",
"\n",
"\n",
"Let's delve into essential terms and parameters crucial for understanding batteries and their simulation in BattMo. These help in evaluating and comparing battery performance and characteristics.\n",
"\n",
"\n",
"**Definitions:**\n",
"\n",
"- [Lower](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_534dd59c_904c_45d9_8550_ae9d2eb6bbc9) ([upper](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_6dcd5baf_58cd_43f5_a692_51508e036c88)) voltage limit:The minimum (maximum) allowable voltage. It is this voltage that generally defines the “empty” (\"full\") state of the battery, this is set as an input parameter in the simulation.The value depends on the cell chemistry.\n",
"- [C\\-Rate](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_e1fd84eb_acdb_4b2c_b90c_e899d552a3ee) (cycling rate): this is the rate at which a battery is discharged in relation to its maximum capacity. Specifically, a 1C rate signifies that the discharge current will exhaust the total battery capacity in 1 hour. The CRate chosen depends on your application, this is set as an input parameter in the simulation\n",
"- [State of Charge (SOC %)](https://w3id.org/emmo/domain/battery#battery_17591da0_34ec_41b9_b3c1_3a4446dc6f0a): ratio of the current battery capacity to its maximum capacity, this is set as an input parameter in the simulation\n",
"- [Open\\-Circuit Voltage](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_9c657fdc_b9d3_4964_907c_f9a6e8c5f52b) (OCV): The voltage between the positive electrode and the negative electrode with no external load, to calculate this in BattMo,one can use a very small charge/discharge current, a CRate of C/20. OCV curves are typically plotted as voltage versus state of charge (SOC), the curves depend on the chemistry of the cell.\n",
"\n",
"**Cell Properties:**\n",
"\n",
"- [Capacity](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_791c1915_a791_4450_acd8_7f94764743b5) / Ah: electric charge which a cell or battery can deliver under specified discharge conditions, calculated as a product of discharge current and discharge time. Increasing the CRate decreases the capacity due to increasing internal losses.\n",
"- [Nominal Capacity](https://w3id.org/emmo/domain/battery#battery_fb9baf9b_680e_493e_a755_da9bb1fc9fae) / Ah: the rated capacity that is representative of the typical value associated with a cell as stated by the manufacturer\n",
"- [Theoretical Capacity](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_b7781ebc_90a7_4f19_997f_aed28dee1b01) / Ah: maximum possible charge, a cell can store, it is a fixed value determined by the amount and type of active material used in the electrodes.\n",
"- [Energy](https://w3id.org/emmo/domain/battery#battery_87bb15ff_4fc2_4929_9938_0b31d9166001) / Wh: calculated as the product of capacity and the average discharge voltage when discharged at a specific C\\-rate,Increasing the CRate decreases the energy.\n",
"- [Energy Density](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_4aa1b96e_44a0_4b1a_a0ac_723d0223d80b) / Wh/L: calculated as the energy divided by the volume of the cell\n",
"- [Specific Energy](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_5e4490b8_c1dd_4e00_980b_c484e1bf4904) / Wh/kg: calculated as the energy divided by the mass of the cell\n",
"- [Round\\-Trip Efficiency](https://w3id.org/emmo/domain/electrochemistry#electrochemistry_79198264_cdf5_4fc3_8bcf_e5140a52547a): ratio of the energy released during discharge to the energy stored during charge. This parameter indicates how effectively a battery converts stored energy into usable energy.\n",
"\n",
"### **1.4 Operational Protocols**\n",
"\n",
"In BattMo, we set the protocols for the charging and discharging of the cell using the [control model schema](https://battmoteam.github.io/BattMo/controlinput.html#control-models). We discuss the basic protocols here:\n",
"\n",
"\n",
"- **Constant Current Discharging.** During discharge, a constant current (CC) based on the chosen C\\-rate is drawn from the cell until the voltage reaches the minimum cut\\-off voltage (lowerCutoffVoltage) of the cell.\n",
"- **Constant Current Constant Voltage Charging.** A Li\\-ion battery is typically charged using a constant current/constant voltage protocol (CC\\-CV). This means the battery is initially charged at a constant current until it reaches a maximum voltage (upperCutoffVoltage). Once this voltage is reached, the protocol switches to maintaining a constant voltage between the terminals while the charging current gradually decreases.\n",
"\n",
"## **2. Modelling with BattMo**\n",
"\n",
"BattMo comes with several default material and cell parameter sets; for more details, refer [here](https://github.com/BattMoTeam/BattMo/tree/main/ParameterData/ParameterSets). Users can also input their own parameterization data. BattMo uses the JSON (JavaScript Object Notation) format to manage input parameters. This allows you to easily save, document, and share complete parameter sets from specific simulations. If you are new to JSON, you can learn more about it [here](https://www.w3schools.com/js/js_json_intro.asp).\n",
"\n",
"\n",
"For the rest of this guide, we will use a starter JSON file, [sample\\_input.json](https://github.com/BattMoTeam/BattMo/blob/main/Examples/JsonDataFiles/sample_input.json) that describes a lithium nickel manganese cobalt oxide (NMC 811) \\- graphite cell \\[2\\] with LiPF6 \\[3\\] as the electrolyte, in a 1D cell according to BattMo['s JSON input specification](https://battmoteam.github.io/BattMo/json.html#json-input-specification).\n",
"\n",
"\n",
"This sample\\_input.json file contains all the information needed to run the simulation. These parameters are neatly arranged into structured schemas. Unless otherwise specified, BattMo uses [SI base units](https://www.nist.gov/si-redefinition/definitions-si-base-units) for physical quantities.\n",
"\n",
"\n",
"**Input schema:**\n",
"\n",
"- A schema for the [**geometry**](https://battmoteam.github.io/BattMo/geometryinput.html#batterygeneratorp2d) **,** contains the dimensions of the whole cell and the different components within the cell.\n",
"- A schema for the [**battery cell material parameters**](https://battmoteam.github.io/BattMo/json.html#material-parameters) **,** contains material parameters for the NMC \\- Graphite cell sourced from the literature.\n",
"- A schema for the **initialization of the state of the battery,** specifies the initial state of the battery, including the initial state of charge (SOC).\n",
"- A schema for the [**control model**](https://battmoteam.github.io/BattMo/controlinput.html#control-models), defines the charging and discharging protocols,\n",
"- A schema for the [**time stepping**](https://battmoteam.github.io/BattMo/json.html#time-stepping-parameters)**,**\n",
"- A schema for the [**solver parameters**](https://battmoteam.github.io/BattMo/json.html#time-stepping-parameters) **,** specifies the parameters for the numerical solver used in the simulation.\n",
"- A schema for the [**output specification**](https://battmoteam.github.io/BattMo/json.html#output-parameters)\n",
"\n",
"### **2.1 P2D/P3D/P4D Models**\n",
"\n",
"As previously mentioned, BattMo utilizes the DFN model, which can be applied across different grid dimensions, ranging from P2D to P4D. The P2D model simulates battery properties along the thickness direction on a macroscopic scale while neglecting in\\-plane variations, essentially representing a 1D geometry, hence the term \"pseudo\\-2D.\" The equations governing the P2D model will be detailed in the second part of the modelling guide. While the P2D model provides a sufficient approximation in many cases, it cannot capture the full complexity of a real battery cell. To address this, the P3D/P4D models incorporate additional spatial dimensions for higher resolution. However, this increased resolution also results in longer computation times and higher computational demands.\n",
"\n",
"\n",
"BattMo offers grid generator functions that create battery geometries ranging from P2D to P4D and configures the grid for calculations according to the specified input dimensions and discretization parameters. For more details, see [here](https://battmoteam.github.io/BattMo/geometryinput.html).\n",
"\n",
"\n",
" \n",
"\n",
"\n",
"**Figure 4: A schematic representation of the P2D model.** *The cell is divided into three regions: the positive and negative electrodes, depicted as spherical particles, and the electrolyte, which fills the spaces between these particles. The figure illustrates the charging process, showing Li\\-ions deintercalating from the positive electrode particles and migrating to the negative electrode spheres \\[5\\].*\n",
"\n",
"#### **Example 1. Build and Visualize the Battery Grid in 3D**\n",
"\n",
"As the first step in modeling, let’s examine how a battery is represented in BattMo in a 3D grid. There are convenient built\\-in functions that help in parsing and visualizing data.\n",
"\n",
"- Load the default sample\\_input.json file using parseBattmoJson function.\n",
"- Merge the default file with a 3D Geometry File with mergeJsonStructs and visualise a 3D battery cell using plotBatteryGrid."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"source": [
"jsonstruct_default = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');\n",
"jsonstruct_3d_geometry = parseBattmoJson('Examples/JsonDataFiles/geometry3d.json');\n",
"jsonstruct_modified_3d = mergeJsonStructs({jsonstruct_3d_geometry , ...\n",
" jsonstruct_default});\n",
"model_3d = setupModelFromJson(jsonstruct_modified_3d);\n",
"plotBatteryGrid(model_3d);\n",
"axis tight\n",
"view(45,45)\n",
"set(gca, 'FontSize', 12)\n",
"legend('Position', [0.15, 0.8, 0.3, 0.1]);\n",
"title('3D Grid of a Battery Cell')"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"execution_count": 1,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### **Example 2. Constant Current Discharging of a Gr\\-NMC Battery Cell in 1D geometry**\n",
"\n",
"Now we are ready to run our first simulation. Refer to the `[sample_input.json](https://github.com/BattMoTeam/BattMo/blob/main/Examples/JsonDataFiles/sample_input.json)` for the exact input values. In summary, we will simulate the constant current (CC) discharge of an NMC\\-Graphite system, starting from a 100% state of charge (SOC) at a C\\-rate of 1. For the sake of the tutorial, we will make use of the 1D geometry and run P2D simulations, Let us visualise this system first,\n",
""
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"source": [
"jsonstruct_default = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');\n",
"model_1d = setupModelFromJson(jsonstruct_default);\n",
"\n",
"% use the plotBatteryGrid function to show the grid\n",
"plotBatteryGrid(model_1d);\n",
"axis tight\n",
"set(gca, 'FontSize', 12)\n",
"xlabel('Position / m')\n",
"title('Simplified 1D Grid of a Battery Cell')"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"execution_count": 2,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"Before running the actual simulation, the function `computeCellCapacity.m` processes the material parameters for the active materials in the electrodes, along with their mass fractions, to compute the maximum cell capacity (theoretical capacity). Using this capacity, the program sets the discharge current accordingly ( $\\textrm{capacity}=\\frac{1}{\\textrm{C}\\textrm{-}\\textrm{rate}}\\times \\textrm{discharge}\\;\\textrm{current}$ )\n",
"\n",
"\n",
"For this system, the typical lower and upper cutoff voltages are 2.4 V and 4.1 V, respectively. The simulation stops when the lower cut\\-off voltage is reached.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"source": [
"jsonstruct = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');% parse the sample_input.json\n",
"disp(jsonstruct.Control);% see the default values set in the control policy"
],
"outputs": [
{
"data": {
"text/plain": [
" controlPolicy: 'CCDischarge'\n",
" DRate: 1\n",
" lowerCutoffVoltage: 3\n",
" upperCutoffVoltage: 4.1000\n",
" dIdtLimit: 0.0100\n",
" dEdtLimit: 0.0100\n",
" rampupTime: 0.1000"
]
},
"metadata": {},
"execution_count": 3,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"The simulation can then be executed using the `runBatteryJson` function.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"source": [
"jsonstruct.TimeStepping.totalTime = (1./jsonstruct.Control.DRate) .* 3600 .* 1.2; % setting the total time of the simulation to be a little over 1 hour for a C-rate/D-rate of 1.\n",
"output_dis_NMC = runBatteryJson(jsonstruct);"
],
"outputs": []
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
" The output matrix returns among other things the model and the states. The model contains information about the setup of the model and initial conditions, while states contains the results of the simulation at each timestep. The model can also output the energy, energy density and specific energy of the system.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"source": [
"disp(output_dis_NMC);"
],
"outputs": [
{
"data": {
"text/plain": [
" model: [1x1 GenericBattery]\n",
" inputparams: [1x1 BatteryInputParams]\n",
" schedule: [1x1 struct]\n",
" initstate: [1x1 struct]\n",
" nonLinearSolver: [1x1 NonLinearSolver]\n",
" time: [255x1 double]\n",
" E: [255x1 double]\n",
" I: [255x1 double]\n",
" globvars: {255x1 cell}\n",
" states: {255x1 cell}\n",
" energy: [254x1 double]\n",
" energyDensity: [254x1 double]\n",
" specificEnergy: []"
]
},
"metadata": {},
"execution_count": 5,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"The `plotDashboard` function displays the Li\\-ion concentration profile in both the solids and electrolytes, as well as the electrode potentials at a specific time step.\n",
"\n",
"\n",
"The concentration profiles help understand how efficiently the intercalation (and deintercalation) processes have occurred. They can identify performance issues such as lithium plating or irreversible lithium loss.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"source": [
"step_number = 19;\n",
"plotDashboard(output_dis_NMC.model, output_dis_NMC.states, 'step', step_number);"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"execution_count": 6,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### **Example 3. Post\\-Processing Voltage Curves**\n",
"\n",
"Let's examine the voltage versus capacity curve, which represents the cell discharge profile. The voltage curve typically exhibits three distinct segments:\n",
"\n",
"- An initial drop, caused by internal resistances and the activation of electrochemical processes.\n",
"- A gently sloping or plateau region where the voltage remains relatively stable. A longer plateau region in a battery's discharge profile is beneficial as it signifies that the voltage remains stable with minimal fluctuations across a substantial portion of its capacity, ensuring consistent and efficient energy delivery. The length and voltage of this plateau depend on the cell chemistry.\n",
"- A final drop as the cell approaches its capacity limit."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"source": [
" % Extract the states from the output\n",
" states = output_dis_NMC.states;\n",
"\n",
" % Extract the time, voltage, and current quantities\n",
" time = cellfun(@(state) state.time, states);\n",
" voltage = cellfun(@(state) state.('Control').E, states);\n",
" current = cellfun(@(state) state.('Control').I, states);\n",
"\n",
" % Calculate the capacity\n",
" capacity = time .* current;\n",
"\n",
" % Instantiate an empty figure\n",
" figure()\n",
"\n",
" % Plot the discharge curve in the figure\n",
" plot((capacity / (hour * milli)), voltage, '-', 'linewidth', 3)\n",
"\n",
" % Label the axes\n",
" xlabel('Capacity / mA \\cdot h')\n",
" ylabel('Voltage / V')\n",
"\n",
" % Adjust the axis limits\n",
" axis tight"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"execution_count": 7,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"### **2.2 Influence of structural and material parameters on the capacity**\n",
"\n",
"For a given cell chemistry, the capacity of a cell is constrained by the number of lithium ions that can be safely intercalated and deintercalated from the electrodes. As cells age, they experience irreversible loss of lithium ions, which reduces their capacity over time. We will look at ageing mechanisms in a later chapter. Now, let's examine how material parameters affect cell capacity. One method to increase a cell's capacity, or the amount of energy stored, is by increasing the mass loading, which is the amount of active material per unit area of the electrode. This can be achieved by reducing the number of pores to increase the effective density or by increasing the mass fraction of the coating relative to other components, such as binders and additives. Alternatively, the thickness of the electrode can be increased while maintaining the same ratio of components, thereby adding more active material.\n",
"\n",
"#### **Example 4. Increasing the thickness of the negative electrode / positive electrode**\n",
"\n",
"Please set the electrode type (electrodeType) to be either 'NegativeElectrode' or 'PositiveElectrode' in the code below.\n",
"\n",
"\n",
"**negative electrode:**\n",
"\n",
"\n",
"We maintain the NMC positive electrode at a constant thickness while increasing the graphite electrode thickness from 64 micrometers to 128 micrometers to observe its impact on the capacity of our 1D system. Additionally, we switch to the CC\\-CV protocol, where we first charge the cell with constant current\\-constant voltage (CC\\-CV) and then discharge it at constant current.\n",
"\n",
"\n",
"We plot the discharge curve and observe that the capacity increases for 58 < 45 < 64 micrometers. However, beyond 64 micrometers, further increasing the thickness has no effect on capacity. This is because the amount of lithium in this scenario is limited by the NMC positive electrode. Although more lithium can initially intercalate into the thicker graphite, beyond a certain thickness, there is no additional lithium available to intercalate into the graphite that can be extracted during discharge. Therefore, the capacity remains unchanged.\n",
"\n",
"\n",
"**positive electrode:**\n",
"\n",
"\n",
"We increase the thickness of the NMC positive electrode from 58 micrometers to 128 micrometers. In this scenario, the negative electrode is intentionally oversized relative to the capacity of the positive electrode by approximately 1.3 times. This design ensures that the capacity of the negative electrode exceeds that of the positive electrode, thereby helping to prevent dangerous lithium plating \\[4\\].\n",
"\n",
"\n",
"The thicker electrode indeed shows a notable increase in capacity. However, this comes with its own set of challenges. The longer diffusion pathways for lithium ions within the electrode, higher overpotentials, and extended paths for electronic transport all contribute to a reduced rate capacity. Despite the increase in energy density, these factors cause the capacity to diminish more rapidly at higher discharge rates, this makes it unsuitable for high power applications. We can see this for 128 micrometer electrode, the capacity has decreased significantly, for a C\\-rate of 1.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"source": [
"% create a vector of diffent thickness values\n",
"thickness = [58,64,72,128].*micro;\n",
"markers={'-','o',\"x\",\"-\"};\n",
"jsonstruct_default = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');\n",
"cccv_control_protocol = parseBattmoJson('cccv_control_charge.json');%loads the CCCV protocol\n",
"jsonstruct_modified = mergeJsonStructs({cccv_control_protocol, jsonstruct_default});\n",
"% instantiate an empty cell array to store the outputs of the simulations\n",
"output_struc = cell(size(thickness));\n",
"\n",
"% instantiate an empty figure\n",
"figure()\n",
"markers = {'-', '-', '-', '-'};\n",
"\n",
"% Select the type of electrode to modify\n",
"electrodeType = 'PositiveElectrode'; % or 'PositiveElectrode'\n",
"dischargeRate ='default'; % or 'default'\n",
"\n",
"% use a for-loop to iterate through the vector of thickness\n",
"for i = 1 : numel(thickness)\n",
" % Modify the value for the coating thickness for the specified electrode type\n",
" if strcmp(electrodeType, 'NegativeElectrode')\n",
" jsonstruct_modified.NegativeElectrode.Coating.thickness = thickness(i);\n",
" elseif strcmp(electrodeType, 'PositiveElectrode')\n",
" if strcmp(dischargeRate, 'high')\n",
" jsonstruct_modified.Control.CRate=5;\n",
" end\n",
" jsonstruct_modified.PositiveElectrode.Coating.thickness = thickness(i);\n",
" jsonstruct_modified.NegativeElectrode.Coating.thickness = thickness(i)*1.3;\n",
" else\n",
" error('Unknown electrode type specified');\n",
" end\n",
"\n",
" % run the simulation and store the results in the output cell array\n",
" output_struc{i} = runBatteryJson(jsonstruct_modified);\n",
"\n",
" % retrieve the states from the simulation result\n",
" states = output_struc{i}.states;\n",
" disp(jsonstruct_modified.Control.CRate);\n",
" % extract the time and voltage quantities\n",
" time = cellfun(@(state) state.time, states);\n",
" voltage = cellfun(@(state) state.('Control').E, states);\n",
" current = cellfun(@(state) state.('Control').I, states);\n",
" % calculate the capacity and plot only the capacity during discharge,\n",
" start_index_current_pos=find(current >= 0, 1);\n",
" time_discharge=time(start_index_current_pos);\n",
" discharge_capacity = (time-time_discharge) .* current;\n",
" start_index = find(discharge_capacity == 0, 1);\n",
" end_index = find(discharge_capacity > 0, 1,\"last\");\n",
" plot(discharge_capacity(start_index:end_index)/(hour*milli),voltage(start_index:end_index), markers{i}, 'linewidth', 3)\n",
" hold on\n",
"end\n",
"hold off\n",
"xlabel('Capacity / mA \\cdot h')\n",
"ylabel('Voltage / V')\n",
"legend( 't_{elde} = 58 µm', 't_{elde} = 64 µm','t_{elde} = 72 µm','t_{elde} = 128 µm')"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"execution_count": 8,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### **Example 5. Increasing the effective density of electrode coating**\n",
"\n",
"The effective density of the electrode coating comprises both the active material and the pores. A crucial aspect of cell design is optimizing the ratio of pores to active material. While increasing the amount of active material enhances capacity and energy density by providing more lithium atoms, a less porous electrode reduces the electrolyte volume fraction. This reduction can impair the rate of ion transfer, leading to lower power densities and potential issues with the electrode’s mechanical stability. The density of the positive electrode, NMC is typically around 4650 kg/m³. To assess the impact of effective density on capacity, we vary it from 3500 to 4000 kg/m³. As discussed earlier, the electrolyte fills the pores between the electrode active particles. Therefore, increasing the effective density indefinitely is not possible, as it would reduce the electrolyte volume and hinder the transport of Li\\-ions. In the plot shown below, we observe that the calculation does not converge for an effective density of 4000 kg/m³. Additionally, we have plotted the carrier concentration in the electrolyte, revealing the depletion of ions within it.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"source": [
"jsonstruct = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');% parse the sample_input.json for default values.\n",
"effective_density = [3500,3700,4000];\n",
"markers={'-',\"-\",'-'};\n",
"% Create two figures\n",
"figure1 = figure; % For capacity vs voltage\n",
"figure2 = figure; % For x vs c\n",
"output_dens = cell(size(effective_density));\n",
"timestep=10;\n",
"% use a for-loop to iterate through the vector of effective density\n",
"for i = 1 : numel(effective_density)\n",
" % Modify the value for the coating thickness for the positiv electrode\n",
" jsonstruct.PositiveElectrode.Coating.effectiveDensity = effective_density(i);\n",
" % run the simulation and store the results in the output cell array\n",
" output_dens{i} = runBatteryJson(jsonstruct);\n",
" % retrieve the states from the simulation result\n",
" states = output_dens{i}.states;\n",
" % extract the time and voltage quantities\n",
" time = cellfun(@(state) state.time, states);\n",
" voltage = cellfun(@(state) state.('Control').E, states);\n",
" current = cellfun(@(state) state.('Control').I, states);\n",
" % calculate the capacity\n",
" capacity = time .* current;\n",
" % plot capacity vs voltage\n",
" % instantiate an empty figure\n",
" figure(figure1)\n",
" hold on\n",
" plot((capacity/(hour*milli)), voltage, markers{i}, 'linewidth', 3);\n",
" title('Capacity vs Voltage');\n",
" xlabel('Capacity / mA \\cdot h')\n",
" ylabel('Voltage / V')\n",
" legend( 'eff-dens = 3500', 'eff-dens = 3700','eff-dens = 4000');\n",
" figure(figure2)\n",
" hold on\n",
" x = output_dens{i}.model.grid.cells.centroids;\n",
" c = output_dens{i}.states{5}.Electrolyte.c; %at timestep 5\n",
" plot(x, c, 'LineWidth', 3);\n",
" title('Position vs Concentration in Electrolyte');\n",
" xlabel('Position / m')\n",
" ylabel('Concentration / mol \\cdot m^{-3}')\n",
" legend( 'eff-dens = 3500', 'eff-dens = 3700','eff-dens = 4000');\n",
"end"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### **Example 6. Influence of material chemistry on capacity**\n",
"\n",
"Let's now replace the positive electrode material NMC 811 with LiFePO4 (LFP) \\[2\\]. Different positive electrode materials have varying lithium saturation concentrations, reaction rate constants, and densities. LFP has a lower density and a lower lithium ion saturation concentration compared to NMC 811. As a result, we expect to observe a lower capacity with LFP. Additionally, the shape of the discharge curve will differ, reflecting the distinct electrochemical behavior of LFP compared to NMC 811.\n",
""
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"source": [
"positive_electrode_materials = [\"NMC\",\"LFP\"];\n",
"markers={'-',\"-\",};\n",
"output_mat = cell(size(positive_electrode_materials));\n",
"% instantiate an empty figure\n",
"figure()\n",
"% use a for-loop to iterate through the vector of positive electrode materials\n",
"for i = 1:numel(positive_electrode_materials)\n",
" % Parse the sample input JSON for default values, not the default\n",
" % material used here is NMC\n",
" jsonstruct = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');\n",
" if positive_electrode_materials(i) == \"LFP\"\n",
" % Load the LFP json parameters\n",
" lfp = parseBattmoJson('ParameterData/MaterialProperties/LFP/LFP.json');\n",
" jsonstruct_lfp.PositiveElectrode.Coating.ActiveMaterial.Interface = lfp;\n",
" jsonstruct = mergeJsonStructs({jsonstruct_lfp, jsonstruct});\n",
" jsonstruct.PositiveElectrode.Coating.ActiveMaterial.density = jsonstruct.PositiveElectrode.Coating.ActiveMaterial.Interface.density;\n",
" % the effective density also needs to be changed here for\n",
" % the new material\n",
" jsonstruct.PositiveElectrode.Coating.effectiveDensity = 2709;\n",
" end\n",
" % Run the simulation and store the results in the output cell array\n",
" output_mat{i} = runBatteryJson(jsonstruct);\n",
" % Retrieve the states from the simulation result\n",
" states = output_mat{i}.states;\n",
" % Extract time and voltage quantities\n",
" time = cellfun(@(state) state.time, states);\n",
" voltage = cellfun(@(state) state.('Control').E, states);\n",
" current = cellfun(@(state) state.('Control').I, states);\n",
" % Calculate the capacity\n",
" capacity = time .* current;\n",
" % plot capacity vs voltage\n",
" plot((capacity/(hour*milli)), voltage, markers{i}, 'linewidth', 3);\n",
" hold on\n",
"end\n",
"hold off\n",
"xlabel('Capacity / mA \\cdot h')\n",
"ylabel('Voltage / V')\n",
"legend( 'NMC', 'LFP')"
],
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"execution_count": 10,
"output_type": "execute_result"
}
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"As expected, we observe that the capacity of LiFePO4 (LFP) is lower compared to NMC, and the maximum open\\-circuit voltage (OCP) for the LFP\\-graphite system is also less than that of the NMC positive electrode. Additionally, the discharge curve for LFP is flatter, indicating that the voltage remains more constant throughout the discharge cycle compared to NMC.\n",
"\n",
"### 3. Summary\n",
"\n",
"We covered the fundamentals of battery components and common terminology used in the battery field. Using BattMo, we visualized the structure of a battery and ran simulations with the default parameter set. Additionally, we explored the structural and material properties of the cell to understand their impact on cell voltage.In the next guide, we will delve into the model equations used in BattMo, which are based on the Doyle\\-Fuller\\-Newman (DFN) model.\n",
"\n",
"### **4. References**\n",
"\n",
"\\[1\\] [Flores Cedeño, E. J. (2020). *Development of operando diagnostics for Li\\-ion positive electrodes by Raman spectroscopy* (Doctoral thesis, ETH Zurich).](https://doi.org/10.3929/ethz-b-000373382)\n",
"\n",
"\n",
"\\[2\\] [Safari, M., et al. \"Multimodal physics–based aging model for life prediction of Li–ion batteries.\" Journal of The Electrochemical Society 156.3 (2008): A145.](https://iopscience.iop.org/article/10.1149/1.3043429/meta)\n",
"\n",
"\n",
"\\[3\\] [Xu, Meng, et al. \"A pseudo three–dimensional electrochemical–thermal model of a prismatic LiFePO4 battery during discharge process.\" Energy 80 (2015): 303–317.](https://www.sciencedirect.com/science/article/pii/S0360544214013437#sec2.6.1)\n",
"\n",
"\n",
"\\[4\\] [Karin Kleiner, Peter Jakes, Sebastian Scharner, Verena Liebau, Helmut Ehrenberg, \"Changes of the balancing between negative electrode and positive electrode due to fatigue in commercial lithium\\-ion cells,\" *Journal of Power Sources*, Volume 317, 2016, Pages 25\\-34, ISSN 0378\\-7753, https://doi.org/10.1016/j.jpowsour.2016.03.049. ](https://www.sciencedirect.com/science/article/pii/S0378775316302506)\n",
"\n",
"\n",
"\\[5\\] [Z. Khalik, M.C.F. Donkers, H.J. Bergvel (2021). \"Model simplifications and their impact on computational complexity for an electrochemistry\\-based battery modeling toolbox\" *Journal of Power Sources*, 488, 229427](https://www.sciencedirect.com/science/article/pii/S0378775320317018?via%3Dihub#fig1). [https://doi.org/10.1016/j.jpowsour.2020.229427.](https://doi.org/10.1016/j.jpowsour.2020.229427.)\n",
"\n",
"\n",
"\\[6\\] [Z. Chen, D. L. Danilov, R.\\-A. Eichel, P. H. L. Notten, Porous Electrode Modeling and its Applications to Li\\-Ion Batteries. *Adv. Energy Mater.* 2022, 12, 2201506. https://doi.org/10.1002/aenm.202201506](https://onlinelibrary.wiley.com/doi/full/10.1002/aenm.202201506)\n",
"\n",
"\n",
"\\[7\\] [A. Sobkowiak, ‘LiFeSO4F as a Cathode Material for Lithium\\-Ion Batteries : Synthesis, Structure, and Function’, PhD dissertation, Acta Universitatis Upsaliensis, Uppsala, 2015.](https://uu.diva-portal.org/smash/record.jsf?pid=diva2%3A855021&dswid=3714)\n",
"\n",
""
]
}
],
"metadata": {
"kernelspec": {
"display_name": "MATLAB (matlabkernel)",
"language": "matlab",
"name": "matlab"
},
"language_info": {
"file_extension": ".m",
"mimetype": "text/matlab",
"name": "matlab",
"nbconvert_exporter": "matlab",
"pygments_lexer": "matlab",
"version": "24.2.0.2863752"
}
},
"nbformat": 4,
"nbformat_minor": 4
}