2. convert functions (specsanalyzer.convert)

convert functions for the specsanalyzer package

Specsanalyzer image conversion module

specsanalyzer.convert.get_damatrix_from_calib2d(lens_mode, kinetic_energy, pass_energy, work_function, calib2d_dict)

This function estimates the best angular conversion coefficients for the current analyzer mode, starting from a dictionary containing the specs .calib2d database. A linear interpolation is performed from the tabulated coefficients based on the retardation ratio value.

Parameters:

  • lens_mode (str) – the lens mode string description

  • kinetic_energy (float) – kinetic energy of the photoelectron

  • pass_energy (float) – analyzer pass energy

  • work_function (float) – work function settings

  • calib2d_dict (dict) – dictionary containing the configuration parameters for angular correction

Returns:

(a_inner, da_matrix, retardation_ratio, source, dims) interpolated a_inner and da_matrix, needed for the coordinate conversion, retardation ratio, interpolation values, dims

Return type:

tuple[float, np.ndarray, float, str, list[str]]

specsanalyzer.convert.bisection(array, value)

Auxiliary function to find the closest rr index from https://stackoverflow.com/questions/2566412/ find-nearest-value-in-numpy-array

Given an array , and given a value , returns an index j such that value is between array[j] and array[j+1]. array must be monotonic increasing. j=-1 or j=len(array) is returned to indicate that value is out of range below and above respectively. This should mimic the function BinarySearch in igor pro 6

Parameters:

  • array (np.ndarray) – ordered array

  • value (float) – comparison value

Returns:

index (non-integer) expressing the position of value between array[j] and array[j+1]

Return type:

int

specsanalyzer.convert.second_closest_rr(rrvec, closest_rr_index)

Return closest_rr_index+1 unless you are at the edge of the rrvec.

Parameters:

  • rrvec (np.ndarray) – the retardation ratio vector

  • closest_rr_index (int) – the nearest rr index corresponding to the scan

Returns:

nearest rr index to calculate the best da coefficients

Return type:

int

specsanalyzer.convert.get_rr_da(lens_mode, calib2d_dict)

Get the retardation ratios and the da for a certain lens mode from the configuration dictionary

Parameters:

  • lens_mode (string) – string containing the lens mode

  • calib2d_dict (dict) – dictionary containing the configuration parameters for angular correction

Raises:

  • KeyError – Raised if the requested lens mode is not found

  • ValueError – Raised if no da values are found for the given mode

Returns:

rr vector, matrix of da coefficients per row row0 : da1, row1: da3, .. up to da7. Non angle resolved lens modes do only posses da1.

Return type:

tuple[np.ndarray, np.ndarray]

specsanalyzer.convert.calculate_polynomial_coef_da(da_matrix, kinetic_energy, pass_energy, e_shift)

Given the da coefficients contained in the scan parameters, the program calculates the energy range based on the eshift parameter and fits a second order polynomial to the tabulated values. The polynomial coefficients are packed in the dapolymatrix array (row0 da1, row1 da3, ..) The function returns a matrix of the fit coefficients, given the physical energy scale Each line of the matrix is a set of coefficients for each of the da[i] corrections

Parameters:

  • da_matrix (np.ndarray) – the matrix of interpolated da coefficients

  • kinetic_energy (float) – photoelectron kinetic energy

  • pass_energy (float) – analyzer pass energy

  • e_shift (np.ndarray) – e shift parameter, defining the energy range around the center for the polynomial fit of the da coefficients

Returns:

dapolymatrix containing the fit results (row0 da1, row1 da3, ..)

Return type:

np.ndarray

specsanalyzer.convert.zinner(kinetic_energy, angle, da_poly_matrix)

Auxiliary function for mcp_position_mm, uses kinetic energy and angle starting from the dapolymatrix, to get the zinner coefficient to calculate the electron arrival position on the mcp withing the a_inner boundaries

Parameters:

  • kinetic_energy (np.ndarray) – kinetic energies

  • angle (np.ndarray) – angles

  • da_poly_matrix (np.ndarray) – matrix with polynomial coefficients

Returns:

returns the calculated positions on the mcp, valid for low angles (< a_inner)

Return type:

np.ndarray

specsanalyzer.convert.zinner_diff(kinetic_energy, angle, da_poly_matrix)

Auxiliary function for mcp_position_mm, uses kinetic energy and angle starting from the dapolymatrix, to get the zinner_diff coefficient to correct the electron arrival position on the mcp outside the a_inner boundaries

Parameters:

  • kinetic_energy (np.ndarray) – kinetic energies

  • angle (np.ndarray) – angles

  • da_poly_matrix (np.ndarray) – polynomial matrix

Returns:

zinner_diff the correction for the zinner position on the MCP for high (>a_inner) angles.

Return type:

np.ndarray

specsanalyzer.convert.mcp_position_mm(kinetic_energy, angle, a_inner, da_poly_matrix)

calculated the position of the photoelectron on the mcp, for a certain kinetic energy and emission angle. This is determined for the given lens mode (as defined by the a_inner and dapolymatrix)

Parameters:

  • kinetic_energy (np.ndarray) – kinetic energies

  • angle (np.ndarray) – photoemission angles

  • a_inner (float) – inner angle parameter of the lens mode

  • da_poly_matrix (np.ndarray) – matrix with the polynomial correction coefficients for calculating the arrival position on the MCP

Returns:

lateral position of photoelectron on the mcp (angular dispersing axis)

Return type:

np.ndarray

specsanalyzer.convert.calculate_matrix_correction(kinetic_energy, pass_energy, nx_pixels, ny_pixels, pixel_size, magnification, e_shift, de1, e_range, a_range, a_inner, da_matrix, angle_offset_px, energy_offset_px)

Calculate the angular and energy interpolation matrices for the correction function.

Parameters:

  • kinetic_energy (float) – analyzer set kinetic energy

  • pass_energy (float) – analyzer set pass energy

  • nx_pixels (int) – number of image pixels (after binning) along the energy dispersing direction

  • ny_pixels (int) – number of image pixels (after binning) along the angle/spatially dispersing direction

  • pixel_size (float) – pixel size in millimeter

  • magnification (float) – magnification of the lens system used for imaging the detector

  • e_shift (np.ndarray) – e shift parameter, defining the energy range around the center for the polynomial fit of the da coefficients

  • de1 (float) – energy dispersion factor (fraction of pass_energy)/mm_z)

  • e_range (np.ndarray) – energy range (minimal/maximal energy, in units of pass_energy)

  • a_range (np.ndarray) – angular/spatial range (minimal/maximal angle or distance, in deg or mm)

  • a_inner (float) – inner angle parameter of the lens mode

  • da_matrix (np.ndarray) – the matrix of interpolated da coefficients

  • angle_offset_px (int) – Angular offset in pixel

  • energy_offset_px (int) – Energy offset in pixel

Returns:

  • ek_axis: kinetic energy axis

  • angle_axis, angle of emission axis

  • angular_correction_matrix: the matrix for angular interpolation

  • e_correction: the matrix for energy interpolation

  • jacobian_determinant: the transformation jacobian for area preserving transformation

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]

specsanalyzer.convert.calculate_jacobian(angular_correction_matrix, e_correction, ek_axis, angle_axis)

calculate the jacobian matrix associated with the transformation

Parameters:

  • angular_correction_matrix (np.ndarray) – angular correction matrix

  • e_correction (np.ndarray) – energy correction

  • ek_axis (np.ndarray) – kinetic energy axis

  • angle_axis (np.ndarray) – angle axis

Returns:

jacobian_determinant matrix

Return type:

np.ndarray

specsanalyzer.convert.physical_unit_data(image, angular_correction_matrix, e_correction, jacobian_determinant)

interpolate the image on physical units, using the map_coordinates function from scipy.ndimage

Parameters:

  • image (np.ndarray) – raw image

  • angular_correction_matrix (np.ndarray) – angular correction matrix

  • e_correction (float) – energy correction

  • jacobian_determinant (np.ndarray) – jacobian determinant for preserving the area normalization

Returns:

interpolated image as a function of angle and energy

Return type:

np.ndarray