QEApp Documentation

.readthedocs.yaml

@@ -0,0 +1,28 @@
+---
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+    os: ubuntu-22.04
+    tools:
+        python: '3.11'
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+    configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+        - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+rebuild:
+	@ make -s clean html

docs/requirements.in

@@ -0,0 +1,3 @@
+sphinx~=4.5.0
+sphinx-design~=0.4.1
+pydata-sphinx-theme==0.8.0

docs/requirements.txt

@@ -0,0 +1,61 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile docs/requirements.in
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.12.1
+    # via sphinx
+beautifulsoup4==4.12.2
+    # via pydata-sphinx-theme
+certifi==2023.5.7
+    # via requests
+charset-normalizer==3.1.0
+    # via requests
+docutils==0.17.1
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via sphinx
+markupsafe==2.1.3
+    # via jinja2
+packaging==23.1
+    # via sphinx
+pydata-sphinx-theme==0.8.0
+    # via -r docs/requirements.in
+pygments==2.15.1
+    # via sphinx
+requests==2.31.0
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.4.1
+    # via beautifulsoup4
+sphinx==4.5.0
+    # via
+    #   -r docs/requirements.in
+    #   pydata-sphinx-theme
+    #   sphinx-design
+sphinx-design==0.4.1
+    # via -r docs/requirements.in
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+urllib3==2.0.3
+    # via requests

docs/source/conf.py

@@ -0,0 +1,95 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+import time
+
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = "Quantum ESPRESSO App"
+copyright_first_year = "2023"
+copyright_owners = "The AiiDAlab Team"
+
+current_year = str(time.localtime().tm_year)
+copyright_year_string = (
+    current_year
+    if current_year == copyright_first_year
+    else f"{copyright_first_year}-{current_year}"
+)
+copyright = "{}, {}. All rights reserved".format(
+    copyright_year_string, copyright_owners
+)
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_design",
+]
+
+# The pydata-sphinx-theme already loads the bootstrap css.
+panels_add_bootstrap_css = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix of source filenames.
+source_suffix = ".rst"
+
+# The master toctree document.
+# ~ master_doc = 'index'
+master_doc = "index"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "pydata_sphinx_theme"
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "_static/images/full_logo.png"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# Define common links
+rst_epilog = """
+.. _AiiDA: https://www.aiida.net
+.. _AiiDAlab: https://www.aiidalab.net/
+.. _Quantum ESPRESSO: https://www.quantum-espresso.org/
+"""

docs/source/howto/import_structure.rst

@@ -0,0 +1,47 @@
+.. _import_structure:
+
+================
+Import structure
+================
+
+You can select a structure from four sources.
+
+- Upload file
+- OPTIMADE
+- AiiDA database
+- From Examples
+
+.. figure:: /_static/images/howto_select_structure.png
+   :width: 20cm
+
+
+Upload
+=======
+
+User can upload a structure file directly from the machine. The supported formats are listed in the https://wiki.fysik.dtu.dk/ase/ase/io/io.html#ase.io.read.
+
+From OPTIMADE
+=============
+`OPTIMADE`_ is a common REST API for accessing structural information of databases that contain calculated properties of existing and hypothetical materials. The OPTIMADE structure importer allows you to search for structures in the a wide range of databases (https://providers.optimade.org/) that support the OPTIMADE API.
+
+In order to select a compound from the OPTIMADE structure importer, you need to
+
+- select the `provider` from the dropdown menu
+- select a database for the selected provider (if there are multiple databases available)
+- enter the formula of the compound in the search field. Or, select the element from the periodic table.
+- click on the `Search` button
+- The importer will then search for the compound in the selected database and return a list of structures that match the search criteria. You can then select the structure you want to import from the list.
+
+AiiDA database
+==============
+
+Here you can select the structure in your AiiDA database.
+
+
+From Examples
+==============
+Here you can select the structure from the examples provided by the `Qeapp` for testing purposes.
+
+
+
+.. _OPTIMADE: https://www.optimade.org/

docs/source/howto/index.rst

@@ -0,0 +1,12 @@
+.. _howto:
+
+How-to guides
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   setup_computer_code
+   import_structure
+   upgrade_uninstall

docs/source/howto/setup_computer_code.rst

@@ -0,0 +1,78 @@
+.. _how_to_setup_computer_code:
+
+Setup remote computer/code
+==========================
+
+The instruction in collapsible text is for CSCS machine.
+
+Now you need set up a new computer (e.g., the CSCS Daint or Eiger machine if you have acount on it) and the codes on this newly setup computer (i.e., you need to tell AiiDA where the executables are, which modules to load etc.).
+
+.. note::
+
+   The widget to assist you in the computer/code setup is not very convinient for CSCS machines, because CSCS requires to specify the account and setting up a default one is not currently straightforward in AiiDA; we are working to improve this.
+
+
+**Setup new code**
+- Click the button `Setup new code`.
+- In the `Domain` field, please select `daint.cscs.ch`.
+- Click `Detailed Setup`, then it will show three steps:
+
+    - password-less SSH
+    - computer in AiiDA
+    - code in AiiDA
+
+**Set up password-less SSH connection**
+- In the `SSH username`, input your username for CSCS.
+- Click `Setup ssh`.
+- On the textbox above `Detailed Setup`, input your password, and click `Continue`.
+- Wait a few seconds, it will ask you to input your password again, and click `Continue`
+
+If you see a message as below:
+```
+30s timeout ...
+```
+Please click the `Setup ssh` button again and input the password.
+
+
+**Setup a computer in AiiDA**
+
+Click the button `Setup computer`, then add one line in the `Prepend text` to specify your account (it is the project account, such as `mr32` or `mrcloud`) at CSCS. Replace the `<account_name>` string with it!
+```
+#SBATCH --account=<account_name>
+```
+You can find further parameters in the screenshot below.
+
+.. figure:: /_static/images/setup_computer.png
+   :width: 12cm
+
+
+Click the button `test computer`, then wait 1 minute: you will see this log message if everything was setup correctly:
+
+.. code-block:: none
+
+   Report: Testing computer<daint-mc> for user<aiida@localhost>...
+   * Opening connection... [OK]
+   * Checking for spurious output... [OK]
+   * Getting number of jobs from scheduler... [OK]: 2255 jobs found in the queue
+   * Determining remote user name... [OK]: xingwang
+   * Creating and deleting temporary file... [OK]
+   Success: all 5 tests succeeded
+
+
+**Set up a code**
+
+In the field `Select computer`, please select the computer you just setup, in this case `daint-mc`. Check all other options, and then click the button `Setup code` to setup the `pw.x` code.
+
+.. figure:: /_static/images/setup_code.png
+   :width: 12cm
+
+Similarly, setup the `dos.x` and `projwfc.x` codes, needed by the app to compute DOS and PDOS. You can skip the computer setup step, since it needs to be done only once per comouter, and go to `Set up a code in AiiDA` directly to setup the remaining codes.
+
+After you finishing the codes setup, you can launch a new calculation with the newly setup codes, that should be called:
+
+- pw-7.0@daint-mc
+- dos-7.0@daint-mc
+- projwfc-7.0@daint-mc
+
+.. figure:: /_static/images/select_new_code.png
+   :width: 12cm