Set aperture according to XRC results

conftest.py

@@ -1,14 +1,11 @@
 from collections.abc import Iterator
-from os import environ
 from unittest.mock import patch
 
 import pytest
 
 # Ensure that the blueapi entry point is not invoked by doctest as this will fail
 collect_ignore = ["src/mx_bluesky/hyperion/blueapi/plans.py"]
 
-environ["HYPERION_TEST_MODE"] = "true"
-
 
 pytest_plugins = ["dodal.testing.fixtures.run_engine"]
 

docs/user/hyperion/advanced/advanced_configuration.rst

@@ -0,0 +1,18 @@
+Advanced Configuration
+======================
+
+Environment Variables
+---------------------
+
+Hyperion deployment is configurable by number of different environment variables:
+
+.. csv-table:: Environment variables
+    :widths: auto
+    :header: "Environment Variable", "Description"
+
+    "ISPYB_CONFIG_PATH", "Path to endpoint and credential configuration for ISPyB and ExpEye"
+    "LOG_DIR", "Path to the logging directory for file-based logging"
+    "DEBUG_LOG_DIR", "Path to the logging directory for the debug log"
+    "ZOCALO_CONFIG", "Path to the configuration YAML file for zocalo"
+    "BEAMLINE", "Defines the name of the beamline"
+    "CONFIG_SERVER_URL", "URL for the config server"

docs/user/hyperion/configuration.rst

@@ -56,4 +56,10 @@ Note that currently the rest of the configuration files are not read from the co
 ultimately it will be the source of all configuration and the remainder of the files in ``daq_configuration`` will be
 moved over to it.
 
+See `Config Server`_ for details of the config server and how it is configured and deployed.
+
 .. _Config Server: https://github.com/DiamondLightSource/daq-config-server/
+
+See also `Advanced Configuration`_ for details of configuration performed at deployment time.
+
+.. _`Advanced Configuration`: advanced/advanced_configuration.html

docs/user/hyperion/troubleshooting.rst

@@ -40,7 +40,7 @@ following
 However on inspection the start log will not show any errors. Hyperion running can be verified as above `Verifying 
 that Hyperion is running`_
 
-.. _`Verifying that Hyperion is running`: advanced/install.rst
+.. _`Verifying that Hyperion is running`: advanced/install.html
 
 Smargon Motion
 ~~~~~~~~~~~~~~

pyproject.toml

@@ -238,7 +238,7 @@ commands = [
         ], extend = true },
     ],
 ]
-set_env = { DODAL_TEST_MODE = "true", BEAMLINE = "test" }
+set_env = { DODAL_TEST_MODE = "true", BEAMLINE = "i03" }
 
 
 # Runs the system tests locally
@@ -260,7 +260,8 @@ DOCKER = "podman"
 DODAL_TEST_MODE = "true"
 ISPYB_CONFIG_PATH = "{toxinidir}/tests/test_data/ispyb-test-credentials.cfg"
 ZOCALO_CONFIG = "{toxinidir}/tests/test_data/zocalo-test-configuration.yaml"
-BEAMLINE = "test"
+BEAMLINE = "i03"
+CONFIG_SERVER_URL = "http://localhost:8555"
 
 [tool.tox.env.docs]
 description = "Run docs build with clean environment"

run_hyperion.sh

@@ -110,6 +110,8 @@ if [ -z "${BEAMLINE}" ]; then
     exit 1
 fi
 
+export CONFIG_SERVER_URL="https://${BEAMLINE}-daq-config.diamond.ac.uk"
+
 if [[ $STOP == 1 ]]; then
     if [ $IN_DEV == false ]; then
         check_user

src/mx_bluesky/beamlines/i04/experiment_plans/i04_grid_detect_then_xray_centre_plan.py

@@ -6,7 +6,7 @@
 import bluesky.preprocessors as bpp
 from bluesky.utils import MsgGenerator
 from dodal.common import inject
-from dodal.devices.aperturescatterguard import ApertureScatterguard, ApertureValue
+from dodal.devices.aperturescatterguard import ApertureScatterguard
 from dodal.devices.attenuator.attenuator import BinaryFilterAttenuator
 from dodal.devices.backlight import Backlight
 from dodal.devices.beamlines.i04.beamsize import Beamsize
@@ -69,7 +69,7 @@
 from mx_bluesky.common.external_interaction.callbacks.xray_centre.nexus_callback import (
     GridscanNexusFileCallback,
 )
-from mx_bluesky.common.parameters.components import get_param_version
+from mx_bluesky.common.parameters.components import AperturePolicy, get_param_version
 from mx_bluesky.common.parameters.constants import (
     EnvironmentConstants,
     OavConstants,
@@ -112,7 +112,7 @@ def _change_beamsize(
     An aperture is needed to reduce scatter but the transfocator is best used for beamsize
     changes as it gives more flux compared to a bigger beam with a small aperture.
     """
-    parameters.selected_aperture = ApertureValue.LARGE
+    parameters.selected_aperture = AperturePolicy.LARGE
     yield from bps.abs_set(
         transfocator, beamsize, group=PlanGroupCheckpointConstants.GRID_READY_FOR_DC
     )

src/mx_bluesky/common/device_setup_plans/manipulate_sample.py

@@ -10,6 +10,7 @@
 from dodal.devices.smargon import CombinedMove, Smargon
 from dodal.devices.thawer import OnOff, Thawer
 
+from mx_bluesky.common.parameters.components import AperturePolicy
 from mx_bluesky.common.parameters.constants import PlanGroupCheckpointConstants
 from mx_bluesky.common.utils.log import LOGGER
 
@@ -18,7 +19,7 @@
 
 def setup_sample_environment(
     aperture_scatterguard: ApertureScatterguard,
-    aperture_position_gda_name: str | None,
+    aperture_policy: AperturePolicy,
     backlight: Backlight,
     thawer: Thawer,
     group="setup_senv",
@@ -29,18 +30,28 @@ def setup_sample_environment(
 
     yield from bps.abs_set(backlight, InOut.OUT, group=group)
 
-    aperture_value = (
-        None
-        if not aperture_position_gda_name
-        else ApertureValue(aperture_position_gda_name)
-    )
+    aperture_value = _rotation_aperture_value_from_policy(aperture_policy)
+
     yield from move_aperture_if_required(
         aperture_scatterguard, aperture_value, group=group
     )
 
     yield from bps.abs_set(thawer, OnOff.OFF, group=group)
 
 
+def prepare_aperture_for_rotation_if_required(
+    aperture_scatterguard: ApertureScatterguard,
+    aperture_policy: AperturePolicy,
+):
+    aperture_value = _rotation_aperture_value_from_policy(aperture_policy)
+    if aperture_value:
+        yield from bps.prepare(
+            aperture_scatterguard,
+            aperture_value,
+            group=PlanGroupCheckpointConstants.PREPARE_APERTURE,
+        )
+
+
 def move_aperture_if_required(
     aperture_scatterguard: ApertureScatterguard,
     aperture_value: ApertureValue | None,
@@ -110,3 +121,19 @@ def move_phi_chi_omega(
     )
     if wait:
         yield from bps.wait(group)
+
+
+def _rotation_aperture_value_from_policy(
+    policy: AperturePolicy,
+) -> ApertureValue | None:
+    match policy:
+        case AperturePolicy.SMALL:
+            return ApertureValue.SMALL
+        case AperturePolicy.MEDIUM:
+            return ApertureValue.MEDIUM
+        case AperturePolicy.LARGE | AperturePolicy.AUTO:
+            return ApertureValue.LARGE
+        case AperturePolicy.CURRENT_POSITION:
+            return None
+        case _:
+            raise ValueError(f"Unsupported aperture policy {policy}")

src/mx_bluesky/common/experiment_plans/change_aperture_then_move_plan.py

@@ -2,16 +2,13 @@
 from typing import Any
 
 import bluesky.plan_stubs as bps
-import numpy
-from dodal.devices.aperturescatterguard import ApertureScatterguard, ApertureValue
 from dodal.devices.smargon import Smargon, StubPosition
 from dodal.devices.zocalo import ZocaloResults
 
 from mx_bluesky.common.device_setup_plans.manipulate_sample import move_x_y_z
 from mx_bluesky.common.experiment_plans.inner_plans.xrc_results_utils import (
     fetch_xrc_results_from_zocalo,
 )
-from mx_bluesky.common.parameters.constants import PlanGroupCheckpointConstants
 from mx_bluesky.common.parameters.device_composites import (
     GridDetectThenXRayCentreComposite,
 )
@@ -45,35 +42,6 @@ def get_results_and_move_to_xtal(
     yield from move_to_xtal(flyscan_results[0], composite.gonio)
 
 
-# Currently not being used, but see https://github.com/DiamondLightSource/mx-bluesky/issues/561
-def get_results_then_change_aperture_and_move_to_xtal(
-    composite: GridDetectThenXRayCentreComposite,
-    parameters: SpecifiedThreeDGridScan,
-    flyscan_event_handler: XRayCentreEventHandler,
-):
-    flyscan_results = yield from _get_xrc_results(
-        composite.zocalo, parameters, flyscan_event_handler
-    )
-    yield from change_aperture(flyscan_results[0], composite.aperture_scatterguard)
-    yield from move_to_xtal(flyscan_results[0], composite.gonio)
-
-
-def change_aperture(
-    best_hit: XRayCentreResult,
-    aperture_scatterguard: ApertureScatterguard,
-):
-    """For the given x-ray centring result,
-    * Change the aperture so that the beam size is comparable to the crystal size
-    """
-    bounding_box_size = numpy.abs(
-        best_hit.bounding_box_mm[1] - best_hit.bounding_box_mm[0]
-    )
-    yield from _set_aperture_for_bbox_mm(
-        aperture_scatterguard,
-        bounding_box_size,
-    )
-
-
 def move_to_xtal(
     best_hit: XRayCentreResult,
     smargon: Smargon,
@@ -93,40 +61,3 @@ def move_to_xtal(
     if set_stub_offsets:
         LOGGER.info("Recentring smargon co-ordinate system to this point.")
         yield from bps.mv(smargon.stub_offsets, StubPosition.CURRENT_AS_CENTER)
-
-
-def _set_aperture_for_bbox_mm(
-    aperture_device: ApertureScatterguard,
-    bbox_size_mm: list[float] | numpy.ndarray,
-    group=PlanGroupCheckpointConstants.GRID_READY_FOR_DC,
-):
-    """Sets aperture size based on bbox_size.
-
-    This function determines the aperture size needed to accommodate the bounding box
-    of a crystal. The x-axis length of the bounding box is used, setting the aperture
-    to Medium if this is less than 50um, and Large otherwise.
-
-    Args:
-        aperture_device: The aperture scatter guard device we are controlling.
-        bbox_size_mm: The [x,y,z] lengths, in mm, of a bounding box
-        containing a crystal. This describes (in no particular order):
-        * The maximum width a crystal occupies
-        * The maximum height a crystal occupies
-        * The maximum depth a crystal occupies
-        constructing a three dimensional cuboid, completely encapsulating the crystal.
-
-    Yields:
-        Iterator[MsgGenerator]
-    """
-
-    # bbox_size is [x,y,z], for i03 we only care about x
-    new_selected_aperture = (
-        ApertureValue.MEDIUM if bbox_size_mm[0] < 0.05 else ApertureValue.LARGE
-    )
-    LOGGER.info(
-        f"Setting aperture to {new_selected_aperture} based on bounding box size {bbox_size_mm}."
-    )
-
-    yield from bps.abs_set(
-        aperture_device.selected_aperture, new_selected_aperture, group=group
-    )

src/mx_bluesky/common/experiment_plans/common_grid_detect_then_xray_centre_plan.py

@@ -7,6 +7,7 @@
 from bluesky import preprocessors as bpp
 from bluesky.utils import MsgGenerator
 from dodal.common.beamlines.beamline_utils import get_config_client
+from dodal.devices.aperturescatterguard import ApertureScatterguard, ApertureValue
 from dodal.devices.backlight import InOut
 from dodal.devices.eiger import EigerDetector
 from dodal.devices.oav.oav_parameters import OAVParameters
@@ -35,6 +36,7 @@
 from mx_bluesky.common.external_interaction.callbacks.xray_centre.ispyb_callback import (
     ispyb_activation_wrapper,
 )
+from mx_bluesky.common.parameters.components import AperturePolicy
 from mx_bluesky.common.parameters.constants import (
     OavConstants,
     PlanGroupCheckpointConstants,
@@ -106,6 +108,11 @@ def detect_grid_and_do_gridscan(
 
     grid_params_callback = GridDetectionCallback()
 
+    # Determine the aperture value before moving it for the OAV in case aperture_policy is CURRENT_POSITION
+    aperture_value = yield from _xrc_aperture_value_from_policy(
+        parameters.selected_aperture, composite.aperture_scatterguard
+    )
+
     yield from setup_beamline_for_oav(
         composite.gonio,
         composite.backlight,
@@ -135,13 +142,12 @@ def run_grid_detection_plan(
             parameters.box_size_um,
         )
 
-    if parameters.selected_aperture:
-        # Start moving the aperture/scatterguard into position without moving it in
-        yield from bps.prepare(
-            composite.aperture_scatterguard,
-            parameters.selected_aperture,
-            group=PlanGroupCheckpointConstants.PREPARE_APERTURE,
-        )
+    # Start moving the aperture/scatterguard into position without moving it in
+    yield from bps.prepare(
+        composite.aperture_scatterguard,
+        aperture_value,
+        group=PlanGroupCheckpointConstants.PREPARE_APERTURE,
+    )
 
     yield from run_grid_detection_plan(
         oav_params,
@@ -158,7 +164,7 @@ def run_grid_detection_plan(
     yield from bps.wait(PlanGroupCheckpointConstants.PREPARE_APERTURE)
     yield from move_aperture_if_required(
         composite.aperture_scatterguard,
-        parameters.selected_aperture,
+        aperture_value,
         group=PlanGroupCheckpointConstants.GRID_READY_FOR_DC,
     )
     xrc_params = create_parameters_for_flyscan_xray_centre(
@@ -190,3 +196,24 @@ def create_parameters_for_flyscan_xray_centre(
     flyscan_xray_centre_parameters = xrc_params_type(**params_json)
     LOGGER.info(f"Parameters for FGS: {flyscan_xray_centre_parameters}")
     return flyscan_xray_centre_parameters
+
+
+def _xrc_aperture_value_from_policy(
+    policy: AperturePolicy, aperture_scatterguard: ApertureScatterguard
+) -> MsgGenerator[ApertureValue | None]:
+    match policy:
+        case AperturePolicy.SMALL | AperturePolicy.AUTO:
+            return ApertureValue.SMALL
+        case AperturePolicy.MEDIUM:
+            return ApertureValue.MEDIUM
+        case AperturePolicy.LARGE:
+            return ApertureValue.LARGE
+        case AperturePolicy.CURRENT_POSITION:
+            previous_aperture_position = yield from bps.rd(aperture_scatterguard)
+            assert isinstance(previous_aperture_position, ApertureValue)
+            LOGGER.info(
+                f"Using previously set aperture position {previous_aperture_position}"
+            )
+            return previous_aperture_position
+        case _:
+            raise ValueError(f"Unsupported aperture policy {policy}")