README.md

Bluesky Tutorial

This is a collection of tutorials on data acquisition and analysis using Bluesky and scientific Python generally. There are a couple ways to use it.

• Try it in the interactive sandbox in the cloud at https://mybinder.org/v2/gh/bluesky/tutorials/master?urlpath=lab.
• Browse the content non-interactively at https://blueskyproject.io/tutorials.
• Download this content and run it on your local machine. This is not recommended for novices. See further instructions below.

Survey

Took our tutorial? Let us know how you thought of it so we can better improve it! Survey

References

• Bluesky Software Documentation Landing Page
• Bluesky Documentation
• Ophyd Documentation
• Databroker Documentation
• Our Gitter Chat Channel (come here for questions)
• Python Help : A collection of Python tutorials geared towards scientific data analysis.

Local Installation

• We strongly recommend creating a fresh software environment. For example, using conda:

  conda create -n bluesky-tutorials python=3.7
  conda activate bluesky-tutorials
  

• You will need git. You can install that using conda, for example.

  conda install git
  

• Ensure pip, setuptools, and numpy are up to date. This helps avoid some pitfalls in the steps to follow.

  pip install --upgrade pip setuptools numpy
  

• Clone this repository.

  git clone https://github.com/bluesky/tutorials
  cd tutorials
  

• Install the requirements.

  pip install -r binder/requirements.txt
  pip install ./bluesky-tutorial-utils
  

• Install the JupyterLab extensions.

  # Install extension that supports '%matplotlib widget'.
  jupyter labextension install @jupyter-widgets/jupyterlab-manager
  jupyter labextension install jupyter-matplotlib
  

• Start the simulated hardware. On Linux and OSX this can be done in one line using supervisor:

  supervisord -c supervisor/supervisord.conf

  You can check their status at any time using

  supervisorctl -c supervisor/supervisord.conf status

  On Windows it must be done manually:

  python3 -m caproto.ioc_examples.decay
  python3 -m caproto.ioc_examples.mini_beamline
  python3 -m caproto.ioc_examples.random_walk
  python3 -m caproto.ioc_examples.random_walk --prefix="random_walk:horiz-"
  python3 -m caproto.ioc_examples.random_walk --prefix="random_walk:vert-"
  python3 -m caproto.ioc_examples.simple
  python3 -m caproto.ioc_examples.thermo_sim
  python3 -m caproto.ioc_examples.trigger_with_pc

• Start Jupyter.

  jupyter lab

Contributing to this tutorial

Install the docs requirements.

pip install -r docs/requirements.txt

Building the documentation

This command copies (select) notebooks into docs/source/, converts them to .rst, and builds static HTML documentation at docs/build/html/.

make -C docs html

Controlling Execution

For testing the notebooks and publishing static renderings of them, we execute them with nbsphinx. It will execute each notebook top to bottom and fail if any of the cells raise exceptions or take longer than nbsphinx_timeout (configured to 600 seconds in docs/source/conf.py) to execute. Special cases can be allowed by editing cell or notebook metadata. These should be used sparingly.

• Allow a cell to raise an exception. Add the cell tag raises-exception.

• Manually execute a notebook. Add the notebook metadata:

  {
    "keep_output": true,
  }

  This setting affects nbstripout. Normally, nbstripout will remove the outputs from every cell when a notebook is committed. This will leave all the cells' outputs intact. When nbsphinx runs it will skip execution and render the existing outputs. This is useful for notebooks that have a very long execution time, contain client-specific outputs, like the output from bluesky.plans.count? in JupyterLab, or require user-initiated interruption, like RunEngine pause/resume. While nbstripout supports applying this at the level of specific cells, it must be applied to the whole notebook to play well with nbsphinx.

For more see https://nbsphinx.readthedocs.io/en/0.7.0/executing-notebooks.html.