Issue 2418 dimensional

CHANGELOG.md

@@ -10,6 +10,10 @@
 
 - Fixed the length scaling for the first dimension of r-R plots ([#2663](https://github.com/pybamm-team/PyBaMM/pull/2663)).
 
+## Breaking changes
+
+- All PyBaMM models are now dimensional. This has been benchmarked against dimensionless models and found to give around the same solve time. Implementing dimensional models greatly reduces the barrier to entry for adding new models. However, this comes with several breaking changes: (i) the `timescale` and `length_scales` attributes of a model have been removed (they are no longer needed) (ii) several dimensionless variables are no longer defined, but the corresponding dimensional variables can still be accessed by adding the units to the name (iii) some parameters used only for non-dimensionalization, such as "Typical current [A]", have been removed ([#2419](https://github.com/pybamm-team/PyBaMM/pull/2419))
+
 # [v23.1](https://github.com/pybamm-team/PyBaMM/tree/v23.1) - 2023-01-31
 
 ## Features

docs/source/user_guide/installation/GNU-linux.rst

@@ -96,7 +96,7 @@ Optional - scikits.odes solver
 
 Users can install `scikits.odes <https://github.com/bmcage/odes>`__ in
 order to use the wrapped SUNDIALS ODE and DAE
-`solvers <https://pybamm.readthedocs.io/en/latest/source/solvers/scikits_solvers.html>`__.
+`solvers <https://pybamm.readthedocs.io/en/latest/source/api/solvers/scikits_solvers.html>`__.
 Currently, only GNU/Linux and macOS are supported.
 
 GNU/Linux

examples/notebooks/Getting Started/Tutorial 10 - Creating a model.ipynb

@@ -306,7 +306,7 @@
     }
    ],
    "source": [
-    "sim.solve([0, 1])  # solve up to a dimensionless time of 1"
+    "sim.solve([0, 1])  # solve up to a time of 1"
    ]
   },
   {
@@ -407,7 +407,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "pybamm",
    "language": "python",
    "name": "python3"
   },
@@ -421,7 +421,12 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.13"
+   "version": "3.9.16"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "187972e187ab8dfbecfab9e8e194ae6d08262b2d51a54fa40644e3ddb6b5f74c"
+   }
   }
  },
  "nbformat": 4,

examples/notebooks/Getting Started/Tutorial 4 - Setting parameter values.ipynb

@@ -387,8 +387,7 @@
     "drive_cycle = pd.read_csv(\"pybamm/input/drive_cycles/US06.csv\", comment=\"#\", header=None).to_numpy()\n",
     "\n",
     "# Create interpolant\n",
-    "timescale = parameter_values.evaluate(model.timescale)\n",
-    "current_interpolant = pybamm.Interpolant(drive_cycle[:, 0], drive_cycle[:, 1], timescale * pybamm.t)\n",
+    "current_interpolant = pybamm.Interpolant(drive_cycle[:, 0], drive_cycle[:, 1], pybamm.t)\n",
     "\n",
     "# Set drive cycle\n",
     "parameter_values[\"Current function [A]\"] = current_interpolant"
@@ -555,7 +554,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "pybamm",
    "language": "python",
    "name": "python3"
   },
@@ -569,7 +568,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.16"
   },
   "toc": {
    "base_numbering": 1,
@@ -586,7 +585,7 @@
   },
   "vscode": {
    "interpreter": {
-    "hash": "1a781583db2df3c2e87436f6d22cce842c2e50a5670da93a3bd820b97dc43011"
+    "hash": "187972e187ab8dfbecfab9e8e194ae6d08262b2d51a54fa40644e3ddb6b5f74c"
    }
   }
  },

examples/notebooks/README.md

@@ -27,19 +27,12 @@ The easiest way to start with PyBaMM is by running and comparing some of the inb
 
 It is also easy to add new models or change the setting that are used:
 
-- [Add a model (documentation)](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)
 - [Add a model (example)](./create-model.ipynb)
 - [Change model options](./models/using-model-options_thermal-example.ipynb)
 - [Using submodels](./using-submodels.ipynb)
 - [Change the settings](./change-settings.ipynb) (parameters, spatial method or solver)
 - [Change the applied current](./parameterization/change-input-current.ipynb)
 
-For more advanced usage, new sets of parameters, spatial methods and solvers can be added:
-
-- [Add parameters](https://pybamm.readthedocs.io/en/latest/tutorials/add-parameter-values.html)
-- [Add a spatial method](https://pybamm.readthedocs.io/en/latest/tutorials/add-spatial-method.html)
-- [Add a solver](https://pybamm.readthedocs.io/en/latest/tutorials/add-solver.html)
-
 ## Expression tree structure
 
 PyBaMM is built around an expression tree structure.
@@ -51,7 +44,7 @@ The following notebooks are specific to different stages of the PyBaMM pipeline,
 
 ### Models
 
-Several battery models are implemented and can easily be used or [compared](./models/lead-acid.ipynb). The notebooks below show the solution of each individual model. We always welcome [new models](https://pybamm.readthedocs.io/en/latest/tutorials/add-model.html)!
+Several battery models are implemented and can easily be used or [compared](./models/lead-acid.ipynb). The notebooks below show the solution of each individual model.
 
 Once you are comfortable with the expression tree structure, a good starting point to understand the models in PyBaMM is to take a look at the [basic SPM](https://github.com/pybamm-team/PyBaMM/blob/develop/pybamm/models/full_battery_models/lithium_ion/basic_spm.py) and [basic DFN](https://github.com/pybamm-team/PyBaMM/blob/develop/pybamm/models/full_battery_models/lithium_ion/basic_dfn.py), since these define the entire model (variables, equations, initial and boundary conditions, events) in a single class and so are easier to understand. However, we recommend that you subsequently use the full models as they offer much greater flexibility for coupling different physical effects and visualising a greater range of variables.
 
@@ -74,13 +67,9 @@ The following spatial methods are implemented
 - Spectral Volumes (1D only)
 - Finite Elements (only for 2D current collector domains)
 
-See [here](https://pybamm.readthedocs.io/en/latest/tutorials/add-spatial-method.html) for instructions on adding new spatial methods.
-
 ### Solvers
 
 The following notebooks show examples for generic ODE and DAE solvers. Several solvers are implemented in PyBaMM and we encourage users to try different ones to find the most appropriate one for their models.
 
 - [ODE solver](./solvers/ode-solver.ipynb)
 - [DAE solver](./solvers/dae-solver.ipynb)
-
-See [here](https://pybamm.readthedocs.io/en/latest/tutorials/add-solver.html) for instructions on adding new solvers.

examples/notebooks/change-settings.ipynb

@@ -682,7 +682,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "pybamm",
    "language": "python",
    "name": "python3"
   },
@@ -696,11 +696,11 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.16"
   },
   "vscode": {
    "interpreter": {
-    "hash": "1a781583db2df3c2e87436f6d22cce842c2e50a5670da93a3bd820b97dc43011"
+    "hash": "187972e187ab8dfbecfab9e8e194ae6d08262b2d51a54fa40644e3ddb6b5f74c"
    }
   }
  },

examples/notebooks/expression_tree/expression-tree.ipynb

@@ -131,7 +131,7 @@
     "\n",
     "## Stage 1 - Symbolic Expression Trees\n",
     "\n",
-    "At each stage, the expression tree consists of certain types of nodes. In the first stage, the model is first proposed using [`pybamm.Parameter`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/parameter.html), [`pybamm.Variable`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/variable.html), and other [unary](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/unary_operator.html) and [binary](https://pybamm.readthedocs.io/en/latest/source/expression_tree/binary_operator.html) operators (which also includes spatial operators such as [`pybamm.Gradient`](https://pybamm.readthedocs.io/en/latest/source/expression_tree/unary_operator.html#pybamm.Gradient) and [`pybamm.Divergence`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/unary_operator.html#pybamm.Divergence)). For example, the right hand side of the equation\n",
+    "At each stage, the expression tree consists of certain types of nodes. In the first stage, the model is first proposed using [`pybamm.Parameter`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/parameter.html), [`pybamm.Variable`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/variable.html), and other [unary](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/unary_operator.html) and [binary](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/binary_operator.html) operators (which also includes spatial operators such as [`pybamm.Gradient`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/unary_operator.html#pybamm.Gradient) and [`pybamm.Divergence`](https://pybamm.readthedocs.io/en/latest/source/api/expression_tree/unary_operator.html#pybamm.Divergence)). For example, the right hand side of the equation\n",
     "\n",
     "$$\\frac{d c}{dt} = D \\nabla \\cdot \\nabla c$$\n",
     "\n",
@@ -244,7 +244,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "pybamm",
    "language": "python",
    "name": "python3"
   },
@@ -258,7 +258,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.9.16"
   },
   "toc": {
    "base_numbering": 1,
@@ -272,6 +272,11 @@
    "toc_position": {},
    "toc_section_display": true,
    "toc_window_display": true
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "187972e187ab8dfbecfab9e8e194ae6d08262b2d51a54fa40644e3ddb6b5f74c"
+   }
   }
  },
  "nbformat": 4,

examples/notebooks/initialize-model-with-solution.ipynb

@@ -81,8 +81,7 @@
     ").to_numpy()\n",
     "# create interpolant\n",
     "param = model.default_parameter_values\n",
-    "timescale = param.evaluate(model.timescale)\n",
-    "current_interpolant = pybamm.Interpolant(drive_cycle[:, 0], drive_cycle[:, 1], timescale * pybamm.t)\n",
+    "current_interpolant = pybamm.Interpolant(drive_cycle[:, 0], drive_cycle[:, 1], pybamm.t)\n",
     "# set drive cycle\n",
     "param[\"Current function [A]\"] = current_interpolant"
    ]
@@ -312,7 +311,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "pybamm",
    "language": "python",
    "name": "python3"
   },
@@ -326,7 +325,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.0"
+   "version": "3.9.16"
   },
   "toc": {
    "base_numbering": 1,
@@ -340,6 +339,11 @@
    "toc_position": {},
    "toc_section_display": true,
    "toc_window_display": true
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "187972e187ab8dfbecfab9e8e194ae6d08262b2d51a54fa40644e3ddb6b5f74c"
+   }
   }
  },
  "nbformat": 4,

examples/notebooks/models/DFN-with-particle-size-distributions.ipynb

@@ -59,9 +59,7 @@
    "outputs": [],
    "source": [
     "# choose option(s)\n",
-    "options = {\n",
-    "    \"particle size\": \"distribution\"\n",
-    "}\n",
+    "options = {\"particle size\": \"distribution\"}\n",
     "\n",
     "# load model\n",
     "model = pybamm.lithium_ion.DFN(options=options, name=\"MP-DFN\")"
@@ -168,11 +166,11 @@
    "source": [
     "# plot some variables that depend on particle size\n",
     "output_variables = [\n",
-    "    \"Negative particle surface concentration distribution\",\n",
-    "    \"Positive particle surface concentration distribution\",\n",
-    "    \"X-averaged negative particle surface concentration distribution\",\n",
-    "    \"Negative area-weighted particle-size distribution\",\n",
-    "    \"Positive area-weighted particle-size distribution\",\n",
+    "    \"Negative particle surface concentration distribution [mol.m-3]\",\n",
+    "    \"Positive particle surface concentration distribution [mol.m-3]\",\n",
+    "    \"X-averaged negative particle surface concentration distribution [mol.m-3]\",\n",
+    "    \"Negative area-weighted particle-size distribution [m-1]\",\n",
+    "    \"Positive area-weighted particle-size distribution [m-1]\",\n",
     "    \"Terminal voltage [V]\",\n",
     "]\n",
     "\n",
@@ -340,8 +338,8 @@
     "\n",
     "# plot\n",
     "output_variables = [\n",
-    "    \"X-averaged negative area-weighted particle-size distribution\",\n",
-    "    \"X-averaged positive area-weighted particle-size distribution\",\n",
+    "    \"X-averaged negative area-weighted particle-size distribution [m-1]\",\n",
+    "    \"X-averaged positive area-weighted particle-size distribution [m-1]\",\n",
     "    \"Terminal voltage [V]\"\n",
     "]\n",
     "quickplot = pybamm.QuickPlot(\n",
@@ -383,7 +381,7 @@
     "# define current function\n",
     "t_cutoff = 3450   # [s]\n",
     "t_rest = 3600  # [s]\n",
-    "I_typ = params[\"Typical current [A]\"]  # current for 1C\n",
+    "I_typ = params[\"Nominal cell capacity [A.h]\"]  # current for 1C\n",
     "\n",
     "def current(t):\n",
     "    return I_typ * pybamm.EqualHeaviside(t, t_cutoff)\n",
@@ -473,7 +471,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "pybamm",
    "language": "python",
    "name": "python3"
   },
@@ -487,7 +485,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.0"
+   "version": "3.9.16"
   },
   "toc": {
    "base_numbering": 1,
@@ -501,6 +499,11 @@
    "toc_position": {},
    "toc_section_display": true,
    "toc_window_display": true
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "187972e187ab8dfbecfab9e8e194ae6d08262b2d51a54fa40644e3ddb6b5f74c"
+   }
   }
  },
  "nbformat": 4,