Graphical interface¶
AbiPy provides interactive dashboards that can be used either as a standalone web applications (dashboards) with the bokeh server or inside jupyter notebooks. This document explains how to install the required dependencies and how to generate dashboards/GUIs either with the command line interface (CLI) or inside jupyter notebooks.
Important
Please note that one needs a running python backend to execute the callbacks triggerered by the GUI widgets. This part, indeed, is implemented in HTML/CSS/JS code executed by the frontend (i.e. your browser) that sends the signal to the python server (the backend). The python server is supposed to process the data and send the results back to the frontend for visualization purposes
Don’t be surprised if you start to click buttons and nothing happens! The examples provided in this page are only meant to show how to build GUI or dashboards with AbiPy.
Installation¶
Install the panel package either from pip with:
pip install panel
or with conda (recommended) using:
conda install panel -c conda-forge
If you plan to use panel within JupyterLab, you will also need to install the PyViz JupyterLab extension and activate it with:
conda install -c conda-forge jupyterlab
jupyter labextension install @pyviz/jupyterlab_pyviz
Basic Usage¶
Several AbiPy objects provide a get_panel
method returning
an object that can be displayed inside the jupyter notebook or inside the browser.
When running inside a jupyter notebook, remember enable the integration
with the panel
infrastructure by executing:
from abipy import abilab
abilab.abipanel();
before calling any AbiPy get_panel
method.
Note
The abipanel
function is needed to load extensions and javascript packages
required by AbiPy.
This function is just a small wrapper around the official panel API:
import panel as pn
pn.extension()
At this point, we can start to construct AbiPy objects.
For our first example, we use the abiopen
function to open a GSR
file,
then we call get_panel
to build a set of widgets that allows us to interact
with the GsrFile:
from abipy import abilab
import abipy.data as abidata
filename = abidata.ref_file("si_nscf_GSR.nc")
gsr = abilab.abiopen(filename)
gsr.get_panel()
The summary tab provides a string representation of the file but there is no widget to interact with it. If you select the e-Bands tab, you will see several widgets and a button that activates the visualization of the KS band energies. Again, in this HTML page there is no python server running in background so if you click the Plot e-bands button nothing happens (this is not a bug!).
The advantage of this notebook-based approach is that it is possible to mix the panel GUIs with python code that can be used to perform more advanced tasks not supported by the GUI.
Obviously it is possible to have multiple panels running in the same notebook.
Calling get_panel
with an AbiPy structure, for instance, creates a set of widgets
to facilitate common operations such as exporting the structure to a different format or
generating a basic Abinit input file for e.g. GS calculations:
gsr.structure.get_panel()
Note
At present, not all the AbiPy objects support the get_panel
protocol
but we plan to gradually support more objects, especially the most important
netcdf files produced by Abinit
To generate a notebook from the command line, use the abiopen.py script:
abiopen.py si_nscf_GSR.nc -nb # short for --notebook
that will automatically open the notebook inside jupyterlab.
If you prefer classic jupyter notebooks, use the -nb --classic-notebook
options
If you do not need to execute python code, you may want to generate a panel dashboard with:
abiopen.py si_nscf_GSR.nc -pn # short for --panel
The same approach can be used with a DDB
file.
In this case, we get more tabs and options because one can use the GUI
to set the input parameters, invoke anaddb
and visualize the results:
# Open DDB file with abiopen and invoke get_panel method.
ddb_path = abidata.ref_file("mp-1009129-9x9x10q_ebecs_DDB")
abilab.abiopen(ddb_path).get_panel()
The same result can be obtained from the CLI with
abiopen.py mp-1009129-9x9x10q_ebecs_DDB -nb
There are, however, cases in which you don’t need the interactive environment provided by jupyter notebooks as you are mainly interested in the visualization of the results. In this case, it is possible to use the command line interface to automatically generate a dashboard with widgets without having to start a notebook.
To build a dashboard for a Structure
object extracted from FILE
, use:
abistruct.py panel FILE
where FILE
is any file providing a Structure
object
e.g. netcdf files, cif files, abi, abo files etc.
To build a dashboard associated to one of the AbiPy file, use the syntax:
abiopen.py FILE --panel
where FILE
is one of the Abinit files supported by abiopen.py
.
For instance, one can create a dashboard to interact with a DDB
file with:
abiopen.py out_DDB --panel
Important
To build a dashboard for an AbiPy Flow use:
abirun.py FLOWDIR panel
or alternatively:
abiopen.py FLOWDIR/__AbinitFlow__.pickle --panel