Merge pull request #2740 from pybamm-team/other-useful-variables

Other useful variables

Author: valentinsulzer

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

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

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:

docs/source/api/models/submodels/particle/fickian_diffusion.rst

@@ -3,5 +3,3 @@ Fickian Diffusion
 
 .. autoclass:: pybamm.particle.FickianDiffusion
     :members:
-
-

examples/notebooks/Creating Models/5-half-cell-model.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]\"])"
    ]
   },
   {

examples/notebooks/Getting Started/Tutorial 3 - Basic plotting.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\"})"
    ]
   },
   {

examples/notebooks/Getting Started/Tutorial 4 - Setting parameter values.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]\"])"
    ]
   },
   {

examples/notebooks/Getting Started/Tutorial 6 - Managing simulation outputs.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)    "
    ]
   },
   {