Skip to content


Repository files navigation

photon correlation

Command-line tools for processing photon arrival time (TCSPC / TTTR) data


This code is written in C with no external dependencies. To build:



This project generates a suite of command-line tools designed for processing photon arrival time data. They are designed for minimum memory usage and maximum flexibility, rather than for absolute performance.

Typical workflows include:

  • calculating a g2 or nth-order correlation
  • histogramming events for lifetime analysis
  • measuring intensity over time
  • all of the above, simulatenously

These programs expect photon arrival time data in the same format as libpicoquant. See below for more details.

If you are just getting started with photon correlation and are not resource constrained (i.e. comparable amounts of RAM as your dataset size) I would consider something more like pycorrelate as this is likely to be a bit simpler to integrate. The tools here are quite flexible but really only work on the command line.

Quick guide for usage

Lifetimes (t3 data only)

photon_gn --file-in t3.csv --mode t3 --order 1 --time 0,1024,524288 --file-out t3.csv.g1


photon_gn will generate the correlation (g2) and intensity trace simulaneously. For t2 we specify the time bins:

photon_gn --file-in t2.csv --mode t2 --order 2 --time -524544,2048,524544 --file-out t2.csv.g2

For t3 we need to specify both time and pulse:

photon_gn --file-in t3.csv --mode t3 --order 2 --time -524544,1,524544 --pulse -10.5,21,10.5 --file-out t3.csv.g2


Each program gives far more detail with --help. There is a detailed description for some of the programs in doc/, and in this PhD thesis


This covers most use cases. It is designed to take in TTTR data and output intensity traces, correlations, and other useful analyzable data.


Takes in photons and outputs correlated tuples


Creates histograms of photons (t3 g1) or correlations (g2 and gn)


Measures the number of photons which arrived during a given interval

intensity_correlate, photon_intensity_correlate

Performs multi-tau correlation for fixed-interval intensity data (intensity_correlate), or for TTTR data (photon_intensity_correlate)

photon_intensity_dependent_gn, photon_flid

Acts like photon_gn, but with a different calculated gn based on the instantaneous intensity. photon_flid is specific to the lifetime case.

photon_number, photon_number_to_channels

For t3 data only. photon_number reports the number of times there were 0, 1, 2, ... photons arriving after a given sync pulse. photon_number_to_channels instead modifies the channel number to indicate how many photons arrived in that pulse, and in what order.


Converts to and from t2 and t3 data.


Treats a channel of t2 data as the sync signal.


Shifts the arrival time and pulse of t3 data, used if the relative timing of the sync and photon detector were incorrect.


Modifies the photon_stream to do things like:

  • add time offset
  • drop channels
  • keep only the first photon arriving after a given pulse (e.g. to suppress afterpulsing)
  • apply time gating (only keep photons which arrived some time after the sync)

Data formats

All data formats are headerless csv, in one of the following types. See sample_data/ for examples.

Photons (input and output)


In ascii format:

channel (uint32), arrival time (uint64)


In ascii format:

channel (uint32), arrival pulse (uint64), arrival time (uint64)

Correlations (input and output)

Correlations are pairs (triplets, quadruplets, ... generally tuples) of photons, with some difference in time (or pulse number).

Histogram bins (output)

T2 histogram

For a g2:

channel photon 0 (uint32), channel photon 1 (uint32), time bin left (uint64), time bin right (uint64), counts (uint64)

where time bins are closed-open ranges ([left, right)).

For a g3:

channel photon 0 (uint32), channel photon 1 (uint32), time bin 0 left (uint64), time bin 0 right (uint64), time bin 1 left (uint64), time bin 1 right (uint64), counts (uint64)

This idea extends to higher orders as well, just with more time bin definitions.

T3 histogram

For a g2:

channel photon 0 (uint32), channel photon 1 (uint32), pulse bin 0 left (uint64), pulse bin 0 right (uint64), time bin 0 left (uint64), time bin 0 right (uint64), counts

As with the t2 data this idea can be extended to higher orders.


Tools for analysis of photon arrival time data (TTTR data).







No releases published


No packages published