Improve docs

abipy/dfpt/phonons.py

@@ -3881,7 +3881,7 @@ class PhononBandsPlotter(NotebookWriter):
         for i, (label, phbands) in enumerate(self.phbands_dict.items()):
             app("[%d] %s --> %s" % (i, label, func(phbands)))
 
-        if self.phdoses_dict:
+        if self.phdoses_dict and verbose:
             for i, (label, phdos) in enumerate(self.phdoses_dict.items()):
                 app("[%d] %s --> %s" % (i, label, func(phdos)))
 

abipy/examples/flows/develop/run_eph_zpr.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python
+import sys
+import os
+import abipy.abilab as abilab
+import abipy.data as abidata
+
+from abipy import flowtk
+
+def make_scf_input(paral_kgb=0):
+    """
+    This function constructs the input file for the GS calculation:
+    """
+    structure = abilab.Structure.from_abivars(
+        acell=[7.7030079150, 7.7030079150, 7.7030079150],
+        rprim=[0.0000000000, 0.5000000000, 0.5000000000,
+               0.5000000000, 0.0000000000, 0.5000000000,
+               0.5000000000, 0.5000000000, 0.0000000000],
+        natom=2,
+        ntypat=2,
+        typat=[1, 2],
+        znucl=[3, 9],
+        xred=[0.0000000000, 0.0000000000, 0.0000000000,
+              0.5000000000, 0.5000000000, 0.5000000000]
+    )
+
+    pseudos = ["03-Li.LDA.TM.pspnc", "09-F.LDA.TM.pspnc"]
+
+    gs_inp = abilab.AbinitInput(structure, pseudos=pseudos)
+
+    gs_inp.set_vars(
+        nband=10,
+        ecut=50.0,
+        istwfk="*1",
+        ngkpt=[8, 8, 8],
+        nshiftk=1,
+        shiftk=[0, 0, 0],
+        paral_kgb=paral_kgb,
+        tolvrs=1.0e-12,
+        diemac=9.0,
+        nstep=150,
+        nbdbuf=4,
+    )
+
+    return gs_inp
+
+
+def build_flow(options):
+    """
+    Create a `Flow` for phonon calculations. The flow has two works.
+    """
+    # Working directory (default is the name of the script with '.py' removed and "run_" replaced by "flow_")
+    if not options.workdir:
+        options.workdir = os.path.basename(__file__).replace(".py", "").replace("run_", "flow_")
+
+    flow = flowtk.Flow(workdir=options.workdir)
+
+    # Build input for GS calculation and create first work with 1 ScfTask.
+    gs_inp = make_scf_input()
+    work = flow.register_scf_task(gs_inp)
+    scf_task = work[0]
+
+
+    # Build new input for NSCF calculation with k-path (automatically selected by AbiPy)
+    # Used to plot the KS band structure and interpolate the QP corrections.
+    nscf_kpath_inp = gs_inp.new_with_vars(
+        nband=12,
+        tolwfr=1e-20,
+        iscf=-2,
+    )
+    nscf_kpath_inp.set_kpath(ndivsm=10)
+    work.register_nscf_task(nscf_kpath_inp, deps={scf_task: "DEN"})
+
+    # Build another NSCF input with k-mesh and empty states.
+    # This step generates the WFK file used to build the EPH self-energy.
+    nscf_empty_kmesh_inp = gs_inp.new_with_vars(
+        nband=630,     # Too low. ~300
+        nbdbuf=30,     # Reduces considerably the time needed to converge empty states!
+        tolwfr=1e-18,
+        iscf=-2,
+    )
+    nscf_empty_task = work.register_nscf_task(nscf_empty_kmesh_inp, deps={scf_task: "DEN"})
+
+
+    NGQPT = [32, 32, 32]
+    nscf_empty_kmesh_inp.set_kmesh(
+        ngkpt=NGQPT,
+        shiftk=[0.0, 0.0, 0.0],
+    )
+
+    # Create work for phonon calculation with WFQ files with a [4, 4, 4] q-mesh.
+    # Electric field and Born effective charges are also computed.
+    ph_work = flowtk.PhononWfkqWork.from_scf_task(scf_task, ngqpt=NGQPT, with_becs=True)
+
+    #for task in ph_work:
+    #   task.input.set_vars(prtwf=-1)
+
+    flow.register_work(ph_work)
+
+    # Build template for self-energy calculation. See also v8/Input/t44.in
+    # The k-points must be in the WFK file
+    #
+    eph_inp = gs_inp.new_with_vars(
+        optdriver=7,             # Enter EPH driver.
+        eph_task=4,              # Activate computation of EPH self-energy.
+        ngkpt=NGQPT,
+        ddb_ngqpt=NGQPT,         # q-mesh used to produce the DDB file (must be consistent with DDB data)
+        symsigma=1,              # Use symmetries in self-energy integration (IBZ_k instead of BZ)
+        # For more k-points...
+        nkptgw=2,
+        kptgw=[0, 0, 0,
+               0.5, 5, 0],
+        bdgw=[1, 8, 1, 8],
+        #gw_qprange=-4,
+        tmesh=[0, 200, 1],    # (start, step, num)
+        zcut="0.1 eV",
+    )
+
+    # Set q-path for Fourier interpolation of phonons.
+    eph_inp.set_qpath(10)
+
+    # Set q-mesh for phonons DOS.
+    eph_inp.set_phdos_qmesh(nqsmall=16, method="tetra")
+
+    # EPH part requires the GS WFK, the DDB file with all perturbations
+    # and the database of DFPT potentials (already merged by PhononWork)
+    deps = {nscf_empty_task: "WFK", ph_work: ["DDB", "DVDB"]}
+
+    # Now we use the EPH template to perform a convergence study in which
+    # we change the q-mesh used to integrate the self-energy and the number of bands.
+    # The code will activate the Fourier interpolation of the DFPT potentials if eph_ngqpt_fine != ddb_ngqpt
+
+    #for eph_ngqpt_fine in [[4, 4, 4], [8, 8, 8]]:
+    for eph_ngqpt_fine in [NGQPT]:
+        # Create empty work to contain EPH tasks with this value of eph_ngqpt_fine
+        eph_work = flow.register_work(flowtk.Work())
+        for nband in [200, 300, 400, 500]:
+            new_inp = eph_inp.new_with_vars(eph_ngqpt_fine=eph_ngqpt_fine, nband=nband)
+            eph_work.register_eph_task(new_inp, deps=deps)
+
+    flow.allocate()
+    return flow
+
+@flowtk.flow_main
+def main(options):
+    """
+    This is our main function that will be invoked by the script.
+    flow_main is a decorator implementing the command line interface.
+    Command line args are stored in `options`.
+    """
+    return build_flow(options)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

abipy/examples/plot/README.txt

@@ -3,16 +3,32 @@
 AbiPy Gallery
 =============
 
-There are a variety of ways to use the AbiPy post-processing tools, 
-and most of them are illustrated in the examples in this directory.
+There are a variety of ways to use the AbiPy post-processing tools,
+and some of them are illustrated in the examples in this directory.
+These examples represent an excellent starting point if you need  to implement
+a customized script to solve your particular problem.
 
-Remember that one can also generate a jupyter notebook directly from the command line with 
-the :ref:`abiopen.py` script and the command::
+Keep in mind, however, that simple visualization tasks can be easily 
+automated by just issuing in the terminal:
 
-    abiopen.py FILE -nb
-
-issue 
+.. code-block:: shell
 
     abiopen.py FILE --expose
 
-to generate plots automatically or use one of the options of :ref:`abiview.py` to plot the results automatically.
+to generate a predefined list of **matplotlib** plots.
+To activate the plotly version use:
+
+.. code-block:: shell
+
+    abiopen.py FILE --plotly
+
+although at the time of writing not all the files support this protocol.
+
+Note also that one can generate a jupyter notebook directly from the command line with
+abiopen.py_ and the command:
+
+.. code-block:: shell
+
+    abiopen.py FILE -nb
+
+use one of the options of abiview.py_ to plot the results automatically.

abipy/examples/plot/plot_ddb_asr.py

@@ -5,6 +5,7 @@ Phonon bands with/without the ASR
 
 This example shows how to plot a phonon band structure
 with and without enforcing the acoustic sum rule (ASR).
+Both matplotlib and plotly are supported.
 
 .. important::
 
@@ -21,19 +22,40 @@ filepath = abidata.ref_file("mp-1009129-9x9x10q_ebecs_DDB")
 ddb = abilab.abiopen(filepath)
 
 #%%
-# The ddb.anacompare_asr method computes the phonon bands and DOS by calling anaddb
+# The ``ddb.anacompare_asr`` method computes the phonon bands and the DOS by calling anaddb
 # with different values of asr and returns a PhononBandsPlotter object:
+# To make the computation faster, we use the **advanced** options dipdip -1.
+# This option should produce results similar to dipdip 1 yet make sure to test
+# the effect of this variable before using it in production.
+
+plotter = ddb.anacompare_asr(asr_list=(0, 2), dipdip=-1)
+print(plotter)
+
+#%%
+# To plot the bands on the same figure with matplotlib, use:
 
-plotter = ddb.anacompare_asr(asr_list=(0, 2))
 plotter.combiplot()
 
 #%%
-# To disable the DOS computation, set nqsmall to 0:
+# For the plotly version, use:
+
+plotter.combiplotly()
+
+#%%
+# To disable the DOS computation, set ``nqsmall` to 0:
+
+plotter = ddb.anacompare_asr(asr_list=(0, 2), nqsmall=0, ndivsm=10, dipdip=-1)
+
+#%%
+# To plot the bands on different subplots with matplotlib, use:
 
-plotter = ddb.anacompare_asr(asr_list=(0, 2), nqsmall=0, ndivsm=10)
 plotter.gridplot()
 
 #%%
-# Remember to close the file with:
+# For the plotly version, use:
+plotter.gridplotly()
+
+#%%
+# Finally, remember to close the file with:
 
 ddb.close()

abipy/examples/plot/plot_phonons_lo_to.py

@@ -1,28 +1,40 @@
 #!/usr/bin/env python
 r"""
-Phonon Bands with LO-TO
-=======================
+Phonon bands with LO-TO from PHBST.nc
+=====================================
 
 This example shows how to plot the phonon band structure of AlAs
-including the LO-TO splitting. See tutorial/lesson_rf2.html
+including the LO-TO splitting.
+See tutorial/lesson_rf2.html
 """
-from abipy.abilab import abiopen
-import abipy.data as abidata
 
+#%%
 # Open PHBST file produced by anaddb and extract the phonon bands object.
 # (alternatively one can use the shell and `abiopen.py OUT_PHBST.nc -nb`
 # to open the file in a jupyter notebook.
+
+from abipy.abilab import abiopen
+import abipy.data as abidata
+
 with abiopen(abidata.ref_file("ZnSe_hex_886.out_PHBST.nc")) as ncfile:
     phbands = ncfile.phbands
 
+#%%
 # Phonon frequencies with non analytical contributions, if calculated, are saved
 # in the anaddb.nc file produced by anaddb. The results should be fetched from there
 # and added to the phonon bands.
-phbands.read_non_anal_from_file(abidata.ref_file("ZnSe_hex_886.anaddb.nc"))
-
 # Notice that all the directions starting from or arriving at gamma that are used
 # in the path should explicitely calculated, even if the values are the same.
 
+phbands.read_non_anal_from_file(abidata.ref_file("ZnSe_hex_886.anaddb.nc"))
+
+#%%
 # Plot the phonon frequencies. Note that the labels for the q-points
 # are found automatically by searching in an internal database.
+
 phbands.plot(title="ZnSe with LO-TO splitting")
+
+#%%
+# For the plotly version, use:
+
+phbands.plotly(title="ZnSe with LO-TO splitting")

abipy/examples/plot/plot_phthermo.py

@@ -6,8 +6,6 @@ Thermodinamic properties
 This example shows how to compute and plot thermodinamic properties within
 the harmonic approximation using the phonon DOS produced by anaddb.
 """
-from __future__ import print_function
-
 from abipy.abilab import abiopen
 import abipy.data as abidata
 
@@ -20,14 +18,22 @@ print(ncfile.structure)
 zpe = phdos.zero_point_energy
 print("Zero point energy:", zpe, zpe.to("J"), zpe.to("Ha"))
 
+#%%
 # Compute free energy from 2 to 300 K (20 points)
 # By default, energies are is eV and thermodynamic quantities are given
 # on a per-unit-cell basis.
 f = phdos.get_free_energy(tstart=2, tstop=300, num=20)
 #f.plot()
 
+#%%
 # Plot U, F, S, Cv as a function of T.
 # Use J/mol units, results are divided by formula_units.
 phdos.plot_harmonic_thermo(units="Jmol", formula_units=1)
 
+#%%
+# Plotly version:
+phdos.plotly_harmonic_thermo(units="Jmol", formula_units=1)
+
+#%%
+# Remember to close the file:
 ncfile.close()

abipy/examples/plot/plotly_ddb_asr.py

@@ -1,42 +0,0 @@
-#!/usr/bin/env python
-r"""
-Phonon bands with/without the ASR (Plotly version)
-==================================================
-
-This example shows how to plot a phonon band structure
-with and without enforcing the acoustic sum rule (ASR).
-
-.. important::
-
-    Note that a **manager.yml** configuration file and an abinit installation are required
-    to run this script as AbiPy needs to invoke anaddb to compute phonons from the DDB file.
-"""
-
-#%%
-# Open the DDB file with:
-
-from abipy import abilab
-import abipy.data as abidata
-filepath = abidata.ref_file("mp-1009129-9x9x10q_ebecs_DDB")
-ddb = abilab.abiopen(filepath)
-
-#%%
-# The ddb.anacompare_asr method computes the phonon bands and DOS by calling anaddb
-# with different values of asr and returns a PhononBandsPlotter object.
-# To make the computation faster we used the **advanced** options dipdip -1.
-
-plotter = ddb.anacompare_asr(asr_list=(0, 2), dipdip=-1)
-plotter.combiplotly()
-
-#%%
-# To disable the DOS computation, set nqsmall to 0:
-
-plotter = ddb.anacompare_asr(asr_list=(0, 2), nqsmall=0, ndivsm=10, dipdip=-1)
-plotter.gridplotly()
-
-#%%
-# Remember to close the file with:
-
-ddb.close()
-
-# sphinx_gallery_thumbnail_path = '_static/plotly_logo.png'

abipy/panels/core.py

@@ -57,7 +57,7 @@ def gen_id(n=1, pre="uuid-"):
 class HTMLwithClipboardBtn(pn.pane.HTML):
     """
     Receives an HTML string and return an HTML pane with a button that allows the user
-    to copy the content to the system clipboard. 
+    to copy the content to the system clipboard.
     Requires call to abipanel to load JS extension.
     """
 
@@ -221,7 +221,7 @@ class ButtonContext(object):
     A context manager for buttons triggering computations on the server.
 
     This manager disables the button when we __enter__ and changes the name of the button to "running".
-    It reverts to the initial state of the button one __exit__ is invoked, showing the Exception type 
+    It reverts to the initial state of the button one __exit__ is invoked, showing the Exception type
     in a "red" button if an exception is raised during the computation.
 
     This a very important tool because we need to disable the button when we start the computation
@@ -232,7 +232,7 @@ class ButtonContext(object):
     Note also that we want to provide some graphical feedback to the user if something goes wrong.
     At present we don't expose the python traceback on the client.
     It would be nice but we need panel machinery to do that.
-    Moreover this is not the recommended approach for security reasons so we just change the "color" 
+    Moreover this is not the recommended approach for security reasons so we just change the "color"
     of the button and use the string representation of the exception as button name.
     """
 
@@ -477,20 +477,20 @@ class PanelWithNcFile(AbipyParameterized):
     This frame allows the user to inspect the dimensions and the variables reported in a netcdf file.
     Tab showing information on the netcdf file.
 
-    Subclasses should implement the `ncfile` property 
+    Subclasses should implement the `ncfile` property
     """
 
     @property
     def ncfile(self):
         """abc does not play well with parametrized so we rely on this to enforce the protocol."""
-        raise NotImplementedError("subclass should implement `ncfile` property.")
+        raise NotImplementedError("subclass should implement the `ncfile` property.")
 
     def get_ncfile_panel(self):
 
         col = pn.Column(sizing_mode='stretch_width'); ca = col.append
 
         #nc_grpname = pnw.Select(name="nc group name", options=["/"])
-            
+
         # Get dataframe with dimesions.
         dims_df = self.ncfile.get_dims_dataframe(path="/")
         ca(dfc(dims_df))
@@ -511,7 +511,7 @@ class PanelWithElectronBands(AbipyParameterized):
     """
     Mixin class for panel object associated to AbiPy object providing an |ElectronBands| object.
 
-    Subclasses should implement `ebands` property 
+    Subclasses should implement `ebands` property
     """
 
     # Bands plot
@@ -554,7 +554,7 @@ class PanelWithElectronBands(AbipyParameterized):
             if self.set_fermie_to_vbm.value:
                 self.ebands.set_fermie_to_vbm()
 
-            fig1 = self.ebands.plot(e0="fermie", ylims=None, with_gaps=self.with_gaps.value, max_phfreq=None, 
+            fig1 = self.ebands.plot(e0="fermie", ylims=None, with_gaps=self.with_gaps.value, max_phfreq=None,
                                     fontsize=8, **self.mpl_kwargs)
 
             fig2 = self.ebands.kpoints.plot(**self.mpl_kwargs)

abipy/scripts/abicomp.py

@@ -971,7 +971,7 @@ codes), a looser tolerance of 0.1 (the value used in Materials Project) is often
             help="Used if --expose to iterate over figures. Expose all figures at once if not given on the CLI.")
     expose_parser.add_argument("-t", "--slide-timeout", type=int, default=None,
             help="Close figure after slide-timeout seconds (only if slide-mode). Block if not specified.")
-    expose_parser.add_argument("--plotly", default=False, action="store_true",
+    expose_parser.add_argument("-ply", "--plotly", default=False, action="store_true",
             help='Generate plotly plots in browser instead of matplotlib. WARNING: Not all the features are supported.')
     expose_parser.add_argument("-cs", "--chart-studio", default=False, action="store_true",
             help="Push figure to plotly chart studio ." +

abipy/scripts/abiopen.py

@@ -145,7 +145,7 @@ def get_parser(with_epilog=False):
         help=("Set matplotlib interactive backend. "
               "Possible values: GTKAgg, GTK3Agg, GTK, GTKCairo, GTK3Cairo, WXAgg, WX, TkAgg, Qt4Agg, Qt5Agg, macosx."
               "See also: https://matplotlib.org/faq/usage_faq.html#what-is-a-backend."))
-    parser.add_argument("--plotly", default=False, action="store_true",
+    parser.add_argument("-ply", "--plotly", default=False, action="store_true",
             help='Generate plotly plots in browser instead of matplotlib. WARNING: Not all the features are supported.')
     parser.add_argument("-cs", "--chart-studio", default=False, action="store_true",
             help="Push figure to plotly chart studio. " +

abipy/scripts/abiview.py

@@ -555,7 +555,7 @@ def get_parser(with_epilog=False):
 
     # Parent parser for commands supporting plotly plots
     plotly_parser = argparse.ArgumentParser(add_help=False)
-    plotly_parser.add_argument('--plotly', default=False, action="store_true",
+    plotly_parser.add_argument("-ply", '--plotly', default=False, action="store_true",
         help='Generate plotly plots in browser instead of matplotlib.')
     plotly_parser.add_argument("-cs", "--chart-studio", default=False, action="store_true",
         help="Push figure to plotly chart studio. " +

docs/_templates/layout.html

@@ -0,0 +1,7 @@
+{%- extends "!layout.html" %}
+
+{%- block scripts %}
+    <script type="text/javascript" src="https://cdn.plot.ly/plotly-latest.min.js"></script> 
+    {{ super() }}
+{%- endblock %}
+

docs/scripts/index.rst

@@ -6,17 +6,35 @@
 Scripts
 =======
 
-This page documents the usage of the AbiPy scripts, 
+This page documents the usage of the AbiPy scripts,
 the subcommands available and the options supported by each subcommand.
 
+To analyze the cystalline structure stored in FILE, use ``abistruct.py``.
+To operate on a **single** FILE, use ``abiopen.py``.
+To compare **multiple** FILES of the same type, use the ``abicomp.py`` script.
+If the analysis requires the execution of additional logic
+(e.g. the computation of phonons with anaddb from the DDB file), use ``abiview.py``.
+To generate a minimalist input file for Abinit, use ``abinp.py``.
+For a command line interface to the Abinit documentation, use ``abidoc.py``.
+
+Finally, use ``abicheck.py`` to validate your AbiPy + Abinit installation **before running** AbiPy flows
+and use ``abirun.py`` to launch Abinit calculations.
+
+.. important::
+
+    Each script provides a ``--help`` option that documents all the commands available
+    and provides a list of typical examples.
+    To list of the options supported by **COMMAND** use e.g. `abicomp.py COMMAND --help`.
+
+
 .. toctree::
    :maxdepth: 3
 
-   abicheck.rst
-   abicomp.rst
-   abidoc.rst
-   abinp.rst
-   abiopen.rst
-   abirun.rst
    abistruct.rst
+   abiopen.rst
+   abicomp.rst
    abiview.rst
+   abinp.rst
+   abidoc.rst
+   abicheck.rst
+   abirun.rst