Update submodel options and add citations. Also change the solid phas…

…e volume fraction to be (1-porosity) rather than the active material volume fraction
pybamm-team · Oct 11, 2023 · 14c0ced · 14c0ced
1 parent 19ac474
commit 14c0ced
Show file tree

Hide file tree

Showing 6 changed files with 301 additions and 39 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 # [v23.9rc0](https://github.com/pybamm-team/PyBaMM/tree/v23.9rc0) - 2023-10-31
 
 ## Features
+- Transport efficiency submodel has new options from the literature relating to different tortuosity factor models and also a new option called "tortuosity factor" for specifying the value or function directly as parameters ([#3437](https://github.com/pybamm-team/PyBaMM/pull/3437))
 - The parameter "Ambient temperature [K]" can now be given as a function of position `(y,z)` and time `t`. The "edge" and "current collector" heat transfer coefficient parameters can also depend on `(y,z)` ([#3257](https://github.com/pybamm-team/PyBaMM/pull/3257))
 - Spherical and cylindrical shell domains can now be solved with any boundary conditions ([#3237](https://github.com/pybamm-team/PyBaMM/pull/3237))
 - Processed variables now get the spatial variables automatically, allowing plotting of more generic models ([#3234](https://github.com/pybamm-team/PyBaMM/pull/3234))

diff --git a/docs/source/examples/notebooks/models/tortuosity_models.ipynb b/docs/source/examples/notebooks/models/tortuosity_models.ipynb
@@ -7,13 +7,94 @@
     "# Transport Efficiency"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pybamm\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "['Bruggeman', 'ordered packing', 'hyperbola of revolution', 'overlapping spheres', 'tortuosity factor', 'random overlapping cylinders', 'heterogeneous catalyst', 'cation-exchange membrane']\n"
+     ]
+    }
+   ],
+   "source": [
+    "sols = []\n",
+    "te_opts = pybamm.BatteryModelOptions({}).possible_options[\"transport efficiency\"]\n",
+    "parameter_values = pybamm.ParameterValues(\"Marquis2019\")\n",
+    "print(te_opts)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Negative electrode porosity\t0.3\n",
+      "Positive electrode porosity\t0.3\n",
+      "Separator porosity\t1.0\n"
+     ]
+    }
+   ],
+   "source": [
+    "parameter_values.search(\"porosity\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Negative electrode Bruggeman coefficient (electrode)\t1.5\n",
+      "Negative electrode Bruggeman coefficient (electrolyte)\t1.5\n",
+      "Positive electrode Bruggeman coefficient (electrode)\t1.5\n",
+      "Positive electrode Bruggeman coefficient (electrolyte)\t1.5\n",
+      "Separator Bruggeman coefficient (electrolyte)\t1.5\n"
+     ]
+    }
+   ],
+   "source": [
+    "parameter_values.search(\"Bruggeman\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Add tortuosity factors that replicate the Bruggeman values"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 5,
    "metadata": {},
    "outputs": [],
    "source": [
-    "import pybamm"
+    "parameter_values.update({'Negative electrode tortuosity factor (electrolyte)': 0.3**(-0.5),\n",
+    "                         'Positive electrode tortuosity factor (electrolyte)': 0.3**(-0.5),\n",
+    "                         'Negative electrode tortuosity factor (electrode)': 0.7**(-0.5),\n",
+    "                         'Positive electrode tortuosity factor (electrode)': 0.7**(-0.5),\n",
+    "                         'Separator tortuosity factor (electrolyte)': 1.0}, check_already_exists=False)"
    ]
   },
   {
@@ -22,40 +103,99 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sols = []\n",
-    "labels = ['log square root', 'log', 'linear', 'half volume fraction', 'Bruggeman']\n",
-    "for t_label in labels:\n",
+    "for t_label in te_opts:\n",
     "    model = pybamm.lithium_ion.DFN(options={'transport efficiency': t_label})  # Doyle-Fuller-Newman model\n",
-    "    sim = pybamm.Simulation(model)\n",
+    "    sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
     "    sols.append(sim.solve([0, 3600]))  # solve for 1 hour"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 7,
    "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "856222356e2c448c990304033c81e410",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x249fb0b0fa0>"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "pybamm.dynamic_plot(sols,labels=te_opts)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "np.allclose(sols[0][\"Terminal voltage [V]\"].data, sols[4][\"Terminal voltage [V]\"].data)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
    "outputs": [],
    "source": [
-    "model = pybamm.lithium_ion.DFN(options={'transport efficiency': 'tortuosity factor'})  # Doyle-Fuller-Newman model\n",
-    "parameter_values = model.default_parameter_values\n",
-    "parameter_values.update({'Negative electrode tortuosity factor (electrolyte)': 1.5,\n",
-    "                         'Positive electrode tortuosity factor (electrolyte)': 1.5,\n",
-    "                         'Negative electrode tortuosity factor (electrode)': 1.5,\n",
-    "                         'Positive electrode tortuosity factor (electrode)': 1.5,\n",
-    "                         'Separator tortuosity factor (electrolyte)': 1.2}, check_already_exists=False)\n",
+    "parameter_values.update({'Negative electrode tortuosity factor (electrolyte)': 4.0,\n",
+    "                         'Positive electrode tortuosity factor (electrolyte)': 4.0,\n",
+    "                         'Negative electrode tortuosity factor (electrode)': 3.0,\n",
+    "                         'Positive electrode tortuosity factor (electrode)': 3.0,\n",
+    "                         'Separator tortuosity factor (electrolyte)': 1.5}, check_already_exists=False)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model = pybamm.lithium_ion.DFN(options={'transport efficiency': \"tortuosity factor\"})  # Doyle-Fuller-Newman model\n",
     "sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
-    "sols.append(sim.solve([0, 3600]))  # solve for 1 hour"
+    "sols.append(sim.solve([0, 3600]))"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "eb0c96127aae440698a5b373282032a8",
+       "model_id": "85ea5ac088354ca6add0e5b83cf0097d",
        "version_major": 2,
        "version_minor": 0
       },
@@ -69,17 +209,53 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x17065c67ac0>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x24980448490>"
       ]
      },
-     "execution_count": 8,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "pybamm.dynamic_plot(sols,labels=labels+['Tortuosity factor'])"
+    "pybamm.dynamic_plot(sols,labels=te_opts+[\"higher tortuosity factor\"])"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[1] KA Akanni, JW Evans, and IS Abramson. Effective transport coefficients in heterogeneous media. Chemical Engineering Science, 42(8):1945–1954, 1987.\n",
+      "[2] Joel A. E. Andersson, Joris Gillis, Greg Horn, James B. Rawlings, and Moritz Diehl. CasADi – A software framework for nonlinear optimization and optimal control. Mathematical Programming Computation, 11(1):1–36, 2019. doi:10.1007/s12532-018-0139-4.\n",
+      "[3] JW Beeckman. Mathematical description of heterogeneous materials. Chemical engineering science, 45(8):2603–2610, 1990.\n",
+      "[4] Von DAG Bruggeman. Berechnung verschiedener physikalischer konstanten von heterogenen substanzen. i. dielektrizitätskonstanten und leitfähigkeiten der mischkörper aus isotropen substanzen. Annalen der physik, 416(7):636–664, 1935.\n",
+      "[5] Marc Doyle, Thomas F. Fuller, and John Newman. Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell. Journal of the Electrochemical society, 140(6):1526–1533, 1993. doi:10.1149/1.2221597.\n",
+      "[6] Charles R. Harris, K. Jarrod Millman, Stéfan J. van der Walt, Ralf Gommers, Pauli Virtanen, David Cournapeau, Eric Wieser, Julian Taylor, Sebastian Berg, Nathaniel J. Smith, and others. Array programming with NumPy. Nature, 585(7825):357–362, 2020. doi:10.1038/s41586-020-2649-2.\n",
+      "[7] JS Mackie and P Meares. The diffusion of electrolytes in a cation-exchange resin membrane i. theoretical. Proceedings of the Royal Society of London. Series A. Mathematical and Physical Sciences, 232(1191):498–509, 1955.\n",
+      "[8] Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15):A3693–A3706, 2019. doi:10.1149/2.0341915jes.\n",
+      "[9] EE Petersen. Diffusion in a pore of varying cross section. AIChE Journal, 4(3):343–345, 1958.\n",
+      "[10] Valentin Sulzer, Scott G. Marquis, Robert Timms, Martin Robinson, and S. Jon Chapman. Python Battery Mathematical Modelling (PyBaMM). Journal of Open Research Software, 9(1):14, 2021. doi:10.5334/jors.309.\n",
+      "[11] Manolis M Tomadakis and Stratis V Sotirchos. Transport properties of random arrays of freely overlapping cylinders with various orientation distributions. The Journal of chemical physics, 98(1):616–626, 1993.\n",
+      "[12] Harold L Weissberg. Effective diffusion coefficient in porous media. Journal of Applied Physics, 34(9):2636–2639, 1963.\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "pybamm.print_citations()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {

diff --git a/pybamm/CITATIONS.bib b/pybamm/CITATIONS.bib
@@ -704,3 +704,73 @@ @article{landesfeind2019temperature
   year={2019},
   publisher={The Electrochemical Society}
 }
+@article{akanni1987effective,
+  title={Effective transport coefficients in heterogeneous media},
+  author={Akanni, KA and Evans, JW and Abramson, IS},
+  journal={Chemical Engineering Science},
+  volume={42},
+  number={8},
+  pages={1945--1954},
+  year={1987},
+  publisher={Elsevier}
+}
+@article{petersen1958diffusion,
+  title={Diffusion in a pore of varying cross section},
+  author={Petersen, EE},
+  journal={AIChE Journal},
+  volume={4},
+  number={3},
+  pages={343--345},
+  year={1958},
+  publisher={Wiley Online Library}
+}
+@article{bruggeman1935berechnung,
+  title={Berechnung verschiedener physikalischer Konstanten von heterogenen Substanzen. I. Dielektrizit{\"a}tskonstanten und Leitf{\"a}higkeiten der Mischk{\"o}rper aus isotropen Substanzen},
+  author={Bruggeman, Von DAG},
+  journal={Annalen der physik},
+  volume={416},
+  number={7},
+  pages={636--664},
+  year={1935},
+  publisher={Wiley Online Library}
+}
+@article{weissberg1963effective,
+  title={Effective diffusion coefficient in porous media},
+  author={Weissberg, Harold L},
+  journal={Journal of Applied Physics},
+  volume={34},
+  number={9},
+  pages={2636--2639},
+  year={1963},
+  publisher={American Institute of Physics}
+}
+@article{tomadakis1993transport,
+  title={Transport properties of random arrays of freely overlapping cylinders with various orientation distributions},
+  author={Tomadakis, Manolis M and Sotirchos, Stratis V},
+  journal={The Journal of chemical physics},
+  volume={98},
+  number={1},
+  pages={616--626},
+  year={1993},
+  publisher={American Institute of Physics}
+}
+@article{beeckman1990mathematical,
+  title={Mathematical description of heterogeneous materials},
+  author={Beeckman, JW},
+  journal={Chemical engineering science},
+  volume={45},
+  number={8},
+  pages={2603--2610},
+  year={1990},
+  publisher={Elsevier}
+}
+@article{mackie1955diffusion,
+  title={The diffusion of electrolytes in a cation-exchange resin membrane I. Theoretical},
+  author={Mackie, JS and Meares, P},
+  journal={Proceedings of the Royal Society of London. Series A. Mathematical and Physical Sciences},
+  volume={232},
+  number={1191},
+  pages={498--509},
+  year={1955},
+  publisher={The Royal Society London}
+}
diff --git a/pybamm/models/full_battery_models/base_battery_model.py b/pybamm/models/full_battery_models/base_battery_model.py
@@ -237,14 +237,6 @@ def __init__(self, extra_options):
                 "integrated",
             ],
             "exchange-current density": ["single", "current sigmoid"],
-            "transport efficiency": [
-                "Bruggeman",
-                "log square root",
-                "log",
-                "linear",
-                "tortuosity factor",
-                "half volume fraction",
-            ],
             "hydrolysis": ["false", "true"],
             "intercalation kinetics": [
                 "symmetric Butler-Volmer",
@@ -312,6 +304,16 @@ def __init__(self, extra_options):
             "surface form": ["false", "differential", "algebraic"],
             "thermal": ["isothermal", "lumped", "x-lumped", "x-full"],
             "total interfacial current density as a state": ["false", "true"],
+            "transport efficiency": [
+                "Bruggeman",
+                "ordered packing",
+                "hyperbola of revolution",
+                "overlapping spheres",
+                "tortuosity factor",
+                "random overlapping cylinders",
+                "heterogeneous catalyst",
+                "cation-exchange membrane",
+            ],
             "working electrode": ["both", "positive"],
             "x-average side reactions": ["false", "true"],
         }