Parameter model

Hyperion employs a parameter model which is separated into external and internal parts, with a conversion between them. The decision to implement it this way is because the internal organisation is impacted by which parameters are needed for executing certain functions, which may not correspond directly to a logical way of specifying instructions for hyperion to run an experiment. For example, the wavelength, resolution, and beam size are internally referred to as "ISPyB" parameters, because they are needed for making IPSyB depositions. However, these values are logically best considered as experiment parameters. The ISPyB parameters are soon to be removed as they can be read from devices during the experiment, but a similar rationale exists for DetectorParams - things which are needed by the detector.

Externally supplied parameters are validated against a strict pydantic model to reduce the chance of executing the wrong instructions. These models are combinations of building blocks found in src/hyperion/parameters/components.py. Building blocks include logical groupings like "an optional goniometer position" (OptionalXyzStarts) or "everything that is compulsory for an experiment which uses beam (DiffractionExperiment). In this way, we can keep naming of parameters between different experiment types consistent and reduce duplication. For example, to specify the parameters for a rotation scan, we can write:

class RotationScan(
    DiffractionExperiment,
    WithScan,
    OptionalGonioAngleStarts,
    OptionalXyzStarts,
    WithSample,
):
...
<only a few additional fields>

and implement the required abstract methods, to end up with a parameter model as follows:

class RotationScan(
    *,
    sample_id: int,
    _puck: int | None = None,
    _pin: int | None = None,
    x_start_um: float | None = None,
    y_start_um: float | None = None,
    z_start_um: float | None = None,
    omega_start_deg: float = 0,
    phi_start_deg: float | None = None,
    chi_start_deg: float | None = None,
    kappa_start_deg: float | None = None,
    parameter_model_version: ParameterVersion,
    visit: str,
    file_name: str,
    exposure_time_s: float,
    comment: str = "",
    beamline: str = CONST.I03.BEAMLINE,
    insertion_prefix: str = CONST.I03.INSERTION_PREFIX,
    det_dist_to_beam_converter_path: str = CONST.PARAM.DETECTOR.BEAM_XY_LUT_PATH,
    zocalo_environment: str = CONST.ZOCALO_ENV,
    detector: str = CONST.I03.DETECTOR,
    trigger_mode: TriggerMode = TriggerMode.FREE_RUN,
    detector_distance_mm: float | None = None,
    demand_energy_ev: float | None = None,
    run_number: int | None = None,
    storage_directory: str,
    rotation_axis: RotationAxis = RotationAxis.OMEGA,
    shutter_opening_time_s: float = CONST.I03.SHUTTER_TIME_S,
    scan_width_deg: float = 360,
    rotation_increment_deg: float = 0.1,
    rotation_direction: RotationDirection = RotationDirection.NEGATIVE,
    transmission_frac: float,
    ispyb_extras: TemporaryIspybExtras
)