Investigate using stricter units on signals

[DominicOram]

As an MX DAQ developer we often have issues where we get confused about what units physical quantities are being expressed in (e.g. DiamondLightSource/mx-bluesky#220). It may be useful if we could be more strict about this in the code by leveraging something like pint. This would mean signals are set with Quantities that have units and will throw exceptions if the units given in the EGU field of the PV do not match. This is a spike to do the investigation on how hard this would be and what an interface would look like.

Acceptance Criteria

• We investigate using a library like pint to allow setting signals with values that have unit metadata
• We investigate how much this would change bluesky etc.
• An estimate for the work is written up, with a mock up of roughly what the interface would look like on the plan/device side
• It is decided whether we do this or not and an ADR is made

[coretl]

My suggestion would be to:

• Add pint.facets.numpy.quantity.NumpyQuantity[x] for x in int, float and pint.facets.plain.quantity.PlainQuantity[x] for x in the supported numpy numeric types here:
  

  ophyd-async/src/ophyd_async/core/_signal_backend.py

  Lines 25 to 44 in f37968e

  	SignalDatatype = (
  	Primitive
  	| StrictEnum
  	| Array1D[np.bool_]
  	| Array1D[np.int8]
  	| Array1D[np.uint8]
  	| Array1D[np.int16]
  	| Array1D[np.uint16]
  	| Array1D[np.int32]
  	| Array1D[np.uint32]
  	| Array1D[np.int64]
  	| Array1D[np.uint64]
  	| Array1D[np.float32]
  	| Array1D[np.float64]
  	| np.ndarray
  	| Sequence[str]
  	| Sequence[StrictEnum]
  	| Table
  	)
  	"""The supported [](#Signal) datatypes:

• Add support in each SignalBackend to deal with type hinted quantity types like SignalW[PlainQuantity[float]] or SignalR[NumpyQuantity[Array1D[np.float64]]]
• Think about a type alias to make that within ophyd-async namespace and shorter, e.g. SignalW[ScalarQuantity[float]] and SignalR[Array1DQuantity[np.float64]]
• If we see something like this, at runtime we need to ensure it has EGUs and they are valid in the default registry
• At runtime then get_value() and read() will start returning pint Quantity instances
• At runtime set() will start requiring pint Quantity instances
• The units will be converted before passing through and back to the control system
• We will need to add support for serialization, and decide how the units are placed in the yaml file
• Need to think through the implications of using Quantity everywhere when it comes to typing

[DominicOram]

This obviously all needs a lot more thought but I think I would also like to specify the units when writing the device. This means that I can then reason about them in the rest of the codebase before runtime. In this case, if the units I specify do not match the EGU I would like the device to crash out or shout loudly.

I think just allowing this and not having the generic runtime creation of units would still help a lot in the accidental conversion stuff so if it's easier to do just this first I would go for that

[Tom-Willemsen]

if the units I specify do not match the EGU I would like the device to crash out or shout loudly.

We would likely adopt that kind of approach at ISIS in many places too, whereas I don't think we'd be able to adopt a pint-based runtime approach as easily (we're using a different library for our units handling). i.e. a "dumb" string comparison of get(EGU) == expected, during connect() - probably set up as an argument to epics_signal_r and friends...

[coretl]

So would:

self.value = epics_signal_rw(float, prefix + ":VALUE", units="mm")

that still gave you a float when you get_value, but failed loudly at connect if .EGU is anything other than "mm" work?

[coretl]

@Tom-Willemsen what library are you using for units handling?

[Tom-Willemsen]

@Tom-Willemsen what library are you using for units handling?

We're using scipp internally which handles physical units, but also uncertainties, xarray-like abstractions, and integrates nicely with scippneutron which has neutron-specific utilities that are useful for us (e.g. "unit conversions" from time-of-flight to wavelength).

[DominicOram]

that still gave you a float when you get_value, but failed loudly at connect if .EGU is anything other than "mm" work?

I think this is a good step but I also think that I would like that unit information to be passed around with the value too. In a really ideal world I would like something like:

self.small_value = epics_signal_rw(float, prefix + ":VALUE1", units="mm")
self.big_value = epics_signal_rw(float, prefix + ":VALUE2", units="m")

my_new_value = self.small_value + self.big_value

and this either throws an exception (probably my preference) or my_new_value will be big_value*1000+small_value when read in mm.

I'm not wedded to pint but looking at scipp it seems overkill for this.

[Tom-Willemsen]

Don't let my comments prevent you from implementing what you need at DLS - we're happy to continue doing what we're already doing at ISIS.

[DominicOram]

Discussed with @coretl today:

1. pint doesn't look like the best option for this as it can only really give us quantities that have units at runtime based on the EGU of the PV. It also does the magic conversion between e.g. mm -> m, which I don't like, I would rather mm + m throw an exception
2. We think it would be better to have something that lets you specify the types of things e.g.:

self.small_value = epics_signal_rw(MilliMeters, prefix + ":VALUE1")
self.big_value = epics_signal_rw(Meters, prefix + ":VALUE2")

We could then have this be caught by the type checker (and raise at runtime) if we do my_new_value = self.small_value + self.big_value. We could also provide helpers like self.bif_value.to_milli. We would also add to ophyd-async to raise on connection if the EGU does not match the type.

We feel like there should be a library out there that does this already so action on me to find one.

3. If we can't find one we instead make epics_signal_rw(float, prefix + ":VALUE2", units="m") raise if the EGU is not correct and kick further discussion into the long grass

[coretl]

Some possible ideas here:
https://stackoverflow.com/questions/62603598/enforcing-units-on-numbers-using-python-type-hints