Abstract interface for motorized polarization controllers and MPC320 driver

[auspicacious]

We want to support motorized polarization controllers such as the Thorlabs MPC320.

This is a good chance for us to see if we can successfully implement an abstract base class as described in https://github.com/moonshot-nagayama-pj/PnPQ/issues/29 before we attempt to refactor existing code.

Acceptance criteria

• Third-party libraries https://thorlabs-apt-device.readthedocs.io/en/latest/index.html , https://pypi.org/project/pyThorlabsAPT/ https://github.com/UniNE-CHYN/thorpy and https://pylablib.readthedocs.io/en/latest/devices/Thorlabs_misc.html https://instrumentkit.readthedocs.io/en/latest/ are evaluated for comparison and possible use
• Abstract base class provides an interface that could be used for any similar device, including ones from competing manufacturers
• Implementation for MPC320 is complete
• Manual testing against physical device is complete
• Code passes all static analysis checks and requirements in https://github.com/moonshot-nagayama-pj/PnPQ/issues/29

Good to have

• Some form of automated testing is possible, maybe by mocking the underlying pySerial library.
• Using a library that allows for easy conversion of scientific units may be desirable, and those should be evaluated.

References

• https://www.thorlabs.com/thorproduct.cfm?partnumber=MPC320
• https://www.notion.so/Thorlabs-Motorized-Polarization-Controller-9fb30b33750545a9916acdb87216e46e
• https://github.com/moonshot-nagayama-pj/playground/blob/main/amin/devel-testbed-tools/polc_thorlabs_CLI_2024_08_22.py

[auspicacious]

Some notes on third-party libraries:

• thorlabs-apt-device is actively maintained and cross-platform. It might be useful for us to use this library in implementation. Unfortunately it does not have type hints yet. There is another issue: it's GPL licensed. Using it in PnPQ would effectively require us to license PnPQ as GPL as well, as well as any further dependent testbed repositories we publish. This warrants a much broader team discussion and I am unsure of the outcome.
• pyThorlabsAPT is focused on Windows and uses the proprietary Thorlabs DLL, so it is not useful to us.
• thorpy does not appear to be maintained.
• pylablib seems like it might be difficult for us to extend compared to thorlabs-apt-device. Also, it seems to be basing its implementations on the SCPI protocol, not APT, so I'm not sure that it's appropriate for our devices. I think that the one APT device they support uses the Thorlabs DLL, so, again, not an option. Pylablib is also GPL.

[auspicacious]

Wow, there are a lot of Python libraries related to scientific units.

No longer maintained or considered not ready for production

We should avoid using these.

• Natu seems to have good design principles, but apparently stalled out on development in 2015 before tests were complete, making it unusable at the moment.
• Dimpy looks to be very old and unmaintained. There are other unrelated packages with the same name.
• Magnitude is described as "ancient" by its developer, although still used, and doesn't appear to be in PyPI, so it's probably not a good choice.
• quantities is dependent on and built around NumPy, which we probably don't want to make into a PnPQ dependency. The documentation also says that it is not ready for production use.
• scalar looks very old and unmaintained. Some of the author's general views on reality are also troubling.
• ScientificPython (not SciPy) contains a units module, but has been unmaintained since 2014.
• udunitspy is explicitly deprecated.
• https://bitbucket.org/adonohue/units seems to have disappeared, although it's still on PyPI.
• Buckingham doesn't look maintained or fully developed.

Dependencies on bigger libraries

We should avoid using these.

• SymPy units are probably more useful for people using SymPy.
• AstroPy units is part of a larger package for astronomy.
• unyt Actively developed, seems like good documentation, requires both NumPy and SymPy

Further investigation required

These might be useful.

• numericalunits was last released in 2020, but maybe it's feature-complete.
• SciMath Units is maintained, with a release every few years.
• cf-units "Units of measure as defined by the Climate and Forecast (CF) Metadata Conventions."
• unum appears to be maintained.
• QuantiPhy
• UnitPy actively developed, very low pre-1.0 version number, support for Numpy but no dependency
• si_units last updated in 2020, appears to be modern Python
• forallpeople built around SI units and uses SI units to define all other units
• pint Appears to be mature, actively developed, documentation, integration with Pandas and NumPy without dependencies on them.

[auspicacious]

Pint seems to have the most features and the most complete documentation. It's also actively maintained. It doesn't have type safety (all quantities are the same class) but the many features it offers, including optional NumPy and pandas integration, seem to make it the only viable choice at this point in time.

Newly discovered but not appropriate

• quantity is the only library I've found that takes a type-safe approach to the problem; each kind of quantity, such as Length or Area, gets its own class. This is ideal, but unfortunately the library does not appear to have sufficient features or maturity to use.
• misura seems to have been deleted from GitHub

Not appropriate

• numericalunits uses an approach that avoids typing and will only make unit mismatch errors visible when a program is run more than once. Even though unit testing would still detect some of these errors, it is not taking advantage of the full capabilities of the programming language.
• SciMath Units, on closer examination, is closely dependent on NumPy.
• cf-units is really a wrapper around a C library and standard for a specific scientific field that is probably not appropriate for us.
• Unum doesn't seem unreasonable, but has no type annotation support.
• QuantiPhy seems to be more focused on string formatting?
• unitpy seems to be fairly limited still
• si_units really only handles SI units, e.g. it will understand radians but not degrees, and this is probably too limiting.
• forallpeople's focus on SI units and relative lack of features makes it less desirable

[auspicacious]

Discovered yet another library that supports Thorlabs APT devices and supports a connection abstraction so it's possible to use, for instance, serial over Ethernet: https://instrumentkit.readthedocs.io/en/latest/

I'm not sure if everything works 100% for the APT protocol, as the library was originally mostly built for SCPI, I think. However, it has a nice object model for building messages (each APT packet is an object). It also uses Pint to make sure that values have units wherever possible.

While I would like to consider using this library, it's AGPL licensed. Using it in PnPQ would effectively require us to license PnPQ as AGPL (or GPL, I think) as well, as well as any further dependent testbed repositories we publish. This warrants a much broader team discussion and I am unsure of the outcome.

[auspicacious]

I'm convinced that implementing a usable interface that can handle things like status updates will require either threading or asyncio, and I'm working through the details now.