Merge pull request #39 from scipp/repeat_pulses

Multiple pulses
scipp · May 22, 2023 · bed8d13 · bed8d13
2 parents 9ef8891 + a457946
commit bed8d13
Show file tree

Hide file tree

Showing 21 changed files with 1,767 additions and 962 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -15,7 +15,7 @@ API Reference
    Detector
    DetectorReading
    Model
-   Pulse
-   PulseParameters
    Result
+   Source
+   SourceParameters
    utils
diff --git a/docs/components.ipynb b/docs/components.ipynb
@@ -32,7 +32,7 @@
    "id": "0543c13d-847d-4642-8736-14a75ed5fd01",
    "metadata": {},
    "source": [
-    "We begin by making a pulse using the profile from ESS."
+    "We begin by making a source pulse using the profile from ESS."
    ]
   },
   {
@@ -42,8 +42,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "pulse = tof.Pulse(facility='ess', neutrons=1_000_000)\n",
-    "pulse.plot()"
+    "source = tof.Source(facility='ess', neutrons=1_000_000)\n",
+    "source.plot()"
    ]
   },
   {
@@ -67,7 +67,7 @@
     "detector = tof.Detector(distance=30.0 * meter)\n",
     "\n",
     "# Build the instrument model\n",
-    "model = tof.Model(pulse=pulse, detectors=[detector])\n",
+    "model = tof.Model(source=source, detectors=[detector])\n",
     "model"
    ]
   },

diff --git a/docs/index.rst b/docs/index.rst
@@ -32,7 +32,8 @@ You can install from ``conda`` using
    :hidden:
 
    short-example
-   pulses
+   sources
    components
+   multiple-pulses
    api
    Release notes <https://github.com/scipp/tof/releases>
diff --git a/docs/multiple-pulses.ipynb b/docs/multiple-pulses.ipynb
@@ -0,0 +1,347 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6b645603-12c0-4b3d-ab3c-529ad4f373e3",
+   "metadata": {},
+   "source": [
+    "# Multiple pulses\n",
+    "\n",
+    "This notebook will illustrate how to use multiple pulses in a model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "899a245a-0ae7-45dd-b684-3b9d1c034cc6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import scipp as sc\n",
+    "import tof\n",
+    "\n",
+    "Hz = sc.Unit('Hz')\n",
+    "deg = sc.Unit('deg')\n",
+    "meter = sc.Unit('m')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3890d24c-93ab-4faa-b653-c9208b5eba23",
+   "metadata": {},
+   "source": [
+    "## Create a source with 3 pulses\n",
+    "\n",
+    "We first create an ESS source with 3 pulses, each containing 1 million neutrons, using the `pulses` argument."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a2699065-309c-439c-bcda-bf15d20edd0b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "source = tof.Source(facility='ess', neutrons=1_000_000, pulses=3)\n",
+    "source"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "49fec301-52a4-45a7-9438-b3f736e50b9f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "source.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b5ffdab6-10cd-4719-8ff2-86e5e1d10571",
+   "metadata": {},
+   "source": [
+    "## Chopper and detector set-up\n",
+    "\n",
+    "We create two WFM choppers, and two frame-overlap choppers, and a single detector 32 meters from the source."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "34314bcc-978c-468c-b5a1-d84ce33e53d5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "choppers = [\n",
+    "    tof.Chopper(\n",
+    "        frequency=70.0 * Hz,\n",
+    "        open=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[98.71, 155.49, 208.26, 257.32, 302.91, 345.3],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        close=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[109.7, 170.79, 227.56, 280.33, 329.37, 375.0],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        phase=47.10 * deg,\n",
+    "        distance=6.6 * meter,\n",
+    "        name=\"WFM1\",\n",
+    "    ),\n",
+    "    tof.Chopper(\n",
+    "        frequency=70 * Hz,\n",
+    "        open=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[80.04, 141.1, 197.88, 250.67, 299.73, 345.0],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        close=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[91.03, 156.4, 217.18, 269.97, 322.74, 375.0],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        phase=76.76 * deg,\n",
+    "        distance=7.1 * meter,\n",
+    "        name=\"WFM2\",\n",
+    "    ),\n",
+    "    tof.Chopper(\n",
+    "        frequency=56 * Hz,\n",
+    "        open=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[74.6, 139.6, 194.3, 245.3, 294.8, 347.2],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        close=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[95.2, 162.8, 216.1, 263.1, 310.5, 371.6],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        phase=62.40 * deg,\n",
+    "        distance=8.8 * meter,\n",
+    "        name=\"Frame-overlap 1\",\n",
+    "    ),\n",
+    "    tof.Chopper(\n",
+    "        frequency=28 * Hz,\n",
+    "        open=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[98.0, 154.0, 206.8, 254.0, 299.0, 344.65],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        close=sc.array(\n",
+    "            dims=['cutout'],\n",
+    "            values=[134.6, 190.06, 237.01, 280.88, 323.56, 373.76],\n",
+    "            unit='deg',\n",
+    "        ),\n",
+    "        phase=12.27 * deg,\n",
+    "        distance=15.9 * meter,\n",
+    "        name=\"Frame-overlap 2\",\n",
+    "    ),\n",
+    "]\n",
+    "\n",
+    "detectors = [\n",
+    "    tof.Detector(distance=32.0 * meter, name='detector'),\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4c3b69b7-5ebe-4188-aa4b-2c6621ec8017",
+   "metadata": {},
+   "source": [
+    "## Results\n",
+    "\n",
+    "We combine the `source`, `choppers`, and `detectors` into our `model`,\n",
+    "and then use the `.run()` method to execute the ray-tracing simulation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "05c191a2-81ef-41d3-8f64-343f72d7555d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model = tof.Model(source=source, choppers=choppers, detectors=detectors)\n",
+    "res = model.run()\n",
+    "res"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7eea136a-4c5f-420c-8fd5-1cdc64be939f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.plot(max_rays=5000)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9b761887-12f7-49f1-bbdb-a607c2376e47",
+   "metadata": {},
+   "source": [
+    "The time-distance diagram reveals that a small number of long-wavelength neutrons from one pulse are polluting the counts detected by the detector for the next pulse (red lines).\n",
+    "\n",
+    "The overlap is also visible when plotting the data seen by the detector,\n",
+    "even though the number of polluting neutrons is very small (the tails of each pulse are almost flat)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "95df472c-bc86-41b7-87f3-a1b8455e8fbc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.detectors['detector'].tofs.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "77d9a554-3cfc-4f24-a5a6-8c5e171ffbef",
+   "metadata": {},
+   "source": [
+    "To try and obtain as clean as possible of a detector signal,\n",
+    "we include an additional chopper in the beamline to remove pulse overlap:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "42bc9c07-1f3e-474d-9434-40e6596ba193",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pol = tof.Chopper(\n",
+    "    frequency=14 * Hz,\n",
+    "    open=sc.array(\n",
+    "        dims=['cutout'],\n",
+    "        values=[50.0],\n",
+    "        unit='deg',\n",
+    "    ),\n",
+    "    close=sc.array(\n",
+    "        dims=['cutout'],\n",
+    "        values=[240.0],\n",
+    "        unit='deg',\n",
+    "    ),\n",
+    "    phase=0 * deg,\n",
+    "    distance=18 * meter,\n",
+    "    name=\"Pulse-overlap\",\n",
+    ")\n",
+    "\n",
+    "model.add(pol)\n",
+    "res = model.run()\n",
+    "res.plot(max_rays=5000)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e39cbf07-deee-447b-835d-9812d6ed69c3",
+   "metadata": {},
+   "source": [
+    "We can now see that the pulses do not overlap at the detector,\n",
+    "and this is confirmed in the detector plot"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "977385c0-cfd5-4e20-97b0-c82ac4f55640",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.detectors['detector'].tofs.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "83c62115-bab6-4060-a3cf-d40529595f27",
+   "metadata": {},
+   "source": [
+    "## Data inspection\n",
+    "\n",
+    "The detector and the chopper readings are a data group with one entry per pulse "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f31387fc-87a0-4d93-832f-4380c6e1103a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.detectors['detector'].tofs.visible.data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "af9d5348-8e5e-4f64-8425-5e1f4e5c8168",
+   "metadata": {},
+   "source": [
+    "It is possible to inspect just a single pulse using the usual slicing notation `[0]` for an array:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a792d72e-cf31-42ca-85e3-e7114dad52d0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.detectors['detector'].tofs.visible[0].data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "151caf0f-582d-4982-bcc0-64792ec5c6f1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.detectors['detector'].tofs.visible[0].plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e3388ce1-f766-4162-b254-22c3f564f3d1",
+   "metadata": {},
+   "source": [
+    "and the same is available one level above on the `tofs` property,\n",
+    "in which case both visible and blocked neutrons for the given pulse are returned:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f9230062-3748-439d-b222-149dee9b0ae7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "res.choppers['WFM1'].tofs[0].plot()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}