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

## ◆ HBT_FctType

enum HBT_FctType

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_analyseHbtFunction()

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

  fct | Function description to analyse.
  capacity | Output: Array size of values
  size | Output: Number of valid items in values
  binWidth | Output: Size of a t step in TDC time units
  iOffset | Output: Index for element of values that represents t=0
  values | Output: Array of function values. The caller has to provide the array; the function copies the original values (at most bufSize) to it.
  bufSize | Buffer size (number of elements) of the values array

## ◆ TDC_calcHbtG2()

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

  fct | Output: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.

Returns
  Error code

## ◆ TDC_calcHbtModelFct()

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

  fctType | Type of function
  params | Intput: Function parameters
  fct | Output: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.

Returns
  Error code

## ◆ TDC_createHbtFunction()

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_enableHbt()

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

  enable | Enable or disable

Returns
  Error code

## ◆ TDC_fitHbtG2()

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

  fct | g(2) function to fit
  fitType | Type of function to fit to
  startParams | Intput: 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.
  fitParams | Output: Values of the function parameters after fit The array must be at least of size HBT_PARAM_SIZE.
  iterations | Output: Number of iterations in the fit process. Special Values: 0 = fit algorithm not called, -1 = fit algorithm failed

Returns
  Error code

## ◆ TDC_generateHbtDemo()

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

  fctType | Type of g(2) function to simulate
  params | Input: Function parameters The array must be at least of size HBT_PARAM_SIZE.
  noiseLv | Noise level, arbitrary units

Returns
  Error code

## ◆ TDC_getHbtCorrelations()

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

  forward | Selects the correlation function: 0=1-2 , 1=2-1
  fct | Output: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.

Returns
  Error code

## ◆ TDC_getHbtDetectorParams()

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

  jitter | Output: Typical detector jitter [s].

Returns
  Error code

## ◆ TDC_getHbtEventCount()

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

  totalCount | Output: Event count since last reset
  lastCount | Output: Event count since last call
  lastRate | Output: Event rate [Hz] since last call; only valid if lastCount > 1

Returns
  Error code

## ◆ TDC_getHbtFitStartParams()

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

  fctType | Type of function
  params | Output: 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_getHbtInput()

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

  channel1 | Output: First channel number
  channel2 | Output: Second channel number

Returns
  Error code

## ◆ TDC_getHbtIntegrationTime()

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

  intTime | Output: Integration Time [s], 0 if no events

Returns
  Error code

## ◆ TDC_getHbtParams()

TDC_API int TDC_CC TDC_getHbtParams | ( | Int32 * | binWidth,
|  | Int32 * | binCount
| ) |  |

Get Correlation Function Parameters.

Retrieves the parameters set by TDC_setHbtParams.

Parameters

  binWidth | Output: Width of a bin in units of the TDC Time Base.
  binCount | Output: Number of bins in the buffers.

Returns
  Error code

## ◆ TDC_releaseHbtFunction()

TDC_API void TDC_CC TDC_releaseHbtFunction | ( | TDC_HbtFunction * | fct | ) |

Release Function Description.

Releases the memory allocated for a funcion description.

Parameters

  fct | Function description to free. After the call, the pointer is invalid!

## ◆ TDC_resetHbtCorrelations()

TDC_API int TDC_CC TDC_resetHbtCorrelations | ( |  | ) |

Reset Correlation Functions.

Clears the accumulated correlation functions.

Returns
  Error code

## ◆ TDC_setHbtDetectorParams()

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

  jitter | Typical detector jitter [s], default = 0.

Returns
  Error code

## ◆ TDC_setHbtInput()

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

  channel1 | First channel number, Range = 1...32, default = 1
  channel2 | Second channel number, Range = 1...32, default = 2

Returns
  Error code

## ◆ TDC_setHbtParams()

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

  binWidth | Width of a bin in units of the TDC Time Base, see TDC_getTimebase . Range = 1 ... 1M, default = 1.
  binCount | Number of bins in the buffers. Range = 16 ... 64k, default = 256.

Returns
  Error code