Repository: pybamm-team/PyBaMM
Pull request #5027 (2025-05-21 16:35:19)

Rename `MSMR` parameters from symbols to plain English names with units
# Description

The MSMR parameter names used symbols instead of following the standard pybamm convention of having a fully spelled-out name. This PR standardizes the MSMR parameter names in a non-breaking way, following the renaming of `"electrode diffusivity"` to `"particle diffusivity"` in https://github.com/pybamm-team/PyBaMM/pull/3624

Examples:
- `"X_n_5"` -> `"Negative electrode host site occupancy fraction (5)"`
- `"X_p_l_3"` -> `"Positive electrode host site occupancy fraction in lithiation (3)"`
- `"X_n_d_5"` -> `"Negative electrode host site occupancy fraction in delithiation (5)"`
- `"Q_p_3"` -> `"Positive electrode host site occupancy capacity (3) [A.h]"`
- `"w_n_2"` -> `"Negative electrode host site ideality factor (2)"`
- `"U0_p_d_4"` -> `"Positive electrode host site standard potential in delithiation (4) [V]"`
- `"a_p_d_5"` -> `"Positive electrode host site charge transfer coefficient in delithiation (5)"`
- `"j0_ref_n_0"` -> `"Negative electrode host site reference exchange-current density (0) [A.m-2]"`

## Type of change

Please add a line in the relevant section of [CHANGELOG.md](https://github.com/pybamm-team/PyBaMM/blob/develop/CHANGELOG.md) to document the change (include PR #)

# Important checks:

Please confirm the following before marking the PR as ready for review:
- No style issues: `nox -s pre-commit`
- All tests pass: `nox -s tests`
- The documentation builds: `nox -s doctests`
- Code is commented for hard-to-understand areas
- Tests added that prove fix is effective or that feature works


review-notebook-app[bot]: Check out this pull request on&nbsp; <a href="https://app.reviewnb.com/pybamm-team/PyBaMM/pull/5027"><img align="absmiddle"  alt="ReviewNB" height="28" class="BotMessageButtonImage" src="https://raw.githubusercontent.com/ReviewNB/support/master/images/button_reviewnb.png"/></a> 

 See visual diffs & provide feedback on Jupyter Notebooks. 

---

 <i>Powered by <a href='https://www.reviewnb.com/?utm_source=gh'>ReviewNB</a></i>

Patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 06e1858e4..2bfd7adb5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # [Unreleased](https://github.com/pybamm-team/PyBaMM/)
 
+## Features
+
+- Renamed MSMR parameters from symbols to written out names with units as a non-breaking change with a deprecation warning. ([#5027](https://github.com/pybamm-team/PyBaMM/pull/5027))
+
 ## Optimizations
 
 - Update docs, examples and tests to use `IDAKLUSolver`. ([#4996](https://github.com/pybamm-team/PyBaMM/pull/4996))
diff --git a/docs/source/examples/notebooks/models/MSMR.ipynb b/docs/source/examples/notebooks/models/MSMR.ipynb
index f188b809f..42d59f37d 100644
--- a/docs/source/examples/notebooks/models/MSMR.ipynb
+++ b/docs/source/examples/notebooks/models/MSMR.ipynb
@@ -17,6 +17,9 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "\n",
+      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m A new release of pip is available: \u001b[0m\u001b[31;49m25.0.1\u001b[0m\u001b[39;49m -> \u001b[0m\u001b[32;49m25.1.1\u001b[0m\n",
+      "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m To update, run: \u001b[0m\u001b[32;49mpip install --upgrade pip\u001b[0m\n",
       "Note: you may need to restart the kernel to use updated packages.\n"
      ]
     }
@@ -107,7 +110,14 @@
    "metadata": {},
    "source": [
     "## Parameterization of the MSMR model\n",
-    "The behaviour of MSMR model is characterised by the parameters $X_j$, $U^0_j$, $\\omega_j$, $\\alpha_j$, and $i_{0,j}^{ref}$. Let's take a look at their values in the example parameter set provided in PyBaMM. The thermodynamic parameter values are taken from Verbrugge et al. (2017) and correspond to a graphite negative electrode and NMC positive electrode. The remaining value are based on a parameterization of the LG M50 cell, from Chen et al. (2020).\n",
+    "The behaviour of MSMR model is characterised by the parameters:\n",
+    "- $X_j$: `host site occupancy fraction (j)`\n",
+    "- $U^0_j$: `host site standard potential (j) [V]`\n",
+    "- $\\omega_j$: `host site ideality factor (j)`\n",
+    "- $\\alpha_j$: `host site charge transfer coefficient (j)`\n",
+    "- $i_{0,j}^{ref}$: `host site reference exchange-current density (j) [A.m-2]`\n",
+    "\n",
+    "Let's take a look at their values in the example parameter set provided in PyBaMM. The thermodynamic parameter values are taken from Verbrugge et al. (2017) and correspond to a graphite negative electrode and NMC positive electrode. The remaining value are based on a parameterization of the LG M50 cell, from Chen et al. (2020).\n",
     "\n",
     "We first load in the MSMR model and specify the number of reactions in each electrode"
    ]
@@ -138,18 +148,56 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "negative electrode:\n",
-      "X_n_0 = 0.43336, U0_n_0 = 0.08843, w_n_0 = 0.08611, a_n_0 = 0.5 j0_ref_n_0 = 2.7\n",
-      "X_n_1 = 0.23963, U0_n_1 = 0.12799, w_n_1 = 0.08009, a_n_1 = 0.5 j0_ref_n_1 = 2.7\n",
-      "X_n_2 = 0.15018, U0_n_2 = 0.14331, w_n_2 = 0.72469, a_n_2 = 0.5 j0_ref_n_2 = 2.7\n",
-      "X_n_3 = 0.05462, U0_n_3 = 0.16984, w_n_3 = 2.53277, a_n_3 = 0.5 j0_ref_n_3 = 2.7\n",
-      "X_n_4 = 0.06744, U0_n_4 = 0.21446, w_n_4 = 0.0947, a_n_4 = 0.5 j0_ref_n_4 = 2.7\n",
-      "X_n_5 = 0.05476, U0_n_5 = 0.36325, w_n_5 = 5.97354, a_n_5 = 0.5 j0_ref_n_5 = 2.7\n",
-      "positive electrode:\n",
-      "X_p_0 = 0.13442, U0_p_0 = 3.62274, w_p_0 = 0.9671, a_p_0 = 0.5 j0_ref_p_0 = 5\n",
-      "X_p_1 = 0.3246, U0_p_1 = 3.72645, w_p_1 = 1.39712, a_p_1 = 0.5 j0_ref_p_1 = 5\n",
-      "X_p_2 = 0.21118, U0_p_2 = 3.90575, w_p_2 = 3.505, a_p_2 = 0.5 j0_ref_p_2 = 5\n",
-      "X_p_3 = 0.3298, U0_p_3 = 4.22955, w_p_3 = 5.52757, a_p_3 = 1 j0_ref_p_3 = 1000000.0\n"
+      "Negative electrode host site occupancy fraction (0) = 0.43336\n",
+      "Negative electrode host site standard potential (0) [V] = 0.08843\n",
+      "Negative electrode host site ideality factor (0) = 0.08611\n",
+      "Negative electrode host site charge transfer coefficient (0) = 0.5\n",
+      "Negative electrode host site reference exchange-current density (0) [A.m-2] = 2.7\n",
+      "Negative electrode host site occupancy fraction (1) = 0.23963\n",
+      "Negative electrode host site standard potential (1) [V] = 0.12799\n",
+      "Negative electrode host site ideality factor (1) = 0.08009\n",
+      "Negative electrode host site charge transfer coefficient (1) = 0.5\n",
+      "Negative electrode host site reference exchange-current density (1) [A.m-2] = 2.7\n",
+      "Negative electrode host site occupancy fraction (2) = 0.15018\n",
+      "Negative electrode host site standard potential (2) [V] = 0.14331\n",
+      "Negative electrode host site ideality factor (2) = 0.72469\n",
+      "Negative electrode host site charge transfer coefficient (2) = 0.5\n",
+      "Negative electrode host site reference exchange-current density (2) [A.m-2] = 2.7\n",
+      "Negative electrode host site occupancy fraction (3) = 0.05462\n",
+      "Negative electrode host site standard potential (3) [V] = 0.16984\n",
+      "Negative electrode host site ideality factor (3) = 2.53277\n",
+      "Negative electrode host site charge transfer coefficient (3) = 0.5\n",
+      "Negative electrode host site reference exchange-current density (3) [A.m-2] = 2.7\n",
+      "Negative electrode host site occupancy fraction (4) = 0.06744\n",
+      "Negative electrode host site standard potential (4) [V] = 0.21446\n",
+      "Negative electrode host site ideality factor (4) = 0.0947\n",
+      "Negative electrode host site charge transfer coefficient (4) = 0.5\n",
+      "Negative electrode host site reference exchange-current density (4) [A.m-2] = 2.7\n",
+      "Negative electrode host site occupancy fraction (5) = 0.05476\n",
+      "Negative electrode host site standard potential (5) [V] = 0.36325\n",
+      "Negative electrode host site ideality factor (5) = 5.97354\n",
+      "Negative electrode host site charge transfer coefficient (5) = 0.5\n",
+      "Negative electrode host site reference exchange-current density (5) [A.m-2] = 2.7\n",
+      "Positive electrode host site occupancy fraction (0) = 0.13442\n",
+      "Positive electrode host site standard potential (0) [V] = 3.62274\n",
+      "Positive electrode host site ideality factor (0) = 0.9671\n",
+      "Positive electrode host site charge transfer coefficient (0) = 0.5\n",
+      "Positive electrode host site reference exchange-current density (0) [A.m-2] = 5\n",
+      "Positive electrode host site occupancy fraction (1) = 0.3246\n",
+      "Positive electrode host site standard potential (1) [V] = 3.72645\n",
+      "Positive electrode host site ideality factor (1) = 1.39712\n",
+      "Positive electrode host site charge transfer coefficient (1) = 0.5\n",
+      "Positive electrode host site reference exchange-current density (1) [A.m-2] = 5\n",
+      "Positive electrode host site occupancy fraction (2) = 0.21118\n",
+      "Positive electrode host site standard potential (2) [V] = 3.90575\n",
+      "Positive electrode host site ideality factor (2) = 3.505\n",
+      "Positive electrode host site charge transfer coefficient (2) = 0.5\n",
+      "Positive electrode host site reference exchange-current density (2) [A.m-2] = 5\n",
+      "Positive electrode host site occupancy fraction (3) = 0.3298\n",
+      "Positive electrode host site standard potential (3) [V] = 4.22955\n",
+      "Positive electrode host site ideality factor (3) = 5.52757\n",
+      "Positive electrode host site charge transfer coefficient (3) = 1\n",
+      "Positive electrode host site reference exchange-current density (3) [A.m-2] = 1000000.0\n"
      ]
     }
    ],
@@ -158,18 +206,19 @@
     "\n",
     "# Loop over domains\n",
     "for domain in [\"negative\", \"positive\"]:\n",
-    "    print(f\"{domain} electrode:\")\n",
-    "    d = domain[0]\n",
+    "    Electrode = domain.capitalize()\n",
     "    # Loop over reactions\n",
     "    N = int(parameter_values[\"Number of reactions in \" + domain + \" electrode\"])\n",
     "    for i in range(N):\n",
-    "        print(\n",
-    "            f\"X_{d}_{i} = {parameter_values[f'X_{d}_{i}']}, \"\n",
-    "            f\"U0_{d}_{i} = {parameter_values[f'U0_{d}_{i}']}, \"\n",
-    "            f\"w_{d}_{i} = {parameter_values[f'w_{d}_{i}']}, \"\n",
-    "            f\"a_{d}_{i} = {parameter_values[f'a_{d}_{i}']} \"\n",
-    "            f\"j0_ref_{d}_{i} = {parameter_values[f'j0_ref_{d}_{i}']}\"\n",
-    "        )"
+    "        names = [\n",
+    "            f\"{Electrode} electrode host site occupancy fraction ({i})\",\n",
+    "            f\"{Electrode} electrode host site standard potential ({i}) [V]\",\n",
+    "            f\"{Electrode} electrode host site ideality factor ({i})\",\n",
+    "            f\"{Electrode} electrode host site charge transfer coefficient ({i})\",\n",
+    "            f\"{Electrode} electrode host site reference exchange-current density ({i}) [A.m-2]\",\n",
+    "        ]\n",
+    "        for name in names:\n",
+    "            print(f\"{name} = {parameter_values[name]}\")"
    ]
   },
   {
@@ -202,6 +251,9 @@
     "param_n = param.n.prim\n",
     "param_p = param.p.prim\n",
     "\n",
+    "num_reactions_n = int(parameter_values[\"Number of reactions in negative electrode\"])\n",
+    "num_reactions_p = int(parameter_values[\"Number of reactions in positive electrode\"])\n",
+    "\n",
     "# set up ranges for plotting\n",
     "U_n = pybamm.linspace(0.05, 1.1, 1000)\n",
     "U_p = pybamm.linspace(2.8, 4.4, 1000)\n",
@@ -225,7 +277,7 @@
     "ax[0, 1].set_ylabel(\"U_p [V]\")\n",
     "\n",
     "# fractional occupancy vs potential\n",
-    "for i in range(6):\n",
+    "for i in range(num_reactions_n):\n",
     "    xj = param_n.x_j(U_n, T, i)\n",
     "    ax[1, 0].plot(\n",
     "        parameter_values.evaluate(x_n),\n",
@@ -236,7 +288,7 @@
     "ax[1, 0].set_xlabel(\"x_n\")\n",
     "ax[1, 0].set_ylabel(\"x_n_j\")\n",
     "ax[1, 0].legend()\n",
-    "for i in range(4):\n",
+    "for i in range(num_reactions_p):\n",
     "    xj = param_p.x_j(U_p, T, i)\n",
     "    ax[1, 1].plot(\n",
     "        parameter_values.evaluate(x_p),\n",
@@ -249,7 +301,7 @@
     "ax[1, 1].legend()\n",
     "\n",
     "# exchange current density vs potential\n",
-    "for i in range(6):\n",
+    "for i in range(num_reactions_n):\n",
     "    xj = param_n.x_j(U_n, T, i)\n",
     "    j0 = param_n.j0_j(c_e, U_n, T, i)\n",
     "    ax[2, 0].plot(\n",
@@ -261,7 +313,7 @@
     "ax[2, 0].set_xlabel(\"x_n\")\n",
     "ax[2, 0].set_ylabel(\"j0_n_j [A.m-2]\")\n",
     "ax[2, 0].legend()\n",
-    "for i in range(4):\n",
+    "for i in range(num_reactions_p):\n",
     "    xj = param_p.x_j(U_p, T, i)\n",
     "    j0 = param_p.j0_j(c_e, U_p, T, i)\n",
     "    ax[2, 1].plot(\n",
@@ -303,7 +355,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.solvers.solution.Solution at 0x364aaa150>"
+       "<pybamm.solvers.solution.Solution at 0x340466ad0>"
       ]
      },
      "execution_count": 5,
@@ -343,7 +395,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "500e074213c84c2986982d16d16613c9",
+       "model_id": "fd76c72d10da44409d278ca058cd3fd8",
        "version_major": 2,
        "version_minor": 0
       },
@@ -357,7 +409,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x363ee33d0>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x341db8f10>"
       ]
      },
      "execution_count": 6,
@@ -397,7 +449,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "8e667aaa7aaf4e57b523bd7085d9a4b7",
+       "model_id": "cfb210d04b62406bbd2d0d9e0cc4e079",
        "version_major": 2,
        "version_minor": 0
       },
@@ -411,7 +463,7 @@
     {
      "data": {
       "text/plain": [
-       "<pybamm.plotting.quick_plot.QuickPlot at 0x363910310>"
+       "<pybamm.plotting.quick_plot.QuickPlot at 0x34192bd90>"
       ]
      },
      "execution_count": 7,
@@ -421,10 +473,10 @@
    ],
    "source": [
     "xns = [\n",
-    "    f\"Average x_n_{i}\" for i in range(6)\n",
+    "    f\"Average x_n_{i}\" for i in range(num_reactions_n)\n",
     "]  # negative electrode reactions: x_n_0, x_n_1, ..., x_n_5\n",
     "xps = [\n",
-    "    f\"Average x_p_{i}\" for i in range(4)\n",
+    "    f\"Average x_p_{i}\" for i in range(num_reactions_p)\n",
     "]  # positive electrode reactions: x_p_0, x_p_1, ..., x_p_3\n",
     "sim.plot(\n",
     "    [\n",
@@ -454,7 +506,7 @@
     {
      "data": {
       "text/plain": [
-       "<matplotlib.legend.Legend at 0x3696c8090>"
+       "<matplotlib.legend.Legend at 0x347fd41d0>"
       ]
      },
      "execution_count": 8,
@@ -537,7 +589,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv",
+   "display_name": ".env",
    "language": "python",
    "name": "python3"
   },
@@ -552,11 +604,6 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.11.7"
-  },
-  "vscode": {
-   "interpreter": {
-    "hash": "9ff3d0c7e37de5f5aa47f4f719e4c84fc6cba7b39c571a05173422444e82fa58"
-   }
   }
  },
  "nbformat": 4,
diff --git a/src/pybamm/input/parameters/lithium_ion/MSMR_example_set.py b/src/pybamm/input/parameters/lithium_ion/MSMR_example_set.py
index 55033431b..dca4c06d4 100644
--- a/src/pybamm/input/parameters/lithium_ion/MSMR_example_set.py
+++ b/src/pybamm/input/parameters/lithium_ion/MSMR_example_set.py
@@ -104,36 +104,36 @@ def get_parameter_values():
         "Contact resistance [Ohm]": 0,
         # negative electrode
         "Number of reactions in negative electrode": 6,
-        "U0_n_0": 0.08843,
-        "X_n_0": 0.43336,
-        "w_n_0": 0.08611,
-        "a_n_0": 0.5,
-        "j0_ref_n_0": 2.7,
-        "U0_n_1": 0.12799,
-        "X_n_1": 0.23963,
-        "w_n_1": 0.08009,
-        "a_n_1": 0.5,
-        "j0_ref_n_1": 2.7,
-        "U0_n_2": 0.14331,
-        "X_n_2": 0.15018,
-        "w_n_2": 0.72469,
-        "a_n_2": 0.5,
-        "j0_ref_n_2": 2.7,
-        "U0_n_3": 0.16984,
-        "X_n_3": 0.05462,
-        "w_n_3": 2.53277,
-        "a_n_3": 0.5,
-        "j0_ref_n_3": 2.7,
-        "U0_n_4": 0.21446,
-        "X_n_4": 0.06744,
-        "w_n_4": 0.09470,
-        "a_n_4": 0.5,
-        "j0_ref_n_4": 2.7,
-        "U0_n_5": 0.36325,
-        "X_n_5": 0.05476,
-        "w_n_5": 5.97354,
-        "a_n_5": 0.5,
-        "j0_ref_n_5": 2.7,
+        "Negative electrode host site standard potential (0) [V]": 0.08843,
+        "Negative electrode host site occupancy fraction (0)": 0.43336,
+        "Negative electrode host site ideality factor (0)": 0.08611,
+        "Negative electrode host site charge transfer coefficient (0)": 0.5,
+        "Negative electrode host site reference exchange-current density (0) [A.m-2]": 2.7,
+        "Negative electrode host site standard potential (1) [V]": 0.12799,
+        "Negative electrode host site occupancy fraction (1)": 0.23963,
+        "Negative electrode host site ideality factor (1)": 0.08009,
+        "Negative electrode host site charge transfer coefficient (1)": 0.5,
+        "Negative electrode host site reference exchange-current density (1) [A.m-2]": 2.7,
+        "Negative electrode host site standard potential (2) [V]": 0.14331,
+        "Negative electrode host site occupancy fraction (2)": 0.15018,
+        "Negative electrode host site ideality factor (2)": 0.72469,
+        "Negative electrode host site charge transfer coefficient (2)": 0.5,
+        "Negative electrode host site reference exchange-current density (2) [A.m-2]": 2.7,
+        "Negative electrode host site standard potential (3) [V]": 0.16984,
+        "Negative electrode host site occupancy fraction (3)": 0.05462,
+        "Negative electrode host site ideality factor (3)": 2.53277,
+        "Negative electrode host site charge transfer coefficient (3)": 0.5,
+        "Negative electrode host site reference exchange-current density (3) [A.m-2]": 2.7,
+        "Negative electrode host site standard potential (4) [V]": 0.21446,
+        "Negative electrode host site occupancy fraction (4)": 0.06744,
+        "Negative electrode host site ideality factor (4)": 0.09470,
+        "Negative electrode host site charge transfer coefficient (4)": 0.5,
+        "Negative electrode host site reference exchange-current density (4) [A.m-2]": 2.7,
+        "Negative electrode host site standard potential (5) [V]": 0.36325,
+        "Negative electrode host site occupancy fraction (5)": 0.05476,
+        "Negative electrode host site ideality factor (5)": 5.97354,
+        "Negative electrode host site charge transfer coefficient (5)": 0.5,
+        "Negative electrode host site reference exchange-current density (5) [A.m-2]": 2.7,
         "Negative electrode conductivity [S.m-1]": 215.0,
         "Maximum concentration in negative electrode [mol.m-3]": 33133.0,
         "Negative particle diffusivity [m2.s-1]": 3.3e-14,
@@ -145,26 +145,26 @@ def get_parameter_values():
         "Negative electrode OCP entropic change [V.K-1]": 0.0,
         # positive electrode
         "Number of reactions in positive electrode": 4,
-        "U0_p_0": 3.62274,
-        "X_p_0": 0.13442,
-        "w_p_0": 0.96710,
-        "a_p_0": 0.5,
-        "j0_ref_p_0": 5,
-        "U0_p_1": 3.72645,
-        "X_p_1": 0.32460,
-        "w_p_1": 1.39712,
-        "a_p_1": 0.5,
-        "j0_ref_p_1": 5,
-        "U0_p_2": 3.90575,
-        "X_p_2": 0.21118,
-        "w_p_2": 3.50500,
-        "a_p_2": 0.5,
-        "j0_ref_p_2": 5,
-        "U0_p_3": 4.22955,
-        "X_p_3": 0.32980,
-        "w_p_3": 5.52757,
-        "a_p_3": 1,
-        "j0_ref_p_3": 1e6,
+        "Positive electrode host site standard potential (0) [V]": 3.62274,
+        "Positive electrode host site occupancy fraction (0)": 0.13442,
+        "Positive electrode host site ideality factor (0)": 0.96710,
+        "Positive electrode host site charge transfer coefficient (0)": 0.5,
+        "Positive electrode host site reference exchange-current density (0) [A.m-2]": 5,
+        "Positive electrode host site standard potential (1) [V]": 3.72645,
+        "Positive electrode host site occupancy fraction (1)": 0.32460,
+        "Positive electrode host site ideality factor (1)": 1.39712,
+        "Positive electrode host site charge transfer coefficient (1)": 0.5,
+        "Positive electrode host site reference exchange-current density (1) [A.m-2]": 5,
+        "Positive electrode host site standard potential (2) [V]": 3.90575,
+        "Positive electrode host site occupancy fraction (2)": 0.21118,
+        "Positive electrode host site ideality factor (2)": 3.50500,
+        "Positive electrode host site charge transfer coefficient (2)": 0.5,
+        "Positive electrode host site reference exchange-current density (2) [A.m-2]": 5,
+        "Positive electrode host site standard potential (3) [V]": 4.22955,
+        "Positive electrode host site occupancy fraction (3)": 0.32980,
+        "Positive electrode host site ideality factor (3)": 5.52757,
+        "Positive electrode host site charge transfer coefficient (3)": 1,
+        "Positive electrode host site reference exchange-current density (3) [A.m-2]": 1e6,
         "Positive electrode conductivity [S.m-1]": 0.18,
         "Maximum concentration in positive electrode [mol.m-3]": 63104.0,
         "Positive particle diffusivity [m2.s-1]": 4e-15,
diff --git a/src/pybamm/models/full_battery_models/lithium_ion/msmr.py b/src/pybamm/models/full_battery_models/lithium_ion/msmr.py
index f1ec7f90b..311dacd86 100644
--- a/src/pybamm/models/full_battery_models/lithium_ion/msmr.py
+++ b/src/pybamm/models/full_battery_models/lithium_ion/msmr.py
@@ -1,4 +1,5 @@
 import pybamm
+import re
 from .dfn import DFN
 
 
@@ -47,3 +48,79 @@ class MSMR(DFN):
     @property
     def default_parameter_values(self):
         return pybamm.ParameterValues("MSMR_Example")
+
+
+# Replace the deprecated MSMR parameter names with the new ones
+# matches e.g. "X_p_3", "X_n_l_300", "Q_n_d_0", "U0_p_42", "a_n_5", "j0_ref_p_d_12", etc.
+_VALID_NAME_RE = re.compile(
+    r"^(?P<base>X|Q|w|U0|a|j0_ref)"  # base (now includes a and j0_ref)
+    r"_(?P<elec>n|p)"  # electrode
+    r"(?:_(?P<qual>[ld]))?"  # optional qualifier
+    r"_(?P<idx>[0-9]+)$"  # non-negative integer index
+)
+
+
+def is_deprecated_msmr_name(key: str) -> bool:
+    """
+    Return True if `key` follows the (legacy) MSMR naming convention:
+      BASE ∈ {X, Q, w, U0, a, j0_ref}
+      electrode ∈ {n, p}
+      optional qualifier ∈ {l, d}
+      index ∈ non-negative integer
+    """
+    return bool(_VALID_NAME_RE.fullmatch(key))
+
+
+_BASE_DESC = {
+    "X": "host site occupancy fraction",
+    "Q": "host site occupancy capacity",
+    "w": "host site ideality factor",
+    "U0": "host site standard potential",
+    "a": "host site charge transfer coefficient",
+    "j0_ref": "host site reference exchange-current density",
+}
+
+# only Q, U0, and j0_ref have units
+_UNITS = {
+    "Q": " [A.h]",
+    "U0": " [V]",
+    "j0_ref": " [A.m-2]",
+}
+
+_ELECTRODE = {
+    "n": "Negative",
+    "p": "Positive",
+}
+
+_QUALIFIER = {
+    "l": "lithiation",
+    "d": "delithiation",
+}
+
+
+def replace_deprecated_msmr_name(key: str) -> str:
+    """
+    Convert e.g. "X_n_d_3" →
+        "Negative electrode host site occupancy fraction (delithiation) (3)"
+    and likewise for a/U0/Q/j0_ref.
+    """
+    m = _VALID_NAME_RE.fullmatch(key)
+    if not m:
+        raise ValueError(f"Invalid MSMR name: {key!r}")
+
+    base = m.group("base")
+    elec = m.group("elec")
+    qual = m.group("qual")
+    idx = m.group("idx")
+
+    # start constructing the description
+    desc = f"{_ELECTRODE[elec]} electrode {_BASE_DESC[base]}"
+    if qual:
+        desc += f" ({_QUALIFIER[qual]})"
+    desc += f" ({idx})"
+
+    # tack on units if this base has them
+    if base in _UNITS:
+        desc += _UNITS[base]
+
+    return desc
diff --git a/src/pybamm/parameters/lithium_ion_parameters.py b/src/pybamm/parameters/lithium_ion_parameters.py
index ee3c01d0a..ad9cfbcd0 100644
--- a/src/pybamm/parameters/lithium_ion_parameters.py
+++ b/src/pybamm/parameters/lithium_ion_parameters.py
@@ -679,32 +679,41 @@ class ParticleLithiumIonParameters(BaseParameters):
         "Available host sites indexed by reaction j"
         inputs = {"Temperature [K]": T}
         domain = self.domain
-        d = domain[0]
-        Xj = pybamm.FunctionParameter(f"X_{d}_{index}", inputs)
+        Electrode = domain.capitalize()
+        Xj = pybamm.FunctionParameter(
+            f"{Electrode} electrode host site occupancy fraction ({index})", inputs
+        )
         return Xj
 
     def U0_j(self, T, index):
         "Equilibrium potential indexed by reaction j"
         inputs = {"Temperature [K]": T}
         domain = self.domain
-        d = domain[0]
-        U0j = pybamm.FunctionParameter(f"U0_{d}_{index}", inputs)
+        Electrode = domain.capitalize()
+        U0j = pybamm.FunctionParameter(
+            f"{Electrode} electrode host site standard potential ({index}) [V]", inputs
+        )
         return U0j
 
     def w_j(self, T, index):
         "Order parameter indexed by reaction j"
         inputs = {"Temperature [K]": T}
         domain = self.domain
-        d = domain[0]
-        wj = pybamm.FunctionParameter(f"w_{d}_{index}", inputs)
+        Electrode = domain.capitalize()
+        wj = pybamm.FunctionParameter(
+            f"{Electrode} electrode host site ideality factor ({index})", inputs
+        )
         return wj
 
     def alpha_bv_j(self, T, index):
         "Dimensional Butler-Volmer exchange-current density indexed by reaction j"
         inputs = {"Temperature [K]": T}
         domain = self.domain
-        d = domain[0]
-        alpha_bv_j = pybamm.FunctionParameter(f"a_{d}_{index}", inputs)
+        Electrode = domain.capitalize()
+        alpha_bv_j = pybamm.FunctionParameter(
+            f"{Electrode} electrode host site charge transfer coefficient ({index})",
+            inputs,
+        )
         return alpha_bv_j
 
     def x_j(self, U, T, index):
@@ -731,7 +740,7 @@ class ParticleLithiumIonParameters(BaseParameters):
     def j0_j(self, c_e, U, T, index):
         "Exchange-current density index by reaction j [A.m-2]"
         domain = self.domain
-        d = domain[0]
+        Electrode = domain.capitalize()
 
         tol = pybamm.settings.tolerances["j0__c_e"]
         c_e = pybamm.maximum(c_e, tol)
@@ -744,7 +753,8 @@ class ParticleLithiumIonParameters(BaseParameters):
         self.X_j(T, index)
         aj = self.alpha_bv_j(T, index)
         j0_ref_j = pybamm.FunctionParameter(
-            f"j0_ref_{d}_{index}", {"Temperature [K]": T}
+            f"{Electrode} electrode host site reference exchange-current density ({index}) [A.m-2]",
+            {"Temperature [K]": T},
         )
 
         # Equation 16, Baker et al 2018. The original formulation would be implemented
diff --git a/src/pybamm/parameters/parameter_values.py b/src/pybamm/parameters/parameter_values.py
index ba8c6c324..952df4e2a 100644
--- a/src/pybamm/parameters/parameter_values.py
+++ b/src/pybamm/parameters/parameter_values.py
@@ -4,6 +4,10 @@ import numbers
 from pprint import pformat
 from warnings import warn
 from collections import defaultdict
+from pybamm.models.full_battery_models.lithium_ion.msmr import (
+    is_deprecated_msmr_name,
+    replace_deprecated_msmr_name,
+)
 
 
 class ParameterValues:
@@ -438,6 +442,14 @@ class ParameterValues:
                     stacklevel=2,
                 )
                 values[new_param] = values.get(param)
+            if is_deprecated_msmr_name(param):
+                new_param = replace_deprecated_msmr_name(param)
+                warn(
+                    f"The parameter '{param}' has been renamed to '{new_param}'",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                values[new_param] = values.get(param)
 
         return values
 


Test patch:
diff --git a/tests/unit/test_parameters/test_msmr_parameter_names.py b/tests/unit/test_parameters/test_msmr_parameter_names.py
new file mode 100644
index 000000000..85e3794fb
--- /dev/null
+++ b/tests/unit/test_parameters/test_msmr_parameter_names.py
@@ -0,0 +1,98 @@
+import pybamm
+import pytest
+from pybamm.models.full_battery_models.lithium_ion.msmr import (
+    is_deprecated_msmr_name,
+    replace_deprecated_msmr_name,
+)
+
+
+class TestMSMRParameterNames:
+    def test_is_deprecated_msmr_name(self):
+        """
+        Test the is_deprecated_msmr_name function with various parameter names
+        """
+        # Valid names (returns True)
+        valid_names = [
+            "X_p_3",
+            "X_n_l_300",
+            "Q_p_42",
+            "w_n_d_7",
+            "U0_p_0",
+        ]
+        for name in valid_names:
+            assert is_deprecated_msmr_name(name) is True
+
+        # Invalid names (returns False)
+        invalid_names = [
+            "X_p_-3",  # Negative index
+            "X_j_3",  # Invalid electrode
+            "Y_p_3",  # Invalid base
+            "X_p_k_3",  # Invalid qualifier
+            "X_p_l",  # Missing electrode
+            "X_3",  # Missing index
+            "X_p_3_extra",  # Extra components
+            "electrode",  # Invalid base
+            "particle",  # Invalid base
+            "",  # Empty string
+        ]
+        for name in invalid_names:
+            assert is_deprecated_msmr_name(name) is False
+
+            with pytest.raises(ValueError, match="Invalid MSMR name"):
+                replace_deprecated_msmr_name(name)
+
+    def test_replace_deprecated_msmr_name(self):
+        """
+        Test the replace_deprecated_msmr_name function with various parameter names
+        """
+        name_mapping = {
+            "X_p_3": "Positive electrode host site occupancy fraction (3)",
+            "X_n_5": "Negative electrode host site occupancy fraction (5)",
+            "X_p_l_3": "Positive electrode host site occupancy fraction (lithiation) (3)",
+            "X_n_d_5": "Negative electrode host site occupancy fraction (delithiation) (5)",
+            "Q_p_3": "Positive electrode host site occupancy capacity (3) [A.h]",
+            "w_n_2": "Negative electrode host site ideality factor (2)",
+            "U0_p_d_4": "Positive electrode host site standard potential (delithiation) (4) [V]",
+            "a_p_d_5": "Positive electrode host site charge transfer coefficient (delithiation) (5)",
+            "j0_ref_n_0": "Negative electrode host site reference exchange-current density (0) [A.m-2]",
+        }
+        for old_name, new_name in name_mapping.items():
+            assert replace_deprecated_msmr_name(old_name) == new_name
+
+    def test_integration_with_parameter_values(self):
+        """
+        Test that the MSMR parameter name functions work correctly when integrated
+        with the ParameterValues class
+        """
+        # Define mapping of old parameter names to values
+        old_params = {
+            "X_p_3": 0.5,
+            "X_n_l_2": 0.3,
+            "Q_p_1": 2.5,
+            "U0_n_d_4": 0.1,
+            "j0_ref_n_0": 0.1,
+        }
+
+        # Define mapping of old parameter names to their human-readable equivalents
+        name_mapping = {
+            "X_p_3": "Positive electrode host site occupancy fraction (3)",
+            "X_n_l_2": "Negative electrode host site occupancy fraction (lithiation) (2)",
+            "Q_p_1": "Positive electrode host site occupancy capacity (1) [A.h]",
+            "U0_n_d_4": "Negative electrode host site standard potential (delithiation) (4) [V]",
+            "j0_ref_n_0": "Negative electrode host site reference exchange-current density (0) [A.m-2]",
+        }
+
+        param_values = pybamm.ParameterValues(old_params)
+
+        # New human-readable keys should be present
+        for new_name in name_mapping.values():
+            assert new_name in param_values
+
+        # Original keys should remain
+        for old_key, val in old_params.items():
+            assert old_key in param_values
+            assert param_values[old_key] == val
+
+        # And their human-readable counterparts map to the same values
+        for old_key, new_key in name_mapping.items():
+            assert param_values[new_key] == old_params[old_key]