TDCBase

Data Structures | Macros | Enumerations | Functions
tdclifetm.h File Reference

Lifetime measurement. More...

`#include "tdcdecl.h"`

Go to the source code of this file.

## Data Structures
struct | TDC_LftFunction
| Histogram Function. More...

## Macros
#define | LFT_PARAM_SIZE 4
| Size of parameter array of model functions.

## Enumerations
enum | LFT_FctType { LFTTYPE_NONE , LFTTYPE_EXP , LFTTYPE_DBL_EXP , LFTTYPE_KOHLRAUSCH }
| Type of a model function. More...

## Functions
TDC_API int TDC_CC | TDC_enableLft (Bln32 enable)
| Enable Lifetime Calculations. More...
TDC_API int TDC_CC | TDC_setLftStartInput (Int32 startChan)
| Set TDC Channel for Start Input. More...
TDC_API int TDC_CC | TDC_addLftHistogram (Int32 stopCh, Bln32 add)
| Add a histogram. More...
TDC_API int TDC_CC | TDC_getLftStartInput (Int32 *startChan)
| Get TDC Channel for Start Input. More...
TDC_API int TDC_CC | TDC_setLftParams (Int32 binWidth, Int32 binCount)
| Set Histogram Parameters. More...
TDC_API int TDC_CC | TDC_getLftParams (Int32 *binWidth, Int32 *binCount)
| Get Histogram Parameters. More...
TDC_API int TDC_CC | TDC_resetLftHistograms (void)
| Reset Histograms. More...
TDC_API TDC_LftFunction *TDC_CC | TDC_createLftFunction (void)
| Create Function Description. More...
TDC_API void TDC_CC | TDC_releaseLftFunction (TDC_LftFunction *fct)
| Release Function Description. More...
TDC_API void TDC_CC | TDC_analyseLftFunction (const TDC_LftFunction *fct, Int32 *capacity, Int32 *size, Int32 *binWidth, double *values, Int32 bufSize)
| Analyse Function Description. More...
TDC_API int TDC_CC | TDC_getLftHistogram (Int32 channel, Bln32 reset, TDC_LftFunction *fct, Int32 *tooBig, Int32 *startEvts, Int32 *stopEvts, Int64 *expTime)
| Retrieve Histogram. More...
TDC_API int TDC_CC | TDC_calcLftModelFct (LFT_FctType fctType, const double *params, TDC_LftFunction *fct)
| Calculate Model Function. More...
TDC_API int TDC_CC | TDC_generateLftDemo (LFT_FctType fctType, const double *params, double noiseLv)
| Generate Demo Data. More...
TDC_API int TDC_CC | TDC_fitLftHistogram (const TDC_LftFunction *fct, LFT_FctType fitType, const double *startParams, double *fitParams, Int32 *iterations)
| Fit Histogram. More...

## Detailed Description

Lifetime measurement.

The header provides functions to calculate start multistop histograms for lifetime measurement. A selceted channel provides start events while events from all other channels act as stop events. Every stop event causes a histogram entry at its time difference to the last start event.

A histogram is provided for every input channel with this channel as stop event source. The histogram corresponding to the start channel is channel integrating, i.e. events from all stop channels are accumulated there.

Use the functions of tdcbase.h to control the device. Set parameters with TDC_setLftParams and TDC_setLftStartInput. Enable the collection of data with TDC_enableLft; when enabled, all incoming events contribute to the histogram. Use TDC_getLftHistogram to to retrieve the histogram.

Definition in file tdclifetm.h.

## Enumeration Type Documentation

## ◆ LFT_FctType

enum LFT_FctType

Type of a model function.

A set of model functions is provided for fitting to the measured histograms 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 LFT_PARAM_SIZE elements.

Enumerator
LFTTYPE_NONE | No function, invalid. No Parameters.
LFTTYPE_EXP | Mono exponential decay. The function requires two parameters: I0 , τ0
LFTTYPE_DBL_EXP | Double exponential decay. The function requires 4 parameters: I0 , α , τ0 , τ1
LFTTYPE_KOHLRAUSCH | Kohlrausch decay. The function requires 3 parameters: I0 , τ0 , β

Definition at line 51 of file tdclifetm.h.

## Function Documentation

## ◆ TDC_addLftHistogram()

TDC_API int TDC_CC TDC_addLftHistogram | ( | Int32 | stopCh,
|  | Bln32 | add
| ) |  |

Add a histogram.

Adds or removes a histogram for with the common start channel and the specified stop channel. Nothing will happen if an already existing histogram is added and vice versa.

Parameters

  stopCh | Channel for stop events, Range = 1...32
  add | Add (true) or remove (false) the histogram

Returns
  Error code

## ◆ TDC_analyseLftFunction()

TDC_API void TDC_CC TDC_analyseLftFunction | ( | const TDC_LftFunction * | fct,
|  | Int32 * | capacity,
|  | Int32 * | size,
|  | Int32 * | binWidth,
|  | 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
  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_calcLftModelFct()

TDC_API int TDC_CC TDC_calcLftModelFct | ( | LFT_FctType | fctType,
|  | const double * | params,
|  | TDC_LftFunction * | 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_createLftFunction()

TDC_API TDC_LftFunction* TDC_CC TDC_createLftFunction | ( | void |  | ) |

Create Function Description.

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

Returns
  Address of a newly created buffer; NULL on error

## ◆ TDC_enableLft()

TDC_API int TDC_CC TDC_enableLft | ( | Bln32 | enable | ) |

Enable Lifetime Calculations.

Enables the calculation of the start multistop histograms. When enabled, all incoming events contribute to the histograms. When disabled, all Lft functions are unavailable. The function implicitly clears the histogram. Use TDC_freezeBuffers to interrupt the accumulation of events without clearing the histogram and TDC_resetLftHistograms to clear without interrupt.

Note
  The function implicitly enables the timer tick channel 104 (see TDC_enableMarkers) because the timing information is required by the calculations.

Parameters

  enable | Enable or disable

Returns
  Error code

## ◆ TDC_fitLftHistogram()

TDC_API int TDC_CC TDC_fitLftHistogram | ( | const TDC_LftFunction * | fct,
|  | LFT_FctType | fitType,
|  | const double * | startParams,
|  | double * | fitParams,
|  | Int32 * | iterations
| ) |  |

Fit Histogram.

Calculates a fit to the histogram to a given model function.

Parameters

  fct | Histogram to fit
  fitType | Type of function to fit to
  startParams | Intput: Start values of the function parameters to fit. The array must be at least of size LFT_PARAM_SIZE.
  fitParams | Output: Values of the function parameters after fit The array must be at least of size LFT_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_generateLftDemo()

TDC_API int TDC_CC TDC_generateLftDemo | ( | LFT_FctType | fctType,
|  | const double * | params,
|  | double | noiseLv
| ) |  |

Generate Demo Data.

Starts generation of data that lead to a histogram of given type with continously decreasing noise level. To disable data generation use function type "none".

Parameters

  fctType | Type of histogram to simulate
  params | Input: Function parameters The array must be at least of size LFT_PARAM_SIZE.
  noiseLv | Noise level, arbitrary units

Returns
  Error code

## ◆ TDC_getLftHistogram()

TDC_API int TDC_CC TDC_getLftHistogram | ( | Int32 | channel,
|  | Bln32 | reset,
|  | TDC_LftFunction * | fct,
|  | Int32 * | tooBig,
|  | Int32 * | startEvts,
|  | Int32 * | stopEvts,
|  | Int64 * | expTime
| ) |  |

Retrieve Histogram.

Retrieves one of the start multistop histograms accumulated internally. The histogram counters will be stored in the fct buffer in floating point format although they only can have integer values. Only histograms can be retrieved that have been added with TDC_addLftHistogram, or the histogram associated with the start channel. That histogram integrates over all stop channels, i.e. events from every channel except start act as stop. NULL pointers can be used for every output parameter to ignore its value.

Parameters

  channel | Selects the histogram whose stop events stem from this channel.
  reset | If the histogram should be cleared after retrieving.
  fct | Output: Function description. If the capacity of the buffer is not sufficient, TDC_OutOfRange will be returned.
  tooBig | Output: Number of time diffs that were bigger than the biggest histogram bin.
  startEvts | Output: Number of start events contributing to the histogram.
  stopEvts | Output: Number of stop events contributing to the histogram.
  expTime | Output: Total exposure time for the histogram: the time difference between the first and the last event that contribute to the histogram. In timebase units.

Returns
  Error code

## ◆ TDC_getLftParams()

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

Get Histogram Parameters.

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

Parameters

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

Returns
  Error code

## ◆ TDC_getLftStartInput()

TDC_API int TDC_CC TDC_getLftStartInput | ( | Int32 * | startChan | ) |

Get TDC Channel for Start Input.

Retrieves the parameter set by TDC_setLftStartInput.

Parameters

  startChan | Output: Channel for start events

Returns
  Error code

## ◆ TDC_releaseLftFunction()

TDC_API void TDC_CC TDC_releaseLftFunction | ( | TDC_LftFunction * | 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_resetLftHistograms()

TDC_API int TDC_CC TDC_resetLftHistograms | ( | void |  | ) |

Reset Histograms.

Clears all accumulated start multistop histograms.

Returns
  Error code

## ◆ TDC_setLftParams()

TDC_API int TDC_CC TDC_setLftParams | ( | Int32 | binWidth,
|  | Int32 | binCount
| ) |  |

Set Histogram Parameters.

Sets common parameters for the histograms. 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 the bins in units of the TDC Time Base, see TDC_getTimebase . Range = 1 ... 1M, default = 1.
  binCount | Number of bins in the histograms. Range = 16 ... 64k, default = 256.

Returns
  Error code

## ◆ TDC_setLftStartInput()

TDC_API int TDC_CC TDC_setLftStartInput | ( | Int32 | startChan | ) |

Set TDC Channel for Start Input.

Selects the TDC channel that provides the start events. All events from other channels act as stop events. This may be the start input or one of the stop input channels. The function implicitly clears the histograms.

Parameters

  startChan | Channel for start events, Range: 0 (for start) and 1...32, default = 0

Returns
  Error code