Package: miniquant
Miniquant -- Python Wrapper for PicoQuant's Harp APIThis is a modern, convenient Python interface for PicoQuant's HydraHarp
photon counter and similar devices. It connects toPicoQuant's properietary
C library.Obligatory disclaimer: this is not an officially supported product of PicoQuant,
or in any other way affiliated, endorsed or sponsored by PicoQuant. Use at your
own risk. If you break it, you get to keep both pieces. If it breaks your hardware
(though it shouldn't), it's on you.Supported DevicesTo this point, Miniquant has been only developed for and tested with PicoQuant's
HydraHarp 400. Other devices (e.g. the PicoHarp) may be easy to support, but
no work has been done on that.InstallationMiniquant has only been tested on Linux. This installation guide focuses
on getting it up and running there.Obtain the Miniquant package.There are several ways to do that:Via PIP:pip install miniquantto run the latest official releaseFromgit repository:$ git clone https://gitlab.com/codedump2/miniquant
$ cd miniquant
$ pip install -e .Obtaininghhlib.soMiniquant uses theofficial manufacturer's API library,hhlib.so. This has to be obtained manually, as it cannot be distributed
with the Miniquant
package for licensing reasons.
Place it somewhere on your system were it's easily accessible
(e.g.~/.local/share/miniquant/hhlib.so, or, quite generically, into/path/to/hhlib.so)
and point the environment variableMINIQUANT_HHLIBto the full path of the library.$ mkdir -p ~/.local/share/miniquant
$ export MINIQUANT_LIB=~/.local/share/miniquant/hhlib.so
$ curl -O $MINIQUANT_LIB https://github.com/PicoQuant/HH400-v3.x-Demos/raw/master/Linux/64bit/library/hhlib.soFor downloadinghhlib.so, you can alternatively use the supplied scripthelpers/download-hhlib, which is located either in the Miniquant source tree,
or in the distribution folder of the installed package.Seting up the proper USB device permissions.The device ID is0e0d:0004for the PicoHarp,
and0e0d:0009for the HydraHarp. You can either set permissions to allow
read-write for everyone (0666), or allow read-write for a specific group
(e.g. dialout). The example filehelpers/miniharp.rulesshows udev rules for
the first option, i.e. allowing access for everyone:$ sudo cp helpers/miniquant.rules /etc/udev/rules.d/99-miniquant.rules
$ sudo udevadm control --reload
$ sudo udevadm triggerDealing with the quirky USB controller.At least the PicoQuant PicoHarp device, possibly others, have buggy USB
controllers. You may have to enable USB core device quirks. To do this
temporarily, execute this as a privileged user (e.g.root):$ echo 0e0d:0009:k >> /sys/module/usbcore/parameters/quirksTo make the changes permanent, appendusbcore.quirks=0e0d:0009:kto the
linux kernel boot command line (e.g. by editing/etc/default/grubor/boot/grub2/grub.cfg, depending on the customs of the Linux distribution
you're using).Failing to do this will result in the HydraHarp 400 not responding
to connection attempts, and a corresponding disconnection entry
indmesg.Checking your installation.For a start,dmesgshould tell you whether you the device is properly reconized:$ dmesg
...
usb 2-2: new SuperSpeed USB device number 4 using xhci_hcd
usb 2-2: New USB device found, idVendor=0e0d, idProduct=0009, bcdDevice= 0.01
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: HydraHarp 400
usb 2-2: Manufacturer: PicoQuant
usb 2-2: SerialNumber: 1041490Trying a simple Python script will also show you whether the connection
can be established:$ python
>>> from miniquant.harp import Monster
>>> h = Monster().find('any')
>>> h.serial
1041490Unit testingMiniquant comes with a set of unit tests which require a Harp device
attached to the computer. As such, they cannot be executed automatically
e.g. in a CI/CD enviroment, but can, and should, be executed by developers
working on Miniquant, or on users wanting to check the compatibility
of their device with the software.The unit tests are in theminiquant.tests_hwmodule, and they are divided
in two groups:harp_test_quirkedcontains tests that check proper failure
reporting on a system that doesnothave the USB quirks enabled
(seeInstallationabove. Essentially, the tests succeed
when connectionfails.harp_testcontains function tests on the hardware itself, i.e.
correct connection and data processing.The tests can be started using Pytest and will use the first device
available.Usage PrinciplesThere are two main classes the end user will directly interact with:miniquant.harp.Monsterrepresents a connection to thehhlib.solibrary. Essentially, requests of finding and opening an attached
device are directed to that class:>>> from miniquant.harp import Monster
>>> h = Monster().find()Monster.find()takes several types of parameters to specify
the identity of the device to be opened. Check theclass documentationfor details.
The function returns a Harp device object.miniquant.harp.MonsterHarpis the Harp device object of
an "open" device. It offers a number of Python properties,
mostly named after getter and setterfunctions in the manufacturer's library.Reading or setting those properties will trigger calls to
those specific functions.Specific propertiesminiquant.harp.MonsterHarpobject will return
sub-objects with properties of subsystems of the Harp ("portals").
For instance:miniquant.harp.InputChannelandminiquant.harp.InputChannelPortalfor access to channel-specific API elementsminiquant.harp.ModuleInfoPortalfor access to API elements specific
to Harp extension modulesminiquant.harp.ErrorStringPortalfor easier handling of error
messages / strings from the Harp API.In general, effort has been made to make access to the Harp device as
"Python-esque" as possible. But ultimately, the capabilities of Miniquant
are limited by the underlying API.See also theexamples section belowfor more elaborate
usage scenarii.ExamplesReading device informationThis is how to open a device and view general information
like hardware details, warnings, features and flags. Note
that some data (e.g. flags) may not necessarily contain useful
data unless measurement work has been started. Consult PicoQuant
documentation for that.#!/usr/bin/python3

import miniquant.harp as harp

hdev = harp.Monster().find()
hdev.initialize (harp.MeasurementMode.Histogramming, harp.ReferenceClock.Internal)

print ("Serial number:", hdev.serialNumber)
print ("Hardware info:", hdev.hardwareInfo)
print ("Base Resolution:", hdev.baseResolution)

print ("Features:", [ f for f in hdev.features ])
print ("Modules:", [ m.info for m in hdev.modules])
print ("Input count rates:", [ c.countRate for c in hdev.channels])
print ("Flags:", [ f for f in hdev.flags])
print ("Warnings:", [ w for w in hdev.warnings])Reading and plotting histogramHere's how to initialize and read a data histogram with
minimal settings to the HydraHarp:#!/usr/bin/python3

import miniquant.harp as harp
import matplotlib.pyplot as plt

hdev = harp.Monster().find()
hdev.initialize(harp.MeasurementMode.Histogramming,  harp.ReferenceClock.Internal)
hdev.calibrate()
hdev.syncCfd = { "level": 0.200, "zerox": 0.01 }
hdev.channels[0].cfd = { "level": 0.300, "zerox": 0.01 }

hdev.clearHistogram()
hdev.acquire(1.0)          ## acquire data for 1 second
while hdev.acquiring:
	pass

data = hdev.channels[0].histogram

plt.plot(data)CopyingNote that Miniquant isonlyavailable under theGNU GPL license. You are not allowed
to base commercial products on Miniquant. You are also not allowed
to redistribute this, or any products derived from it, unless you
place said products under the same license.