API Reference

Buffer

tangy.Records

Container for timetags

Contains array of timetags, required channel information will be either an array of the same dimensions as timetags or simply the only channels. allowed corresponding to a specific coincidence pattern.

Parameters:

count (uint64) –

Number of events
resolution (float) –

Resolution of timetags
clock_period (float) –

Clock period (if required)
channels (ndarray(u8n) –

Channels
timetags (Union[ndarray(uint64), Tuple[ndarray(uint64), ndarray(uint64)]]) –

Timetags

Examples:

>>> records = Records(count=10, resolution=1e-9, clock_period=1.0,
>>>                   channels=[0, 1], timetags=[0, ..., 10])

>>> records = Records(count=4, resolution=1e-9, clock_period=1.0,
>>>                   channels=[0, 1, 1, 0], timetags=[0, 1, 4, 5])

Timetag Formats

StandardClocked

// Timetag format
typedef struct std {
    u8 channel;
    u64 timestamp;
} timetag_standard;

typedef f64 resolution_standard;

typedef struct timestamp_clocked {
    u64 clock;
    u64 delta;
} timestamp_clocked;

// Timetag format
typedef struct timetag_clocked {
    u8 channel;
    timestamp_clocked timestamp;
} timetag_clocked;

typedef struct resolution_clocked {
    f64 coarse;
    f64 fine;
} resolution_clocked;

tangy.TangyBufferType

Bases: Enum

Format of timetags to use in instance of TangyBuffer

tangy.TangyBuffer

TangyBuffer(
    name: str,
    resolution: float = 0.1,
    clock_period: float = 1.0,
    channel_count: int = 4,
    capacity: int = 10000000,
    format: TangyBufferType = ...,
)

Interface to underlying ring buffer

Provides ability to create, connect and modify a buffer of timetags and includes method to analyse the timetags currently held within it.

Parameters:

name (str) –

Name of buffer to be created or attached to.
resolution (float = 0.1, default: 0.1 ) –

Resolution of timetags in seconds. Unused if connecting.
clock_period (float = 1.0, default: 1.0 ) –

Length of clock period in seconds for measurements that include clock information in each timetag. Unused if connecting
channel_count (Optional[int] = 4, default: 4 ) –

Number of channels. Unused if connecting.
length (Optional[int] = 10_000_000) –

Length of buffer to create. Unused if connecting.
format (TangyBufferType = TangyBufferType.Standard, default: ... ) –

Format of timetags in the buffer, default is the standard format with a single value for the channel and single value for timeing information. Unused if connecting.

Attributes:

name (str) –

Name of buffer
resolution (float) –

Resolution of timetags in seconds
clock_period (float) –

Clock period of clock signal used if timetags with clock information are used. Defaults to 1.0 otherwise
resolution_bins (int) –

Resolution in bins
clock_period_bins (int) –

Clock period in units of resolution
conversion_factor (int) –

Factor to convert between time and bins
capacity (int) –

Maximum number of timetags that can be stored
count (int) –

total number of timetags written to the buffer
reference_count (int) –

Number of reference to current open buffer. Other processes can connect to the same buffer
channel_count (int) –

Number of available channels in the buffer
begin (int) –

Index of first timetag. Can be greater than capacity
end (int) –

Index of last timetag. Can be greater than capacity and will always be greater than begin

Note

If connecting to an existing buffer the resolution, clock_period, n_channels, capacity and format arguments will be ignored even if supplied. The correct values will be made available from the buffer connected to.

Examples:

Creation of a TangyBuffer object for both the Standard and Clocked timetag formats that can hold 1,000,000 timetags for a device with 4 channels. The method to connect to these buffers is also shown. This method of creating new buffers and connecting to existing ones allows the user to hold on to and continously read timetags from a device in one process and then connect to that buffer in another to perform analysis on the current data.

Buffer in Standard formatBuffer in Clocked format

# Here we will create a buffer called 'standard' (imaginitive)
# that will only except timetags in the ``Standard`` format
standard_buffer = tangy.TangyBuffer("standard", 1e-9,
                                    channel_count=4,
                                    capacity=int(1e6)
                                    format=TangyBufferType.Standard)

# A new buffer object can be made by connecting to a buffer with
# the correct name
standard_buffer_connection = tangy.TangyBuffer("standard")

# Here we will create a buffer called 'clocked' (imaginitive)
# that will only except timetags in the ``Clocked`` format
clocked_buffer = tangy.TangyBuffer("clocked", 1e-12,
                                    clock_period=12.5e-9,  # 80MHz Ti-Sapph
                                    channel_count=4,
                                    capacity=int(1e6)
                                    format=TangyBufferType.Clocked)

# A new buffer object can be made by connecting to a buffer with
# the correct name
clocked_buffer_connection = tangy.TangyBuffer("clocked")

Attributes

begin `property`

begin: int

Index of first record in buffer Returns: (int): Index of first record in buffer

capacity `property`

capacity: int

Maximum number of timetags the buffer can hold

Returns:

int –

maximum number of timetags

channel_count `property` `writable`

channel_count: int

Maximum number of channels in the buffer

Typically set by a device or a file to limit the range of valid channels available.

Returns:

int –

number of channels

clock_period `property` `writable`

clock_period: float

Clock period of timetags in buffer

For timetags with 'coarse + fine' timing this returns the 'coarse' timing component, typically this will be the resolution / period of an external clock signal

Returns:

float –

clock period of timetags

clock_period_bins `property`

clock_period_bins: int

Clock period in terms of bins of timetags in buffer

Returns:

int –

clock period of timetags

conversion_factor `property`

conversion_factor: int

doc

count `property`

count: int

Number of timetags written to the buffer

end `property`

end: int

Index of last record in buffer Returns: (int): Index of last record in buffer

name `property`

name: str

Name of buffer

Returns:

str –

buffer name

reference_count `property` `writable`

reference_count: int

Number of current connections to the buffer

Tracks number of connections to buffer, used to determine if it is safe to delete the backing memory and close the memory mapping.

Returns:

int –

number of connections

resolution `property` `writable`

resolution: float

Resolution of timetags in buffer

Returns:

float –

resolution of timetags

resolution_bins `property`

resolution_bins: int

Resolution in terms of bins of timetags in buffer

Returns:

int –

resolution of timetags

Functions

call

__call__(time: float) -> int

Converts a time to an buffer position

Takes a time and converts it to a position in the buffer relative to the total time currently held within the buffer. Positive numbers find positions from the start of the buffer whilst negative numbers find positions from the end of the buffer.

Examples:

Find the position bounding the first second in the buffer

>>> idx = buffer(1)
Find the position bounding the last second in the buffer
>>> idx = buffer(-1)

Returns:

int –

Index corresponding to requested time

getitem

__getitem__(key)

Access subscript of buffer

len

__len__() -> int

Length of buffer

Returns:

int –

Length of buffer

bins_from_time

bins_from_time(time: float) -> int

Convert amount of time to a number of time bins

Parameters:

time (float) –

Amount of time in seconds

Returns:

int –

number of bins

coincidence_collect

coincidence_collect(
    read_time: float,
    window: float,
    channels: list[int],
    delays: list[float] | None = None,
) -> Records | None

Collect coincident timetags

Collects the timetags in coincdience for the chosen channels over the specified read time provided the timetags have a distance between them less than the window. Optionally delays can be applied to each channel.The read time is taken as time from the most recent timetag in the buffer, e.g. a read time of 1s in a buffer containing 100s will give a result from the 99th second to the 100th.

Parameters:

read_time (float) –

time to integrate over
window (float) –

maximum distance between timetags allowed
channels (List[int]) –

channels to find coincidences between
delays (Optional[List[float]] = None,, default: None ) –

delays for each channel

Returns:

Records –

Records found in coincidence

coincidence_count

coincidence_count(
    read_time: float,
    window: float,
    channels: list[int],
    delays: list[float] | None = None,
) -> int

Count coincidences

Counts the coincidences for the chosen channels over the specified read time provided the timetags have a distance between them less than the window. Optionally delays can be applied to each channel.The read time is taken as time from the most recent timetag in the buffer, e.g. a read time of 1s in a buffer containing 100s will give a result from the 99th second to the 100th.

Parameters:

read_time (float) –

time to integrate over
window (float) –

maximum distance between timetags allowed
channels (List[int]) –

channels to find coincidences between
delays (Optional[List[float]] = None,, default: None ) –

delays for each channel

Returns:

int –

Number of coincidences found

current_time

current_time() -> float

Returns the time of the most recent timetag Returns: (float): Most recent timetag as time

joint_delay_histogram

joint_delay_histogram(
    signal: int,
    idler: int,
    channels: list[int],
    read_time: float,
    radius: float,
    delays: list[float] | None = None,
    clock: int | None = None,
    bin_width: int = 1,
    centre: bool = True,
) -> JointHistogram

2-D histogram of delays between channels

Histograms relative delays of channsl found to be in coincdience for over the specified read time provided the timetags have a distance between them less than the window. Optionally delays can be applied to each channel.The read time is taken as time from the most recent timetag in the buffer, e.g. a read time of 1s in a buffer containing 100s will give a result from the 99th second to the 100th. Can be used to produce a joint spectral intensity if the conversion from time to wavelength (frequency) is known.

Parameters:

signal (int) –

channel of signal photon
idler (int) –

channel of idler photon
channels ((List[int])) –

channels to test for coincidence, must contain signal, idler and optionally a clock channel
read_time (float) –

time to integrate over
radius ((float)) –

maximum distance between timetags allowed
delays (Optional[List[float]] = None,, default: None ) –

delays for each channel
clock (Optional[int] = None,, default: None ) –

Optional clock channel
bin_width (int = 1,, default: 1 ) –

Width of bins in histogram
centre (bool = True, default: True ) –

Whether or not to centre the histogram

Returns:

JointHistogram –

Joint delay histogram and marginal distributions

lower_bound

lower_bound(time: float) -> int

Find the position in the buffer that gives the last "time" seconds in the buffer

Performs a binary search on the buffer where the location being searched for is buffer.time_in_buffer() - time.

Parameters:

time (float) –

Amount of time, in seconds, to split the buffer by

Returns:

int –

Index in buffer corresponding to the timetag that is greater than or equal to buffer.time_in_buffer() - time

relative_delay

relative_delay(
    channel_a: int,
    channel_b: int,
    read_time: float,
    resolution: float = 1e-09,
    window: float | None = None,
) -> delay_result

Relative delay between two channels

Parameters:

channel_a (int) –

First channel
channel_b (int) –

Second channel
read_time ((float)) –

Time to integrate over
resolution (float = 1e-9,, default: 1e-09 ) –

Resolution of bins
window (Optional[float] = None, default: None ) –

Correlation window

Returns:

delay_result –

Dataclass containing histogram data and fitting results

singles

singles(
    read_time: float | None = None,
    start: int | None = None,
    stop: int | None = None,
) -> tuple[int, list[int]]

Count the occurances of each channel over a region of the buffer

Parameters:

buffer (RecordBuffer) –

Buffer containing timetags
read_time (Optional[float] = None, default: None ) –

Length of time to integrate over
start (Optional[int] = None, default: None ) –

Buffer position to start counting from
stop (Optional[int] = None, default: None ) –

Buffer position to sotp counting to

Returns:

(int, List[int]) –

Total counts and list of total counts on each channel

Examples:

Get all of the singles in a buffer

>>> tangy.singles(buffer, buffer.time_in_buffer())

Count the singles in the last 1s

>>> tangy.singles(buffer, 1)

Count the singles in the last 1000 tags

>>> tangy.singles(buffer, buffer.count - 1000, buffer.count)

time_in_buffer

time_in_buffer() -> float

Amount of time held in the buffer Returns: (float): Time between oldest and newest timetags

timetags

timetags(
    channels: int | list[int] | None = None,
    start: int | None = None,
    stop: int | None = None,
) -> list[tuple[int, NDArray]]

Get the timetags for selected channels Args: channels (Optional[Union[int, List[int]]]): Channels to get timetags for, can be either a single channel (int) or many (list of ints). If no channels are set and value left as None, all channels will gathered. start (Optional[int]): Position in buffer to start collecting from, if None the first valid position in the buffer will be used. stop (Optional[int]): Position in the buffer to collect timetags up to, if left as None the end of the buffer will be used.

Returns:

List[Tuple[int, NDArray]] –

a list of tuples, each list element contains the channel index and ndarray of timetags for that channel

Examples:

Get all timetags for channels 0 and 1

>>> timetags = buffer.timetags(channels=[0, 1])

Get the first 10 timetags on channel 2

>>> start = buffer.begin
>>> stop = start + 10
>>> channel_target = 2
>>> timetags_channel_2 = timetags(channels=channel_target,
                                  start=start,
                                  stop=stop)

Get the last 100 timetags on channel 4

>>> stop = buffer.end
>>> stop = stop - 100
>>> timetags_channel_2 = timetags(channels=4,
                                  start=start,
                                  stop=stop)

timetrace

timetrace(
    channels: int | list[int],
    read_time: float,
    resolution: float = 10.0,
)

Time trace of buffer for chosen channels and read time

Produces an array of count rates accumulated for the chosen channels over the read time specified. The read time is taken as time from the most recent timetag in the buffer, e.g. a read time of 1s in a buffer containing 100s will give a result from the 99th second to the 100th.

Parameters:

channels (List[int]) –

Channels to count timetags of
read_time (float) –

Amount of time to measure over, In seconds
resolution (float = 10.0, default: 10.0 ) –

Size of bins in seconds

Returns:

ndarray –

intensities

Buffer Management

tangy.buffer_list_update

buffer_list_update() -> dict

Up-to-date list of available buffers

Gets the list of available buffers from the Tangy configuration directory, for example, ~/.config/Tangy/buffers on linux and C:\Users\user_name\AppData\Local\PeterBarrow\Tangy\buffers on Windows. For each buffer configuration file the existence of the associated buffer is checked, buffers that no longer exists have their corresponding configuration file removed. Upon completion this returns a dictionary containing the buffer name, buffer format and path to the configuration file.

Returns: (dict): Dictionary of {"name": {"format": fmt, "path": "/path/to/config"}

tangy.buffer_list_append

buffer_list_append(buffer: TangyBuffer)

Adds the configuration of a buffer to the Tangy configuration directory

Parameters:

buffer (TangyBuffer) –

buffer with configuration to save

tangy.buffer_list_delete_all

buffer_list_delete_all() -> None

tangy.buffer_list_show

buffer_list_show() -> None

File Readers

tangy.PTUFile

PTUFile(file_path: str, name: str, length: int = 1000)

Class to read data from Picoquant PTU file and write into buffer.

Args:
    file_path (str): Path to Picoquant PTU file.
    name (str): Name of buffer to be created (or connected to).
    length (int = 1000):

Attributes:
    buffer: Buffer being written to
    header (dict): Dictionary containing information found in the file header
    record_count (int): Total number of records processed from PTU file
    count (int): Total number of timetags written into the buffer

Examples:
    Open a .ptu file and create a new buffer with a name

ptu = tangy.PTUFile("my_measurement.ptu", "measurement", int(1e8))

    Get the underlying buffer and count the singles from it
    >>> (total, singles) = tangy.singles(ptu.buffer, 1)

Functions

read

read(n: u64n) -> int

Read an amount of tags from the target file

Parameters:

n (int) –

Number of tags to read from the file

Returns:

uint64 –

NUmber of records read

Devices

tangy._uqd.UQDLogic16

UQDLogic16(
    device_id: int = 1,
    calibrate: bool = True,
    add_buffer: bool = False,
    buffer_size: int | None = 10000000,
)

NOTE

Linux users will need to add the following file to their system, /etc/udev/rules.d/UQDLogic16.rules that contains the following line ATTR{idVendor}=="0bd0", ATTR{idProduct}=="f100", MODE="666". This will ensure that the device does not need additional root privaledges to operate. After this file has been created the user will have to log out and the log in again or run the following command sudo udevadm control --reload-rules && udevadm trigger to update the current device rules.

Attributes

led_brightness `property` `writable`

led_brightness: int

Brightness of front panel LED.

Parameters:

percent (int) –

brightness in percent

fpga_version `property`

fpga_version: int

Version of FPGA design on device.

Returns:

int –

fpga design version

resolution `property`

resolution: float

Get the resolution of the device.

Depending on the device firmware this will return either 78.125ps or 156.25ps.

Returns:

float –

resolution

number_of_channels `property`

number_of_channels: int

Number of channels enabled on the device.

Depending on loaded firmware this will return either 8 or 16

Returns:

int –

number of useable input channels

input_threshold `property` `writable`

input_threshold: list[float64]

Input thresholds

Returns:

list[float64] –

List[float64]: Currently set input thresholds

inversion `property` `writable`

inversion: list[uint8]

Channels set to use negative edge triggering

Returns:

List[uint8] –

List of channels set to trigger on negative edges

input_delay `property` `writable`

input_delay: float64

Delays in seconds set on each channel

Returns:

float64 –

delays on each channel in seconds

function_generator `property` `writable`

function_generator: tuple[int, int]

Function generator period and width, both in units of 5ns

external_10MHz_reference `property` `writable`

external_10MHz_reference: bool

filter_min_count `property` `writable`

filter_min_count: int

Minimum size of a group to be transmitted to the host computer.

Returns:

int –

Minimum size of a group to be transmitted

filter_max_time `property` `writable`

filter_max_time: double

Maximum time between two pulses in the same group.

Returns:

float –

maximum time between two pulses in the same group

exclusion `property` `writable`

exclusion: list[uint8]

level_gate `property` `writable`

level_gate: bool

time_gating `property` `writable`

time_gating: bool

time_gate_width `property` `writable`

time_gate_width: int

Functions

is_open

is_open() -> bool

calibrate

calibrate() -> None

start_timetags

start_timetags() -> None

Start transmitting timetags from the device to the host computer

stop_timetags

stop_timetags() -> None

Stop transmitting timetags from the device to the host computer

read_tags

read_tags() -> tuple[int, list[uint8], list[uint64]]

buffer

buffer() -> TangyBuffer

Acquire buffer

write_to_buffer

write_to_buffer()

Write tags directly into buffer

API Reference

Buffer

tangy.Records

Timetag Formats

tangy.TangyBufferType

tangy.TangyBuffer

Attributes

begin property

capacity property

channel_count property writable

clock_period property writable

clock_period_bins property

conversion_factor property

count property

end property

name property

reference_count property writable

resolution property writable

resolution_bins property

Functions

__call__

__getitem__

__len__

bins_from_time

coincidence_collect

coincidence_count

current_time

joint_delay_histogram

lower_bound

relative_delay

singles

time_in_buffer

timetags

timetrace

Buffer Management

tangy.buffer_list_update

tangy.buffer_list_append

tangy.buffer_list_delete_all

tangy.buffer_list_show

File Readers

tangy.PTUFile

Functions

read

Devices

tangy._uqd.UQDLogic16

Attributes

led_brightness property writable

fpga_version property

resolution property

number_of_channels property

input_threshold property writable

inversion property writable

input_delay property writable

function_generator property writable

external_10MHz_reference property writable

filter_min_count property writable

filter_max_time property writable

exclusion property writable

level_gate property writable

time_gating property writable

time_gate_width property writable

Functions

is_open

calibrate

start_timetags

stop_timetags

read_tags

buffer

write_to_buffer

begin `property`

capacity `property`

channel_count `property` `writable`

clock_period `property` `writable`

clock_period_bins `property`

conversion_factor `property`

count `property`

end `property`

name `property`

reference_count `property` `writable`

resolution `property` `writable`

resolution_bins `property`

call

getitem

len

led_brightness `property` `writable`

fpga_version `property`

resolution `property`

number_of_channels `property`

input_threshold `property` `writable`

inversion `property` `writable`

input_delay `property` `writable`

function_generator `property` `writable`

external_10MHz_reference `property` `writable`

filter_min_count `property` `writable`

filter_max_time `property` `writable`

exclusion `property` `writable`

level_gate `property` `writable`

time_gating `property` `writable`

time_gate_width `property` `writable`