CLI: add install --from-dir for sssp and pseudo-dojo

Our workaround for installing an "established" family like a `SsspFamily`
or `PseudoDojoFamily` required using the `install family` command, but
this is explicitly forbidden since we do not want the user to be able to
install an arbitrary set of pseudopotentials as one of these classes.
This means there is currently no way to install the archive and metadata
obtained with the `--download` option of the automated install commands.

Here, we add the `--from-dir` option to the automated install commands
to allow the user to install the downloaded pseudopotentials and set the
recommended cutoffs automatically for an `SsspFamily` or
`PseudoDojoFamily`.

aiida_pseudo/cli/install.py

@@ -167,9 +167,10 @@ def download_pseudo_dojo(
 @options.FUNCTIONAL(type=click.Choice(['PBE', 'PBEsol']), default='PBE', show_default=True)
 @options.PROTOCOL(type=click.Choice(['efficiency', 'precision']), default='efficiency', show_default=True)
 @options.DOWNLOAD_ONLY()
+@options.FROM_DIR()
 @options.TRACEBACK()
 @decorators.with_dbenv()
-def cmd_install_sssp(version, functional, protocol, download_only, traceback):
+def cmd_install_sssp(version, functional, protocol, download_only, from_dir, traceback):
     """Install an SSSP configuration.
 
     The SSSP configuration will be automatically downloaded from the Materials Cloud Archive entry to create a new
@@ -183,6 +184,11 @@ def cmd_install_sssp(version, functional, protocol, download_only, traceback):
     from aiida_pseudo.groups.family import SsspFamily
     from .utils import attempt, create_family_from_archive
 
+    if download_only and from_dir is not None:
+        raise click.BadParameter(
+            'cannot specify both `--download-only` and `--from-dir`.', param_hint="'--download-only' / '--from-dir'"
+        )
+
     configuration = SsspConfiguration(version, functional, protocol)
     label = SsspFamily.format_configuration_label(configuration)
     description = f'SSSP v{version} {functional} {protocol} installed with aiida-pseudo v{__version__}'
@@ -195,11 +201,16 @@ def cmd_install_sssp(version, functional, protocol, download_only, traceback):
 
     with tempfile.TemporaryDirectory() as dirpath:
 
-        dirpath = pathlib.Path(dirpath)
+        if from_dir is not None:
+            dirpath = pathlib.Path(from_dir).absolute()
+        else:
+            dirpath = pathlib.Path(dirpath)
+
         filepath_archive = dirpath / 'archive.tar.gz'
         filepath_metadata = dirpath / 'metadata.json'
 
-        download_sssp(configuration, filepath_archive, filepath_metadata, traceback)
+        if from_dir is None:
+            download_sssp(configuration, filepath_archive, filepath_metadata, traceback)
 
         description += f'\nArchive pseudos md5: {md5_file(filepath_archive)}'
         description += f'\nPseudo metadata md5: {md5_file(filepath_metadata)}'
@@ -246,10 +257,11 @@ def cmd_install_sssp(version, functional, protocol, download_only, traceback):
 @options.PSEUDO_FORMAT(type=click.Choice(['psp8', 'upf', 'psml', 'jthxml']), default='psp8', show_default=True)
 @options.DEFAULT_STRINGENCY(type=click.Choice(['low', 'normal', 'high']), default='normal', show_default=True)
 @options.DOWNLOAD_ONLY()
+@options.FROM_DIR()
 @options.TRACEBACK()
 @decorators.with_dbenv()
 def cmd_install_pseudo_dojo(
-    version, functional, relativistic, protocol, pseudo_format, default_stringency, download_only, traceback
+    version, functional, relativistic, protocol, pseudo_format, default_stringency, download_only, from_dir, traceback
 ):
     """Install a PseudoDojo configuration.
 
@@ -281,6 +293,11 @@ def cmd_install_pseudo_dojo(
     )
     # yapf: enable
 
+    if download_only and from_dir is not None:
+        raise click.BadParameter(
+            'cannot specify both `--download-only` and `--from-dir`.', param_hint="'--download-only' / '--from-dir'"
+        )
+
     try:
         pseudo_type = pseudo_type_mapping[pseudo_format]
     except KeyError:
@@ -298,11 +315,16 @@ def cmd_install_pseudo_dojo(
 
     with tempfile.TemporaryDirectory() as dirpath:
 
-        dirpath = pathlib.Path(dirpath)
+        if from_dir is not None:
+            dirpath = pathlib.Path(from_dir).absolute()
+        else:
+            dirpath = pathlib.Path(dirpath)
+
         filepath_archive = dirpath / 'archive.tgz'
         filepath_metadata = dirpath / 'metadata.tgz'
 
-        download_pseudo_dojo(configuration, filepath_archive, filepath_metadata, traceback)
+        if from_dir is None:
+            download_pseudo_dojo(configuration, filepath_archive, filepath_metadata, traceback)
 
         description += f'\nArchive pseudos md5: {md5_file(filepath_archive)}'
         description += f'\nPseudo metadata md5: {md5_file(filepath_metadata)}'

aiida_pseudo/cli/params/options.py

@@ -103,3 +103,12 @@
         'pseudopotential family.'
     )
 )
+
+FROM_DIR = OverridableOption(
+    '--from-dir',
+    type=click.STRING,
+    required=False,
+    default=None,
+    show_default=False,
+    help='Install the pseudpotential family from the archive and metadata downloaded with the `--download-only` option.'
+)

docs/source/_static/aiida-pseudo-custom.css

@@ -0,0 +1,3 @@
+.bigfont {
+    font-size: 140%;
+}

docs/source/conf.py

@@ -62,16 +62,21 @@
 #
 html_theme = 'sphinx_book_theme'
 html_static_path = ['_static']
-html_css_files = ['aiida-custom.css']
+html_css_files = [
+    'aiida-custom.css',
+    'aiida-pseudo-custom.css'
+]
 html_theme_options = {
     'home_page_in_toc': True,
     'repository_url': 'https://github.com/aiidateam/aiida-pseudo',
     'repository_branch': 'master',
     'use_repository_button': True,
     'use_issues_button': True,
+    'use_fullscreen_button': False,
     'path_to_docs': 'docs',
     'use_edit_page_button': True,
-    'extra_navbar': ''
+    'extra_navbar': '',
+    'extra_navbar': '<p>Made possible by the support of <a href="http://nccr-marvel.ch/" target="_blank"> NCCR MARVEL</a>, <a href="http://www.max-centre.eu/" target="_blank"> MaX CoE</a> and the <a href="https://www.materialscloud.org/swissuniversities" target="_blank"> swissuniversities P-5 project</a>.</p>'
 }
 html_domain_indices = True
 html_logo = '_static/logo.png'

docs/source/howto.rst

@@ -28,12 +28,16 @@ Similar to the `SSSP`_ pseudopotential family, the options can be used to set ve
 Moreover, the format of the pseudopotentials can be specified, as well as the default stringency.
 Use ``aiida-pseudo install pseudo-dojo --help`` for more information.
 
+.. note::
+
+    In case you are unable to use this command because of connection issues, please consult the :ref:`troubleshooting section <troubleshooting:automated-fail>`.
+
 .. _how-to:install_archive:
 
 Installing from archive or folder
 =================================
 
-In case the automated install commands fail, or the pseudopotential family you want to use is not supported, you can install the pseudopotential family manually with the following command:
+In case the pseudopotential family you want to use is not supported, you can install the pseudopotential family manually with the following command:
 
 .. code-block:: console
 
@@ -93,6 +97,7 @@ The available pseudopotential family classes can be listed with the command:
 .. important::
 
     The ``pseudo.family.sssp`` and ``pseudo.family.pseudo_dojo`` family types are blacklisted since they have their own :ref:`dedicated install commands <how-to:install_automated>` in ``aiida-pseudo install sssp`` and ``aiida-pseudo install pseudo-dojo``, respectively.
+    In case you are unable to use this command because of connection issues, please consult the :ref:`troubleshooting section <troubleshooting:automated-fail>`.
 
 Adding recommended cutoffs
 --------------------------

docs/source/index.rst

@@ -63,3 +63,47 @@ Contents
    cli
 
 .. _SSSP: https://www.materialscloud.org/discover/sssp/table/efficiency
+
+Acknowledgements
+================
+
+If you use this plugin and/or AiiDA for your research, please cite the following work:
+
+* Sebastiaan. P. Huber, Spyros Zoupanos, Martin Uhrin, Leopold Talirz, Leonid Kahle, Rico Häuselmann, Dominik Gresch, Tiziano Müller, Aliaksandr V. Yakutovich, Casper W. Andersen, Francisco F. Ramirez, Carl S. Adorf, Fernando Gargiulo, Snehal Kumbhar, Elsa Passaro, Conrad Johnston, Andrius Merkys, Andrea Cepellotti, Nicolas Mounet, Nicola Marzari, Boris Kozinsky, and Giovanni Pizzi, |AiiDA main paper|_, Scientific Data **7**, 300 (2020)
+
+* Martin Uhrin, Sebastiaan. P. Huber, Jusong Yu, Nicola Marzari, and Giovanni Pizzi, |AiiDA engine paper|_, Computational Materials Science **187**, 110086 (2021)
+
+.. rst-class:: bigfont
+
+    We acknowledge support from:
+
+.. list-table::
+    :widths: 60 40
+    :class: logo-table
+    :header-rows: 0
+
+    * - The `NCCR MARVEL`_ funded by the Swiss National Science Foundation.
+      - |marvel|
+    * - The EU Centre of Excellence "`MaX – Materials Design at the Exascale`_" (Horizon 2020 EINFRA-5, Grant No. 676598).
+      - |max|
+    * - The `swissuniversities P-5 project "Materials Cloud"`_.
+      - |swissuniversities|
+
+.. |marvel| image:: images/MARVEL.png
+    :width: 100%
+
+.. |max| image:: images/MaX.png
+    :width: 100%
+
+.. |swissuniversities| image:: images/swissuniversities.png
+    :width: 100%
+
+.. |AiiDA main paper| replace:: *AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance*
+.. _AiiDA main paper: https://doi.org/10.1038/s41597-020-00638-4
+
+.. |AiiDA engine paper| replace:: *Workflows in AiiDA: Engineering a high-throughput, event-based engine for robust and modular computational workflows*
+.. _AiiDA engine paper: https://doi.org/10.1016/j.commatsci.2020.110086
+
+.. _NCCR MARVEL: http://nccr-marvel.ch/
+.. _MaX – Materials Design at the Exascale: http://www.max-centre.eu/
+.. _`swissuniversities P-5 project "Materials Cloud"`: https://www.materialscloud.org/swissuniversities

docs/source/troubleshooting.rst

@@ -5,9 +5,16 @@
 Troubleshooting
 ###############
 
+.. _troubleshooting:automated-fail:
+
 The automated install commands fail
 ===================================
 
 These failures are often due to unstable internet connections causing the download of the pseudopotential archive from the web to fail.
-In this case, it is possible to install the family manually from an archive that is already available on the local file system.
-You can read more on this in the :ref:`how-to section <how-to:install_archive>`.
+In this case, it is possible to download the archive and metadata of the established family, transfer them to the machine where the pseudopotentials need to be installed and install from a directory.
+
+.. TODO: Complete this section once we're settled on the implementation.
+
+.. install the family manually from an archive that is already available on the local file system.
+
+.. we provide the ``--download-only`` option, as well as the ``--archive`` and ``--metadata`` options which both have to be specified to install the pseudopotential family.

setup.json

@@ -55,7 +55,7 @@
         "docs": [
             "sphinx~=3.2.1",
             "sphinx-copybutton~=0.3.0",
-            "sphinx-book-theme~=0.0.39",
+            "sphinx-book-theme~=0.1.0",
             "sphinx-autoapi~=1.8.1",
             "sphinx-click~=2.7.1"
         ]