Add transmission system configuration validating reader classes

* Use pydantic BaseModel classes to capture blobs from Transmission System
  specification config JSON files for I19 beamlines EH-1 / EH-2

Author: CoePaul

…/transmission/spec_from_json/__init__.py …ransmission/spec_from_config/__init__.pysrc/dodal/devices/beamlines/i19/transmission/spec_from_json/__init__.py renamed to src/dodal/devices/beamlines/i19/transmission/spec_from_config/__init__.py src/dodal/devices/beamlines/i19/transmission/spec_from_json/__init__.py renamed to src/dodal/devices/beamlines/i19/transmission/spec_from_config/__init__.py

@@ -1,4 +1,3 @@
-
 from pydantic import BaseModel, ConfigDict, Field, StrictFloat, model_validator
 
 
@@ -19,7 +18,7 @@ class EnergyIntervalSpec(BaseModel):
     upper: StrictFloat
 
     # Base Model internal setting to make this class immutable
-    model_config = ConfigDict(frozen=True)
+    model_config = ConfigDict(frozen=True, extra="forbid")
 
     @model_validator(mode="after")
     def validate_attributes(self) -> "EnergyIntervalSpec":

…n/spec_from_json/energy_interval_spec.py …spec_from_config/energy_interval_spec.pysrc/dodal/devices/beamlines/i19/transmission/spec_from_json/energy_interval_spec.py renamed to src/dodal/devices/beamlines/i19/transmission/spec_from_config/energy_interval_spec.py src/dodal/devices/beamlines/i19/transmission/spec_from_json/energy_interval_spec.py renamed to src/dodal/devices/beamlines/i19/transmission/spec_from_config/energy_interval_spec.py

@@ -4,7 +4,8 @@
 
 from dodal.common.general_maths.interval import ClosedInterval, FloatInterval
 
-PHYSICAL_ROLL_OFF: Final[FloatInterval] = ClosedInterval(lower=-4.0,upper=-2.0)
+PHYSICAL_ROLL_OFF: Final[FloatInterval] = ClosedInterval(lower=-4.0, upper=-2.0)
+
 
 class FittedAbsorptionCurveSpec(BaseModel):
     """JSON built sub-dict of one absorption curve, used in specifying material absorption spectra.
@@ -27,7 +28,7 @@ class FittedAbsorptionCurveSpec(BaseModel):
     residuals_polynomial_coeffs: list[StrictFloat] = Field(default_factory=list)
 
     # Base Model internal setting to make this class immutable
-    model_config = ConfigDict(frozen=True)
+    model_config = ConfigDict(frozen=True, extra="forbid")
 
     @model_validator(mode="after")
     def validate_attributes(self) -> "FittedAbsorptionCurveSpec":
@@ -38,7 +39,7 @@ def validate_attributes(self) -> "FittedAbsorptionCurveSpec":
                 f"Photon absorption constant {self.photon_absorption} is invalid."
             )
         _msg = (
-            f"Absorption roll off {self.roll_off} does not seem likely on physics grounds." 
+            f"Absorption roll off {self.roll_off} does not seem likely on physics grounds."
             if self.roll_off < 0
             else "Absorption roll off is a negative exponent typically close to -3.0 ∓ 1"
         )

…rom_json/fitted_absorption_curve_spec.py …m_config/fitted_absorption_curve_spec.pysrc/dodal/devices/beamlines/i19/transmission/spec_from_json/fitted_absorption_curve_spec.py renamed to src/dodal/devices/beamlines/i19/transmission/spec_from_config/fitted_absorption_curve_spec.py src/dodal/devices/beamlines/i19/transmission/spec_from_json/fitted_absorption_curve_spec.py renamed to src/dodal/devices/beamlines/i19/transmission/spec_from_config/fitted_absorption_curve_spec.py

@@ -0,0 +1,48 @@
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    StrictFloat,
+)
+
+
+class FoilThicknessSpec(BaseModel):
+    """The specification for a flat foil thickness (as specified by configuration, typically **JSON**).
+
+    Attributes:
+        units: The length unit used to specify the foil thickness.
+        value: The foil thickness in the specified unit.
+    """
+
+    units: str
+    value: StrictFloat
+
+    # Base Model internal setting to make this class immutable
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class AbsorberSpec(BaseModel):
+    """The specification for a FixedDepth absorber (as specified by configuration, typically **JSON**).
+
+    Attributes:
+        material: The name of the absorber material, as present the in the materials section of the configuration.
+        thickness: ThicknessProvider geometry of the flat foil absorber.
+    """
+
+    material: str
+    thickness: FoilThicknessSpec
+
+    # Base Model internal setting to make this class immutable
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class FoilSpec(BaseModel):
+    """The specification for a filter slot in a wheel.
+
+    Attributes:
+        absorber: Absorbing filter configuration for a given slot.
+    """
+
+    absorber: AbsorberSpec
+
+    # Base Model internal setting to make this class immutable
+    model_config = ConfigDict(frozen=True, extra="forbid")

src/dodal/devices/beamlines/i19/transmission/spec_from_config/foil_spec.py

@@ -0,0 +1,73 @@
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictFloat,
+    ValidationError,
+    model_validator,
+)
+
+from dodal.common.general_maths.interval import ClosedInterval
+from dodal.devices.beamlines.i19.transmission.spec_from_config.system_aspect_base_parser import (
+    SystemAspectBaseParser,
+)
+
+
+class LateralMotorSpec(BaseModel):
+    """The positions scale for an axial wedge motor (as specified by configuration, typically **JSON**).
+
+    Notes:
+        - The (potentially counterintuitive) class' attribute names match beamline scientists' "domain jargon".
+
+        - Each lateral motor drives one absorber wedge sideways across the x-ray beam:
+            - expected sideways motions are pure horizontal or pure vertical
+                - but that's a detail, azimuthal orientation around the beam should not matter.
+            - The position of the scale zero relative to the wedge location is hereby nailed down.
+            - The wedge motor scale has
+                - an **out** position
+                - and then a range of "active" positions, ( where the mathematical assumption of a linear taper is reasonable ).
+
+        - Although the units here will default to **mm** when unspecified (i.e. when omitted),
+        the units setting is still likely to appear in the JSON, as a handy reminder to human readers of the configuration file.
+
+    Attributes:
+        units: At present only "mm" are supported.
+        out: Motor position consistent with having fully retracted the wedge from the x-ray beam.
+        threshold: Motor position for minimal absorption in the permitted active absorbing position range.
+        max: Motor position for minimal absorption in the permitted active range.
+        tolerance: Motor position accepted margin for readout error.
+    """
+
+    units: str = Field(default="mm")
+    out: StrictFloat
+    threshold: StrictFloat
+    max: StrictFloat
+    tolerance: StrictFloat = Field(default=5.0e-3)
+
+    # Base Model internal setting to make this class immutable
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @model_validator(mode="after")
+    def validate_attributes(self) -> "LateralMotorSpec":
+        # counter-intuitive naming, but depending on
+        # motor scale orientation relative to wedge orientation
+        # max (thickness) position could greater or smaller than threshold
+        _lower = min(self.out, self.max)
+        _upper = max(self.out, self.max)
+        _interval = ClosedInterval(lower=_lower, upper=_upper)
+        if self.threshold in _interval:
+            return self
+        msg: str = r"Inconsistent wedge geometry: Threshold not between max and out."
+        raise ValidationError(msg)
+
+
+class LateralMotorsConfig(SystemAspectBaseParser[LateralMotorSpec]):
+    """Maps from highest level configuration (JSON) dict to extract lateral motor specifications.
+
+    Uses base class method **extract_specifications** and some pythonic type handling magic.
+
+    See Also:
+        Base of this parser class, namely **SystemAspectBaseParser**
+    """
+
+    pass

src/dodal/devices/beamlines/i19/transmission/spec_from_config/lateral_motor_spec.py

@@ -0,0 +1,133 @@
+import re
+from typing import Any, Final
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
+from pydantic_core import PydanticCustomError
+
+from dodal.devices.beamlines.i19.transmission.spec_from_config.energy_interval_spec import (
+    EnergyIntervalSpec,
+)
+from dodal.devices.beamlines.i19.transmission.spec_from_config.fitted_absorption_curve_spec import (
+    FittedAbsorptionCurveSpec,
+)
+from dodal.devices.beamlines.i19.transmission.spec_from_config.system_aspect_base_parser import (
+    SystemAspectBaseParser,
+)
+
+
+class MaterialNameValidation:
+    """Absorber materials naming validation regular expression.
+
+    Either permits (at start of name):
+    - leading underscore followed immediately by a letter,
+    or,
+    - leading letter,
+    then any number of alphanumerics or underscores or hyphens.
+    """
+
+    MATERIAL_NAME_REGEXP: Final = r"^([A-Za-z]|_[A-Za-z])[A-Za-z0-9_-]*$"
+
+    @staticmethod
+    def validate_material_name(*, material_name: str) -> None:
+        _matcher = re.compile(MaterialNameValidation.MATERIAL_NAME_REGEXP)
+        if _matcher.match(material_name) is None:
+            raise PydanticCustomError(
+                "invalid_material_name",
+                "Material name '{m}' needed to be alphanumeric or underscores, (hyphens permitted after first character).",
+                {"m": material_name},
+            )
+
+
+class AbsorptionVsEnergyRelation(BaseModel):
+    """Configuration dict for one piece of an absorption spectrum, one energy range specific fit curve.
+
+    Note:
+        This relation class is a pairing.  The internal pair consists of :
+        - The x-ray energy interval over which this piece of the spectrum is valid (a.k.a. domain).
+        - The parameters of a fitted absorption curve.
+
+    Attributes:
+        valid_energies: Specifies x-ray energy *domain* valid for the fitted curve.
+        fit_parameters: Specifies parameters needed to calculate absorption values on the fitted curve.
+
+    *See also, these closely related classes:*
+        **FittedAbsorptionCurveSpec**: Fitted curve specification
+        **EnergyIntervalSpec**: Energy range (interval) specification
+        **ClosedInterval**: General maths class underpinning interval definition
+    """
+
+    valid_energies: EnergyIntervalSpec
+    fit_parameters: FittedAbsorptionCurveSpec
+
+    # Base Model internal setting to make this class immutable
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class MaterialAbsorptionSpectrumSpec(BaseModel):
+    """Configuration dict for the absorption spectrum of a specific material.
+
+    Note:
+        One spectrum absorption curve covers a specific energy range where it is valid.
+        One or more such curves make up one absorption spectrum.
+
+    Attributes:
+        absorption_curves: List of absorption curves
+    """
+
+    absorption_curves: list[AbsorptionVsEnergyRelation] = Field(..., min_length=1)
+
+    # Base Model internal setting to make this class immutable and valid
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_raw_list_to_absorption_curves_dict(cls, data: Any) -> Any:
+        """Wrap spectrum pieces listing internally as a dict."""
+        if isinstance(data, list):
+            return {"absorption_curves": data}
+        if isinstance(data, dict):
+            return data
+        raise ValueError(
+            "Absorption spectrum data should be a list or dict of fitted curves."
+        )
+
+
+class MaterialAbsorptionSpectralConfig(
+    SystemAspectBaseParser[MaterialAbsorptionSpectrumSpec]
+):
+    """Configuration dict for the absorption spectra of all specified absorber materials.
+
+    Maps each material name to its absorption spectrum specification, as extracted from configuration (JSON).
+
+    Note:
+        Base class does all the heavy lifting
+    """
+
+    # Base Model internal setting to make this class immutable and valid
+    model_config = ConfigDict(frozen=True)
+
+    @field_validator("root")
+    @classmethod
+    def _ensure_material_has_been_validly_named(
+        cls,
+        all_absorber_materials_specifications: dict[
+            str, MaterialAbsorptionSpectrumSpec
+        ],
+    ) -> dict[str, MaterialAbsorptionSpectrumSpec]:
+        """Validates all names for absorber materials.
+
+        Raises:
+            ValidationError should it find any material name is not compliant.
+        """
+        _specified_absorber_materials = all_absorber_materials_specifications.keys()
+        for absorber_material_name in _specified_absorber_materials:
+            MaterialNameValidation.validate_material_name(
+                material_name=absorber_material_name
+            )
+        return all_absorber_materials_specifications

src/dodal/devices/beamlines/i19/transmission/spec_from_config/material_absorption_spectrum_spec.py

@@ -0,0 +1,24 @@
+from typing import (
+    Any,
+    Generic,
+    TypeVar,
+)
+
+from pydantic import BaseModel, RootModel
+
+# A Type variable bound to the transmission system sub-specifications
+# ( each specified aspect of the overall transmission system )
+TxSubSpecT = TypeVar("TxSubSpecT", bound=BaseModel)
+
+
+class SystemAspectBaseParser(RootModel[dict[str, TxSubSpecT]], Generic[TxSubSpecT]):
+    """Generic Base Model handling dict validation and extraction from the (JSON) configuration highest level dict."""
+
+    @classmethod
+    def extract_specifications(
+        cls, *, transmission_system_configuration: dict[str, Any]
+    ) -> tuple[str, TxSubSpecT]:
+        """Extracts specification and validates configuration for one aspect of the transmission system."""
+        _parsed_blob = cls.model_validate(transmission_system_configuration)
+        _system_aspects = _parsed_blob.root.items()
+        return next(iter(_system_aspects))

src/dodal/devices/beamlines/i19/transmission/spec_from_config/system_aspect_base_parser.py

@@ -0,0 +1,44 @@
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+)
+
+from dodal.devices.beamlines.i19.transmission.spec_from_config.lateral_motor_spec import (
+    LateralMotorsConfig,
+)
+from dodal.devices.beamlines.i19.transmission.spec_from_config.material_absorption_spectrum_spec import (
+    MaterialAbsorptionSpectralConfig,
+)
+from dodal.devices.beamlines.i19.transmission.spec_from_config.usage_priority_spec import (
+    UsagePriorityConfig,
+)
+from dodal.devices.beamlines.i19.transmission.spec_from_config.wedges_spec import (
+    WedgesConfig,
+)
+from dodal.devices.beamlines.i19.transmission.spec_from_config.wheels_spec import (
+    WheelsConfig,
+)
+
+
+class TransmissionSystemSpec(BaseModel):
+    """Maps input configuration (i.e. JSON ) to highest level dict for I19 transmission system.
+
+    Note:
+         Sub-dictionaries carry the details of each aspect of the system.
+
+    Attributes:
+        lateral_motors: Position (scale) for wedge motors.
+        materials: Absorption spectra for all absorber filter materials in wedges or foils.
+        wedges: The shape, motor and material details for all system variable depth wedge absorbers.
+        wheels: The slot occupancy, foil materials, motor name for all system filter wheels.
+        usage_priority: Beamline scientists policy on which absorbers to prefer using first.
+    """
+
+    lateral_motors: LateralMotorsConfig
+    materials: MaterialAbsorptionSpectralConfig
+    wedges: WedgesConfig
+    wheels: WheelsConfig
+    usage: UsagePriorityConfig
+
+    # Base Model internal setting to make this class immutable and valid
+    model_config = ConfigDict(frozen=True, extra="forbid")