TDCBase
Data Structures | Macros | Enumerations | Functions
tdchbt.h File Reference

g(2) Functions and Fitting More...

#include "tdcdecl.h"

Go to the source code of this file.

Data Structures

struct  TDC_HbtFunction
 Correlation Function or g(2) Function. More...
 

Macros

#define HBT_PARAM_SIZE   5
 Size of parameter array of model functions.
 

Enumerations

enum  HBT_FctType {
  FCTTYPE_NONE, FCTTYPE_COHERENT, FCTTYPE_THERMAL, FCTTYPE_SINGLE,
  FCTTYPE_ANTIBUNCH, FCTTYPE_THERM_JIT, FCTTYPE_SINGLE_JIT, FCTTYPE_ANTIB_JIT,
  FCTTYPE_THERMAL_OFS, FCTTYPE_SINGLE_OFS, FCTTYPE_ANTIB_OFS, FCTTYPE_THERM_JIT_OFS,
  FCTTYPE_SINGLE_JIT_OFS, FCTTYPE_ANTIB_JIT_OFS
}
 Type of a model function. More...
 

Functions

TDC_API int TDC_CC TDC_enableHbt (Bln32 enable)
 Enable HBT Calculations. More...
 
TDC_API int TDC_CC TDC_setHbtParams (Int32 binWidth, Int32 binCount)
 Set Correlation Function Parameters. More...
 
TDC_API int TDC_CC TDC_getHbtParams (Int32 *binWidth, Int32 *binCount)
 Get Correlation Function Parameters. More...
 
TDC_API int TDC_CC TDC_setHbtDetectorParams (double jitter)
 Set Detector Parameters. More...
 
TDC_API int TDC_CC TDC_getHbtDetectorParams (double *jitter)
 Get Detector Parameters. More...
 
TDC_API int TDC_CC TDC_setHbtInput (Int32 channel1, Int32 channel2)
 Set TDC Channels for Input. More...
 
TDC_API int TDC_CC TDC_getHbtInput (Int32 *channel1, Int32 *channel2)
 Get TDC Channels for Input. More...
 
TDC_API int TDC_CC TDC_resetHbtCorrelations ()
 Reset Correlation Functions. More...
 
TDC_API int TDC_CC TDC_getHbtEventCount (Int64 *totalCount, Int64 *lastCount, double *lastRate)
 Retrieve Event Count and Rate. More...
 
TDC_API int TDC_CC TDC_getHbtIntegrationTime (double *intTime)
 Retrieve Integration Time. More...
 
TDC_API int TDC_CC TDC_getHbtCorrelations (Bln32 forward, TDC_HbtFunction *fct)
 Retrieve Correlation Function. More...
 
TDC_API int TDC_CC TDC_calcHbtG2 (TDC_HbtFunction *fct)
 Calculate g(2) Function. More...
 
TDC_API int TDC_CC TDC_fitHbtG2 (const TDC_HbtFunction *fct, HBT_FctType fitType, const double *startParams, double *fitParams, Int32 *iterations)
 Fit g(2) Function. More...
 
TDC_API const double *TDC_CC TDC_getHbtFitStartParams (HBT_FctType fctType, double *params)
 Get Recommended Fit Start Parameters. More...
 
TDC_API int TDC_CC TDC_calcHbtModelFct (HBT_FctType fctType, const double *params, TDC_HbtFunction *fct)
 Calculate Model Function. More...
 
TDC_API int TDC_CC TDC_generateHbtDemo (HBT_FctType fctType, const double *params, double noiseLv)
 Generate Demo Data. More...
 
TDC_API TDC_HbtFunction *TDC_CC TDC_createHbtFunction (void)
 Create Function Description. More...
 
TDC_API void TDC_CC TDC_releaseHbtFunction (TDC_HbtFunction *fct)
 Release Function Description. More...
 
TDC_API void TDC_CC TDC_analyseHbtFunction (const TDC_HbtFunction *fct, Int32 *capacity, Int32 *size, Int32 *binWidth, Int32 *iOffset, double *values, Int32 bufSize)
 Analyse Function Description. More...
 

Detailed Description

g(2) Functions and Fitting

The header provides functions to calculate 2nd order correlation functions and g(2) functions from TDC data. The g(2) functions may be fit to some model functions.

Use the functions of tdcbase.h to control the device. Set HBT parameters with TDC_setHbtParams, TDC_setHbtInput, and others. Enable the collection of data with TDC_enableHbt. When enabled, all incoming events on the selected channels contribute to the correlation functions. Use TDC_calcHbtG2 to calculate a g(2) from the current correlations and TDC_fitHbtG2 to fit it to a given model.

Definition in file tdchbt.h.

Enumeration Type Documentation

Type of a model function.

A set of model functions is provided for fitting to the measured g(2) functions and for the generation of demo data. The type describes the kind of function to use. Function parameters are generally transported in an array of double that should have at least HBT_PARAM_SIZE elements.

Enumerator
FCTTYPE_NONE 

No function, invalid.

No Parameters.

FCTTYPE_COHERENT 

Coherent light.

No Parameters.

FCTTYPE_THERMAL 

Thermal light source.

The function requires 3 parameters: A, c, B

FCTTYPE_SINGLE 

Single photon light source.

The function requires 1 parameter: t1

FCTTYPE_ANTIBUNCH 

Three level system light source.

The function requires 4 parameters: pf2, c, tb, ta

FCTTYPE_THERM_JIT 

Thermal with detector jitter considered.

The function requires 3 parameters: A, c, B

FCTTYPE_SINGLE_JIT 

Single photon with detector jitter considered.

The function requires 1 parameter: t1

FCTTYPE_ANTIB_JIT 

Three level system with detector jitter.

The function requires 4 parameters: pf2, c, tb, ta

FCTTYPE_THERMAL_OFS 

Thermal with addtitional fit of detector offset The function requires 4 parameters: A, c, B, dt.

FCTTYPE_SINGLE_OFS 

Single photon with addtitional fit of detector offset The function requires 2 parameters: t1, dt.

FCTTYPE_ANTIB_OFS 

Three level system with addtitional fit of detector offset The function requires 5 parameters: pf2, c, tb, ta, dt.

FCTTYPE_THERM_JIT_OFS 

Thermal with detector jitter considered and offset fit The function requires 4 parameters: A, c, B, dt.

FCTTYPE_SINGLE_JIT_OFS 

Single photon with detector jitter considered and offset fit The function requires 2 parameters: t1, dt.

FCTTYPE_ANTIB_JIT_OFS 

Three level system with detector jitter considered and offset fit The function requires 5 parameters: pf2, c, tb, ta, dt.

Definition at line 46 of file tdchbt.h.

Function Documentation

TDC_API void TDC_CC TDC_analyseHbtFunction ( const TDC_HbtFunction fct,
Int32 capacity,
Int32 size,
Int32 binWidth,
Int32 iOffset,
double *  values,
Int32  bufSize 
)

Analyse Function Description.

Disassembles a function description object to its components. The object itself stays valid. May be useful for non-C/C++ programmers. All output parameters may be NULL to ignore the component.

Parameters
fctFunction description to analyse.
capacityOutput: Array size of values
sizeOutput: Number of valid items in values
binWidthOutput: Size of a t step in TDC time units
iOffsetOutput: Index for element of values that represents t=0
valuesOutput: Array of function values. The caller has to provide the array; the function copies the original values (at most bufSize) to it.
bufSizeBuffer size (number of elements) of the values array
TDC_API int TDC_CC TDC_calcHbtG2 ( TDC_HbtFunction fct)

Calculate g(2) Function.

Calculates the g(2) function based on the current state of the correlation functions.

Parameters
fctOutput: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.
Returns
Error code
TDC_API int TDC_CC TDC_calcHbtModelFct ( HBT_FctType  fctType,
const double *  params,
TDC_HbtFunction fct 
)

Calculate Model Function.

Calculates the values of a model function with specified parameters.

Parameters
fctTypeType of function
paramsIntput: Function parameters
fctOutput: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.
Returns
Error code
TDC_API TDC_HbtFunction* TDC_CC TDC_createHbtFunction ( void  )

Create Function Description.

Creates a function description buffer by allocating memory according to the current values of binWidth and binCount (see TDC_setHbtParams). If those values are increased, new buffers have to be created. Release a buffer with TDC_releaseHbtFunction.

Returns
Address of a newly created buffer; NULL on error
TDC_API int TDC_CC TDC_enableHbt ( Bln32  enable)

Enable HBT Calculations.

Enables the calculation of 2nd order cross correlation functions as the base of a g(2) function. When enabled, all incoming events on the selected TDC channels 1 and 2 contribute to the correlation functions 1-2 and 2-1. When disabled, all HBT functions are unavailable. The function implicitly clears the correlation functions. Use TDC_freezeBuffers to interrupt the accumulation of events without clearing the functions and TDC_resetHbtCorrelations to clear without interrupt.

Parameters
enableEnable or disable
Returns
Error code
TDC_API int TDC_CC TDC_fitHbtG2 ( const TDC_HbtFunction fct,
HBT_FctType  fitType,
const double *  startParams,
double *  fitParams,
Int32 iterations 
)

Fit g(2) Function.

Calculates a fit to the g(2) function to a given model function.

Parameters
fctg(2) function to fit
fitTypeType of function to fit to
startParamsIntput: Start values of the function parameters to fit. If the pointer is NULL, standard values will be used (see TDC_getHbtFitStartParams). If not NULL, the array must be at least of size HBT_PARAM_SIZE.
fitParamsOutput: Values of the function parameters after fit The array must be at least of size HBT_PARAM_SIZE.
iterationsOutput: Number of iterations in the fit process. Special Values: 0 = fit algorithm not called, -1 = fit algorithm failed
Returns
Error code
TDC_API int TDC_CC TDC_generateHbtDemo ( HBT_FctType  fctType,
const double *  params,
double  noiseLv 
)

Generate Demo Data.

Starts generation of data that lead to a g(2) function of given type with continously decreasing noise level. To disable data generation use function type "none". TDC_getHbtCorrelations will not work with generated data.

Parameters
fctTypeType of g(2) function to simulate
paramsInput: Function parameters The array must be at least of size HBT_PARAM_SIZE.
noiseLvNoise level, arbitrary units
Returns
Error code
TDC_API int TDC_CC TDC_getHbtCorrelations ( Bln32  forward,
TDC_HbtFunction fct 
)

Retrieve Correlation Function.

Retreives the current state of the correlation function. A function is represented by an array of data of size binCount (see TDC_setHbtParams), containing unnormalized counter values for detected time diffs falling in the respective bin.

Parameters
forwardSelects the correlation function: 0=1-2 , 1=2-1
fctOutput: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.
Returns
Error code
TDC_API int TDC_CC TDC_getHbtDetectorParams ( double *  jitter)

Get Detector Parameters.

Retrieves the parameters set by TDC_setHbtDetectorParams. All output parameters may be NULL to ignore the value.

Parameters
jitterOutput: Typical detector jitter [s].
Returns
Error code
TDC_API int TDC_CC TDC_getHbtEventCount ( Int64 totalCount,
Int64 lastCount,
double *  lastRate 
)

Retrieve Event Count and Rate.

Retreives the number and rate of events contributing to the correlation functions. The total count since the last reset is delivered as well as count and rate since the last call of the function. The time difference is derived from the TDC timestamps; therefore at least two events are necessary to calculate a valid rate.

Parameters
totalCountOutput: Event count since last reset
lastCountOutput: Event count since last call
lastRateOutput: Event rate [Hz] since last call; only valid if lastCount > 1
Returns
Error code
TDC_API const double* TDC_CC TDC_getHbtFitStartParams ( HBT_FctType  fctType,
double *  params 
)

Get Recommended Fit Start Parameters.

Returns a set of recommended fit start values for a specific fit funcion.

Parameters
fctTypeType of function
paramsOutput: Array of HBT_PARAM_SIZE parameter values; If not NULL, the result will be copied here.
Returns
Array of HBT_PARAM_SIZE parameter values; NULL if fctType is invalid.
TDC_API int TDC_CC TDC_getHbtInput ( Int32 channel1,
Int32 channel2 
)

Get TDC Channels for Input.

Retrieves the parameters set by TDC_setHbtInput. All output parameters may be NULL to ignore the value.

Parameters
channel1Output: First channel number
channel2Output: Second channel number
Returns
Error code
TDC_API int TDC_CC TDC_getHbtIntegrationTime ( double *  intTime)

Retrieve Integration Time.

Retreives the total integration time of the correlation functions. The time is derived from the TDC timestamps; therefore at least one event on both channels are necessary to calculate a valid time.

Parameters
intTimeOutput: Integration Time [s], 0 if no events
Returns
Error code
TDC_API int TDC_CC TDC_getHbtParams ( Int32 binWidth,
Int32 binCount 
)

Get Correlation Function Parameters.

Retrieves the parameters set by TDC_setHbtParams.

Parameters
binWidthOutput: Width of a bin in units of the TDC Time Base.
binCountOutput: Number of bins in the buffers.
Returns
Error code
TDC_API void TDC_CC TDC_releaseHbtFunction ( TDC_HbtFunction fct)

Release Function Description.

Releases the memory allocated for a funcion description.

Parameters
fctFunction description to free. After the call, the pointer is invalid!
TDC_API int TDC_CC TDC_resetHbtCorrelations ( )

Reset Correlation Functions.

Clears the accumulated correlation functions.

Returns
Error code
TDC_API int TDC_CC TDC_setHbtDetectorParams ( double  jitter)

Set Detector Parameters.

Sets the typical detector jitter. The jitter is used for fitting with some of the model functions, see HBT_FctType. If this feature isn't used, the parameter hasn't to be set.

Parameters
jitterTypical detector jitter [s], default = 0.
Returns
Error code
TDC_API int TDC_CC TDC_setHbtInput ( Int32  channel1,
Int32  channel2 
)

Set TDC Channels for Input.

Sets the first and second input channel for correlation function calculation. If the function is not called, default values are in place. The function implicitly clears the correlation functions.

Parameters
channel1First channel number, Range = 1...32, default = 1
channel2Second channel number, Range = 1...32, default = 2
Returns
Error code
TDC_API int TDC_CC TDC_setHbtParams ( Int32  binWidth,
Int32  binCount 
)

Set Correlation Function Parameters.

Sets parameters for the correlation functions and g(2) function. If the function is not called, default values are in place. When the function is called, all collected data are cleared.

Parameters
binWidthWidth of a bin in units of the TDC Time Base, see TDC_getTimebase . Range = 1 ... 1M, default = 1.
binCountNumber of bins in the buffers. Range = 16 ... 64k, default = 256.
Returns
Error code