Hello Bluesky.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Hello Bluesky: Reading detectors and scanning\n",
    "\n",
    "In this notebook you will:\n",
    "\n",
    "* Connect to some simulated hardware.\n",
    "* Acquire some data via two common experimental procedures (\"plans\"), ``count`` and ``scan``.\n",
    "* Write a custom plan.\n",
    "\n",
    "Recommend Prerequisites:\n",
    "\n",
    "* [Hello Python and Jupyter](./Hello%20Python%20and%20Jupyter.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuration\n",
    "Below, we will connect to EPICS IOC(s) controlling simulated hardware in lieu of actual motors and detectors. An EPICS IOC is control system software that allows communication with a wide variety of hardware using a common interface. The IOCs should already be running in the background. Run this command to verify that they are running: it should produce output with RUNNING on each line. In the event of a problem, edit this command to replace `status` with `restart all` and run again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib widget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!supervisorctl -c supervisor/supervisord.conf status"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%run scripts/beamline_configuration.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# aliases for convenience/readability\n",
    "motor = motor_ph\n",
    "det = ph"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check that we can communicate with the hardware. If this doesn't raise an error, it worked."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "det.wait_for_connection()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data Acquisition\n",
    "\n",
    "### Executing a `count` plan with various parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the example below, the Bluesky run engine is the interpreter of experiment plans and `count` is an experiment plan used here to acquire one reading from a point detector."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bluesky.plans import count\n",
    "RE(count([det]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The return value is a list of the run IDs that uniquely identify this data set. The \"scan num\" is easier to remember but is not good for long-term reference because it may not be unique.\n",
    "\n",
    "Let's looks at the documentation for `count` to see what our other options are."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(count)  # or, equiavently, type count? or ?count"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Creating a figure explicitly in advance helps with the\n",
    "# top-to-bottom flow of this notebook, but it is not necessary.\n",
    "# If this is omitted, bluesky will cause a figure to appear\n",
    "# during the RE(...) execution below.\n",
    "plt.figure('ph_det vs time')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# five consecutive readings\n",
    "RE(count([det], num=5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.gcf()  # Display a snapshot of the current state of the figure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "plt.gcf().canvas  # To avoid needing to scroll up, display the interactive canvas again here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# five sequential readings separated by a 1-second delay\n",
    "RE(count([det], num=5, delay=1))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.gcf()  # Display a snapshot of the current state of the figure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Scan\n",
    "\n",
    "Scan ``motor`` from -10 to 10, stopping at 15 equally-spaced points along the way and reading ``det``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Creating a figure explicitly in advance helps with the\n",
    "# top-to-bottom flow of this notebook, but it is not necessary.\n",
    "# If this is omitted, bluesky will cause a figure to appear\n",
    "# during the RE(...) execution below.\n",
    "plt.figure('ph_det vs motor_ph')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RE(scan([det], motor, -10, 10, 15))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.gcf()  # Display a snapshot of the current state of the figure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simulators\n",
    "\n",
    "Bluesky includes utilities to inspecting plans before they are run. You can imagine various reasons you might want to do this. Example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bluesky.simulators import summarize_plan\n",
    "\n",
    "summarize_plan(scan([det], motor, -1, 1, 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Custom plan\n",
    "\n",
    "Define a custom \"plan\", using the Python syntax ``yield from`` to dispatch out to built-in plans."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "plt.gcf().canvas  # To avoid needing to scroll up, display the interactive canvas again here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The plan_stubs module contains smaller plans.\n",
    "# They can be used alone or as buildling blocks for larger plans.\n",
    "from bluesky.plan_stubs import mv\n",
    "\n",
    "\n",
    "def sweep_exposure_time(times):\n",
    "    \"Multiple scans: one per exposure time setting.\"\n",
    "    for t in times:\n",
    "        yield from mv(det.exp, t)\n",
    "        yield from scan([det], motor, -10, 10, 5)\n",
    "        \n",
    "RE(sweep_exposure_time([0.01, 0.1, 1]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.gcf()  # Display a snapshot of the current state of the figure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Q1: Above we ran a `count` with multiple readings separated by a fixed delay. The ``delay`` parameter also accepts a list of values. Try a `count` with a variable delay.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try your solution here. Fill in the blank:\n",
    "# RE(count(____)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Execute the following cell to reveal a solution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load solutions/count_variable_delay.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Q2: Write a custom plan that scans the same region twice, first with coarse steps and then with fine steps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try your solution here. Fill in the blank:\n",
    "# def coarse_and_fine(detectors, motor, start, stop):\n",
    "#     yield from scan(___)\n",
    "#     yield from scan(___)\n",
    "#\n",
    "# RE(coarse_and_fine([det], motor, -10, 10))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load solutions/scan_coarse_and_fine.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Q3. All of the usages of scan we have seen so far scan from negative to positive. Scan from positive to negative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try your solution here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load solutions/scan_positive_to_negative.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Q4: The ``scan`` plan samples equally-spaced points. To sample *arbitrary* points, you can use ``list_scan``. Import it from the same module that we imported ``scan`` from, then use ``list_scan?`` to view its documentation and figure out how to use it. Scan the positions ``[1, 1, 2, 3, 5, 8]``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Try your solution here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load solutions/scan_fibonacci.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Q5: What's wrong with this? (What does it do?)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Broken example\n",
    "def sweep_exposure_time(times):\n",
    "    \"Multiple scans: one per exposure time setting.\"\n",
    "    for t in times:\n",
    "        mv(det.exp, t)\n",
    "        scan([det], motor, -10, 10, 15)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load solutions/broken_sweep_exposure_time_explanation.txt"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}