Many-Particle Models

docs/source/expression_tree/unary_operator.rst

@@ -81,7 +81,7 @@ Unary Operators
 
 .. autofunction:: pybamm.r_average
 
-.. autofunction:: pybamm.R_average
+.. autofunction:: pybamm.size_average
 
 .. autofunction:: pybamm.z_average
 

examples/notebooks/models/MPM.ipynb

@@ -298,7 +298,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "fb2cf1a877d243cea4aa5eae1144b78b",
+       "model_id": "b66ea72826fe48e69565e67441ebc889",
        "version_major": 2,
        "version_minor": 0
       },
@@ -312,7 +312,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x7f1c534be160>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x7fd1e0c47fd0>"
       ]
      },
      "execution_count": 7,
@@ -448,24 +448,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Define a lognormal distribution\n",
-    "def lognormal(R, R_av, sd):\n",
-    "    '''\n",
-    "    A lognormal distribution with arguments\n",
-    "        R :     particle radius\n",
-    "        R_av:   mean particle radius\n",
-    "        sd :    standard deviation\n",
-    "    '''\n",
-    "    # calculate usual lognormal parameters\n",
-    "    mu_ln = pybamm.log(R_av ** 2 / pybamm.sqrt(R_av ** 2 + sd ** 2))\n",
-    "    sigma_ln = pybamm.sqrt(pybamm.log(1 + sd ** 2 / R_av ** 2))\n",
-    "    return (\n",
-    "        pybamm.exp(-((pybamm.log(R) - mu_ln) ** 2) / (2 * sigma_ln ** 2))\n",
-    "        / pybamm.sqrt(2 * np.pi * sigma_ln ** 2)\n",
-    "        / R\n",
-    "    )\n",
-    "\n",
-    "\n",
     "# Parameter set (no distribution parameters by default)\n",
     "params = pybamm.ParameterValues(chemistry=pybamm.parameter_sets.Marquis2019)\n",
     "\n",
@@ -483,15 +465,16 @@
     "R_max_n = 2 * R_a_n_dim\n",
     "R_max_p = 3 * R_a_p_dim\n",
     "\n",
-    "# Set the area-weighted particle-size distributions\n",
-    "# Note: the only argument must be the particle size R\n",
+    "# Set the area-weighted particle-size distributions.\n",
+    "# Choose a lognormal (but any pybamm function could be used)\n",
     "def f_a_dist_n_dim(R):\n",
-    "    return lognormal(R, R_a_n_dim, sd_a_n_dim)\n",
+    "    return pybamm.lognormal(R, R_a_n_dim, sd_a_n_dim)\n",
     "\n",
     "\n",
     "def f_a_dist_p_dim(R):\n",
-    "    return lognormal(R, R_a_p_dim, sd_a_p_dim)\n",
-    "\n"
+    "    return pybamm.lognormal(R, R_a_p_dim, sd_a_p_dim)\n",
+    "\n",
+    "# Note: the only argument must be the particle size R\n"
    ]
   },
   {
@@ -522,7 +505,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "5dff78a1e2bc4a1884d5811ff443897c",
+       "model_id": "8b545ec433484ec1b738983bb0d90b80",
        "version_major": 2,
        "version_minor": 0
       },
@@ -536,7 +519,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x7f1c5299d1d0>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x7fd1dfe1cf28>"
       ]
      },
      "execution_count": 12,
@@ -621,7 +604,7 @@
     "\n",
     "# Set the area-weighted particle-size distribution\n",
     "def f_a_dist_p_dim(R):\n",
-    "    return lognormal(R, R_a_p_dim, sd_a_p_dim)\n",
+    "    return pybamm.lognormal(R, R_a_p_dim, sd_a_p_dim)\n",
     "\n",
     "# input to param dictionary\n",
     "distribution_params = {\n",
@@ -641,7 +624,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "1d8c9493b65344a580dbe0cd7fef4081",
+       "model_id": "9e0887e23c884591bdd97caac3e670d5",
        "version_major": 2,
        "version_minor": 0
       },
@@ -655,7 +638,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x7f1c48b02c88>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x7fd1dfe74c18>"
       ]
      },
      "execution_count": 15,
@@ -766,7 +749,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "30e5982a7e1345d7912e3aa131fa6ff7",
+       "model_id": "ca33360fe25f423fbae0fe20bad989e1",
        "version_major": 2,
        "version_minor": 0
       },
@@ -780,7 +763,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x7f1c482d2278>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x7fd1e18b4550>"
       ]
      },
      "execution_count": 18,
@@ -830,7 +813,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "6938c3cab8f14709985552080e01355e",
+       "model_id": "4cfa09f7cdac41cfac0c38ab4be1cf38",
        "version_major": 2,
        "version_minor": 0
       },
@@ -844,7 +827,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x7f1c3fd2d940>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x7fd1d48c5550>"
       ]
      },
      "execution_count": 19,
@@ -884,7 +867,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "0ff76ec97d994aed8415b4088e84b925",
+       "model_id": "462351065ca445868719ac5a85a66cf7",
        "version_major": 2,
        "version_minor": 0
       },
@@ -898,7 +881,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x7f1c3f0f9e48>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x7fd1cd3f6438>"
       ]
      },
      "execution_count": 20,

pybamm/CITATIONS.txt

@@ -428,4 +428,15 @@ doi={10.1149/2.0661810jes}
 	pages = {060554},
 	doi = {10.1149/1945-7111/ac0bf7},
 	url = {https://doi.org/10.1149/1945-7111/ac0bf7},
-}
+}
+
+@article{Xu2019,
+  title={Evolution of Dead Lithium Growth in Lithium Metal Batteries: Experimentally Validated Model of the Apparent Capacity Loss},
+  author={Xu, Shanshan and Chen, Kuan-Hung and Dasgupta, Neil P and Siegel, Jason B and Stefanopoulou, Anna G},
+  journal={Journal of The Electrochemical Society},
+  volume={166},
+  number={14},
+  pages={A3456},
+  year={2019},
+  publisher={IOP Publishing}
+}

pybamm/__init__.py

@@ -173,6 +173,7 @@ def version(formatted=False):
 from .parameters.thermal_parameters import thermal_parameters, ThermalParameters
 from .parameters.lithium_ion_parameters import LithiumIonParameters
 from .parameters.lead_acid_parameters import LeadAcidParameters
+from .parameters.size_distribution_parameters import *
 from .parameters import parameter_sets
 
 #

pybamm/expression_tree/unary_operators.py

@@ -1413,25 +1413,24 @@ def r_average(symbol):
         return Integral(symbol, r) / Integral(v, r)
 
 
-def R_average(symbol, param):
+def size_average(symbol):
     """convenience function for averaging over particle size R using the area-weighted
     particle-size distribution.
 
     Parameters
     ----------
     symbol : :class:`pybamm.Symbol`
         The function to be averaged
-    param : :class:`pybamm.LithiumIonParameters`
-        The parameter object containing the area-weighted particle-size distributions
-        f_a_dist_n and f_a_dist_p.
     Returns
     -------
     :class:`Symbol`
         the new averaged symbol
     """
     # Can't take average if the symbol evaluates on edges
     if symbol.evaluates_on_edges("primary"):
-        raise ValueError("Can't take the R-average of a symbol that evaluates on edges")
+        raise ValueError(
+            """Can't take the size-average of a symbol that evaluates on edges"""
+        )
 
     # If symbol doesn't have a domain, or doesn't have "negative particle size"
     #  or "positive particle size" as a domain, it's average value is itself
@@ -1465,10 +1464,11 @@ def R_average(symbol, param):
             auxiliary_domains=symbol.auxiliary_domains,
             coord_sys="cartesian",
         )
+        geo = pybamm.geometric_parameters
         if ["negative particle size"] in list(symbol.domains.values()):
-            f_a_dist = param.f_a_dist_n(R)
+            f_a_dist = geo.f_a_dist_n(R)
         elif ["positive particle size"] in list(symbol.domains.values()):
-            f_a_dist = param.f_a_dist_p(R)
+            f_a_dist = geo.f_a_dist_p(R)
 
         # take average using Integral and distribution f_a_dist
         return Integral(f_a_dist * symbol, R) / Integral(f_a_dist, R)

pybamm/geometry/battery_geometry.py

@@ -51,11 +51,10 @@ def battery_geometry(
         options is not None and
         options["particle size"] == "distribution"
     ):
-        param = pybamm.LithiumIonParameters(options)
-        R_min_n = param.R_min_n
-        R_min_p = param.R_min_p
-        R_max_n = param.R_max_n
-        R_max_p = param.R_max_p
+        R_min_n = geo.R_min_n
+        R_min_p = geo.R_min_p
+        R_max_n = geo.R_max_n
+        R_max_p = geo.R_max_p
         geometry.update(
             {
                 "negative particle size": {