widget-bandsplot: Jupyter Widget to Plot Band Structure and Density of States

A Jupyter widget to plot band structures and density of states. The widget is using the mc-react-bands Javascript package and is turned into a Jupyter widget with anywidget.

Installation & usage

pip install widget-bandsplot

Usage

1. Plot both the band structure and the density of states (DOS) side by side

w = BandsPlotWidget(bands=[banddata1, banddata2], dos=dosdata, plot_fermilevel = True, show_legend = True, energy_range = [-10,10])
display(w)

In order to plot the band structure and density of states, one needs to provide bands data and DOS data as JSON-files. The examples of the input JSON-files are provided in the examples/data folder. The JSON-files for the band structure can be exported with the AiiDA command line interface (CLI) verdi as demonstrated in the code below:

verdi data band export <PK> --format=json

One can plot several band structure input files together with the widget. The format of the DOS input dict is validate by the PDOS Schema, the exampla valid input is:

dos_data = {
    "fermi_energy": -7.0,
    "dos": [
        {
            "label": "Total DOS",   # required
            "x": [0.0, 0.1, 0.2],   # required
            "y": [1.2, 3.2, 0.0],   # required
            "borderColor": "#41e2b3",   # optional
            "backgroundColor": "#51258b",   # optional
            "backgroundAlpha": "52%",  #optional: A string with integer between 0-100 and '%' in end.
            "lineStyle": "dash",    # optional
        },
        {
            "label": "Co (s↑)",
            "x": [0.0, 0.1, 0.2],
            "y": [1.2, 3.2, 0.0],
            "lineStyle": "solid",
            "borderColor": "#43ee8b",
            "backgroundColor": "#59595c",
        },
        {
            "label": "Co (s↓)",
            "x": [0.0, 0.1, 0.2],
            "y": [1.2, 3.2, 0.0],
            "lineStyle": "solid",
            "borderColor": "#403bae",
            "backgroundColor": "#a16c5e",
        },
    ],
}

2. Plot only the band structure

w = BandsPlotWidget(bands=[banddata1, banddata2], plot_fermilevel = True, show_legend = True, energy_range = [-10,10])
display(w)

3. Plot only the density of states (DOS)

w = BandsPlotWidget(dos=dosdata, plot_fermilevel = True, show_legend = True, energy_range = [-10, 10])
display(w)

When only plotting the density of states, the plot will be shown in horizontal format.

Development

Install the python code:

pip install -e .[dev]

You then need to install the JavaScript dependencies and run the development server.

npm install
npm run dev

Open examples/example.ipynb in Jupyter notebook or lab to start developing. Changes made in js/ will be reflected in the notebook.

Releasing and publishing a new version

In order to make a new release of the library and publish to PYPI, run

bumpver update --major/--minor/--patch

This will

• update version numbers, make a corresponding git commit and a git tag;
• push this commit and tag to Github, which triggers the Github Action that makes a new Github Release and publishes the package to PYPI.

Github workflow testing

If the widget test fails, it indicates there is something wrong with the code, and the widget is NOT being displayed correctly in the test.

If the widget test passes but the screenshot comparison fails, it indicates the appearance of the widget is different from the previous version. In this case, you'll need to manually download the artifact from the widget test and use it to replace the widget-sample.png figure in the test folder.

Acknowledgements

We acknowledge support from the EPFL Open Science Fund via the OSSCAR project.