Experiment mwp

docs/docs/tutorials/component_collection.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# Component Collection\n",
     "\n",
-    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+    "Most data will be modelled by a sum of components, which is what a ComponentCollection handles. Here we show how to create a ComponentCollection and add components to it."
    ]
   },
   {
@@ -67,7 +67,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "easydynamics_newbase",
    "language": "python",
    "name": "python3"
   },

docs/docs/tutorials/components.ipynb

@@ -7,7 +7,9 @@
    "source": [
     "# Components\n",
     "\n",
-    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+    "Components are the basic ingredients for all models. Currently, the available components are Gaussian, Lorentzian, Voigt (the convolution of a Gaussian with a Lorentzian), delta function, damped harmonic oscillator and polynomial. This notebooks shows how to use the components. \n",
+    "\n",
+    "Note in particular that a Gaussian, Lorentzian, Voigt or delta function where the center has not been given will be centered at 0."
    ]
   },
   {

docs/docs/tutorials/convolution.ipynb

@@ -7,7 +7,11 @@
    "source": [
     "# Convolution\n",
     "\n",
-    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+    "The experimental resolution function must be taken into account when analysing neutron scattering data, especially QENS. In general, the scattering is given by the convolution of the model of the scattering from the sample with the model of the resolution function. Here, both the scattering from the sample and the resolution function is modelled by a ComponentCollection.\n",
+    "\n",
+    "Analytical expressions exist for the convolution between Gaussians, Lorentzians and Voigt functions, as well as between delta functions and any other function. We use these expressions whenever possible. When analytical convolution is not possible, e.g. for a Damped Harmonic Oscillator or if detailed balancing is included, we use numerical convolution based on the Fast fourier transform algorithm. The accuracy of numerical convolution depends on several factors such as the width of the peaks related to the bin size and full span of the data. Warnings are given if it seems the accuracy is low, and several settings are available to improve the accuracy.\n",
+    "\n",
+    "For most purposes, the convolution will happen behind the scenes, and you will not need to call it yourself. However, we here show how to use it and play around with the settings."
    ]
   },
   {
@@ -93,6 +97,7 @@
     "sample_components.append_component(gaussian)\n",
     "sample_components.append_component(dho)\n",
     "sample_components.append_component(lorentzian)\n",
+    "sample_components.append_component(delta)\n",
     "\n",
     "resolution_components = ComponentCollection()\n",
     "resolution_gaussian = Gaussian(display_name='Resolution Gaussian', width=0.15, area=0.8)\n",

docs/docs/tutorials/detailed_balance.ipynb

@@ -6,8 +6,13 @@
    "metadata": {},
    "source": [
     "# Detailed Balance\n",
+    "Detailed balance describes the relationship between the intensity of inelastic and quasielastic scattering at positive and negative energy transfers. The equation is $S(-{\\bf Q}, E) = \\exp(-\\beta E) S({\\bf Q}, E)$, where $E$ is the energy transfer, ${\\bf {Q}}$ is the momentum transfer and $\\beta=1/k_BT$ is the inverse of the temperature ($T$) multiplied by Boltzman's constant ($k_B$). To enforce this relationship, we can multiply our scattering function using the Detailed Balance Factor (DBF), defined by $DBF = E (1+n)$, where $n$ is the Bose occupation factor.\n",
     "\n",
-    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+    "In some communities it is customary to normalise the DBF by temperature, i.e. $DBF_N = E/(k_B T) (1+n)$.\n",
+    "\n",
+    "This notebook shows how to calculate and use the DBF. Note that it will be automatically applied if temperature is set, so you do not have to think about it.\n",
+    "\n",
+    "Details on detailed balancing can be found in most textbooks on neutron scattering."
    ]
   },
   {
@@ -46,7 +51,8 @@
     "plt.xlabel('Energy transfer (meV)')\n",
     "plt.ylabel('Detailed balance factor')\n",
     "plt.title(\n",
-    "    'Detailed balance factor for different temperatures, normalized to 1 at zero energy transfer'\n",
+    "    'Detailed balance factor for different temperatures, \\n '\n",
+    "    'normalized to 1 at zero energy transfer'\n",
     ")\n",
     "plt.show()"
    ]
@@ -76,39 +82,11 @@
     "plt.title('Detailed balance factor for different temperatures, not normalized')\n",
     "plt.show()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import scipp as sc\n",
-    "\n",
-    "temperatures = [1, 10, 100]\n",
-    "temperature_unit = 'K'\n",
-    "energy = np.linspace(-1, 1, 100)\n",
-    "# energy=1.0\n",
-    "energy_unit = 'meV'\n",
-    "\n",
-    "plt.figure()\n",
-    "for temperature in temperatures:\n",
-    "    DBF = detailed_balance_factor(\n",
-    "        energy, temperature, sc.Unit('meV'), sc.Unit('K'), divide_by_temperature=False\n",
-    "    )\n",
-    "    plt.plot(energy, DBF, label=f'T={temperature} K')\n",
-    "plt.legend()\n",
-    "plt.xlabel('Energy transfer (meV)')\n",
-    "plt.ylabel('Detailed balance factor')\n",
-    "plt.title('Detailed balance factor for different temperatures, not normalized')\n",
-    "plt.show()"
-   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "newdynamics",
+   "display_name": "easydynamics_newbase",
    "language": "python",
    "name": "python3"
   },
@@ -122,7 +100,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.13"
+   "version": "3.12.12"
   }
  },
  "nbformat": 4,

docs/docs/tutorials/diffusion_model.ipynb

@@ -6,8 +6,7 @@
    "metadata": {},
    "source": [
     "# Diffusion Model\n",
-    "\n",
-    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+    "We support several standard models of diffusion. Here we show an example of Browniand Translational Diffusion, where the scattering is a Lorentzian with width ($\\Gamma$) given by $\\Gamma = D Q^2$, where $D$ is the diffusion coefficient (in m$^2$/s) and $Q$ is the momentum transfer."
    ]
   },
   {
@@ -66,6 +65,26 @@
     "plt.ylabel('Intensity (arb. units)')\n",
     "plt.title('Brownian Translational Diffusion Model')"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a50c67ec",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Calculate and plot the half width at half maximum (HWHM) as function\n",
+    "# of Q\n",
+    "Q = np.linspace(0.1, 2, 101)\n",
+    "HWHM = diffusion_model.calculate_width(Q)\n",
+    "plt.figure()\n",
+    "plt.plot(Q, HWHM)\n",
+    "plt.xlabel('Q (Å$^{-1}$)')\n",
+    "plt.ylabel('HWHM (meV)')\n",
+    "plt.xlim(0, 2.5)\n",
+    "plt.ylim(0, max(HWHM) * 1.1)\n",
+    "plt.title('HWHM vs Q for Brownian Translational Diffusion')"
+   ]
   }
  ],
  "metadata": {

docs/docs/tutorials/experiment.ipynb

@@ -0,0 +1,83 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "906b959a",
+   "metadata": {},
+   "source": [
+    "# Experiment\n",
+    "The experimental data is stored in an Experiment class. Underneath we use Scipp and Plopp to handle and plot the data. We here show how to load an example data set, rebin it and plot it in various ways."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c7d23add",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from easydynamics.experiment import Experiment\n",
+    "\n",
+    "%matplotlib widget"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2b7c5ca8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load and plot example vanadium data\n",
+    "vanadium_experiment = Experiment('Vanadium')\n",
+    "vanadium_experiment.load_hdf5(filename='vanadium_data_example.h5')\n",
+    "\n",
+    "vanadium_experiment.plot_data()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "238ba6ee",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Rebin the data and plot again\n",
+    "vanadium_experiment.rebin({'Q': 5, 'energy': 50})\n",
+    "vanadium_experiment.plot_data()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bc32ab1f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Plot using the plopp slicer with extra arguments\n",
+    "vanadium_experiment.plot_data(slicer=True, keep='energy', vmin=0, vmax=2.0)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "easydynamics_newbase",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/docs/tutorials/index.md

@@ -17,9 +17,16 @@ The tutorials are organized into the following categories:
 
 ## Getting Started
 
-- [Component collection](component_collection.ipynb) – Learn how to ...
-- [Components](components.ipynb) – Learn how to ...
-- [Convolution](convolution.ipynb) – Learn how to ...
-- [Detailed balance](detailed_balance.ipynb) – Learn how to ...
-- [Diffusion model](diffusion_model.ipynb) – Learn how to ...
-- [Sample model](sample_model.ipynb) – Learn how to ...
+- [Component collection](component_collection.ipynb) – Learn how to
+  create a collectin of components for fitting
+- [Components](components.ipynb) – Learn how to use the EasyDynamics
+  components
+- [Convolution](convolution.ipynb) – Learn how to calculate the
+  convolution of your resolution function with your model
+- [Detailed balance](detailed_balance.ipynb) – Learn how to apply
+  detailed balancing to your model
+- [Diffusion model](diffusion_model.ipynb) – Learn how to create and use
+  a model of diffusion
+- [Sample model](sample_model.ipynb) – Learn how to create a model of
+  the scattering from your sample
+- [Experiment](experiment.ipynb) - Learn how to load and bin your data

docs/docs/tutorials/sample_model.ipynb

@@ -6,8 +6,11 @@
    "metadata": {},
    "source": [
     "# Sample Model\n",
+    "We here introduce the SampleModel, ResolutionModel and BackgroundModel, which all function in a similar way. They are, as the name implies, used to describe scattering from the sample, the resolution function and the background, respectively.\n",
     "\n",
-    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+    "The models describe the scattering from the sample as function of ${\\bf Q}$ and $E$. This is done by generating ComponentCollection's for each ${\\bf Q}$, where each ComponentCollection contains a collection of ModelComponents such as Gaussians and Lorentzians. The model can be given a single template component or a collection of components that will be copied to each ${\\bf Q}$\n",
+    "\n",
+    "We further support various models of diffusion, which typically generate one or more Lorentzian components, where the width (and usually the area) has a particular dependence on $Q$."
    ]
   },
   {

docs/mkdocs.yml

@@ -178,6 +178,7 @@ nav:
           - Detailed balance: tutorials/detailed_balance.ipynb
           - Diffusion model: tutorials/diffusion_model.ipynb
           - Sample model: tutorials/sample_model.ipynb
+          - Experiment: tutorials/experiment.ipynb
   - API Reference:
       - API Reference: api-reference/index.md
       - convolution: api-reference/convolution.md