ARPES API

Bands Class

class aurelia_arpes.Bands(symmetry=None, klim=None, Nbands=None, warp=None, Npts=None, edges=None)

Calculates the bandstructure based on a tight-binding model. The input arguments are saved in the Bands object.

Optional args:

symmetry: A string. Defines the lattice of the tight-binding model. The available inputs are ‘rectangle’, ‘square’, ‘hexagonal’, ‘honeycomb’. If an input is not given, one is chosen at random.
klim: A $2 \times 2$ numpy array defining the limits of $k_x$ and $k_y$ in the list. If an input is not given, the lower limit is chosen randomly between $[-1,-0.5]$, and the upper limit is chosen randomly between $[0.5, 1]$.
Nbands: An integer defining the number of bands in the tight-binding model. If an input is not given, one is chosen at random between $[1, 5]$.
warp: A string. “on” or “off”. Toggles next-nearest neighbour hopping in the tight-binding model.
Npts: A $2 \times 1$ numpy array (elements are integers) defining the number of points calculated in the $k_x$ and $k_y$ dimensions.
edges: A float slightly larger than one. Since we calculate a limited region of k-space, interpolation may be off at the edges if we use large offset angles in the experiment. Here, the k-space edge is padded and later cropped to exclude artifacts.

Import_bands(filename)

This function imports bands from a file. The file should have kx in column 1, ky in column 2. Each band should be in its own column from 3 onwards.

args:

filename: A string. The name of the file to be imported.

Saved args:

The following and read from the file and saved to the Bands object: Npts, kax, kay, klim, kpath, bands, Nbands
The following parameters are defined statically:

bands.edges = 1
bands.warp = "off"
bands.symmetry = "custom" 

Make_bands(tb=None, lattice=None)

This function calculates the dispersion using a tight-binding model.

Optional args:

tb: A Python dictionary representing the tight-binding parameters. The dictionary is of the form:

tb = {"E0": [], "t": []}

$E_0$ and $t$ must be NumPy arrays of dimension $[1 , N_\text{bands}]$.
$E_0$ contains the center energies of the bands.
$t$ contains the hopping parameter of each band.

If the lattice is rectangular (as defined in Bands.symmetry), then $t$ must have shape $[2, N_\text{bands}]$.

If no input is provided, $E_0$ is randomly generated in the interval [-1, 0], and $t$ is randomly generated in the interval [-1, 1].

lattice: A Python dictionary of the lattice parameters.

These lattice parameters define the size of the Brillouin zone and – by extension – the field of view given by the limits set in Bands.klim. The dictionary is of the form:

lattice = {"a": [], "b": []}

$a$ and $b$ are floats.

If no input is provided, $a$ and math:b are calculated from the k-space limits.

Saved args:

Bands.bands: A $[N , N_{\text{bands}}$ numpy array defining the dispersion of each band along the k-path. N is given by the product of Bands.Npts.

Make_kpath()

This function defines the $k_x$ and $k_y$ grid the bands are calculated on. The edges are padded so that rotation and interpolation do not create artifacts. The calculation of the dispersion is not particularly time-intensive, so a grid of points is typically calculated. To speed up computation, the ARPES spectra can be calculated over just $k_x$, but the grid of points are needed for interpolation in the case of rotational or offset domains.

This function adds the following to the Bands object:

Saved args:

Bands.kpath: A $N \times 2$ numpy array defining the k-path along which the dispersion is calculated. $N$ is the product of the elements of Bands.Npts. The first and second columns correspond to $k_x$ and $k_y$, respectively.
Bands.kax: A $N_\text{pts}^x \times 1$ numpy array defining the $k_x$ axis. Used for plotting purposes.
Bands.kay: A $N_\text{pts}^y \times 1$ numpy array defining the $k_y$ axis. Used for plotting purposes.

print_variables(): Provides a summary of variables used to define the band structure.

Spec Class

class aurelia_arpes.Spec(bands, dimension=None, Omega=None)

Calculates the photoemission spectra. Includes the Fermi-Dirac distribution, matrix elements and resolution broadening.

args:

The input bands is an object. Defines the electronic dispersion and k-path.

Optional args:

dimension: A string. Defines the dimension of the calculation, three modes are available.
- The input “cube” calculates the spectra in binding energy $\omega$, and the crystal momenta $k_x$, and $k_y$.
- The input “sliceEk” calculates the spectra in $\omega$ and $k_x$. The “dispersion cut”.
- The input “slicekk” calculates the spectra in $k_x$ and $k_y$. The “Fermi surface” or “constant energy cut”.
Omega: A $M \times 1$ numpy array defining the binding energy range points over which the photoemission spectra are calculated.

Saved args:

spec.bands : The object defining the electronic dispersion and k-path.
spec.kax : numpy array of shape $(N_\text{pts}^x, 1)$. Defines the $k_x$ axis. Used for plotting purposes.
spec.kay : numpy array of shape $(N_\text{pts}^y, 1)$. Defines the $k_y$ axis. Used for plotting purposes.
spec.matrix_elements : numpy array of shape $(N, N_\text{bands})$. Matrix elements of each band along the k-path. Same shape as Bands.bands. Initialized as an array of ones.
spec.ReS : numpy array of shape $(M, N_\text{bands})$. The real part of the self-energy, initialized as zeros.
spec.ImS : numpy array of shape $(M, N_\text{bands})$. The real part of the self-energy, initialized as with a single value of 0.2.
spec.domain : numpy array. Defines the relative intensity of rotational and offset domains. Initialized (for the primary domain) as an array of ones with shape $(1, N_{\text{bands}})$.

Make_matrix_elements(ME=None)

This function creates fake matrix elements aimed at varying the intensity of bands to mimic photoemission intensity.

args:

A Python dictionary. Defines the type of fake photoemission matrix elements that are generated. Accepts three strings.
- "symm": Gives matrix elements the same symmetry as that of the tight-binding model, in that they are periodic in k-space in the same way.
- "rot" : Gives matrix elements with rotational symmetry, which mimics the orbital selectivity of linear and/or circularly polarized light.
- "poly": Gives matrix elements defined by a random polynomial. Used to modulate the intensity of the bands and is used to mimic the unpredictable effects of experimental geometry variance in the light.

Saved args:

spec.matrix_elements: A NumPy array defining the matrix elwith the same dimensions as Bands.bands.
spec.ME: The Python dictionary specifying parameters of the matrix-element calculation.

Make_self_energy(SE)

This function is optional, since the self-energy is already initialized. For more realistic ARPES spectra, two types of self-energy are available through the input dictionary SE:

args:

SE: a python dictionary. The key type accepts two strings: "FL" or "kink", corresponding to Fermi-liquid or electron-boson kink.
- for Fermi-liquid type self energy, additional fields val and ImS0 may be specified (or will be randomly chosen)
- for electron-boson kink, additional fields ImS0, ImS1, Amp, Ekink, and gamma may be specified (or will be randomly chosen).

Saved args:

spec.ReS : numpy array of shape $(M, N_\text{bands})$. The real part of the self-energy.
spec.ImS : numpy array of shape $(M, N_\text{bands})$. The real part of the self-energy.
spec.SE : the python dictionary with parameters used in the calculation of the self-energy.

Make_specfun(mod)

This function calculates the photoemission spectral intensity based on the band structure as well as the self-energy given.

args: - mod: a Python dictionary of the form mod = {"ER": [], "kR": [], "Temp": []}, where the three fields define the energy resolution, the angular resolution, and the electronic temperature, respectively. mod is an object generated by the aurelia_static_vars module.

The outputs of the function are:

spec.mod: The Python dictionary which collects the modification parameters.
spec.specfun: A numpy array with a dimension specified by spec.dimension, such that:
- cube: $M \times N_{pts}^x \times N_{pts}^y$
- sliceEk: $M \times N_{pts}^x$
- slicekk: $1 \times N_{pts}^x \times N_{pts}^y$

Make_specmod(mod)

This function modifies the intensity in self.specfun by adding the Fermi-Dirac distribution and resolution broadening.

args:

mod: an object generated the aurelia_static_vars module. Defines the energy resolution, the angular resolution, and the electronic temperature.

Saved args:

spec.specfun: The modified intensity replaces that previous calculated via spec.Make_specfun(mod)

print_variables(): Provides a summary of variables used to calculate the measured spectral intensity.

ARPES Class

class aurelia_arpes.ARPES(spec, exp, ang_lim=None, dimension=None)

This function initializes the ARPES simulation.

args:

spec: An object containing the spectral intensity calculated from the dispersion.
exp: An object containing the experimental parameters, initialized from the aurelia_static_vars module.

Optional args:

dimension: A string defining the dimension of the calculation. Three modes are available:
- "cube": Spectra in binding energy, $k_x$, and $k_y$.
- "sliceEk": Spectra in binding energy and $k_x$ (dispersion cut).
- "slicekk": Spectra in $k_x$ and $k_y$ (Fermi surface).

The default dimension string is the same as Spec.dimension. If Spec.dimension = "cube", then arpes.dimension can be set to "sliceEk" or "slicekk". This allows offset and rotational domains to be accurately calculated, while saving computational time and file size.

ang_lim: A python dictionary with the fields ang_lim["th"] and ang_lim["ph"]. The values are 2-element numpy arrays defining the limits of $\theta$ and $\phi$ seen by the detector. If not specified, the angle limits are calculated using the k-space limits in Spec.

Saved args:

arpes.spec: An object containing the spectral intensity calculated from the dispersion.
arpes.exp: An object containing the experimental parameters.
arpes.Ek: The kinetic energy axis, calculated as:
arpes.dimension: A string defining the dimension of the calculation.
arpes.th: A NumPy array of shape $N_{pts}^x \times 1$. Defines the angles along the $k_x$ direction.
arpes.ph: A NumPy array of shape $N_{pts}^y \times 1$. Defines the angles along the $k_y$ direction.
arpes.crop: A boolean. Checks if the edges have been cropped. Initialized as false. The edges are defined by Bands.edges.

Crop_edges(): This function crops the edges of the simulation to remove artifacts.

Make_angle_conv(const=None, domain=None)

This function converts the intensity stored in spec.specfun in momentum and binding energy to arpes.intensity in angle and kinetic energy.

args:

const: A float. If the dimension of the calculation is not "cube", this
gives the value at which the slice is calculated.
- For self.dimension = "sliceEk", const corresponds to the
$\phi$ axis. Defaults to the mean $\phi$ value. - For self.dimension = "slicekk", const corresponds to $E_k$ axis. Defaults to the Fermi energy.
domain: An object containing information about offset angles for
calculating offset domains.

Saved args:

arpes.intensity: A numpy array with shape specified by arpes.dimension.
- cube: $M\times N_{pts}^x \times N_{pts}^y$
- sliceEk: $M\times N_{pts}^x$
- slicekk: $1\times N_{pts}^x \times N_{pts}^y$
arpes.bkgd: A numpy array with the same shape as arpes.intensity. Initialized as zeros.
arpes.response: A numpy array with the same shape as arpes.intensity. Initialized as ones.

Returned args:

If this function is used to calculate a domain, then the intensity is not saved, but simply returned.

Make_kwarp_check(): This function checks the momentum-to-angle conversion by performing an angle-to-momentum conversion before interpolation to show that the original k-mesh is reporduced. It gives no outputs but plots the intensity before warping, after warping to angle, and after warping back to momentum space.

Make_quality_score(param=None)

This function provides a quality score for the spectra based on the metrics, feature sharpness, the number of electrons, the signal to background, and a total score.

args:

param: A dictionary of the form param = {"threshold": [], "penalty": [], "weight": []}. The fields are:
- param["threshold"]: A numpy array of shape $m \times 1$ defining the
score brackets where each penalty is incurred. Default: [0.9, 0.7, 0.5, 0.3]. - param["penalty"]: A numpy array of shape $m \times 1$ defining the penalty amount incurred in each score bracket. Default: [1, 2, 3, 4]. - param["weight"]: A numpy array of shape $3 \times 1$ defining the relative weights of penalties for each metric. Default: [1, 1, 1].

Saved args:

arpes.score, a dictionary with the following fields:
- score["width"]: Feature sharpness score, out of 1.
- score["bkgd"]: Signal-to-background score, out of 1.
- score["counts"]: Number of electrons score, out of 1.
- score["final"]: Total score, out of 10.

Make_statistics(exp)

This function takes the ARPES intensity $I(\theta,\phi, \omega)$ and uses it as a probability distribution function to generate a measured spectrum of $N$ electrons.

args:

exp: An object containing the experimental parameters. Defined via the aurelia_static_vars module.

Saved args:

arpes.stats: A numpy array containing the spectra generated by $N_e$ random electrons that has the same dimension as arpes.intensity.
arpes.dstats: A numpy array containing the spectra generated by $N_e$ random electrons that has the same dimension as arpes.domains.

print_variables(): Provides a summary of variables used to calculate the measured arpes spectra.