Add Hall-Ross, circle jump and 3D Gaussian diffusion models

docs/docs/tutorials/diffusion_model.ipynb

@@ -6,7 +6,9 @@
    "metadata": {},
    "source": [
     "# Diffusion Model\n",
-    "We support several standard models of diffusion. Here we show examples of Brownian Translational Diffusion, Jump Translational Diffusion and Chudley-Elliott Jump Diffusion. In each model the scattering is a Lorentzian for every $Q$, and the models differ in how the width $\\Gamma(Q)$ depends on $Q$. For Brownian Translational Diffusion, the width is given by $\\Gamma = D Q^2$, where $D$ is the diffusion coefficient (in m$^2$/s) and $Q$ is the momentum transfer."
+    "We support several standard models of diffusion. Here we show examples of Brownian Translational Diffusion, Jump Translational Diffusion, Chudley-Elliott Jump Diffusion and Hall-Ross Jump Diffusion. In each model the scattering is a Lorentzian for every $Q$, and the models differ in how the width $\\Gamma(Q)$ depends on $Q$. For Brownian Translational Diffusion, the width is given by $\\Gamma = D Q^2$, where $D$ is the diffusion coefficient (in m$^2$/s) and $Q$ is the momentum transfer.\n",
+    "\n",
+    "Models with an elastic line and several Lorentzians have their own tutorials: [equivalent sites on a circle](equivalent_sites_circle.ipynb), [jump sites with a log-normal distribution](jump_sites_log_normal_distribution.ipynb) and [the 3D Gaussian model](gaussian_model_3d.ipynb)."
    ]
   },
   {
@@ -204,13 +206,7 @@
    "metadata": {},
    "source": [
     "## Chudley-Elliott Jump Diffusion\n",
-    "The Chudley-Elliott model of\n",
-    "\n",
-    "> C. T. Chudley and R. J. Elliott, *Neutron Scattering from a Liquid on a Jump Diffusion Model*,\n",
-    "> Proc. Phys. Soc. **77**, 353 (1961),\n",
-    "> [doi:10.1088/0370-1328/77/2/319](https://doi.org/10.1088/0370-1328/77/2/319).\n",
-    "\n",
-    "describes a particle that sits on a site for a residence time $\\tau$ and then jumps a fixed distance $l$. The width is\n",
+    "The Chudley-Elliott model<sup>1</sup> describes a particle that sits on a site for a residence time $\\tau$ and then jumps a fixed distance $l$. The width is\n",
     "\n",
     "$$\\Gamma(Q) = \\frac{\\hbar}{\\tau}\\left(1 - \\frac{\\sin(Ql)}{Ql}\\right),$$\n",
     "\n",
@@ -295,6 +291,115 @@
     "plt.title('HWHM vs Q for Chudley-Elliott Jump Diffusion')\n",
     "plt.show()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "17",
+   "metadata": {},
+   "source": [
+    "## Hall-Ross Jump Diffusion\n",
+    "The Hall-Ross model<sup>2</sup> describes a particle that sits on a site for a residence time $\\tau$ and then jumps a random distance drawn from a Gaussian distribution. The width is\n",
+    "\n",
+    "$$\\Gamma(Q) = \\frac{\\hbar}{\\tau}\\left(1 - \\exp\\left(-\\frac{Q^2 l^2}{2}\\right)\\right),$$\n",
+    "\n",
+    "where $\\tau$ is the residence time (in ps) and $l$ is the standard deviation of the jump-length distribution (in Å).<sup>3</sup> The mean-square jump length is $\\langle r^2 \\rangle = 3 l^2$. Unlike Chudley-Elliott, the width does not oscillate: it rises monotonically from $\\hbar D Q^2$, with $D = l^2 / (2\\tau)$, to $\\hbar/\\tau$."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18",
+   "metadata": {},
+   "source": [
+    "### Model for different Q values"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "19",
+   "metadata": {},
+   "source": [
+    "# Create Hall-Ross Jump Diffusion model\n",
+    "# and plot the model for different Q values.\n",
+    "# Q is in Angstrom^-1 and energy in meV.\n",
+    "\n",
+    "Q = np.linspace(0.5, 2, 7)\n",
+    "energy = np.linspace(-2, 2, 501)\n",
+    "scale = 1.0\n",
+    "residence_time = 1.0  # ps\n",
+    "jump_length = 1.5 / np.sqrt(3)  # Å, the standard deviation l\n",
+    "\n",
+    "hall_ross_model = edyn.HallRossJumpDiffusion(\n",
+    "    display_name='HallRossModel',\n",
+    "    scale=scale,\n",
+    "    residence_time=residence_time,\n",
+    "    jump_length=jump_length,\n",
+    "    Q=Q,\n",
+    ")\n",
+    "\n",
+    "component_collections = hall_ross_model.get_component_collections()\n",
+    "\n",
+    "cmap = plt.cm.jet\n",
+    "nQ = len(component_collections)\n",
+    "plt.figure()\n",
+    "for Q_index in range(len(component_collections)):\n",
+    "    color = cmap(Q_index / (nQ - 1))\n",
+    "    y = component_collections[Q_index].evaluate(energy)\n",
+    "    plt.plot(energy, y, label=f'Q={Q[Q_index]} Å^-1', color=color)\n",
+    "\n",
+    "plt.legend()\n",
+    "plt.xlabel('Energy (meV)')\n",
+    "plt.ylabel('Intensity (arb. units)')\n",
+    "plt.title('Hall-Ross Jump Diffusion Model')\n",
+    "plt.show()"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "20",
+   "metadata": {},
+   "source": [
+    "### Width as a function of Q\n",
+    "The standard deviation above was chosen as $l = 1.5/\\sqrt{3}$ Å, so that the mean-square jump length, $3 l^2 = 2.25$ Å$^2$, equals that of the Chudley-Elliott model above with its fixed jump of 1.5 Å. Both models then have the same diffusion coefficient and agree at low $Q$; at high $Q$ the Hall-Ross width approaches $\\hbar/\\tau$ without oscillating."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "21",
+   "metadata": {},
+   "source": [
+    "# Calculate and plot the half width at half maximum (HWHM) as function\n",
+    "# of Q, together with the Chudley-Elliott model with the same mean-square jump length\n",
+    "Q = np.linspace(0.1, 4, 201)\n",
+    "HWHM = hall_ross_model.calculate_width(Q)\n",
+    "plt.figure()\n",
+    "plt.plot(Q, HWHM, label='Hall-Ross')\n",
+    "plt.plot(Q, chudley_elliott_model.calculate_width(Q), linestyle='dashed', label='Chudley-Elliott')\n",
+    "plt.xlabel('Q (Å$^{-1}$)')\n",
+    "plt.ylabel('HWHM (meV)')\n",
+    "plt.xlim(0, 4.2)\n",
+    "plt.ylim(0, max(HWHM) * 1.2)\n",
+    "plt.title('HWHM vs Q for Hall-Ross Jump Diffusion')\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "22",
+   "metadata": {},
+   "source": [
+    "## References\n",
+    "\n",
+    "1. C. T. Chudley and R. J. Elliott, *Neutron Scattering from a Liquid on a Jump Diffusion Model*, Proc. Phys. Soc. **77**, 353 (1961), [doi:10.1088/0370-1328/77/2/319](https://doi.org/10.1088/0370-1328/77/2/319).\n",
+    "\n",
+    "2. P. L. Hall and D. K. Ross, *Incoherent neutron scattering functions for random jump diffusion in bounded and infinite media*, Mol. Phys. **42**, 673 (1981), [doi:10.1080/00268978100100521](https://doi.org/10.1080/00268978100100521).\n",
+    "\n",
+    "3. The same convention as Mantid's [`HallRoss` fit function](https://github.com/mantidproject/mantid/blob/17c1cd96c1d46b39bee21dc75a60017b658d689c/Framework/PythonInterface/plugins/functions/HallRoss.py#L30-L39), whose `L` parameter is this $l$."
+   ]
   }
  ],
  "metadata": {