Skip to content
This repository has been archived by the owner on Sep 2, 2024. It is now read-only.

Getting Started as a Developer

Jump to bottom
rtuck99 edited this page Nov 7, 2023 · 4 revisions

These notes are aimed at anyone who wants to get more involved in Hyperion development, likely DLS staff. As such it is mostly aimed at people that are not necessarily familiar with GitHub workflows and Python 3 development.

Development Environment

This codebase is public so you are free to clone it without any privileges. However, if you wish to make edits you must first have a GitHub account.

To get started with developing Hyperion, do the following:

  • Clone this repo git clone [email protected]:DiamondLightSource/hyperion.git
  • Use the instructions in the README to get a dev environment set up

Nb. If you have a new system or have not connected to github with ssh before, you may get the following error message:

[email protected]: Permission denied (publickey).

in which case you need to set up ssh access to github with instructions here: ssh

You can now use your chosen IDE to develop with, however vscode is the recommended IDE. This can be used at DLS by running:

cd /where/this/project/is
module load vscode
code ./.vscode/hyperion.code-workspace
  • You should then be able to run the unit tests in vscode by going to the testing panel and pressing the run all button in the top right (note the system tests will not necessarily pass at this point but all unit tests should): image
  • Note that because Hyperion makes heavy use of Dodal the workspace specified above contains both repos. On first running vscode you may need to change the interpretter that dodal is using to be the same as the Hyperion one (.venv/bin/python), see here on how to do this.

There are then two ways of making edits to the code:

  • For people making the occasional edits you can make a fork and submit a PR through that
  • For people working regularly on the codebase get in touch through Slack with your GH username and you can be added to the contributors list

When writing code, particularly as a regular developer, you should follow the documented workflow. This workflow is mostly based of the GH Workflow and is a little different from the gerrit flow.

Beamline Deployment

See here for instructions on deploying a new version of Hyperion. It can then be run by running the run_hyperion.sh script from the beamline control machine as gda2. Alternatively, if the beamline is already running Hyperion you can just call hyperion_restart() from the GDA Jython console. For GDA to talk to Hyperion it needs to be switched to this change and a server restart. Subsequently any Xraycentring gridscans run by GDA will use Hyperion. Details on where the logs are and other info for debugging Hyperion as a reasonably well informed user can be found here.

Background on Bluesky

The written Bluesky tutorial or the interactive one are good places to start on on how to use Bluesky, which Hyperion uses for the actual logic of how to do a scan. The other infrastructure that Hyperion uses is:

  • Flask for communication between GDA<->Hyperion
  • dataclasses_json is used to convert parameters passed to Hyperion into Python dataclasses
  • Hyperion attaches callbacks to the Bluesky plan to perform communications with outside services:
    • nexgen for writing NeXus files
    • ispyb for registering collections into the database
    • zocalo for triggering analysis and receiving results

Hyperion uses many of the modern features of Python 3. In particular you should take some time to review:

  • Generators - all Bluesky plans are generators
  • Decorators - there are a number of helper decorators in Bluesky, in general Hyperion tends not to use them to increase readability but they could be used
Clone this wiki locally