Python interface for the Harp class of PicoQuant\'s time interval analysers and photon counters
Project description
Miniquant -- Python Wrapper for PicoQuant's Harp API
This is a modern, convenient Python interface for PicoQuant's HydraHarp photon counter and similar devices. It connects to PicoQuant'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 Devices
To 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.
Installation
Miniquant 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 miniquant
to run the latest official release - From git repository:
$ git clone https://gitlab.com/codedump2/miniquant $ cd miniquant $ pip install -e .
- Via PIP:
-
Obtaining
hhlib.so
Miniquant uses the official 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_HHLIB
to 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.so
For downloading
hhlib.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 is
0e0d:0004
for the PicoHarp, and0e0d:0009
for 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.rules
shows 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 trigger
-
Dealing 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/quirks
To make the changes permanent, append
usbcore.quirks=0e0d:0009:k
to the linux kernel boot command line (e.g. by editing/etc/default/grub
or/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 in
dmesg
. -
Checking your installation. For a start,
dmesg
should 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: 1041490
Trying 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 1041490
Unit testing
Miniquant 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 the miniquant.tests_hw
module, and they are divided
in two groups:
-
harp_test_quirked
contains tests that check proper failure reporting on a system that does not have the USB quirks enabled (see Installation above. Essentially, the tests succeed when connection fails. -
harp_test
contains 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 Principles
There are two main classes the end user will directly interact with:
-
miniquant.harp.Monster
represents a connection to thehhlib.so
library. 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 the class documentation for details. The function returns a Harp device object. -
miniquant.harp.MonsterHarp
is the Harp device object of an "open" device. It offers a number of Python properties, mostly named after getter and setter functions in the manufacturer's library. Reading or setting those properties will trigger calls to those specific functions.
Specific properties miniquant.harp.MonsterHarp
object will return
sub-objects with properties of subsystems of the Harp ("portals").
For instance:
-
miniquant.harp.InputChannel
andminiquant.harp.InputChannelPortal
for access to channel-specific API elements -
miniquant.harp.ModuleInfoPortal
for access to API elements specific to Harp extension modules -
miniquant.harp.ErrorStringPortal
for 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 the examples section below for more elaborate usage scenarii.
Examples
Reading device information
This 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 histogram
Here'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)
Copying
Note that Miniquant is only available under the GNU 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for miniquant-0.3.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 84f938da96cb9cd05c8b2adeab3bc62fba4ff5b9c5128eff05002c94d013ce12 |
|
MD5 | 5fffe6f2a9fa3f166bd203a22a55376d |
|
BLAKE2b-256 | e38c3ae38b1ccbfb8f7f459962485d74009dcae67fc106ce20061f3d2f3aa681 |