Skip to content
A Python library to read PTU files from PicoQuant
C Python
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.
readPTU.egg-info Removed unncecsary comment Dec 22, 2017
readPTU Merge branch 'master' of Nov 27, 2019
.gitignore Fixed last commit Dec 9, 2017 modified so that we can directly use the functions by imp… Dec 18, 2017
TODO added TODO file -RProux Dec 8, 2017 Corrected time_range calculation mistake in and added time… Dec 14, 2017

readPTU library

PicoQuant uses a specific homemade file format called PTU for its time-tag time-resolved measurements. This format is subsequent to the former .pt2 or .pt3 and can handle both T2 and T3 acquisition modes for a variety of devices (Hydraharp, Picoharp, Timeharp, etc.).

For now the library handles Hydraharp V2 and Picoharp files in T2 mode only — which are the only devices we have available for testing.


To install this package, you need to have a compiler present on your system (gccon Linux, clang on macOS or vc on Windows). you can run the file using The package should compile the libraries when installed

Use example

To start, you should import the readPTU library you should open the PTU file using a PTUfile() object. Constructing a PTUfile() object automatically opens the file and leaves it open for further analysis. As a first step, you can then print the header which will bring useful information on the measurement, like measurement time, number of records, record format type, etc.

ptu_file = PTUfile(r'path/to/the/file')

To analyse the file, e.g. to calculate a timetrace or a g2, you should use the PTUmeasurement() class. To construct a PTUmeasurement() object, you need to provide an open PTUfile object (ptu_file in our example).

ptu_meas = PTUmeasurement(ptu_file)

The PTUmeasurement() object has methods to analyse the measurement. For example, to calculate a timetrace with a time bin resolution of 1 second:

timetrace_x, timetrace_y, timetrace_recnum = ptu_meas.time_trace(resolution=1)

For a g2 measurement, you can use:

histo_x, histo_y = ptu_meas.calculate_g2(correlation_window=1000000, resolution=10000, fast=True)

The g2 measurement in particular has two available algorithms which may be selected using the fast parameter:

  • fast=True is faster to compute (typical time: a few minutes for a 10 GB file). It consists in finding chronologically the sequence of start-stop — start-stop — start-stop... photons and record the associated delays in a histogram. This is very similar to the histogram mode of most correlation cards, which will do this live during the measurement. This algorithm presents the disadvantage of keeping only the first stop photon and remove all subsequent stop photons which should count in a proper g2 but are lost by the algorithm. The concrete effect is an exponential decay artefact which will appear obviously when using long correlation windows or performing a measurement with high photon rates.
  • fast=False is typically an order of magnitude slower than fast mode. This algorithm will consider all possible pairs of start-stop photons with a delay smaller than the correlation window. The main advantage is that for a given start photon, you count all the subsequent stop photons, removing the exponential decay artefact. You usually end up with more coincidence counts as well.

Dynamic library compilation

readPTU uses the cffi package which handles building and interfacing of C dynamic libraries. The C code is in the readTTTRRecords-for-import.c file, which is imported in Python and compiled by executing the file.

If there is no dynamic library matching your system, you should simply execute in python. You still need to have a compiler installed. If it does not work, you should explore cffi's documentation for platform-specific installation instructions. Some hints for Windows: set up visual studio from the website of Microsoft and using import setuptools has worked... You can have a look here and here as well. On Mac or Linux, simply installing gcc should work, if it is not already there.


Raphaël Proux - 12/10/2017 - first release with T2 mode only and support of Hydraharp v2 tested, Hydraharp v1 and Picohard untested (but implemented).

Raphaël Proux - 18/10/2017 - tested on windows 7 64 bits! It works!! (you need to add import setuptools in the python build file though).

Guillem Ballesteros-Garcia and Raphaël Proux - 18/12/2017 - very optimised version with new algorithms (ring, symmetric) and new functionnalities (timetrace channel selection, post-selection). Also was put in a package style to import it easily on new machines.

You can’t perform that action at this time.