erlab.analysis.kspace

Momentum conversion functions.

Typically, the user will not have to call this module directly, but will instead use the accessor method xarray.DataArray.kspace.convert().

For more front-end utilities related to momentum conversion, see the documentation of the xarray.DataArray.kspace accessor.

Angle conventions and function forms are based on Ref. [3].

Functions

broadcast_args(func)

Decorate a function to broadcast all DataArray arguments.

change_configuration(darr, configuration)

Apply a new axis configuration to the ARPES data.

get_kconv_forward(configuration)

Return the appropriate forward momentum conversion function.

get_kconv_func(kinetic_energy, ...)

Return appropriate momentum conversion functions.

get_kconv_inverse(configuration)

Return the appropriate inverse momentum conversion function.

hv_func(kx, ky, kz, inner_potential, ...)

Calculate the photon energy \(hν\).

kperp_from_kz(kz, inner_potential)

Calculate the out-of-plane momentum outside the sample \(k_\perp\).

kz_func(kinetic_energy, inner_potential, kx, ky)

Calculate the out-of-plane momentum inside the sample \(k_z\).

Classes

AxesConfiguration(*values)

Enum class for different types of axes configurations in an ARPES experiment.

Callable()

erlab.analysis.kspace.change_configuration(darr, configuration)[source]

Apply a new axis configuration to the ARPES data.

Returns a copy of the input data with the coordinates renamed to match the given configuration. The original data is not modified.

This function is useful for setups that are capable of changing the experimental geometry.

Parameters:

  • darr (DataArray) – The DataArray containing the ARPES data in angle space to modify.

  • configuration (AxesConfiguration | int) – The new configuration to apply.

Returns:

xarray.DataArray – The ARPES data with the new configuration.

Return type:

DataArray

erlab.analysis.kspace.kz_func(kinetic_energy, inner_potential, kx, ky)[source]

Calculate the out-of-plane momentum inside the sample \(k_z\).

\(k_z\) is computed from the given kinetic energy \(E_k\), inner potential \(V_0\), and in-plane momenta \(k_x\), and \(k_y\) by

\[k_z = \sqrt{k^2 - k_x^2 - k_y^2 + \frac{2 m_e V_0}{\hbar^2}}\]

where \(k =\sqrt{2 m_e E_k}/\hbar\).

erlab.analysis.kspace.kperp_from_kz(kz, inner_potential)[source]

Calculate the out-of-plane momentum outside the sample \(k_\perp\).

\(k_\perp\) is computed from the out-of-plane momentum \(k_z\) and inner potential \(V_0\) by

\[k_\perp = \sqrt{k_z^2 - \frac{2 m_e V_0}{\hbar^2}}\]
erlab.analysis.kspace.hv_func(kx, ky, kz, inner_potential, work_function, binding_energy)[source]

Calculate the photon energy \(hν\).

The kinetic energy \(E_k\) is computed from the given out-of-plane momentum \(k_z\), inner potential \(V_0\), and in-plane momenta \(k_x\), and \(k_y\) by

\[E_k = \frac{\hbar^2}{2 m_e} \left(k_x^2 + k_y^2 + k_z^2\right) - V_0\]

Then, the kinetic energy is converted to the photon energy \(hν\) by

\[hν = E_k + \Phi - E_b\]

where \(\Phi\) is the work function of the system and \(E_b\) is the binding energy (negative for occupied states).

erlab.analysis.kspace.get_kconv_func(kinetic_energy, configuration, angle_params)[source]

Return appropriate momentum conversion functions.

The appropriate function is chosen based on the configuration and kinetic energy.

Parameters:

  • kinetic_energy (float | ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] | DataArray) – The kinetic energy of the photoelectrons in eV.

  • configuration (AxesConfiguration | int) – Experimental configuration.

  • angle_params (dict[str, float]) – Dictionary of required angle parameters. If the configuration has a DA, the parameters should be delta, chi, chi0, xi, and xi0. Otherwise, they should be delta, xi, xi0, and beta0, following the notation in Ref. [3].

Returns:

  • forward_func (Callable) – Forward function that takes \((α, β)\) and returns \((k_x, k_y)\).

  • inverse_func (Callable) – Inverse function that takes \((k_x, k_y)\) or \((k_x, k_y, k_\perp)\) and returns \((α, β)\). If \(k_\perp\) is given, it will return the angles broadcasted to \(k_\perp\) instead of the provided kinetic energy.

Raises:

ValueError – If the given configuration is not valid.

Return type:

tuple[Callable, Callable]

Note

  • The only requirement for the input parameters of the returned functions is that the shape of the input angles must be broadcastable with each other, and with the shape of the kinetic energy array. This means that the shape of the output array can be controlled By adjusting the shape of the input arrays. For instance, if the kinetic energy is given as a (L, 1, 1) array, \(k_x\) as a (1, M, 1) array, and \(k_y\) as a (1, 1, N) array, the output angle arrays \(α\) and \(β\) will each be broadcasted to a (L, M, N) array which can be directly used for interpolation.

  • However, the user will not have to worry about the shape of the input arrays, because using xarray.DataArray objects as the input will most likely broadcast the arrays automatically!

See also

NumPy Broadcasting Documentation

erlab.analysis.kspace.get_kconv_forward()

Get only the forward function.

erlab.analysis.kspace.get_kconv_inverse()

Get only the inverse function.

erlab.analysis.kspace.get_kconv_forward(configuration)[source]

Return the appropriate forward momentum conversion function.

The returned function takes \((α, β, k_{tot})\) as mandatory arguments and returns \((k_x, k_y)\). Note that \(k_{tot}\) must be computed from the kinetic energy before passing it to the function. The angle parameters can be passed as optional arguments with default values of zero.

Parameters:

configuration (AxesConfiguration | int) – Experimental configuration.

Returns:

forward (Callable) – The forward conversion function with the following signature:

def forward(alpha, beta, kinetic_energy, **angle_params) -> (kx, ky)
...

**angle_params are the optional angle parameters. For geometry without DA, they are delta, xi, xi0, beta0. For geometry with DA, they are delta, chi, chi0, xi, xi0. All angle parameters have default values of zero.

Return type:

Callable

erlab.analysis.kspace.get_kconv_inverse(configuration)[source]

Return the appropriate inverse momentum conversion function.

The returned function takes \((k_x, k_y, k_\perp, E_k)\) as mandatory arguments and returns \((α, β)\). The angle parameters can be passed as optional arguments with default values of zero.

If \(k_\perp\) is None, it will be computed from the kinetic energy \(E_k\). Otherwise, the angles will be computed at the given \(k_\perp\).

Parameters:

configuration (AxesConfiguration | int) – Experimental configuration.

Returns:

inverse (Callable) – The inverse conversion function with the following signature:

def inverse(kx, ky, kperp, kinetic_energy, **angle_params) -> (alpha, beta)
...

**angle_params are the optional angle parameters. For geometry without DA, they are delta, xi, xi0, beta0. For geometry with DA, they are delta, chi, chi0, xi, xi0. All angle parameters have default values of zero.

If kperp is None, it will be computed from kinetic_energy.

Return type:

Callable