`Instrument`

class nexus.Instrument(id)

Abstract class for Instrument. Do not use this class directly. An instrumental function implementation must be derived from this class in Python the following way. The returned function must be symmetric around the center grid value.

Added in version 2.0.0.

# definition of the derived class
class InstrumentDefinedInPython(nx.Instrument):
    def __init__(self, id, [additional parameters]):
        super().__init__(id)
        [do something with additional parameters]
        self.fit_variables = [...parameter...]


    # implementation of the actual instrumental function
    def InstrumentFunction(self, grid):
        # IMPORTANT - Do not remove this steps to get proper center to avoid shifts during convolution
        grid = np.array(grid)
        center = grid[grid.size // 2]

        # implementation of function
        kernel = f(grid - center, ...)  # function of several parameters

        # OPTIONAL - Truncation for faster convolution.
        # DO NOT DO THIS for asymmetric functions due to possible shifts during convolution.
        # The relative value is important for the kernel type. For Lorentzian it is around 30 gamma ~ 1.1e-3.
        kernel = self.TruncateKernel(kernel, relative_truncation_threshold = 1e-3)

        # IMPORTANT - normalize kernel
        kernel = self.NormalizeKernel(kernel, 1.0)

        return kernel

    # or for 2D data sets, e.g. for :class:`EnergyTimeSpectrum`
    def InstrumentFunction2D(self, detuning_grid, time_grid):
        # IMPORTANT - Do not remove this steps to get proper center to avoid shifts during convolution
        detuning_grid = np.array(detuning_grid)
        time_grid = np.array(time_grid)

        # IMPORTANT - use this meshgrid order for numpy.
        time_mesh, detuning_mesh = np.meshgrid(time_grid, detuning_grid)

        # IMPORTANT - center to grid array this way.
        detuning_center = detuning_grid[detuning_grid.size // 2]
        time_center = time_grid[time_grid.size // 2]

        # kernel
        kernel = f(detuning_mesh - detuning_center, time_mesh - time_center, ...)

        # OPTIONAL - Truncation for faster convolution
        # DO NOT DO THIS for asymmetric functions due to possible shifts during convolution.
        # The relative value is important for the kernel type. For Lorentzian it is around 30 gamma ~ 1.1e-3.
        kernel = self.TruncateKernel(kernel, relative_truncation_threshold = 1e-3)

        # IMPORTANT - normalize kernel
        kernel = self.NormalizeKernel(kernel, 1.0)

        return kernel

Some instrument functions are predefined in the library instrument.

Parameters:: id (string) – User identifier.

id

User identifier.

Type:: string

truncate

If larger 0, the convolution kernel will be truncated for faster computation. The truncation value is relative to the maximum value of the kernel. All kernel values smaller max_value * truncate will not be used in the convolution. For non point-symmetric kernels this value must be 0. Default is 1e-3.

Type:: float

relative_epsilon

Difference value for the check of equidistant steps. Default is 1e-6.

Type:: float

fit_variables

List of nx.Var objects.

Type:: list

InstrumentFunction(grid)

Call of the instrument function implementation from python.

The function must return a normalized kernel to the sum of one in order to preserve intensity of the theoretical curve during the convolution. A normalization factor can be applied via NormalizeKernel(), which simulates the Lamb-Moessbauer factor of a Moessbauer source.

Args:
grid (list or ndarray): The grid for the instrument function calculation.

Returns:
list or ndarray: Implemented instrumental function.

InstrumentFunction2D(grid_x, grid_y)

Call of the instrument function 2D implementation from python.

Parameters:

grid_x (list of list or 2D ndarray) – The grid for the instrument calculation, e.g. drive_detuning for EnergyTimeSpectrum.
grid_y (list of list or 2D ndarray) – The grid for the instrument calculation, e.g. time for EnergyTimeSpectrum..

Returns:

Implemented instrumental function.

Return type:

2D ndarray

NormalizeKernel(kernel, norm_factor=1.0)

Normalize a kernel (1D or 2D) such that its sum is norm_factor (default 1.0). The normalization preserves the intensity of the theoretical curve during the convolution. A normalization factor < 1 simulates the Lamb-Moessbauer factor of a Moessbauer source.

Parameters:

kernel (np.array) – kernel array to be normalized.
norm_factor (float) – normalization factor (default 1.0).

Returns:

normalized kernel.

Return type:

np.array

TruncateKernel(kernel, relative_truncation_threshold)

Truncate a kernel (1D or 2D) at the given relative threshold.

Parameters:

kernel (np.array) – 1D or 2D kernel array.
relative_truncation_threshold (float) – truncation threshold relative to the max value in the array (0.0 - 1.0).

Returns:

truncated kernel.

For 1D: 1D array of values >= threshold.
For 2D: 2D array of values >= threshold with rows/columns removed if all values < threshold.

Return type:

np.array

Examples can be found in the Tutorial section.

Instrument

`Instrument`