erlab.accessors.kspace¶

Defines an accessor for momentum conversion related utilities.

Classes

`AngleScaleView`(xarray_obj)	A view of angle-scale compensation factors for momentum conversion.
`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.

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

Bases: object

A view of angle-scale compensation factors for momentum conversion.

The scale factors compensate extrinsic warping in the stored angle coordinates. Missing scale attributes default to 1.0. Momentum conversion uses raw angle * scale for each axis.

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

Update angle-scale compensation factors.

items()[source]¶

Return a view of angle-scale factors as key-value pairs.

reset()[source]¶

Reset all angle-scale compensation factors.

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 angle_scales: AngleScaleView¶

Angle-scale compensation factors used in momentum conversion.

The mapping has "alpha" and "beta" keys. Values are stored in the DataArray attributes alpha_scale and beta_scale and must be finite positive scalars. Use these factors sparingly to compensate known extrinsic angle-coordinate warping.

Added in version 3.24.0.

property alpha_scale: float¶: Alpha-axis scale compensation factor.

Added in version 3.24.0.

property beta_scale: float¶: Beta-axis scale compensation factor.

Added in version 3.24.0.

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 target grid spacing for a momentum axis.

The returned value controls interpolation sampling. It is not an estimate of the instrumental momentum resolution.

Parameters:

axis (Literal['kx', 'ky', 'kz']) – Momentum axis for which to estimate the spacing.
lims (tuple[float, float] | None, default: None) – Lower and upper axis bounds in Å⁻¹, used when from_numpoints is True. If omitted, estimate_bounds() supplies the bounds.
from_numpoints (bool, default: False) – If True, estimate the spacing from the number of points in the relevant measured axis. If False, estimate it from the angular resolution or, for kz, the photoelectron inelastic mean free path. Default is False.

Returns:

float – Estimated target grid spacing in Å⁻¹.

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.

Assign exact momentum coordinates without interpolating the intensity.

Returns:: xarray.DataArray – A new array with the same dimensions, coordinate sampling, intensity values, name, and attributes as the input. The applicable kx and ky coordinates are added. For photon-energy-dependent data, kz is also added. All units for momentum are in Å⁻¹. The momentum coordinates can depend on more than one measured dimension. The input is not modified.
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) – Lower and upper bounds for each target momentum axis, in Å⁻¹. Keys can be "kx", "ky", or "kz" when that axis applies to the input. Any omitted bound is estimated from the measured angular range.
resolution (dict[str, float] | None, default: None) – Target grid spacing for each momentum axis, in Å⁻¹. This is interpolation sampling, not instrumental momentum resolution. The final spacing can differ slightly because the requested bounds contain an integer number of intervals. If omitted, the target spacing is estimated from the input. For in-plane momentum, the estimate uses the angular resolution and kinetic energy. For kz, the smaller estimate from the photon-energy sampling and the photoelectron inelastic mean free path is used.
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 – Explicit one-dimensional target coordinates, in Å⁻¹, supplied as kx, ky, or kz. An explicit coordinate overrides bounds and resolution for that axis.

Returns:

xarray.DataArray – A new array containing the intensity interpolated on the target momentum grid. Automatically generated momentum coordinates are regularly spaced; explicit coordinates supplied through coords are used as given. Unaffected dimensions retain their names. For fixed-photon-energy cuts, alpha is replaced by the momentum axis parallel to the analyzer slit. For angular maps, alpha and beta are replaced by kx and ky. For photon-energy-dependent cuts, alpha and hv are replaced by the slit-parallel momentum axis and kz. The eV dimension is retained and uses binding energy. The data name and attributes are preserved, and the interpolated values use a floating dtype. Points outside the measured angular coverage contain missing values. The input is not modified.

Return type:

DataArray

Notes

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 or assigned 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.

Use this method for an endstation that can acquire data in more than one physical configuration. The coordinates of the new DataArray are renamed by their physical roles to match the given configuration. The original data is not modified.

This method does not infer the acquisition geometry or repair arbitrary coordinate names from an incorrect loader implementation. The input must use the standard coordinate names for its current configuration.

Parameters:: configuration (AxesConfiguration | int) – The new configuration to apply.
Returns:: xarray.DataArray – A new array with unchanged data values, shape, dimension order, name, and dtype. Standard angle coordinates are renamed by their physical roles. A dimension is also renamed when it uses one of those coordinates. Other coordinates and attributes are retained, and the configuration attribute is updated.
Return type:: DataArray

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.
Returns:: xarray.DataArray – Calculated kz values in Å⁻¹. A scalar photon energy returns values along the applicable eV and slit-parallel momentum dimensions. An array of photon energies adds an hv dimension with the supplied values. The converted intensity data is not changed.
Return type:: DataArray

Notes

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.