{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "# Tutorial 1 \\- Your First BattMo Model\n", "\n", "## Introduction\n", "\n", "Let’s make your first **BattMo** model! ?⚡?\n", "\n", "\n", "In this tutorial, we will build, run, and visualize a simple pseudo\\-two\\-dimensional (P2D) simulation for a Li\\-ion battery cell. We will first introduce how **BattMo** handles model parameters, then run the simulation, dashboard the results, and explore the details of the simulation output.\n", "\n", "## Define Parameters\n", "\n", "**BattMo** uses JSON to manage parameters. This allows you to easily save, document, and share complete parameter sets from specific simulations. We have used long and explicit key names for good readability. If you are new to JSON, you can learn more about it [here](https://www.w3schools.com/js/js_json_intro.asp). Details on the BattMo specification are available in the [JSON input specification](http://json.html/#json-input-specification).\n", "\n", "\n", "For this example, we provide a sample JSON file [sample\\_input.json](https://github.com/BattMoTeam/BattMo/blob/main/Examples/JsonDataFiles/sample_input.json) that describes a simple NMC\\-Graphite cell.\n", "\n", "\n", "We load and parse the JSON input file into **BattMo** using the command:\n", "" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "source": [ "jsonstruct = parseBattmoJson('Examples/JsonDataFiles/sample_input.json');" ], "outputs": [] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "This transforms the parameter data as a [MATLAB structure](https://se.mathworks.com/help/matlab/structures.html) jsonstruct that is used to setup the simulation. We can explore the structure within the MATLAB Command Window by navigating the different levels of the structure.\n", "" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "source": [ "disp(jsonstruct)" ], "outputs": [ { "data": { "text/plain": [ " use_thermal: 0\n", " include_current_collectors: 0\n", " Geometry: [1x1 struct]\n", " NegativeElectrode: [1x1 struct]\n", " PositiveElectrode: [1x1 struct]\n", " Separator: [1x1 struct]\n", " Control: [1x1 struct]\n", " Electrolyte: [1x1 struct]\n", " ThermalModel: [1x1 struct]\n", " TimeStepping: [1x1 struct]\n", " Output: [1x1 struct]\n", " SOC: 0.9900\n", " initT: 298.1500" ] }, "metadata": {}, "execution_count": 2, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "We can see that the structure contains various attributes for the different aspects of the model. For example, if we want to know the thickness of the negative electrode coating, we can navigate the hierarchy to find it:\n", "" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "source": [ "disp(jsonstruct.NegativeElectrode.Coating.thickness)" ], "outputs": [ { "data": { "text/plain": [ " 6.4000e-05" ] }, "metadata": {}, "execution_count": 3, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "Unless otherwise specified, BattMo uses [SI base units](https://www.nist.gov/si-redefinition/definitions-si-base-units) for physical quantities.\n", "\n", "## Run Simulation\n", "\n", "We can run the simulation with the command:\n", "" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "source": [ "output = runBatteryJson(jsonstruct);" ], "outputs": [] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Show the Dashboard\n", "\n", "We can dashboard the main results using [plotDashboard](https://github.com/BattMoTeam/BattMo/blob/main/Utilities/Visualization/plotDashboard.m). Here, for example at time step 10,\n", "" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "source": [ "plotDashboard(output.model, output.states, 'step', 10);" ], "outputs": [ { "data": { "text/html": [ "
\"figure_0.png\"
" ] }, "metadata": {}, "execution_count": 5, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "The left 3 columns of the dashboard shows the profiles for the main state quantities (concentration and electric potential) in the negative electrode, electrolyte, and positive electrode. The rightmost column shows the calculated cell current and voltage. In the following subsections, we will explore how to access and plot this data from the simulation output.\n", "\n", "## Explore the Output\n", "\n", "The output structure returns among other thing the model and the states.\n", "" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "source": [ "disp(output)" ], "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: [116x1 double]\n", " E: [116x1 double]\n", " I: [116x1 double]\n", " globvars: {116x1 cell}\n", " states: {116x1 cell}\n", " energy: [115x1 double]\n", " energyDensity: [115x1 double]\n", " specificEnergy: []" ] }, "metadata": {}, "execution_count": 6, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "The model contains information about the setup of the model and initial conditions, while states contains the results of the simulation at each timestep. Plotting the simulation results requires information about the grid (i.e. what is the position where the quantity is calculated?) and the state (i.e. what is the value of the quantity in that position at a given time?).\n", "\n", "## Explore the Grid\n", "\n", "The grid (or mesh) is one of the most used properties of the model, which can be accessed with the command:\n", "" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "source": [ "disp(output.model.grid)" ], "outputs": [ { "data": { "text/plain": [ " cells: [1x1 struct]\n", " faces: [1x1 struct]\n", " nodes: [1x1 struct]\n", " griddim: 1\n", " type: 'generic'" ] }, "metadata": {}, "execution_count": 7, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "We can see that the grid is stored as a structure with information about the cells, faces, nodes, etc. The values of the state quantities (e.g. concentration and electric potential) are calculated at the centroids of the cells. To plot the positions of the centroids, we can use the following commands:\n", "" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "source": [ "% get the centroid locations for the full grid\n", "x = output.model.grid.cells.centroids;\n", "\n", "% plot them in a figure\n", "figure();\n", "grid_axes = axes();\n", "plot(grid_axes, x, zeros(size(x)), '+', 'LineWidth', 2)\n", "\n", "% remove the y-axis ticks\n", "yticks([]);\n", "\n", "% add plot annotations\n", "title('Grid Centroids');\n", "xlabel('Position / m');" ], "outputs": [ { "data": { "text/html": [ "
\"figure_1.png\"
" ] }, "metadata": {}, "execution_count": 8, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "This shows the overall grid that is used for the model. However, **BattMo** models use a modular hierarchy where the overall cell model is composed of smaller submodels for electrodes, electrolyte, and current collectors. Each of these submodels has its own grid.\n", "\n", "\n", "For example, if we want to plot the grid associated with the different submodels in different colors, we can use the following commands:\n", "" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "source": [ "% get the centroid locations for the negative electrode (x_ne), separator\n", "% (x_sep), and positive electrode (x_pe)\n", "x_ne = output.model.NegativeElectrode.grid.cells.centroids;\n", "x_sep = output.model.Separator.grid.cells.centroids;\n", "x_pe = output.model.PositiveElectrode.grid.cells.centroids;\n", "\n", "% plot them together on one figure\n", "figure()\n", "plot(x_ne, zeros(size(x_ne)), '+', 'LineWidth', 2)\n", "hold on\n", "plot(x_sep, zeros(size(x_sep)), '+k', 'LineWidth', 2)\n", "plot(x_pe, zeros(size(x_pe)), '+r', 'LineWidth', 2)\n", "\n", "% remove the y-axis tick marks\n", "yticks([]);\n", "\n", "% add plot annotations\n", "title('Grid Centroids by Component')\n", "xlabel('Position / m')\n", "legend('Negative Electrode', 'Separator', 'Positive Electrode')" ], "outputs": [ { "data": { "text/html": [ "
\"figure_2.png\"
" ] }, "metadata": {}, "execution_count": 9, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "If you would like more information about the **BattMo** model hierarchy, please see [BattMo Model Architecture](http://architecture.html/#battmo-model-architecture).\n", "\n", "## Explore the States\n", "\n", "The values of the state quantities at each time step are stored in the states [cell array](https://se.mathworks.com/help/matlab/cell-arrays.html). Each entry in the array describes the state of the simulation at a given timestep.\n", "\n", "\n", "For example, we can look at the state of the simulation at timestep 10 (shown in the dashboard plot above) using the command:\n", "" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "source": [ "timestep = 10;\n", "disp(output.states{timestep})" ], "outputs": [ { "data": { "text/plain": [ " NegativeElectrode: [1x1 struct]\n", " PositiveElectrode: [1x1 struct]\n", " Electrolyte: [1x1 struct]\n", " Control: [1x1 struct]\n", " time: 168\n", " ThermalModel: [1x1 struct]" ] }, "metadata": {}, "execution_count": 10, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "We see that the time of the state is 504 seconds and there are other structures containing the states of the electrodes and electrolyte. We can look into the state of the electrolyte using the command:\n", "" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "source": [ "disp(output.states{timestep}.Electrolyte)" ], "outputs": [ { "data": { "text/plain": [ " phi: [30x1 double]\n", " c: [30x1 double]" ] }, "metadata": {}, "execution_count": 11, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "which shows that there are two quantities there for concentration, c, and electric potential, phi.\n", "\n", "## Plot a Result\n", "\n", "Let’s plot the concentration in the electrolyte at timestep 10. We can plot the results using basic MATLAB commands this way:\n", "" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "source": [ "% get the centroid locations and the values for the electrolyte\n", "% concentration at the given timestep\n", "x = output.model.grid.cells.centroids;\n", "c = output.states{timestep}.Electrolyte.c;\n", "\n", "% plot the concentration values at the given grid centroid locations\n", "figure()\n", "plot(x, c, 'LineWidth', 3)\n", "\n", "% add plot annotations\n", "xlabel('Position / m')\n", "ylabel('Concentration / mol \\cdot m^{-3}')" ], "outputs": [ { "data": { "text/html": [ "
\"figure_3.png\"
" ] }, "metadata": {}, "execution_count": 12, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "**BattMo** also includes dedicated plotting functions that will come in handy when we start working with more complex systems (e.g. P4D grids). To demonstrate how it works, we can plot the electrolyte concentration profile at every timestep using the **BattMo** function plotCellData:\n", "" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "source": [ "% create a figure and use hold on to show multiple lines in one figure\n", "figure();\n", "hold on\n", "\n", "% define a colormap for the line colors\n", "cm = cmocean('matter', length(output.states));\n", "\n", "% iterate through each of the output states and plot the calculated\n", "% electrolyte concentration at each timestep\n", "for timestep = 1:length(output.states)\n", " plotCellData(output.model.grid, output.states{timestep}.Electrolyte.c, 'LineWidth', 3, 'Color', cm(timestep,:))\n", "end\n", "\n", "% add plot annotations and turn hold off\n", "xlabel('Position / m')\n", "ylabel('Concentration / mol \\cdot m^{-3}')\n", "hold off" ], "outputs": [ { "data": { "text/html": [ "
\"figure_4.png\"
" ] }, "metadata": {}, "execution_count": 13, "output_type": "execute_result" } ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "You did it! ? You have run an post\\-processed your first BattMo simulation! But there are still a lot of exciting features to discover. Let’s keep going and explore making chages to the model. ?\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.1.0.2689473" } }, "nbformat": 4, "nbformat_minor": 4 }