Author - Yatharth Bhasin

License: – (this repo is private and unlicensed)

Online doxygen documentation Link (auto-updated): https://yatharthb97.github.io/Correlator/index.html

PlateformIO documentation: https://docs.platformio.org/en/latest/

Local documentation can be generated in the doc subdirectory : >> doxygen CorrDoxyfile

Doxygen documentation: https://www.doxygen.nl/manual/index.html

→ Photon Statistics Device: Multi-modal device that is built with a framework of **"feature lines"**, that individually contain a set of features that can be used simultaneously. The features can be be selected with the option "Feature Line" in the config.json file. Set of valid feature lines include:

"ACF" - Autocorrelation function and related calculations
"Interarrival" - Interarrival statistics
"Sampler" - Samples the counter value at periodic intervals and maintains a running mean of the counter values.

Usage

Select the correct options and set the required values in config.json file.
Compile and push code to the device after saving the config.json file.
Run the PC side software (instructions below).

The board (microcontroller) settings are present in the file plateformio.ini. This file can be generated by using PlateformIO.
The module settings are present in the file config.json. This file is autogenerated if it is absent in the root directory. Missing fields are also added to the file during compile time with default values, and a warning message is generated.

Errors and Debugging options ==Incomplete==

Emulation and Testing

The software modules can be tested/simulated on a PC. The files test.cpp, pseudoSerial.hpp, and pseudoSerial.cpp in the subdirectory ./code/software/ provide functionality to do so. The macro CORR_SIMULATION must be set during compilation to enable the contents of this file.
The file test.cpp contain module by module tests for the software modules. pseudoSerial.hpp, and pseudoSerial.cpp emulate the serial port on the device.

Compile:

g++ test.cpp pseudoSerial.cpp -D CORR_SIMULATION
The subdirectory ./full_emulator/ includes a complete emulator for the multitau module that operates with the python GUI. ==Incomplete==
- The module can be fed data from a saved file or the counter values can be randomly generated.

Feature Lines (Device Modes)

Feature Lines are specific modes for the device. This is a framework that arranges all the different features and tests in a neat and accessible manner.

Common Features

"Enable Sync Code" - A specific synchronization code (set by "Sync Code" option) is added to the start of each struct that is transmitted from the device. At the receiver end, the software verifies this code and generates and error message if the code is not correct. The error means that the struct is misaligned and the data that is received cannot be used.

One way to emulate this error is to change the config.json file and start the PC software without compiling and pushing the changed configuration to the device.

Feature Line 1 - `ACF` (Gate Counting)

This is the main feature line. This mode supports the following features which can be selectively be enabled from the configuration file. The features have zero-footprint on performance when disabled, similarly, each feature adds an overhead to the performance of the device.

Device ready state is indicated by the RED LED and Device running state is indicated by the GREEN LED on the Panel.

"Enable ACF" : Enable Auto-correlation calculation
"Enable Count Rate" - Enable Count Rate Calculation
"Enable PC Histogram" - Enable Photon Counting Histogram
"Enable Performance Counters" - Enable Performance Counters for Serial Output and ACF calculation. This counts the number of clock cycles for the particular operations and maintains a mean value.

"Enable Points Norm" - Enable simple points normalization (under review).
"Enable Mean Norm" - Enable normalization based on mean count rate. (under review)

Feature Line 2 - `Interarrival` (Tight Polling)

Device ready state is indicated by the BLUE LED and Device running state is indicated by the WHITE LED on the Panel.

==Implementation Pending==

Feature Line 3 - `Sampler` (Gate Counting)

Device ready state is indicated by the WHITE LED and Device running state is indicated by the GREEN LED on the Panel.

This feature samples the Counter value at periodic intervals (set by "Sampling Delay ms") and prints the counter value, mean counter value, etc with line separation. Hence, the "Enable Synchronization Code" is ignored, since the synchronization is performed via the endline characters \r\n.

Typical output: cv: counter value (sampled), m: mean, c: count of read values, a: accumulate

cv: 10 m: 0.10 c: 2667270000 a: 268435456.00

Module Description (`Incomplete`)

Pure Software Modules

This folder contains the implementation of the software correlator that will be used on Teensy. The file descriptions are as follows:

Lin_ACorr_RT_Base.hpp - Base (Interface) for Linear Correlators
Lin_ACorr_RT_Teensy.hpp - Implementation specific to Teensy
multi_tau.hpp - Teensy specific implementation of multi-tau Auto-correlator
accumulator.hpp - Adapter object used by Multi Tau ACorr
discarder.hpp - Adapter object used by Multi Tau ACorr
simpler_circular_buffer.hpp - Simple circlar buffer used for storing the cout values.
types.hpp - Contains the typedef of the abstracted typenames
- counter_t - Type returned by the Counter module
- index_t - Type used to index arrays and buffers in the implementation
test.cpp - File used for tsting
circlar_buffer.hpp - Another implementation of circular buffer (unsued right now)
Lin_CrossCorr_RT_Base.hpp - Base interface for Linear Cross Correlators
Lin_CrossCorr_RT_Teensy.hpp - Teensy specific Liner Cross Correlator interface

Hardware Modules (are specific to Teensy 4.1)

File descriptions:

pit.hpp - Defines class PITController that provides an abstraction layer on the PIT timer controls.
qtmr1.hpp - Defines 'class QTMR1Controller' that provides an abstraction layer on the QTMR1 timer controls.
lifetime_timer.hpp - Interface for using PIT timers in chained mode to create a 64-bit lifetime counter

Common Interface

modules.hpp - Defines functions that represent highest-abstracted modules in the system.
errors.hpp - Defines common error codes and error generating functions.
utilities.hpp - Contains some utility functions

PC Application

This portion is written in python 3.

The PC application can be launched : >> python ./code/pc_app/photon_statistics.py