Use AiiDAlab widgets#

AiiDAlab largely relies on Jupyter widgets, also known as ipywidgets, for the graphical user interface (GUI). We have created a collection of reusable widgets that are already integrated with AiiDA and help you accomplish common tasks.

AiiDAlab widgets#

AiiDAlab apps typically involve some of the following steps:

  • Prepare the input for a calculation (e.g. an atomic structure).

  • Select computational resources and submit a calculation to AiiDA.

  • Monitor a running calculation.

  • Find and analyze the results of a calculation.

The AiiDAlab widgets help with these common tasks and are preinstalled in the AiiDAlab environment. Please see https://aiidalab-widgets-base.readthedocs.io for documentation on the individual widgets.

text

More widgets#

  • ipywidgets: basic GUI components, such as a text, sliders, buttons, progress bars, drowdowns, etc.

  • widget-periodictable : interactive periodic table for element selection

  • widget-bandsplot : plot electronic bandstructure and density of states

  • widget-jsmol : use the JSmol molecular visualizer inside a Jupyter notebook

Terminology and background#

Widgets and traitlets#

Widgets are Python objects that display GUI components, such as a sliders, buttons, progress bars, drowdowns, etc. ipywidgets is a Python package that provides interactive widgets for the use in Jupyter notebooks.

Widgets can have one or more attributes, whose value can be _observed_ and accessed from Python such that we can react to changes to their values. This is implemented using traitlets.

For example, try the following code in a Jupyter notebook:

from ipywidgets import FloatSlider

# slider widget that has a `value` traitlet attribute
slider = FloatSlider(value=273.0, min=100.0, max=500.0, description="Temperature [K]");

# Access the slider value as `slider.value`
# print(slider.value)

def slider_change(change):
    """Handle slider changes.

    This function is called when the slider value is changed by the user.
    """
    if change["new"] > 373.0:
        print("Boiling now!")

slider.observe(slider_change, names="value")

Creating your own widgets#

Each widget consists of a Python component that defines how to interact with the widget from Python, and a Javascript (or TypeScript) component that is responsible for the graphical representation of the widget and communicates updates back to the Jupyter kernel.

If the goal is to combine existing widgets into new, reusable components, this can be done in Python without touching the Javascript component. See for example the implementation of the AiiDAlab widgets, most of which are of this type.

To modify the appearance of an existing widget or to create an entirely new visualization, one needs to write Javascript/TypeScript. See the detailed tutorial on how to develop a custom widget or have a look at some of the examples from More widgets.