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)[source]¶

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

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}

See also

set_normal: Method used to set angle offsets from explicitly provided normal emission angles.

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 [Seah and Dench, 1979] and the kinetic energy. Note that this is a rough estimate based on the universal curve of mean free path.

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

estimate_bounds()[source]¶

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)[source]¶

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

Changed in version 3.20.1: When from_numpoints=True, the estimated step now uses adjacent-point spacing over inclusive bounds: (max - min) / (N - 1). Datasets with fewer than 2 points on the relevant axis return np.inf.

Returns:

float – The estimated resolution.

Raises:

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

Return type:

float

convert_coords()[source]¶

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)[source]¶

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.

For non-hv scans, if the eV axis is all-positive, it is interpreted as kinetic energy and converted to binding energy. For hv-dependent scans, the eV axis must already be in binding energy.

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)[source]¶

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)
2D data with alpha and eV dimensions, and a fixed beta coordinate (angle-energy cuts)
3D data with dimensions including alpha and eV (including maps and hv-dependent cuts)

as_configuration(configuration)[source]¶

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)[source]¶

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 method returns an overlay curve \(k_z(hν)\) for converted momentum data. The returned values depend on the requested photon energies, binding energy, and in-plane momentum coordinates, but never on the converted data’s current kz grid.

If the carried in-plane momentum perpendicular to the slit is independent of the converted kz axis, \(k_z\) is evaluated directly from

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

If that carried orthogonal momentum depends on the converted kz axis, the method solves the sampled fixed-point relation

\[k_z = \sqrt{\frac{2 m_e}{\hbar^2}(E_k + V_0) - k_{\mathrm{slit}}^2 - k_{\mathrm{other}}(k_z)^2}\]

on the stored kz grid. If several sampled roots are present, a continuous branch is selected across the momentum axis along the slit. Slices with no sampled solution are returned as NaN. The legacy angle-roundtrip path is only used when the orthogonal in-plane momentum coordinate is unavailable.

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.

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

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

items()[source]¶

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

reset()[source]¶

Reset all angle offsets.