erlab.accessors.kspace

Defines an accessor for momentum conversion related utilities.

Classes

MomentumAccessor(xarray_obj)	xarray.DataArray.kspace accessor for momentum conversion related utilities.
OffsetView(xarray_obj)	A class representing an offset view for an xarray.DataArray.

Exceptions

IncompleteDataError(kind, name)

Raised when the data is not in the expected format for momentum conversion.

exception erlab.accessors.kspace.IncompleteDataError(kind, name)

Bases: ValueError

Raised when the data is not in the expected format for momentum conversion.

See conventions for required data attributes and coordinates.

class erlab.accessors.kspace.MomentumAccessor(xarray_obj)

Bases: ERLabDataArrayAccessor

xarray.DataArray.kspace accessor for momentum conversion related utilities.

This class provides convenient access to various momentum-related properties of a data object. It allows getting and setting properties such as configuration, inner potential, work function, angle resolution, slit axis, momentum axes, angle parameters, and offsets.

property configuration: AxesConfiguration

Experimental configuration.

For data loaded with a properly implemented data loader plugin, the configuration attribute is automatically set upon loading. If the configuration is missing, the attributes of the data may have been lost since loading due to averaging or other operations. In such cases, try to reload the data after setting xr.set_options(keep_attrs='True').

See erlab.constants.AxesConfiguration for possible configurations.

Data from some ARPES setups may have a dynamic configuration that changes per data. In such cases, the configuration should be converted with xarray.DataArray.kspace.as_configuration().

property inner_potential: float

Inner potential of the sample in eV.

The inner potential is stored in the inner_potential attribute of the data. If the inner potential is not set, a warning is issued and a default value of 10.0 eV is assumed.

Note

This property provides a setter method that takes a float value and sets the data attribute accordingly.

Example

>>> data.kspace.inner_potential = 13.0
>>> data.kspace.inner_potential
13.0

property work_function: float

Work function of the system in eV.

Here, the work function here refers to the work function of the entire system in electrical contact with the sample, which determines the Fermi level.

The work function is stored in the sample_workfunction attribute of the data. If not found, a warning is issued and a default value of 4.5 eV is assumed.

Note

This property provides a setter method that takes a float value and sets the data attribute accordingly.

Example

>>> data.kspace.work_function = 4.5
>>> data.kspace.work_function
4.5

property angle_resolution: float

Retrieve the angular resolution of the data in degrees.

Checks for the angle_resolution attribute of the data. If not found, a default value of 0.1° is silently assumed.

This property is used in best_kp_resolution upon estimating momentum step sizes through estimate_resolution.

Note

This property provides a setter method that takes a float value and sets the data attribute accordingly.

Example

>>> data.kspace.angle_resolution = 0.05
>>> data.kspace.angle_resolution
0.05

property slit_axis: Literal['kx', 'ky']

Momentum axis parallel to the analyzer slit.

Returns:

str – Returns 'kx' for type 1 configurations, 'ky' otherwise.

property other_axis: Literal['kx', 'ky']

Momentum axis perpendicular to the analyzer slit.

Returns:

str – Returns 'ky' for type 1 configurations, 'kx' otherwise.

property momentum_axes: tuple[Literal['kx', 'ky', 'kz'], ...]

Momentum axes of the data after conversion.

Returns:

tuple – For photon energy dependent scans, it returns the slit axis and 'kz'. For maps, it returns 'kx' and 'ky'. Otherwise, it returns only the slit axis.

property angle_params: dict[str, float]

Parameters passed to erlab.analysis.kspace.get_kconv_func().

property offsets: OffsetView

Angle offsets used in momentum conversion.

Returns:

OffsetView – A mapping between valid offset keys and their corresponding offsets.

Examples

• View all offsets

  >>> data.kspace.offsets
  {'delta': 0.0, 'xi': 0.0, 'beta': 0.0}
  

• Offsets to dictionary

  >>> dict(data.kspace.offsets)
  {'delta': 0.0, 'xi': 0.0, 'beta': 0.0}
  

• View single offset

  >>> data.kspace.offsets["beta"]
  0.0
  

• Set single offset

  >>> data.kspace.offsets["beta"] = 3.0
  >>> data.kspace.offsets
  {'delta': 0.0, 'xi': 0.0, 'beta': 3.0}
  

• Overwrite offsets with dictionary

  >>> data.kspace.offsets = dict(delta=1.5, xi=2.7)
  >>> data.kspace.offsets
  {'delta': 1.5, 'xi': 2.7, 'beta': 0.0}
  

• Update offsets

  >>> data.kspace.offsets.update(beta=0.1, xi=0.0)
  {'delta': 1.5, 'xi': 0.0, 'beta': 0.1}
  

• Reset all offsets

  >>> data.kspace.offsets.reset()
  {'delta': 0.0, 'xi': 0.0, 'beta': 0.0}
  

property best_kp_resolution: float

Estimated minimum in-plane momentum resolution.

The resolution is estimated with the kinetic energy and angular resolution:

\[\Delta k_{\parallel} \sim \sqrt{2 m_e E_k/\hbar^2} \cos(\alpha) \Delta\alpha\]

property best_kz_resolution: float

Estimated minimum out-of-plane momentum resolution.

The resolution is estimated based on the mean free path [8] and the kinetic energy.

\[\Delta k_z \sim 1/\lambda\]

estimate_bounds()

Estimate the bounds of the data in momentum space.

Returns:

bounds (dict of str to tuple of float) – A dictionary containing the estimated bounds for each parameter. The keys of the dictionary are ‘kx’, ‘ky’, and ‘kz’ (for \(hν\)-dependent data). The values are tuples representing the minimum and maximum values.

Return type:

dict[Literal[‘kx’, ‘ky’, ‘kz’], tuple[float, float]]

estimate_resolution(axis, lims=None, from_numpoints=False)

Estimate resolution for a given momentum axis.

Parameters:

• axis (Literal['kx', 'ky', 'kz']) – Axis to estimate the resolution for.

• lims (tuple[float, float] | None, default: None) – The limits of the axis used when from_numpoints is True. If not provided, reasonable limits will be calculated by estimate_bounds(), by default None

• from_numpoints (bool, default: False) – If True, estimate the resolution from the number of points in the relevant axis. If False, estimate the resolution based on the data, by default False

Returns:

float – The estimated resolution.

Raises:

ValueError – If no photon energy axis is found in data for axis 'kz'.

Return type:

float

convert_coords()

Convert coordinates to momentum space.

Assigns new exact momentum coordinates to the data. This is useful when you want to work with momentum coordinates but don’t want to interpolate the data.

Returns:

xarray.DataArray – The DataArray with transformed coordinates.

Return type:

DataArray

convert(bounds=None, resolution=None, *, method='linear', silent=True, **coords)

Convert to momentum space.

Parameters:

• bounds (dict[str, tuple[float, float]] | None, default: None) – A dictionary specifying the bounds for each coordinate axis. The keys are the names of the axes, and the values are tuples representing the lower and upper bounds of the axis. If not provided, the bounds will be estimated based on the data.

• resolution (dict[str, float] | None, default: None) – A dictionary specifying the resolution for each momentum axis. The keys are the names of the axes, and the values are floats representing the desired resolution of the axis. If not provided, the resolution will be estimated based on the data. For in-plane momentum, the resolution is estimated from the angle resolution and kinetic energy. For out-of-plane momentum, two values are calculated. One is based on the number of photon energy points, and the other is estimated as the inverse of the photoelectron inelastic mean free path given by the universal curve. The resolution is estimated as the smaller of the two values.

• method (str, default: 'linear') – The interpolation method to use, passed to erlab.analysis.interpolate.interpn(). Using methods other than 'linear' will result in slower performance.

• silent (bool, default: True) – If False, print progress messages during the conversion.

• **coords – Array-like keyword arguments that specifies the coordinate array for each momentum axis. If provided, the bounds and resolution will be ignored.

Returns:

xarray.DataArray – The converted data.

Return type:

DataArray

Note

This method converts the data to a new coordinate system specified by the provided bounds and resolution. It uses interpolation to map the data from the original coordinate system to the new one.

The converted data is returned as a DataArray object with updated coordinates and dimensions.

Examples

Set parameters and convert with automatic bounds and resolution:

data.kspace.offsets = {"delta": 0.1, "xi": 0.0, "beta": 0.3}

data.kspace.work_function = 4.3

data.kspace.inner_potential = 12.0

converted_data = data.kspace.convert()

Convert with specified bounds and resolution:

bounds = {"kx": (0.0, 1.0), "ky": (-1.0, 1.0)}

resolution = {"kx": 0.01, "ky": 0.01}

converted_data = data.kspace.convert(bounds, resolution)

interactive(**kwargs)

Open the interactive momentum space conversion tool.

The interactive tool currently supports the following kinds of data:

• 2D data with alpha and beta dimensions (constant energy surfaces)

• 3D data with dimensions including alpha and eV (including maps and hv-dependent cuts)

as_configuration(configuration)

Return a new DataArray with modified experimental configuration.

The coordinates of the new DataArray are renamed to match the given configuration. The original data is not modified.

Parameters:

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

Note

This method assumes a conversion between 4 typical setups listed in the table in Nomenclature. Any non-standard setups should be handled by the user.

hv_to_kz(hv)

Return \(k_z\) for a given photon energy.

Useful when creating overlays on \(hν\)-dependent data.

Parameters:

hv (float | Iterable[float]) – Photon energy in eV.

Note

This will be inexact for hv-dependent cuts that do not pass through the BZ center since we lost the exact angle values, i.e. the exact momentum perpendicular to the slit, during momentum conversion.

class erlab.accessors.kspace.OffsetView(xarray_obj)

Bases: object

A class representing an offset view for an xarray.DataArray.

This class provides a convenient way to access and manipulate angle offsets associated with the given data.

Parameters:

xarray_obj (DataArray) – The xarray.DataArray for which the offset view is created.

__len__() → int:

Returns the number of valid offset keys.

__iter__() → Iterator[str, float]:

Returns an iterator over the valid offset keys and their corresponding values.

__getitem__(key: str) → float:

Returns the offset value associated with the given key.

__setitem__(key: str, value: float) → None:

Sets the offset value for the given key.

__eq__(other: object) → bool:

Compares the offset view with another object for equality. True if the dictionary representation is equal, False otherwise.

__repr__() → str:

Returns a string representation of the offset view.

_repr_html_() → str:

Returns an HTML representation of the offset view.

update(other=None, **kwargs)

Update the offset view with the provided key-value pairs.

items()

Return a view of the offset view as a list of (key, value) pairs.

reset()

Reset all angle offsets to zero.