fuller

Integrated computational framework for electronic band structure reconstruction and parametrization, powered by probabilistic machine learning

Introduction

This Python package comprises a set of tools to reconstruct and parametrize the electronic band structure (EBS) from photoemission spectroscopy data. It implements the Markov Random Field model introduced in Xian & Stimper et al. (2020) in TensorFlow.

Methods of installation

The latest version of the package can be installed via pip

pip install --upgrade git+https://github.com/mpes-kit/fuller.git

Alternatively, download the repository and run

python setup.py install

Install directly from PyPI

pip install fuller

Requirements

Apart from the packages specified in the requirements.txt file, tensorflow is needed. Installation instructions can be found at the official webpage. The package works with the CPU only and GPU supported version of the framework. Currently, only version TensorFlow 1 (1.14 onwards) is supported, but we are working on porting it to TensorFlow 2.

Sample dataset

As a model system to demonstrate the effectiveness of the methodology we worked on 3D photoemission data of the semiconductor tungsten diselenide (WSe₂). It resolve the momentum along the x- and y- axis (k_x and k_y) and the energy.

Reconstruction

All 14 valence band of WSe₂ are visible in the dataset. The optimization was initialized by DFT calculation with HSE06 hybrid exchange-correlation functional. The results are shown in the figure below.

Documentation

Complete API documentation is provided here.

Preprocessing and Reconstruction

Class MrfRec

The MrfRec class is of central importance for reconstruction as well as preprocessing the data. To reconstruct the EBS create a MrfRec object and use its methods to perform the algorithms and plot the results. Here, we list a selection of the most important methods of the class. For further illustration on how to use the class check out the mpes_reconstruction_mrf.ipynb notebook in the example folder.

__init__

def __init__(E, kx=None, ky=None, I=None, E0=None, eta=0.1, includeCurv=False, etaCurv=0.1):
    ...

• E: Energy as 1D numpy array
• kx: Momentum along x axis as 1D numpy array, if None it is set to 0
• ky: Momentum along y axis as 1D numpy array, if None it is set to 0
• I: Measured intensity wrt momentum (rows) and energy (columns), generated if None
• E0: Initial guess for band structure energy values, if None the median of E is taken
• eta: Standard deviation of neighbor interaction term
• includeCurv: Flag, if true curvature term is included during optimization
• etaCurv: Standard deviation of curvature term

iter_para

def iter_para(num_epoch=1, updateLogP=False, use_gpu=True, disable_tqdm=False, graph_reset=False):
    ...

Hereby, the parallel optimization of Markov Random Field model can be performed to reconstruct an electronic band.

• num_epoch: Number of epochs to perform
• updateLogP: Flag, if true logP is updated every half epoch (requires more computations)
• use_gpu: Flag, if true gpu is used for computations if available
• disable_tqdm: Flag, it true no progress bar is shown during optimization
• graph_reset: Flag, if true Tensorflow graph is reset after computation to reduce memory demand

normalizeI

def normalizeI(kernel_size=None, n_bins=128, clip_limit=0.01, use_gpu=True, threshold=1e-6):
    ...

This performs Multidimensional Contrast Limited Adaptive Histogram Equalization (MCLAHE), introduced in Stimper et al. 2019. The method is a wrapper for the TensorFlow implementation of the mclahe function.

• kernel_size: Tuple of kernel sizes, 1/8 of dimension lengths of x if None
• n_bins: Number of bins to be used in the histogram
• clip_limit: Relative intensity limit to be ignored in the histogram equalization
• use_gpu: Flag, if true gpu is used for computations if available
• threshold: Threshold below which intensity values are set to zero

Citation

If you are using this package within your own projects, please cite it as

R. P. Xian, V. Stimper, M. Zacharias, S. Dong, M. Dendzik, S. Beaulieu, B. Schölkopf, M. Wolf, L. Rettig, C. Carbogno, S. Bauer, and R. Ernstorfer, "A machine learning route between band mapping and band structure," arXiv:2005.10210, 2020.

Bibtex code

@article{Xian2020,
    author={R. P. Xian and V. Stimper and M. Zacharias and S. Dong and M. Dendzik and S. Beaulieu and
            B. Schölkopf and M. Wolf and L. Rettig and C. Carbogno and S. Bauer and R. Ernstorfer},
    journal={arXiv:2005.10210},
    title={A machine learning route between band mapping and band structure},
    year={2020},
}