BandMap

File containing the band map class.

class xarpes.bandmap.BandMap(intensities=None, angles=None, ekin=None, enel=None, energy_resolution=None, angle_resolution=None, temperature=None, hnuminPhi=None, hnuminPhi_std=None)

Band map container for ARPES intensity data.

A BandMap stores a two-dimensional ARPES intensity map together with its angular axis and a single energy axis (either kinetic or binding energy). Conversion between kinetic and binding energy is handled internally via the work-function offset hnuminPhi when available.

See also

BandMap.from_ibw_file

BandMap.from_np_arrays

Notes

Users are encouraged to construct instances via from_ibw_file() or from_np_arrays(). The __init__ method expects fully initialized, canonical NumPy arrays and performs no file I/O.

The intensity array is assumed to have shape (n_energy, n_angle), consistent with all downstream operations (plotting, MDC extraction, Fermi-edge fitting).

classmethod from_ibw_file(datafile, transpose=False, flip_ekin=False, flip_angles=False, **kwargs)

Construct a BandMap from an IGOR Binary Wave (.ibw) file.

The IGOR wave header is used to reconstruct the angular and kinetic-energy axes. The resulting instance uses kinetic energy (ekin) as the explicit energy axis.

Parameters:

datafilepath-like

Path to the .ibw file.

transposebool, optional

If True, transpose the loaded intensity array and swap the associated axis metadata accordingly.

flip_ekinbool, optional

If True, reverse the kinetic-energy axis (first dimension).

flip_anglesbool, optional

If True, reverse the angle axis (second dimension).

**kwargs

Additional keyword arguments forwarded to BandMap.__init__.

Returns:

BandMap

New instance constructed from the file contents.

Raises:

ValueError

If the dimensions reported in the file header do not match the shape of the stored intensity array.

classmethod from_np_arrays(intensities=None, angles=None, ekin=None, enel=None, **kwargs)

Construct a BandMap directly from NumPy arrays.

Exactly one of ekin or enel must be provided and will become the authoritative energy axis. The other energy axis may be derived later if the work-function offset hnuminPhi is known.

Parameters:

intensitiesarray-like

ARPES intensity map with shape (n_energy, n_angle) [counts].

anglesarray-like

Angular axis values with shape (n_angle,) [degree].

ekinarray-like, optional

Kinetic-energy axis values with shape (n_energy,) [eV].

enelarray-like, optional

Binding-energy axis values with shape (n_energy,) [eV].

**kwargs

Additional keyword arguments forwarded to BandMap.__init__.

Returns:

BandMap

New instance constructed from the provided arrays.

Raises:

ValueError

If intensities or angles is missing, or if both (or neither) of ekin and enel are provided.

property hnuminPhi

Returns the photon energy minus the work function in eV if it has been set, either during instantiation, with the setter, or by fitting the Fermi-Dirac distribution to the integrated weight.

Returns:

hnuminPhifloat, None

Kinetic energy minus the work function [eV]

property hnuminPhi_std

Returns standard deviation of the photon energy minus the work function in eV.

Returns:

hnuminPhi_stdfloat

Standard deviation of energy minus the work function [eV]

shift_angles(shift)

Shifts the angles by the specified amount in degrees. Used to shift from the detector angle to the material angle.

Parameters:

shiftfloat

Angular shift [degrees]

mdc_set(angle_min, angle_max, energy_value=None, energy_range=None)

Return a set of momentum distribution curves (MDCs).

This method extracts MDCs from the stored ARPES intensity map from a specified angular interval and either selecting a single energy slice or an energy window.

Parameters:

angle_minfloat

Minimum angle of the integration interval [degrees].

angle_maxfloat

Maximum angle of the integration interval [degrees].

energy_valuefloat, optional

Energy value [same units as self.enel] at which a single MDC is extracted. Exactly one of energy_value or energy_range must be provided.

energy_rangearray-like, optional

Energy interval [same units as self.enel] over which MDCs are extracted. Exactly one of energy_value or energy_range must be provided.

Returns:

mdcsndarray

Extracted MDC intensities. Shape is (n_angles,) when a single energy_value is provided, or (n_energies, n_angles) when an energy_range is provided.

angle_rangendarray

Angular values corresponding to the MDCs [degrees].

angle_resolutionfloat

Angular resolution associated with the MDCs.

energy_resolutionfloat

Energy resolution associated with the MDCs.

temperature: float

Temperature associated with the band map [K].

energy_rangendarray or float

Energy value (scalar) or energy array corresponding to the MDCs.

hnuminPhifloat

Photon-energy-related offset propagated from the BandMap.

Raises:

ValueError

If neither or both of energy_value and energy_range are provided.

plot(abscissa='momentum', ordinate='electron_energy', self_energies=None, ax=None, markersize=None, plot_dispersions='none')

Plot the band map. Optionally overlay a collection of self-energies, e.g. a CreateSelfEnergies instance or any iterable of self-energy objects. Self-energies are not stored internally; they are used only for this plotting call.

When self-energies are present and abscissa='momentum', their MDC maxima are overlaid with 95 % confidence intervals.

The plot_dispersions argument controls bare-band plotting:

• “full” : use the full momentum range of the map (default)

• “none” : do not plot bare dispersions

• “kink” : for each self-energy, use the min/max of its own momentum range (typically its MDC maxima), with len(self.angles) points.

• “domain” : for SpectralQuadratic, use only the left or right domain relative to center_wavevector, based on the self-energy attribute side (“left” / “right”); for other cases this behaves as “full”.

Notes

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: True.

fit_fermi_edge(hnuminPhi_guess, background_guess=0.0, integrated_weight_guess=1.0, angle_min=-inf, angle_max=inf, ekin_min=-inf, ekin_max=inf, ax=None)

Fits the Fermi edge of the band map and plots the result. Also sets hnuminPhi, the kinetic energy minus the work function in eV. The fitting includes an energy convolution with an abscissa range expanded by 5 times the energy resolution standard deviation.

Parameters:

hnuminPhi_guessfloat

Initial guess for kinetic energy minus the work function [eV]

background_guessfloat

Initial guess for background intensity [counts]

integrated_weight_guessfloat

Initial guess for integrated spectral intensity [counts]

angle_minfloat

Minimum angle of integration interval [degrees]

angle_maxfloat

Maximum angle of integration interval [degrees]

ekin_minfloat

Minimum kinetic energy of integration interval [eV]

ekin_maxfloat

Maximum kinetic energy of integration interval [eV]

axMatplotlib-Axes / NoneType

Axis for plotting the Fermi edge on. Created if not provided by the user.

Returns:

figMatplotlib-Figure

Figure containing the Fermi edge fit

Notes

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: True.

correct_fermi_edge(hnuminPhi_guess=None, background_guess=0.0, integrated_weight_guess=1.0, angle_min=-inf, angle_max=inf, ekin_min=-inf, ekin_max=inf, slope_guess=0, offset_guess=None, linear_guess=0.0, quadratic_guess=0.0, edge_function='linear', true_angle=0, ax=None)

TBD hnuminPhi_guess should be estimated at true angle

Parameters:

hnuminPhi_guessfloat, optional

Initial guess for kinetic energy minus the work function [eV].

linear_guessfloat, optional

Initial guess for the first-order coefficient when edge_function='quadratic'.

quadratic_guessfloat, optional

Initial guess for the second-order coefficient when edge_function='quadratic'.

edge_functionstr, optional

Edge model fitted to the angle-dependent Fermi-edge positions. Supported values are 'linear' and 'quadratic'.

Returns:

figMatplotlib-Figure

Figure containing the Fermi edge fit

Notes

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: True.