Remove unused subplans and improve docs (#1548)

* Remove unused subplans and improve docs

* Remove more unused plan names

Author: DominicOram

docs/developer/general/explanations/callback_and_run_logic.rst

@@ -13,6 +13,16 @@ Currently, the requirement of needing to have written to ispyb is explicit as th
 
 In general, the ordering flow of when callbacks are triggered is controlled by emitting documents with the expected plan name and data.
 
+Xray Centring
+-------------
+The xray centring code generally has three parts; detect the grid to flyscan over, do the fast grid scan, collect the data from zocalo and move to the centre it defines. It does this with the following runs:
+
+1. ``CONST.PLAN.GRID_DETECT_AND_DO_GRIDSCAN`` is the outer run. When this starts it will deposit the initial ispyb information (but more is added as the collection continues)
+2. ``CONST.PLAN.GRIDSCAN_OUTER`` is started after we have done the grid detection but before we do the work for setting up the gridscan. It is used to set transmission (and optionally feedback as per the selected preprocessors) and to initialise nexus writing (the final nexus file is only written when all the relevant data is read from the beamline)
+3. ``CONST.PLAN.DO_FGS`` is the internal run that is opened just before the actual gridscan motion happens. The start of this will create the data to send to zocalo, zocalo is then triggered once all the (zocalo triggered by the hardware read)
+4. ``CONST.PLAN.FLYSCAN_RESULTS`` is used to emit the results of the flyscan, that are then picked up by a ``XRayCentreEventHandler`` so that we can use them later in the plan.
+
+
 Rotation Scans
 ---------------------
 
@@ -23,3 +33,5 @@ It does this by starting 1+2*N different runs:
 1. ``CONST.PLAN.ROTATION_MULTI``: This is emitted once for the whole multiple rotation. It is used by the nexus callback to get the full number of images and meta_data_run_number so that it knows which hdf file to use. When this is finished zocalo end is triggered.
 2. ``CONST.PLAN.ROTATION_OUTER``: Emitted N times, inside a ``CONST.PLAN.ROTATION_MULTI`` run. This is used to create the initial ispyb deposition and create the nexus writer (but not actually write the file)
 3. ``CONST.PLAN.ROTATION_MAIN``: Emitted N times, inside ``CONST.PLAN.ROTATION_OUTER`` run. Used to finish writing to ispyb (i.e. write success/failure) and to send collection information to zocalo.
+
+There is also a ``CONST.PLAN.ROTATION_MULTI_OUTER``, which is used when the rotation scan is run independently (i.e. outside of a bigger ``load_centre_collect``). This is needed as we need to activate the ``BeamDrawingCallback`` for this case.

src/mx_bluesky/beamlines/aithre_lasershaping/experiment_plans/robot_load_plan.py

@@ -166,7 +166,7 @@ def robot_load_and_snapshots_plan(
                 ],
             },
         ),
-        PlanNameConstants.ROBOT_LOAD_AND_SNAPSHOTS,
+        PlanNameConstants.ROBOT_LOAD,
     )
 
 

src/mx_bluesky/common/experiment_plans/common_flyscan_xray_centre_plan.py

@@ -256,8 +256,6 @@ def _generate_dummy_xrc_result(params: SpecifiedThreeDGridScan) -> XRayCentreRes
     )
 
 
-@bpp.set_run_key_decorator(PlanNameConstants.GRIDSCAN_MAIN)
-@bpp.run_decorator(md={"subplan_name": PlanNameConstants.GRIDSCAN_MAIN})
 def run_gridscan(
     fgs_composite: FlyScanEssentialDevices,
     parameters: SpecifiedThreeDGridScan,

src/mx_bluesky/common/external_interaction/callbacks/xray_centre/ispyb_callback.py

@@ -71,7 +71,7 @@ def ispyb_activation_wrapper(plan_generator: MsgGenerator, parameters):
                 "mx_bluesky_parameters": parameters.model_dump_json(),
             },
         ),
-        PlanNameConstants.ISPYB_ACTIVATION,
+        PlanNameConstants.GRID_DETECT_AND_DO_GRIDSCAN,
     )
 
 

src/mx_bluesky/common/parameters/constants.py

@@ -56,28 +56,28 @@ class OavConstants:
 
 @dataclass(frozen=True)
 class PlanNameConstants:
+    """
+    See https://diamondlightsource.github.io/mx-bluesky/main/developer/general/explanations/callback_and_run_logic.html
+    for how these are used.
+    """
+
+    # UDC plan
     LOAD_CENTRE_COLLECT = "load_centre_collect"
     # Robot subplans
     ROBOT_LOAD = "robot_load"
     ROBOT_UNLOAD = "robot_unload"
-    # Gridscan
+    # Gridscan and xrc subplans
     GRID_DETECT_AND_DO_GRIDSCAN = "grid_detect_and_do_gridscan"
-    GRID_DETECT_INNER = "grid_detect"
     GRIDSCAN_OUTER = "run_gridscan_move_and_tidy"
-    GRIDSCAN_AND_MOVE = "run_gridscan_and_move"
-    GRIDSCAN_MAIN = "run_gridscan"
     DO_FGS = "do_fgs"
-    # IspyB callback activation
-    ISPYB_ACTIVATION = "ispyb_activation"
-    ROBOT_LOAD_AND_SNAPSHOTS = "robot_load_and_snapshots"
+    FLYSCAN_RESULTS = "xray_centre_results"
     # Rotation scan
     ROTATION_MULTI = "multi_rotation_wrapper"
     ROTATION_MULTI_OUTER = "multi_rotation_outer"
     ROTATION_OUTER = "rotation_scan_with_cleanup"
     ROTATION_MAIN = "rotation_scan_main"
-    FLYSCAN_RESULTS = "xray_centre_results"
+
     SET_ENERGY = "set_energy"
-    UNNAMED_RUN = "unnamed_run"
 
 
 @dataclass(frozen=True)

src/mx_bluesky/hyperion/experiment_plans/robot_load_and_change_energy.py

@@ -174,5 +174,5 @@ def robot_load_and_change_energy_plan(
                 ],
             },
         ),
-        CONST.PLAN.ROBOT_LOAD_AND_SNAPSHOTS,
+        CONST.PLAN.ROBOT_LOAD,
     )

src/mx_bluesky/hyperion/experiment_plans/rotation_scan_plan.py

@@ -260,6 +260,10 @@ def rotation_scan(
     parameters: RotationScan,
     oav_params: OAVParameters | None = None,
 ) -> MsgGenerator:
+    """This is intended to be the external API for doing the rotation scan on its own
+    rather than part of a larger UDC-like collection. In the UDC case the
+    BeamDrawingCallback will already be activated."""
+
     @bpp.set_run_key_decorator(CONST.PLAN.ROTATION_MULTI_OUTER)
     @bpp.run_decorator(
         md={

tests/conftest.py

@@ -1361,7 +1361,6 @@ def test_grid_detect_and_gridscan_start_document(self) -> RunStart:
             "versions": {"ophyd": "1.6.4.post76+g0895f9f", "bluesky": "1.8.3"},
             "scan_id": 1,
             "plan_type": "generator",
-            "plan_name": "test",
             "subplan_name": PlanNameConstants.GRID_DETECT_AND_DO_GRIDSCAN,
             "mx_bluesky_parameters": _dummy_params(self._tmp_path).model_dump_json(),
         }
@@ -1447,7 +1446,6 @@ def test_do_fgs_start_document(self) -> RunStart:
             "versions": {"ophyd": "1.6.4.post76+g0895f9f", "bluesky": "1.8.3"},
             "scan_id": 1,
             "plan_type": "generator",
-            "plan_name": PlanNameConstants.GRIDSCAN_AND_MOVE,
             "subplan_name": PlanNameConstants.DO_FGS,
             "omega_to_scan_spec": {
                 GridscanPlane.OMEGA_XY: specs[0],

tests/unit_tests/common/experiment_plans/test_common_flyscan_xray_centre_plan.py

@@ -3,6 +3,7 @@
 from unittest.mock import MagicMock, call, patch
 
 import bluesky.plan_stubs as bps
+import bluesky.preprocessors as bpp
 import numpy as np
 import pytest
 from bluesky.run_engine import RunEngine, RunEngineResult
@@ -440,7 +441,9 @@ def test_when_grid_scan_fails_with_exception_then_detector_disarmed_and_correct_
 
         with pytest.raises(CompleteError):
             run_engine(
-                run_gridscan(fake_fgs_composite, test_fgs_params, beamline_specific)
+                bpp.run_wrapper(
+                    run_gridscan(fake_fgs_composite, test_fgs_params, beamline_specific)
+                )
             )
 
         fake_fgs_composite.eiger.disable_roi_mode.assert_called()

tests/unit_tests/common/preprocessors/test_preprocessors.py

@@ -267,7 +267,7 @@ def first_unnamed_run():
     def second_unnamed_run():
         yield from bps.null()
 
-    @bpp.set_run_key_decorator(PlanNameConstants.GRID_DETECT_INNER)
+    @bpp.set_run_key_decorator("test")
     @bpp.run_decorator()
     @pause_xbpm_feedback_during_collection_at_desired_transmission_decorator(
         devices=xbpm_and_transmission_wrapper_composite,
@@ -276,7 +276,7 @@ def second_unnamed_run():
     def first_named_run():
         yield from second_named_run()
 
-    @bpp.set_run_key_decorator(PlanNameConstants.GRID_DETECT_INNER)
+    @bpp.set_run_key_decorator("test")
     @bpp.run_decorator()
     def second_named_run():
         yield from bps.null()