Merge branch 'develop' into 2439-autogenerate-docstrings

msaini28r · Mar 8, 2023 · 7347b6a · 7347b6a
2 parents 7eecb68 + f45f4a5
commit 7347b6a
Show file tree

Hide file tree

Showing 143 changed files with 6,242 additions and 5,727 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -9,7 +9,7 @@ repos:
       - id: black
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.0.253"
+    rev: "v0.0.254"
     hooks:
       - id: ruff
         args: [--ignore=E741, --exclude=__init__.py]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,20 @@
 # [Unreleased](https://github.com/pybamm-team/PyBaMM/)
 
+## Features
+
+- Renamed "Terminal voltage [V]" to just "Voltage [V]". "Terminal voltage [V]" can still be used and will return the same value as "Voltage [V]".
+- Added "Negative electrode surface potential difference at separator interface [V]", which is the value of the surface potential difference (`phi_s - phi_e`) at the anode/separator interface, commonly controlled in fast-charging algorithms to avoid plating. Also added "Positive electrode surface potential difference at separator interface [V]". ([#2740](https://github.com/pybamm-team/PyBaMM/pull/2740))
+- Added "Open-circuit voltage [V]", which is the open-circuit voltage as calculated from the bulk particle concentrations. The old variable "Measured open circuit voltage [V]", which referred to the open-circuit potential as calculated from the surface particle concentrations, has been renamed to "Surface open-circuit voltage [V]". ([#2740](https://github.com/pybamm-team/PyBaMM/pull/2740))
+- Added an example for `plot_voltage_components`, explaining what the different voltage components are. ([#2740](https://github.com/pybamm-team/PyBaMM/pull/2740))
+
+## Bug fixes
+
+- Fixed `plot_voltage_components` so that the sum of overpotentials is now equal to the voltage ([#2740](https://github.com/pybamm-team/PyBaMM/pull/2740))
+
 ## Breaking changes
 
+- Renamed "Measured open circuit voltage [V]" to "Surface open-circuit voltage [V]". This variable was calculated from surface particle concentrations, and hence "hid" the overpotential from particle gradients. The new variable "Open-circuit voltage [V]" is calculated from bulk particle concentrations instead. ([#2740](https://github.com/pybamm-team/PyBaMM/pull/2740))
+- Renamed all references to "open circuit" to be "open-circuit" instead. ([#2740](https://github.com/pybamm-team/PyBaMM/pull/2740))
 - 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.2](https://github.com/pybamm-team/PyBaMM/tree/v23.2) - 2023-02-28

diff --git a/docs/source/api/models/submodels/interface/open_circuit_potential.rst b/docs/source/api/models/submodels/interface/open_circuit_potential.rst
@@ -1,4 +1,4 @@
-Open circuit potential models
+Open-circuit potential models
 =============================
 
 .. autoclass:: pybamm.open_circuit_potential.BaseOpenCircuitPotential

diff --git a/docs/source/api/models/submodels/particle/base_particle.rst b/docs/source/api/models/submodels/particle/base_particle.rst
@@ -4,3 +4,5 @@ Particle Base Model
 .. autoclass:: pybamm.particle.BaseParticle
     :members:
 
+.. autoclass:: pybamm.particle.TotalConcentration
+    :members:
diff --git a/docs/source/api/models/submodels/particle/fickian_diffusion.rst b/docs/source/api/models/submodels/particle/fickian_diffusion.rst
@@ -3,5 +3,3 @@ Fickian Diffusion
 
 .. autoclass:: pybamm.particle.FickianDiffusion
     :members:
-
-
diff --git a/examples/notebooks/Creating Models/5-half-cell-model.ipynb b/examples/notebooks/Creating Models/5-half-cell-model.ipynb
diff --git a/examples/notebooks/Getting Started/Tutorial 3 - Basic plotting.ipynb b/examples/notebooks/Getting Started/Tutorial 3 - Basic plotting.ipynb
diff --git a/examples/notebooks/Getting Started/Tutorial 4 - Setting parameter values.ipynb b/examples/notebooks/Getting Started/Tutorial 4 - Setting parameter values.ipynb
@@ -434,7 +434,7 @@
     "model = pybamm.lithium_ion.SPMe()\n",
     "sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
     "sim.solve()\n",
-    "sim.plot([\"Current [A]\", \"Terminal voltage [V]\"])"
+    "sim.plot([\"Current [A]\", \"Voltage [V]\"])"
    ]
   },
   {
@@ -507,7 +507,7 @@
     "sim = pybamm.Simulation(model, parameter_values=parameter_values)\n",
     "t_eval = np.arange(0, 121, 1)\n",
     "sim.solve(t_eval=t_eval)\n",
-    "sim.plot([\"Current [A]\", \"Terminal voltage [V]\"])"
+    "sim.plot([\"Current [A]\", \"Voltage [V]\"])"
    ]
   },
   {

diff --git a/examples/notebooks/Getting Started/Tutorial 6 - Managing simulation outputs.ipynb b/examples/notebooks/Getting Started/Tutorial 6 - Managing simulation outputs.ipynb
@@ -84,7 +84,7 @@
    "outputs": [],
    "source": [
     "t = solution[\"Time [s]\"]\n",
-    "V = solution[\"Terminal voltage [V]\"]"
+    "V = solution[\"Voltage [V]\"]"
    ]
   },
   {
@@ -353,7 +353,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sol.save_data(\"sol_data.pkl\", [\"Current [A]\", \"Terminal voltage [V]\"])"
+    "sol.save_data(\"sol_data.pkl\", [\"Current [A]\", \"Voltage [V]\"])"
    ]
   },
   {
@@ -369,10 +369,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sol.save_data(\"sol_data.csv\", [\"Current [A]\", \"Terminal voltage [V]\"], to_format=\"csv\")\n",
+    "sol.save_data(\"sol_data.csv\", [\"Current [A]\", \"Voltage [V]\"], to_format=\"csv\")\n",
     "# matlab needs names without spaces\n",
-    "sol.save_data(\"sol_data.mat\", [\"Current [A]\", \"Terminal voltage [V]\"], to_format=\"matlab\",\n",
-    "              short_names={\"Current [A]\": \"I\", \"Terminal voltage [V]\": \"V\"})"
+    "sol.save_data(\"sol_data.mat\", [\"Current [A]\", \"Voltage [V]\"], to_format=\"matlab\",\n",
+    "              short_names={\"Current [A]\": \"I\", \"Voltage [V]\": \"V\"})"
    ]
   },
   {

diff --git a/examples/notebooks/Getting Started/Tutorial 7 - Model options.ipynb b/examples/notebooks/Getting Started/Tutorial 7 - Model options.ipynb
@@ -105,7 +105,7 @@
     }
    ],
    "source": [
-    "sim.plot([\"Cell temperature [K]\", \"Total heating [W.m-3]\", \"Current [A]\", \"Terminal voltage [V]\"])"
+    "sim.plot([\"Cell temperature [K]\", \"Total heating [W.m-3]\", \"Current [A]\", \"Voltage [V]\"])"
    ]
   },
   {

diff --git a/examples/notebooks/Getting Started/Tutorial 9 - Changing the mesh.ipynb b/examples/notebooks/Getting Started/Tutorial 9 - Changing the mesh.ipynb
@@ -235,7 +235,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can now pass our list of solutions to the dynamic plot method, allowing use to see the influence of the mesh on the computed terminal voltage. We pass our list of points using the `labels` keyword so that the plots are labeled with the number of points used in the simulation"
+    "We can now pass our list of solutions to the dynamic plot method, allowing use to see the influence of the mesh on the computed voltage. We pass our list of points using the `labels` keyword so that the plots are labeled with the number of points used in the simulation"
    ]
   },
   {
@@ -269,7 +269,7 @@
     }
    ],
    "source": [
-    "pybamm.dynamic_plot(solutions, [\"Terminal voltage [V]\"], time_unit=\"seconds\", labels=npts)    "
+    "pybamm.dynamic_plot(solutions, [\"Voltage [V]\"], time_unit=\"seconds\", labels=npts)    "
    ]
   },
   {

diff --git a/examples/notebooks/change-settings.ipynb b/examples/notebooks/change-settings.ipynb
@@ -79,7 +79,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To verify the solution, we can look at a plot of the Terminal voltage over time"
+    "To verify the solution, we can look at a plot of the Voltage over time"
    ]
   },
   {
@@ -100,10 +100,10 @@
    ],
    "source": [
     "time = solution[\"Time [h]\"].entries\n",
-    "voltage = solution[\"Terminal voltage [V]\"].entries\n",
+    "voltage = solution[\"Voltage [V]\"].entries\n",
     "plt.plot(time, voltage, lw=2, label=model.name)\n",
     "plt.xlabel(\"Time [h]\", fontsize=15)\n",
-    "plt.ylabel(\"Terminal voltage [V]\", fontsize=15)\n",
+    "plt.ylabel(\"Voltage [V]\", fontsize=15)\n",
     "plt.show()"
    ]
   },
@@ -422,7 +422,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In order to compare solutions with different parameter values, parameters must be changed to `InputParameter` objects, whose value can then be specified when solving. For example, we can compare the Terminal voltage calculated using both the old and new current values."
+    "In order to compare solutions with different parameter values, parameters must be changed to `InputParameter` objects, whose value can then be specified when solving. For example, we can compare the Voltage calculated using both the old and new current values."
    ]
   },
   {
@@ -452,17 +452,17 @@
     "# Solution with current = 0.68\n",
     "old_solution = solver.solve(model, t_eval, inputs={\"Current function [A]\": 0.68})\n",
     "old_time = old_solution[\"Time [h]\"].entries\n",
-    "old_voltage = old_solution[\"Terminal voltage [V]\"].entries\n",
+    "old_voltage = old_solution[\"Voltage [V]\"].entries\n",
     "\n",
     "# Solution with current = 1.4\n",
     "new_solution = solver.solve(model, t_eval, inputs={\"Current function [A]\": 1.4})\n",
     "new_time = new_solution[\"Time [h]\"].entries\n",
-    "new_voltage = new_solution[\"Terminal voltage [V]\"].entries\n",
+    "new_voltage = new_solution[\"Voltage [V]\"].entries\n",
     "\n",
     "plt.plot(old_time, old_voltage, lw=2, label=\"Current = 0.68\")\n",
     "plt.plot(new_time, new_voltage, lw=2, label=\"Current = 1.4\")\n",
     "plt.xlabel(\"Time [h]\", fontsize=15)\n",
-    "plt.ylabel(\"Terminal voltage [V]\", fontsize=15)\n",
+    "plt.ylabel(\"Voltage [V]\", fontsize=15)\n",
     "plt.legend(fontsize=15)\n",
     "plt.show()"
    ]

diff --git a/examples/notebooks/models/DFN-with-particle-size-distributions.ipynb b/examples/notebooks/models/DFN-with-particle-size-distributions.ipynb
@@ -171,7 +171,7 @@
     "    \"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",
+    "    \"Voltage [V]\",\n",
     "]\n",
     "\n",
     "sim.plot(output_variables=output_variables)"
@@ -340,7 +340,7 @@
     "output_variables = [\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",
+    "    \"Voltage [V]\"\n",
     "]\n",
     "quickplot = pybamm.QuickPlot(\n",
     "    [sim, sim_custom], output_variables=output_variables, labels=[\"default lognormals\", \"custom\"]\n",
@@ -416,8 +416,8 @@
     }
    ],
    "source": [
-    "# plot current, terminal voltage \n",
-    "qp = pybamm.QuickPlot(sims, output_variables=[\"Current [A]\", \"Terminal voltage [V]\"])\n",
+    "# plot current, voltage \n",
+    "qp = pybamm.QuickPlot(sims, output_variables=[\"Current [A]\", \"Voltage [V]\"])\n",
     "qp.plot(0)"
    ]
   },

diff --git a/examples/notebooks/models/MPM.ipynb b/examples/notebooks/models/MPM.ipynb
@@ -74,7 +74,7 @@
     "j_\\text{k}=j_{\\text{0,k}} \\sinh\\left[\\frac{F}{2R_g T}(\\Delta \\phi_{\\text{s,k}}-U_{\\text{k}}(c_{\\text{s},\\text{k}}))\\right], \\ \\ j_{\\text{0,k}} =  m_{\\text{k}}(c_{\\text{e}}c_{\\text{s,k}})^{1/2}(c_\\text{k,max}-c_{\\text{s,k}})^{1/2}.\n",
     "$$\n",
     "This gives an integral (or algebraic once discretized) equation for $\\Delta \\phi_{\\text{s,k}}$ which is coupled to the concentration equations above.\n",
-    "The terminal voltage is then obtained from\n",
+    "The voltage is then obtained from\n",
     "$$\n",
     "V = \\Delta \\phi_{\\text{s,p}} - \\Delta \\phi_{\\text{s,n}}\n",
     "$$"
@@ -328,7 +328,7 @@
     "    \"X-averaged positive electrode interfacial current density distribution [A.m-2]\",\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",
+    "    \"Voltage [V]\",\n",
     "]\n",
     "\n",
     "sim.plot(output_variables=output_variables)"
@@ -908,7 +908,7 @@
     "    \"X-averaged positive electrode interfacial current density distribution [A.m-2]\",\n",
     "    \"Negative current collector potential [V]\",\n",
     "    \"Positive current collector potential [V]\",\n",
-    "    \"Terminal voltage [V]\",\n",
+    "    \"Voltage [V]\",\n",
     "]\n",
     "pybamm.dynamic_plot(sim_cc, output_variables=output_variables)"
    ]

diff --git a/examples/notebooks/models/SEI-on-cracks.ipynb b/examples/notebooks/models/SEI-on-cracks.ipynb
@@ -121,12 +121,12 @@
    "outputs": [],
    "source": [
     "t1 = sol1[\"Time [s]\"].entries\n",
-    "V1 = sol1[\"Terminal voltage [V]\"].entries\n",
+    "V1 = sol1[\"Voltage [V]\"].entries\n",
     "SEI1 = sol1[\"Loss of lithium to SEI [mol]\"].entries\n",
     "lithium_neg1 = sol1[\"Total lithium in negative electrode [mol]\"].entries\n",
     "lithium_pos1 = sol1[\"Total lithium in positive electrode [mol]\"].entries\n",
     "t2 = sol2[\"Time [s]\"].entries\n",
-    "V2 = sol2[\"Terminal voltage [V]\"].entries\n",
+    "V2 = sol2[\"Voltage [V]\"].entries\n",
     "SEI2 = sol2[\"Loss of lithium to SEI [mol]\"].entries + sol2[\"Loss of lithium to SEI on cracks [mol]\"].entries\n",
     "lithium_neg2 = sol2[\"Total lithium in negative electrode [mol]\"].entries\n",
     "lithium_pos2 = sol2[\"Total lithium in positive electrode [mol]\"].entries"
@@ -156,7 +156,7 @@
     "ax1.plot(t1,V1,label=\"without cracking\")\n",
     "ax1.plot(t2,V2,label=\"with cracking\")\n",
     "ax1.set_xlabel(\"Time [s]\")\n",
-    "ax1.set_ylabel(\"Terminal voltage [V]\")\n",
+    "ax1.set_ylabel(\"Voltage [V]\")\n",
     "ax1.legend()\n",
     "ax2.plot(t1,SEI1,label=\"without cracking\")\n",
     "ax2.plot(t2,SEI2,label=\"with cracking\")\n",
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,5 +3,3 @@ Fickian Diffusion

		.. autoclass:: pybamm.particle.FickianDiffusion
		:members:
-Original file line number
+Diff line change
@@ Expand Up / @@ -105,7 +105,7 @@ @@
         }
        ],
        "source": [
-        "sim.plot([\"Cell temperature [K]\", \"Total heating [W.m-3]\", \"Current [A]\", \"Terminal voltage [V]\"])"
+        "sim.plot([\"Cell temperature [K]\", \"Total heating [W.m-3]\", \"Current [A]\", \"Voltage [V]\"])"
        ]
       },
       {
@@ Expand Down @@