erlab.accessors.kspace¶

Functions

`only_angles`([method])	Decorate methods that require data to be in angle space.
`only_momentum`([method])	Decorate methods that require data to be in momentum space.

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`.

class erlab.accessors.kspace.MomentumAccessor(xarray_obj)[source]¶

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.

convert(bounds=None, resolution=None, *, silent=False, **coords)[source]¶

Convert to momentum space.

Parameters:

bounds (dict[str, tuple[float, float]] | 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) – 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.
silent (bool) – If True, suppresses printing, by default False.
**coords – Array-like keyword arguments that specifies the coordinate array for each momentum axis. If provided, the bounds and resolution will be ignored.

Returns:

The converted data.

Return type:

xarray.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)

convert_coords()[source]¶

Convert the 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:: The DataArray with transformed coordinates.
Return type:: xarray.DataArray

estimate_bounds()[source]¶

Estimate the bounds of the data in momentum space.

Returns:: bounds – 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[str, tuple[float, float]]

estimate_resolution(axis, lims=None, from_numpoints=False)[source]¶

Estimate the resolution for a given momentum axis.

Parameters:

axis (Literal['kx', 'ky', 'kz']) – Axis to estimate the resolution for.
lims (tuple[float, float] | 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) – 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:

The estimated resolution.

Return type:

float

Raises:

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

hv_to_kz(hv)[source]¶

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

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

Parameters:: hv (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.

interactive(**kwargs)[source]¶: Open the interactive momentum space conversion tool.

property alpha: DataArray¶

property angle_params: dict[str, float]¶: Parameters passed to erlab.analysis.kspace.get_kconv_func().

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.

property best_kp_resolution: float¶

Estimate the 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¶

Estimate the 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\]

property beta: DataArray¶

property binding_energy: DataArray¶

property configuration: AxesConfiguration¶

Return the experimental configuration.

For a properly implemented data loader, the configuration attribute must be set on data import. See erlab.analysis.kspace.AxesConfiguration for details.

property has_beta: bool¶

Check if the coordinate array for \(β\) has more than one element.

Returns:: Returns True if the size of the coordinate array for \(β\) is greater than 1, False otherwise.
Return type:: bool

Note

This may be True for data that are not maps. For instance, \(hν\)-dependent cuts with an in-plane momentum offset may have a \(hν\)-dependent \(β\) offset.

property has_eV: bool¶: Return True if object has an energy axis.

property has_hv: bool¶: Return True for photon energy dependent data.

property hv: DataArray¶

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 kinetic_energy: DataArray¶

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

Return the momentum axes of the data after conversion.

Returns:: 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.
Return type:: tuple

property offsets: OffsetView¶

Angle offsets used in momentum conversion.

Returns:: A mapping between valid offset keys and their corresponding offsets.
Return type:: OffsetView

Examples

View all offsets

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

View single offset
```
>>> data.kspace.offsets["beta"]
0.0
```

Offsets to dictionary

>>> dict(data.kspace.offsets)
{'delta': 0.0, 'xi': 0.0, '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 other_axis: Literal['kx', 'ky']¶

Return the momentum axis perpendicular to the slit.

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

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

Return the momentum axis parallel to the slit.

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

property valid_offset_keys: tuple[str, ...]¶

Get valid offset angles based on the experimental configuration.

Returns:: A tuple containing the valid offset keys. For configurations with a deflector, returns ("delta", "chi", "xi"). Otherwise, returns ("delta", "xi", "beta").
Return type:: tuple

property work_function: float¶

Work function of the sample in eV.

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

class erlab.accessors.kspace.OffsetView(xarray_obj)[source]¶

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]:[source]¶: Returns an iterator over the valid offset keys and their corresponding values.

__getitem__(key: str) → float:[source]¶: Returns the offset value associated with the given key.

__setitem__(key: str, value: float) → None:[source]¶: Sets the offset value for the given key.

__eq__(other: object) → bool:[source]¶: Compares the offset view with another object for equality. True if the dictionary representation is equal, False otherwise.

__repr__() → str:[source]¶: Returns a string representation of the offset view.

_repr_html_() → str:[source]¶: Returns an HTML representation of the offset view.

items()[source]¶

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

reset()[source]¶

Reset all angle offsets to zero.

update(other=None, **kwargs)[source]¶

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