dut_alignment

All DUT alignment functions in space and time are listed here plus additional alignment check functions

Methods

testbeam_analysis.dut_alignment.correlate_cluster(input_cluster_files, output_correlation_file, n_pixels, pixel_size=None, dut_names=None, plot=True, chunk_size=4999999)

“Calculates the correlation histograms from the cluster arrays. The 2D correlation array of pairs of two different devices are created on event basis. All permutations are considered (all clusters of the first device are correlated with all clusters of the second device).

Parameters:

• input_cluster_files (iterable) – Iterable of filenames of the cluster files.
• output_correlation_file (string) – Filename of the output correlation file with the correlation histograms.
• n_pixels (iterable of tuples) – One tuple per DUT describing the total number of pixels (column/row), e.g. for two FE-I4 DUTs [(80, 336), (80, 336)].
• pixel_size (iterable of tuples) – One tuple per DUT describing the pixel dimension (column/row), e.g. for two FE-I4 DUTs [(250, 50), (250, 50)]. If None, assuming same pixel size for all DUTs.
• dut_names (iterable of strings) – Names of the DUTs. If None, the DUT index will be used.
• plot (bool) – If True, create additional output plots.
• chunk_size (uint) – Chunk size of the data when reading from file.

testbeam_analysis.dut_alignment.merge_cluster_data(input_cluster_files, output_merged_file, n_pixels, pixel_size, chunk_size=4999999)

Takes the cluster from all cluster files and merges them into one big table aligned at a common event number.

Empty entries are signaled with column = row = charge = nan. Position is translated from indices to um. The local coordinate system origin (0, 0) is defined in the sensor center, to decouple translation and rotation. Cluster position errors are calculated from cluster dimensions.

Parameters:

• input_cluster_files (list of pytables files) – File name of the input cluster files with correlation data.
• output_merged_file (pytables file) – File name of the output tracklet file.
• n_pixels (iterable of tuples) – One tuple per DUT describing the total number of pixels (column/row), e.g. for two FE-I4 DUTs [(80, 336), (80, 336)].
• pixel_size (iterable of tuples) – One tuple per DUT describing the pixel dimension (column/row), e.g. for two FE-I4 DUTs [(250, 50), (250, 50)].
• chunk_size (uint) – Chunk size of the data when reading from file.

testbeam_analysis.dut_alignment.prealignment(input_correlation_file, output_alignment_file, z_positions, pixel_size, s_n=0.1, fit_background=False, reduce_background=False, dut_names=None, no_fit=False, non_interactive=True, iterations=3, plot=True, gui=False, queue=False)

Deduce a pre-alignment from the correlations, by fitting the correlations with a straight line (gives offset, slope, but no tild angles).

The user can define cuts on the fit error and straight line offset in an interactive way.

Parameters:

• input_correlation_file (string) – Filename of the input correlation file.
• output_alignment_file (string) – Filename of the output alignment file.
• z_positions (iterable) – The z positions of the DUTs in um.
• pixel_size (iterable of tuples) – One tuple per DUT describing the pixel dimension (column/row), e.g. for two FE-I4 DUTs [(250, 50), (250, 50)].
• s_n (float) – The signal to noise ratio for peak signal over background peak. This should be specified when the background is fitted with a gaussian function. Usually data with a lot if tracks per event have a gaussian background. A good S/N value can be estimated by investigating the correlation plot. The default value is usually fine.
• fit_background (bool) – Data with a lot if tracks per event have a gaussian background from the beam profile. Also try to fit this background to determine the correlation peak correctly. If you see a clear 2D gaussian in the correlation plot this shoud be activated. If you have 1-2 tracks per event and large pixels this option should be off, because otherwise overfitting is possible.
• reduce_background (bool) – Reduce background (uncorrelated events) by using SVD of the 2D correlation array.
• dut_names (iterable) – Names of the DUTs. If None, the DUT index will be used.
• no_fit (bool) – Use Hough transformation to calculate slope and offset.
• non_interactive (bool) – Deactivate user interaction and estimate fit range automatically.
• iterations (uint) – The number of iterations in non-interactive mode.
• plot (bool) – If True, create additional output plots.
• gui (bool) – If True, this function is excecuted from GUI and returns figures
• queue (bool, dict) – If gui is True and non_interactive is False, queue is a dict with a in and output queue to communicate with GUI thread

testbeam_analysis.dut_alignment.apply_alignment(input_hit_file, input_alignment_file, output_hit_file, inverse=False, force_prealignment=False, no_z=False, use_duts=None, chunk_size=1000000)

Takes a file with tables containing hit information (x, y, z) and applies the alignment to each DUT hit (positions and errors). The alignment data is used. If this is not available a fallback to the pre-alignment is done. One can also inverse the alignment or apply the alignment without changing the z position.

This function cannot be easily made faster with multiprocessing since the computation function (apply_alignment_to_chunk) does not contribute significantly to the runtime (< 20 %), but the copy overhead for not shared memory needed for multipgrocessing is higher. Also the hard drive IO can be limiting (30 Mb/s read, 20 Mb/s write to the same disk)

Parameters:

• input_hit_file (string) – Filename of the input hits file (e.g. merged data file, tracklets file, etc.).
• input_alignment_file (string) – Filename of the input alignment file.
• output_hit_file (string) – Filename of the output hits file with hit data after alignment was applied.
• inverse (bool) – If True, apply the inverse alignment.
• force_prealignment (bool) – If True, use pre-alignment, even if alignment data is availale.
• no_z (bool) – If True, do not change the z alignment. Needed since the z position is special for x / y based plane measurements.
• use_duts (iterable) – Iterable of DUT indices to apply the alignment to. If None, use all DUTs.
• chunk_size (uint) – Chunk size of the data when reading from file.

testbeam_analysis.dut_alignment.alignment(input_track_candidates_file, input_alignment_file, n_pixels, pixel_size, align_duts=None, selection_fit_duts=None, selection_hit_duts=None, selection_track_quality=1, initial_rotation=None, initial_translation=None, max_iterations=10, use_n_tracks=200000, plot=False, chunk_size=100000)

This function does an alignment of the DUTs and sets translation and rotation values for all DUTs. The reference DUT defines the global coordinate system position at 0, 0, 0 and should be well in the beam and not heavily rotated.

To solve the chicken-and-egg problem that a good dut alignment needs hits belonging to one track, but good track finding needs a good dut alignment this function work only on already prealigned hits belonging to one track. Thus this function can be called only after track finding.

These steps are done 1. Take the found tracks and revert the pre-alignment 2. Take the track hits belonging to one track and fit tracks for all DUTs 3. Calculate the residuals for each DUT 4. Deduce rotations from the residuals and apply them to the hits 5. Deduce the translation of each plane 6. Store and apply the new alignment

repeat step 3 - 6 until the total residual does not decrease (RMS_total = sqrt(RMS_x_1^2 + RMS_y_1^2 + RMS_x_2^2 + RMS_y_2^2 + ...))

Parameters:

• input_track_candidates_file (string) – file name with the track candidates table
• input_alignment_file (pytables file) – File name of the input aligment data
• n_pixels (iterable of tuples) – One tuple per DUT describing the total number of pixels (column/row), e.g. for two FE-I4 DUTs [(80, 336), (80, 336)].
• pixel_size (iterable of tuples) – One tuple per DUT describing the pixel dimension (column/row), e.g. for two FE-I4 DUTs [(250, 50), (250, 50)].
• align_duts (iterable or iterable of iterable) – The combination of duts that are algined at once. One should always align the high resolution planes first. E.g. for a telesope (first and last 3 planes) with 2 devices in the center (3, 4): align_duts=[[0, 1, 2, 5, 6, 7], # align the telescope planes first [4], # Align first DUT [3]], # Align second DUT
• selection_fit_duts (iterable or iterable of iterable) – Defines for each align_duts combination wich devices to use in the track fit. E.g. To use only the telescope planes (first and last 3 planes) but not the 2 center devices selection_fit_duts=[0, 1, 2, 5, 6, 7]
• selection_hit_duts (iterable or iterable of iterable) – Defines for each align_duts combination wich devices must have a hit to use the track for fitting. The hit does not have to be used in the fit itself! This is useful for time reference planes. E.g. To use telescope planes (first and last 3 planes) + time reference plane (3) selection_hit_duts = [0, 1, 2, 4, 5, 6, 7]
• selection_track_quality (uint or iterable or iterable of iterable) – Track quality for each hit DUT.
• initial_rotation (array) – Initial rotation array.
• initial_translation (array) – Initial translation array.
• max_iterations (uint) – Maximum number of iterations of calc residuals, apply rotation refit loop until constant result is expected. Usually the procedure converges rather fast (< 5 iterations)
• use_n_tracks (uint) – Defines the amount of tracks to be used for the alignment. More tracks can potentially make the result more precise, but will also increase the calculation time.
• plot (bool) – If True, create additional output plots.
• chunk_size (uint) – Chunk size of the data when reading from file.