From 74a7479a146d90ac4e9eac33175e9d6a48b8b9d9 Mon Sep 17 00:00:00 2001 From: Jusong Yu Date: Wed, 15 Nov 2023 17:35:41 +0100 Subject: [PATCH] Using mkdocs for doc (#232) --- .readthedocs.yml | 23 ++- README.md | 162 +---------------- docs/Makefile | 41 ----- .../_static/logo.png => assets/favicon.png} | Bin docs/assets/logo.png | Bin 0 -> 24514 bytes docs/gui.md | 3 + docs/index.md | 65 +++++++ docs/requirements.txt | 1 + docs/source/conf.py | 94 ---------- docs/source/developer_guide/index.rst | 96 ---------- docs/source/index.rst | 46 ----- docs/source/rtd_settings.py | 89 ---------- docs/source/user_guide/get_started.rst | 82 --------- docs/source/user_guide/index.rst | 9 - docs/source/user_guide/tutorial.rst | 76 -------- docs/spec.md | 167 ++++++++++++++++++ mkdocs.yml | 9 + 17 files changed, 263 insertions(+), 700 deletions(-) delete mode 100755 docs/Makefile rename docs/{source/_static/logo.png => assets/favicon.png} (100%) create mode 100644 docs/assets/logo.png create mode 100644 docs/gui.md create mode 100644 docs/index.md create mode 100644 docs/requirements.txt delete mode 100755 docs/source/conf.py delete mode 100644 docs/source/developer_guide/index.rst delete mode 100755 docs/source/index.rst delete mode 100644 docs/source/rtd_settings.py delete mode 100644 docs/source/user_guide/get_started.rst delete mode 100644 docs/source/user_guide/index.rst delete mode 100644 docs/source/user_guide/tutorial.rst create mode 100644 docs/spec.md create mode 100644 mkdocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml index 8596b34a..c5587fb2 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,10 +1,19 @@ ---- +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required version: 2 +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +mkdocs: + configuration: mkdocs.yml + +# Optionally declare the Python requirements required to build your docs python: - version: 3.7 - install: - - method: pip - path: . - extra_requirements: - - docs + install: + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index 4008fa20..9e058760 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,6 @@ -# aiida-sssp-workflow +# SSSP workflow -## Initial dual (E_rho/E_wfc) for convergence test - -For NC psp we use dual start from 4, PAW/US use dual from 8 for most of elements but 18 for high dual elements which we found usually high charge density cutoff are needed. -They are O,Fe,Hf, Mn, Co, Ni, Cr. - -## Logic of convergence test on different criteria protocol - -The wavefunction cutoff scan list are same no matter which criteria protocol is used. -Therefore, the running of wavefunction cutoff test write wavefunction cutoff recommendation for all criteria protocol. -When switching to other criteria protocol, the wavefunction cutoff test can be skipped by setting `preset_ecutwfc`. It will then be used and only run charge density cutoff test. -This is not conflict with the caching workflow, since caching workflow will only run on wfc test the results is that for caching workflow when `preset_ecutwfc` is set, only reference calculation is run. - -## Lanthanides - -For lanthanides the precision measure is run on nitrides as Wentzcovitch paper and on oxides. -The unaries are not run for precision measurement since it is know that the oxidation state of lanthanides pseudopotentials is not zero. -Only for lanthanide nitrides the magnatization is on. -It is mostly because the reference of RE-N (Wentzcovitch) and RE-O (ACWF) is run with/without magnatization. -The kpoint distance of lanthanide nitrides is hard code to `0.2` (both for precision measure, for delta convergence and first EOS reference calculation of pressure convergence test as well. implemented as `+ 0.1` of precision protocol and `+ 0.05` of convergence protocol from acwf value) using the tetrahedron method rather than as acwf protocol where kpoint distance is `0.10` with fermi-dirac smearing, in order to compatible with Wentzcovitch paper results. -Lanthanide nitrides such as ErN, in equation of state calculation, large (0.06) volume change lead to supurious energy. -To mitigate the issue, the `scale_increment` is set to 0.01 (??? probably only for Er?) to make sure the volume change is in the parabolic range. -The nitrogen pseudopotential is the one from first run on pseudopotentials verifications on nitrigen on libraries include Pslibrary 0.1, Pslibrary 1.0.0, pseudo-dojo, ONCVPSP with legacy sg15 inputs... (Run and check) -The lanthanides have convergence issue if mixing is too large or number of bands is not enough. -For bands measure, the `nbnd_factor` is set to `2.0` while for precision measure and convergence the factor is set to `1.5`. -The mixing is set to 0.5 (default is 0.7 for non-lanthanides), and even smaller for atomic calculation of lanthanides elements which set to 0.3. -The `nbnd` set for lanthanides oxides are set to `1.5` times of the default number of bands since it also has issue that highest bands partially occupied and often retrigger the error handler to restart the calculation. - -## Criteria and protocol of pressure convergence - -Since the magnitude of pressure (P = 1/3 Tr(sigma)) directly output from DFT calcultion depends on the stiffness of the material strongly. -We convert it into an equivalent volume. -This what we call it residual volume is therefore a stiffness-agnostic value that can be used to set criteria for all elements. - -## Delta & nu metric in precision and convergence verificaiton - -In convergence delta factor calculation, the GS configurations from Cottiner's paper are used. -To have a uniform sence of precision through looking at delta factor, the value is defined as delta factor per atom. -However, since it is hard to define delta per/atom for oxides, ACWF does not use per/atom value to represent results. -It uses the nu factor which was defined in the ACWF paper. - -For the oxides, it needs oxygen pseudopotential first, same as nitrides. -The verification needs to run for all know oxygen/nitrigen pseudopotentials filst. However, the cutoffs of them are not known and the cutoffs are input for the precision measure. -So the very first run is the convergence test on all oxygen/nitrigen pseudopotentials. -Once the recommended cutoffs are known, the precision measure can be run for all oxygen/nitrigen elements. - -In the convergence verification, there are many options to choose from for what configuration to use. But it is redundant to use all of them, we what the configuration that gives the largest recommended cutoff energy for the pseudopotential. -After tests (show test results, which in `sssp-verify-scripts`), we found that the for non-magnetic elements, the Diamond configuration that gives the largest cutoff energy. For magnetic elements, the GS configuration calculation with magnetization turned on for the bulk (in cohesive energy which usually give the largest recommended cutoff, where the atomic calculation still don't have magnetization turned on and it is not needed because the pseudopotential is generated in the close shell approximiation (??)) that gives the largest cutoff energy. - -## Phonon frequencies specification - -For some elements, we have neglected the first n frequencies in the summation above, because the frequencies are negative and/or with strong oscillations as function of the cutoff for all the considered pseudos). We have neglected the first 4 frequencies for H and I, 12 for N and Cl, 6 for O and ??SiF4 (which replaces F)??. -## bands distance compare specification - -### bands distance of magnetic structures - -The bands of magnetic structure has one more dimension to distinguish up and down spins. -In bands distance comparing, I simply reduce the array along the last axis e.g. does not distinguish the spins but -merge eigenvalues (sorted) of the same kpoints. - -### bands distance protocol specifications - -There are three kinds of kpoint distance (`kpoints_distance_scf`, `kpoints_distance_bands` and `kpoints_distance_band_strcuture` respectively) for bands measure workflow and two for bands distance convergence workflow where the band structure is not calculated in convergence verification. - -In the production protocol, `kpoints_distance_scf` and `kpoints_distance_bands` are set to `0.15`. -We choose a uniform k-grid for bands distance comparison, -in the full Brillouin zone and with symmetry reduction which not implemented in previous version. -After applying symmetry reduction, it is able to compute with more dense grids. -Because, choosing a high-symmetry path could result in an unsatisfactory arbitrary choice, -as different recipes for the standardisation of paths have been introduced in the recent literature and interesting features of the band structure may occur far from the high-symmetry lines (such as Weyl points). -A uniform mesh is also more appropriate from the point of view of electron’s nearsightedness -if the energy eigenvalues are known on a sufficiently fine uniform k-points mesh, -it is possible to get an exact real-space representation of the Hamiltonian in a Wannier function basis and then interpolate to an arbitrary fine mesh. - -## Parameters of protocol - -### Specific parameters for magnetic elements - -For atomic energy calculated for cohesive energy, it is hard to converge for magnetic elements with untreated parameters. -The following extra parameters are added for the calculation: - -``` -"SYSTEM": { - "nspin": 2, - "starting_magnetization": { - self.ctx.element: 0.5, - }, -}, -"ELECTRONS": { - "diagonalization": 'cg', - "mixing_beta": 0.5, - "electron_maxstep": 200, -}, -``` - -## Resource options and parallelization - -## parallelization for atomic calculation - -In case of atomic calculation running on a machine with too many CPUs, -the `npool` and `ndiag` is explicitly set to 1 for atomic calculation. -Since there is only one kpoint in atomic case, there is no efficient lost of this parallelization setting. - -Because using too many `mpiprocs` (128 in EIGER) in atomic calculation would cause spurious issue the calculation terminate and not being handled. -The maximum number of mpiprocs is set to `32`. - -### Walltime settings - -The max wallclock seconds are set from the `options` input parameters from verification workflow. -This option will then pass to all the inside pw and ph calculation process as the `metadata.options` setting. -The `options` dict has the format of: - -```python -{ - "resources": { - "num_machines": 1, - "num_mpiprocs_per_machine": 36, - }, - "max_wallclock_seconds": 1800, # 30 min - "withmpi": True, -} - -``` -where the `max_wallclock_seconds` is exactly used for pw calculation while for ph calculation the value is set to 4 times of value since the ph calculation roughly estimated to elapse 4 times slower that pw calculation of the corresponding pw calculation to finish. -For atomic calculation in cohesive energy evaluation of lanthanides, the `max_wallclock_seconds` also set to 4 times otherwise it may not finished after 5 times of restart. - - -## Configurations - -Different verifications use different structure configurations. -For all precision measure verification, the configurations are all compatible with the ACWF. -While for bands measure and convergence workflow, the configurations used are set in file `statics/cif/mapping.json`. -The principles are for bands measure, using the configurations from Cottiner's paper since they are the groud state structures exist in real wolrd. -And for lanthanoids using the Nitrides from Wenzowitch paper for bands measure and convergence otherwise hard to converge in scf calculation. - -But the structures used for convergence verfication are varias. -The lanthanides still using the nitrides from Wenzovitch paper. -We keep on using GS nature configuration from Cottiner's paper, but convert them to primitive with pymatgen (for magnetic elements, no primitive convert process but still refine with `pymatgen`). -Maybe the flourine (F) still have thekproblem mentioned in legacy SSSP that hard to convergence (SCF convergence), will rollback to use SiF4 for it. - -## Work chains clean policy - -It is very delegate of how to set the remote folder clean in pseudopotential verification, since the verification consist of workflows with lots of sub processes and create huge amount of remote files, although the single calculations are small and resource non-stringent. -If the work chains are not cleaned, the number of remote files will increase rapidly and disk quota in remote machine will soon being run out. -On the contrast, if clean too early would make caching machanism not used and therefore waste resource for same calculations. -To trait off above two side of contradiction, the clean policy is designed as: -- set to the precision measures are cleaned right after its workchain are finished. -- set to clean remote workdir right after the evaluate work chains, but only clean calcjobs that are not cached from. Since (see [#150](https://github.com/aiidateam/aiida-sssp-workflow/pull/150) for detail) cached calcjob node share remote path with its nonmenon, the nonmenon nodes by `_caching` should clean itself in the last. -- set calcjob nodes of `_caching` work chain to be cleaned only by calling from verefication work chain in its terminate step rather than do itself. -For other convergence work chain, they used nodes cached from `_caching` workchain and will clean themself right after it is finished. -The nodes create from other cached nodes (which have `_aiida_cached_from` extra attributes) from convergence work chain never used for furthur caching except for testing mode. - -This partially solve the caching issue of bands calculation ([issue #138](https://github.com/aiidateam/aiida-sssp-workflow/issues/138). -But same as ph.x calculation, is subsequent step failed and previous step cleaned, it will still failed to continue. -In phonon, the workaround is to check if the remote folder is empty. -This has the expense of even the ph.x calculation finished ok, the previous step clean will force the scf prepare calculation to run again so to sure the ph.x get its parent_folder not empty. -Also implemented in [#150](https://github.com/aiidateam/aiida-sssp-workflow/pull/150), the force running of `_caching` workflow is applied. To make sure the second run of phonon_frequencies and bands convergence workflow will use the `parant_folder` that are not empty. The expense of such strategy is the `_caching` always need to be run for second run of verification, but since in principle not always to run second time and it bring huge advantage to make the second run more robust. - -The clean policy of big verification work chain is controlled by `test_mode`. -It will do clean as described above or do not clean anything so it can be checked afterwards. +[![Documentation Status](https://readthedocs.org/projects/aiida-sssp-workflow/badge/?version=latest)](https://aiida-sssp-workflow.readthedocs.io/en/latest/?badge=latest) ## For maintainers diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100755 index 218b9cf4..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,41 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault - -## Runs with nitty-pick and converting warnings into errors to -## make sure the documentation is properly written -customdefault: - $(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html - -all: html - -clean: - rm -r $(BUILDDIR) - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - - -view: - xdg-open $(BUILDDIR)/html/index.html diff --git a/docs/source/_static/logo.png b/docs/assets/favicon.png similarity index 100% rename from docs/source/_static/logo.png rename to docs/assets/favicon.png diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..8313201f46cabc75409a9da365e8b49062c08c73 GIT binary patch literal 24514 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 U&L)QKy?swpRad22$>z=f0GS!kA^-pY literal 0 HcmV?d00001 diff --git a/docs/gui.md b/docs/gui.md new file mode 100644 index 00000000..7009e838 --- /dev/null +++ b/docs/gui.md @@ -0,0 +1,3 @@ +# AiiDAlab SSSP app + +The [`aiidalab-sssp` app](https://github.com/aiidalab/aiidalab-sssp) based ond the [AiiDAlab](https://aiidalab.net/) provides a user-friendly interface to the SSSP libraries and the verification workflows. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..611f9715 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,65 @@ +# Introduction + +This is the documentation for the `aiida-sssp-workflow` plugin and `aiidalab-sssp` AiiDAlab app. +The solid-state pseudopotential (SSSP) libraries are collections of pseudopotentials for solid-state calculations. + +The pseudopotentials of the SSSP libraries are carefully validated and optimized to ensure transferability and precision by using the automated verification workflows through the workflow engine [AiiDA](https://aiida.net/) by `aiida-sssp-workflow` plugin. + +The `aiidalab-sssp` app based ond the [AiiDAlab](https://aiidalab.net/) provides a user-friendly interface to the SSSP libraries and the verification workflows. + +The workflows contains the verification of transferability (precision) and softness of the pseudopotentials. +The precision of the pseudopotentials are measured by comparing the EOS of the solid-state calculation with the all-electron calculation. + +The workflows run verification for pseudopotential convergence are for: + + * Delta factor: + * Cohesive energy: + * Phonon frequencies: + * Bands distance: + * Residual pressure: reflect the precision and the softness of the given pseudopotential. + +## Quick start + +The verification can be run and inspected by plugin through the command line interface (CLI) or the AiiDAlab app (Go to [GUI App](gui/) for more information). + +To run through CLI we provide a docker image to setup working environment without installing the plugin and AiiDA. + +First, you need to [install Docker on your workstation or laptop](https://docs.docker.com/get-docker/). + +If you are using Linux or MacOS, you can run the following command to run the workflow: + +```bash +docker run -it ghcr.io/unkcpz/aiida-sssp-workflow:edge bash +``` + +If you are using Windows, open the Docker desktop and search for the `aiida-sssp-workflow` image to start the container, then go to "Exec" tab to open a terminal. + +Then you can run the following command to run the workflow: + +```bash +wget -c https://raw.githubusercontent.com/unkcpz/sssp-verify-scripts/main/libraries-pbe/PAW-PSL1.0.0-high/Si.paw.z_4.ld1.psl.v1.0.0-high.upfwget -c +aiida-sssp-workflow launch --property convergence --pw-code pw-7.2@localhost --ph-code ph-7.2@localhost --protocol test --cutoff-control test --criteria efficiency --withmpi True --num-mpiprocs 2 --npool 1 -- Si.paw.z_4.ld1.psl.v1.0.0-high.upf +``` + +The workflow is run with the Quantum ESPRESSO codes installed in the docker image. +Since the verfication requires a lot of calculations, it is recommended to setup and configure codes on a remote cluster. See AiiDA documentation on [how to run external codes](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html) for more information. + +To run the convergence workflow change the `--property` option to `convergence`, the option accept multiple values to run on multiple properties. +For example, to run the convergence workflow for cohesive energy and phonon frequencies: + +```bash +aiida-sssp-workflow launch --property convergence.phonon_frequencies --property convergence.cohesive_energy --pw-code pw-7.2@localhost --ph-code ph-7.2@localhost --protocol test --cutoff-control test --criteria efficiency --withmpi True -- Si.paw.z_4.ld1.psl.v1.0.0-high.upf +``` + +Please run `aiida-sssp-workflow launch --help` for more information about the command line interface. + +The verification workflows has its node pk as the label, you can use `verdi process list -a -L VerificationWorkChain` to check the status of the workflow. + +The outputs can be inspected by generating the report and summary PDF files by run: + +```bash +aiida-sssp-workflow inspect +``` + +You can use `-o` option to specify the output name. +See `aiida-sssp-workflow inspect --help` for more information. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..d9e9707d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs-material~=9.4 diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100755 index 0c534836..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,94 +0,0 @@ -# -*- coding: utf-8 -*- -# 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 - -from reentry import manager - -manager.scan() - -# -- 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 - -sys.path.insert(0, os.path.abspath("../../")) - -import aiida_sssp_workflow - -# -- Project information ----------------------------------------------------- - -project = "aiida-sssp-workflow" -copyright = "2020-2021, ECOLE POLYTECHNIQUE FEDERALE DE LAUSANNE (Theory and Simulation of Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)), Switzerland" -release = aiida_sssp_workflow.__version__ - -# -- 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_copybutton", - "autoapi.extension", - "sphinx_click", - "sphinx.ext.intersphinx", -] - -# Settings for the `sphinx_copybutton` extension -copybutton_selector = "div:not(.no-copy)>div.highlight pre" -copybutton_prompt_text = ( - r">>> |\.\.\. |(?:\(.*\) )?\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " -) -copybutton_prompt_is_regexp = True - -# Settings for the `autoapi` extension -autoapi_dirs = ["../../aiida_sssp_workflow"] -autoapi_ignore = ["*cli*"] - -# Settings for the `sphinx.ext.intersphinx` extension -intersphinx_mapping = { - "aiida": ("http://aiida_core.readthedocs.io/en/latest/", None), -} - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# 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 = "sphinx_book_theme" -html_static_path = ["_static"] -html_css_files = [] -html_theme_options = { - "home_page_in_toc": True, - "repository_url": "https://github.com/aiidateam/aiida-sssp-workflow", - "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": '

Made possible by the support of NCCR MARVEL, MaX CoE and the swissuniversities P-5 project.

', -} -html_domain_indices = True -html_logo = "_static/logo.png" - -# Warnings to ignore when using the -n (nitpicky) option -nitpick_ignore = [ - ("py:class", "logging.Logger"), - ("py:obj", "aiida_optimize.engines.base.OptimizationEngineWrapper"), -] diff --git a/docs/source/developer_guide/index.rst b/docs/source/developer_guide/index.rst deleted file mode 100644 index 1ad8b990..00000000 --- a/docs/source/developer_guide/index.rst +++ /dev/null @@ -1,96 +0,0 @@ -=============== -Developer guide -=============== - -Running the tests -+++++++++++++++++ - -The following will discover and run all unit test:: - - pip install -e .[testing] - pytest -v - -Automatic coding style checks -+++++++++++++++++++++++++++++ - -Enable enable automatic checks of code sanity and coding style:: - - pip install -e .[pre-commit] - pre-commit install - -After this, the `yapf `_ formatter, -the `pylint `_ linter -and the `prospector `_ code analyzer will -run at every commit. - -If you ever need to skip these pre-commit hooks, just use:: - - git commit -n - - -Continuous integration -++++++++++++++++++++++ - -``aiida-sssp-workflow`` comes with a ``.github`` folder that contains continuous integration tests on every commit using `GitHub Actions `_. It will: - -#. run all tests for the ``django`` ORM -#. build the documentation -#. check coding style and version number (not required to pass by default) - -Building the documentation -++++++++++++++++++++++++++ - - #. Install the ``docs`` extra:: - - pip install -e .[docs] - - #. Edit the individual documentation pages:: - - docs/source/index.rst - docs/source/developer_guide/index.rst - docs/source/user_guide/index.rst - docs/source/user_guide/get_started.rst - docs/source/user_guide/tutorial.rst - - #. Use `Sphinx`_ to generate the html documentation:: - - cd docs - make - -Check the result by opening ``build/html/index.html`` in your browser. - -Publishing the documentation -++++++++++++++++++++++++++++ - -Once you're happy with your documentation, it's easy to host it online on ReadTheDocs_: - - #. Create an account on ReadTheDocs_ - - #. Import your ``aiida-sssp-workflow`` repository (preferably using ``aiida-sssp-workflow`` as the project name) - -The documentation is now available at `aiida-sssp-workflow.readthedocs.io `_. - -PyPI release -++++++++++++ - -Your plugin is ready to be uploaded to the `Python Package Index `_. -Just register for an account and:: - - pip install twine - python setup.py sdist bdist_wheel - twine upload dist/* - -After this, you (and everyone else) should be able to:: - - pip install aiida-sssp-workflow - -You can also enable *automatic* deployment of git tags to the python package index: -simply generate a `PyPI API token `_ for your PyPI account and add it as a secret to your GitHub repository under the name ``pypi_token`` (Go to Settings -> Secrets). - -.. note:: - - When updating the plugin package to a new version, remember to update the version number both in ``setup.json`` and ``aiida_sssp_workflow/__init__.py``. - - -.. _ReadTheDocs: https://readthedocs.org/ -.. _Sphinx: https://www.sphinx-doc.org/en/master/ diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100755 index 16c85661..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. figure:: _static/logo.png - :width: 1600px - :align: left - -The aiida-sssp-workflow plugin for `AiiDA`_ -===================================================== - -``aiida-sssp-workflow`` is available at http://github.com/aiidateam/aiida-sssp-workflow - - -.. toctree:: - :maxdepth: 2 - - user_guide/index - developer_guide/index - API documentation - -If you use this plugin for your research, please cite the following work: - -.. highlights:: SSSP: G. Prandini, A. Marrazzo, I. E. Castelli, N. Mounet and N. - Marzari, npj Computational Materials 4, 72 (2018); - https://www.nature.com/articles/s41524-018-0127-2 - -.. highlights:: K. Lejaeghere et al., Science 351 (6280), 1415 (2016). - http://molmod.ugent.be/deltacodesdft - -If you use AiiDA for your research, please cite the following work: - -.. highlights:: Giovanni Pizzi, Andrea Cepellotti, Riccardo Sabatini, Nicola Marzari, - and Boris Kozinsky, *AiiDA: automated interactive infrastructure and database - for computational science*, Comp. Mat. Sci 111, 218-230 (2016); - https://doi.org/10.1016/j.commatsci.2015.09.013; http://www.aiida.net. - -``aiida-sssp-workflow`` is released under the MIT license. - -Please contact morty.yeu@gmail.com for information concerning ``aiida-sssp-workflow`` and the `AiiDA mailing list `_ for questions concerning ``aiida``. - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - -.. _AiiDA: http://www.aiida.net diff --git a/docs/source/rtd_settings.py b/docs/source/rtd_settings.py deleted file mode 100644 index ced6a0a7..00000000 --- a/docs/source/rtd_settings.py +++ /dev/null @@ -1,89 +0,0 @@ -# -*- coding: utf-8 -*- -########################################################################### -# Copyright (c), The AiiDA team. All rights reserved. # -# This file is part of the AiiDA code. # -# # -# The code is hosted on GitHub at https://github.com/aiidateam/aiida_core # -# For further information on the license, see the LICENSE.txt file # -# For further information please visit http://www.aiida.net # -########################################################################### -""" -This is a mock of a django settings to make the documentation compile without the call to load_dbenv() - -For more information on this file, see -https://docs.djangoproject.com/en/1.7/topics/settings/ - -For the full list of settings and their values, see -https://docs.djangoproject.com/en/1.7/ref/settings/ -""" - -# Build paths inside the project like this: os.path.join(BASE_DIR, ...) -import os - -BASE_DIR = os.path.dirname(os.path.dirname(__file__)) - -# Quick-start development settings - unsuitable for production -# See https://docs.djangoproject.com/en/1.7/howto/deployment/checklist/ - -# SECURITY WARNING: keep the secret key used in production secret! -SECRET_KEY = "qv*h$2ndwg)mhy)vf%+8t(v654%)u&vt4+w-&dw!ac$0#ck(7&" # noqa - -# SECURITY WARNING: don't run with debug turned on in production! -DEBUG = True - -TEMPLATE_DEBUG = True - -ALLOWED_HOSTS = [] - -# Application definition - -INSTALLED_APPS = ( - "django.contrib.admin", - "django.contrib.auth", - "django.contrib.contenttypes", - "django.contrib.sessions", - "django.contrib.messages", - "django.contrib.staticfiles", -) - -MIDDLEWARE_CLASSES = ( - "django.contrib.sessions.middleware.SessionMiddleware", - "django.middleware.common.CommonMiddleware", - "django.middleware.csrf.CsrfViewMiddleware", - "django.contrib.auth.middleware.AuthenticationMiddleware", - "django.contrib.auth.middleware.SessionAuthenticationMiddleware", - "django.contrib.messages.middleware.MessageMiddleware", - "django.middleware.clickjacking.XFrameOptionsMiddleware", -) - -ROOT_URLCONF = "pippo.urls" - -WSGI_APPLICATION = "pippo.wsgi.application" - -# Database -# https://docs.djangoproject.com/en/1.7/ref/settings/#databases - -DATABASES = { - "default": { - "ENGINE": "django.db.backends.sqlite3", - "NAME": ":memory:", - } -} - -# Internationalization -# https://docs.djangoproject.com/en/1.7/topics/i18n/ - -LANGUAGE_CODE = "en-us" - -TIME_ZONE = "UTC" - -USE_I18N = True - -USE_L10N = True - -USE_TZ = True - -# Static files (CSS, JavaScript, Images) -# https://docs.djangoproject.com/en/1.7/howto/static-files/ - -STATIC_URL = "/static/" diff --git a/docs/source/user_guide/get_started.rst b/docs/source/user_guide/get_started.rst deleted file mode 100644 index 4594874a..00000000 --- a/docs/source/user_guide/get_started.rst +++ /dev/null @@ -1,82 +0,0 @@ -=============== -Getting started -=============== - -``aiida-sssp-workflow`` is an AiiDA plugin contains workflows to running pseudopotential verification. -It runs delta factor calculation and convergence testes on cohesive energy, phonon frequencies, bands distance and -residual pressure, which reflect the precision and the softness of the given pseudopotential. - -Installation -++++++++++++ - -Use the following commands to install the plugin for developing:: - - git clone https://github.com/aiidateam/aiida-sssp-workflow . - cd aiida-sssp-workflow - pip install -e . # also installs aiida, if missing (but not postgres) - #pip install -e .[pre-commit,testing] # install extras for more features - verdi quicksetup # better to set up a new profile - verdi calculation plugins # should now show your calclulation plugins - -Or you can install it from pypi by:: - - pip install aiida-sssp-workflow - -To use this plugin you show have ``aiida-quantumespresso`` plugin installed and configure -codes for ``quantumespresso.pw`` and ``quantumespresso.ph``. - -Add the following line into activate script file to enable the autocompletiom of -cammand line interface:: - - eval "$(_AIIDA_SSSP_WORKFLOW_COMPLETE=source aiida-sssp-workflow)" - -Moreover, enable the caching_ of ``quantumespresso.pw`` and ``quantumespresso.ph`` can -save time and computational resource in running the verification. - -.. _caching: https://aiida.readthedocs.io/projects/aiida-core/en/latest/topics/provenance/caching.html - -Usage -+++++ - -A quick demo of how to submit a verification through command line:: - - verdi daemon start # make sure the daemon is running - aiida-sssp-workflow workflow launch verification -w 5400 -X qe-6.5-pw@daint-mc -Y qe-6.5-ph@daint-mc -D 4 ../psp/sg15/Si_ONCV_PBE-1.2.upf --daemon - -The options of ``aiida-sssp-workflow workflow launch verification`` are:: - - Usage: aiida-sssp-workflow workflow launch verification [OPTIONS] PSEUDO - - Run the workflow to calculate delta factor - - Options: - -X, --pw-code CODE A single code identified by its ID, UUID or - label. [required] - - -Y, --ph-code CODE A single code identified by its ID, UUID or - label. [required] - - -P, --protocol TEXT The protocol used in verification. - [default: acwf] - - -D, --dual INTEGER The dual between ecutwfc and ecutrho. - [default: 8] - - -x, --clean-workdir Clean the remote folder of all the launched - calculations after completion of the - workchain. [default: False] - - -m, --max-num-machines INTEGER The maximum number of machines (nodes) to - use for the calculations. [default: 1] - - -w, --max-wallclock-seconds INTEGER - the maximum wallclock time in seconds to set - for the calculations. [default: 1800] - - -i, --with-mpi Run the calculations with MPI enabled. - [default: True] - - -d, --daemon Submit the process to the daemon instead of - running it locally. [default: False] - - -h, --help Show this message and exit. diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst deleted file mode 100644 index 9ae5135d..00000000 --- a/docs/source/user_guide/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -========== -User guide -========== - -.. toctree:: - :maxdepth: 3 - - get_started - tutorial diff --git a/docs/source/user_guide/tutorial.rst b/docs/source/user_guide/tutorial.rst deleted file mode 100644 index 9358d673..00000000 --- a/docs/source/user_guide/tutorial.rst +++ /dev/null @@ -1,76 +0,0 @@ -======== -Tutorial -======== - -Running verification workflows for a given pseudopotential. The complete verification -workflow contain a delta factor calculation, a band structure calculation and -convergence tests for cohesive energy, phonon frequencies, bands distance and residual -pressure. - -The required inputs of the verification workflows are ``pw_code`` for -``quantumespresso.pw`` code node, -``ph_code`` for ``quantumespresso.ph`` code node -and ``pseudo`` for a ``UpfData`` node which can be imported by:: - - verdi data upf import - -The delta factor workflow and four convergence workflow are also included in -the ``aiida.workflow`` entry point. Their minimal required inputs are the same -the codes and the pseudopotential upf node. Except for pressure convergence -workflow which need Birch-Murnaghan fit result the V0, B0, B1 as an additional -required input to calculate the residual pressure(TODO: link to the definition). - -The others common optional inputs for convergence workflows are 1) the list of energy cutoff of -wavefunction ``ecutwfc_list`` 2) the list energy cutoff of charge density ``ecutrho_list`` -3) ``ref_cutoff_pair`` which set the wavefunction cutoff and density charge cutoff used -as the reference quantum-espresso pw.x inputs. - -The outputs of every subworkflow are included as specific output namespace of the -verification workflow. -If all subworkflows are running successful and all the convergence -are reached within the pre-setting energy cutoff list the outputs would be the following:: - - Outputs PK Type - --------------------------------- ----- --------- - band_structure - seekpath_band_structure - scf_parameters 27250 Dict - band_parameters 27372 Dict - band_structure 27370 BandsData - scf_parameters 26971 Dict - band_parameters 27039 Dict - band_structure 27037 BandsData - nbands_factor 27410 Float - convergence_bands - output_pseudo_header 26862 Dict - output_convergence_parameters 27505 Dict - xy_data_ecutwfc 27506 XyData - xy_data_ecutrho 27507 XyData - output_parameters 27508 Dict - convergence_cohesive_energy - output_pseudo_header 27813 Dict - output_convergence_parameters 28112 Dict - xy_data_ecutwfc 28113 XyData - xy_data_ecutrho 28114 XyData - output_parameters 28115 Dict - convergence_phonon_frequencies - output_pseudo_header 26860 Dict - output_convergence_parameters 27805 Dict - xy_data_ecutwfc 27806 XyData - xy_data_ecutrho 27807 XyData - output_parameters 27808 Dict - convergence_pressure - output_pseudo_header 27815 Dict - output_convergence_parameters 28108 Dict - xy_data_ecutwfc 28109 XyData - xy_data_ecutrho 28110 XyData - output_parameters 28111 Dict - delta_measure - output_pseudo_header 26858 Dict - output_eos_parameters 27143 Dict - output_birch_murnaghan_fit 27242 Dict - output_parameters 27208 Dict - -Otherwise, if some of the convergence workflow not converged, the ``output_convergence_parameters`` will not been given. Or if some subworkflow -not finished ok with exit code 0, you will not see its outputs in the output namespace -of verification workflow. diff --git a/docs/spec.md b/docs/spec.md new file mode 100644 index 00000000..9fb8ee3b --- /dev/null +++ b/docs/spec.md @@ -0,0 +1,167 @@ +# Verification protocol + +(TODO: moved from README.md, need to be updated) + +This document describes the verification protocol of the SSSP workflow. + +## Initial dual (E_rho/E_wfc) for convergence test + +For NC psp we use dual start from 4, PAW/US use dual from 8 for most of elements but 18 for high dual elements which we found usually high charge density cutoff are needed. +They are O,Fe,Hf, Mn, Co, Ni, Cr. + +## Logic of convergence test on different criteria protocol + +The wavefunction cutoff scan list are same no matter which criteria protocol is used. +Therefore, the running of wavefunction cutoff test write wavefunction cutoff recommendation for all criteria protocol. +When switching to other criteria protocol, the wavefunction cutoff test can be skipped by setting `preset_ecutwfc`. It will then be used and only run charge density cutoff test. +This is not conflict with the caching workflow, since caching workflow will only run on wfc test the results is that for caching workflow when `preset_ecutwfc` is set, only reference calculation is run. + +## Lanthanides + +For lanthanides the precision measure is run on nitrides as Wentzcovitch paper and on oxides. +The unaries are not run for precision measurement since it is know that the oxidation state of lanthanides pseudopotentials is not zero. +Only for lanthanide nitrides the magnatization is on. +It is mostly because the reference of RE-N (Wentzcovitch) and RE-O (ACWF) is run with/without magnatization. +The kpoint distance of lanthanide nitrides is hard code to `0.2` (both for precision measure, for delta convergence and first EOS reference calculation of pressure convergence test as well. +Implemented as `+ 0.1` of precision protocol and `+ 0.05` of convergence protocol from acwf value) using the tetrahedron method rather than as acwf protocol where kpoint distance is `0.10` with fermi-dirac smearing, in order to compatible with Wentzcovitch paper results. +Lanthanide nitrides such as ErN, in equation of state calculation, large (0.06) volume change lead to supurious energy. +To mitigate the issue, the `scale_increment` is set to 0.01 (??? probably only for Er?) to make sure the volume change is in the parabolic range. +The nitrogen pseudopotential is the one from first run on pseudopotentials verifications on nitrigen on libraries include Pslibrary 0.1, Pslibrary 1.0.0, pseudo-dojo, ONCVPSP with legacy sg15 inputs... (Run and check) +The lanthanides have convergence issue if mixing is too large or number of bands is not enough. +For bands measure, the `nbnd_factor` is set to `2.0` while for precision measure and convergence the factor is set to `1.5`. +The mixing is set to 0.5 (default is 0.7 for non-lanthanides), and even smaller for atomic calculation of lanthanides elements which set to 0.3. +The `nbnd` set for lanthanides oxides are set to `1.5` times of the default number of bands since it also has issue that highest bands partially occupied and often retrigger the error handler to restart the calculation. + +## Criteria and protocol of pressure convergence + +Since the magnitude of pressure (P = 1/3 Tr(sigma)) directly output from DFT calcultion depends on the stiffness of the material strongly. +We convert it into an equivalent volume. +This what we call it residual volume is therefore a stiffness-agnostic value that can be used to set criteria for all elements. + +## Delta & nu metric in precision and convergence verificaiton + +In convergence delta factor calculation, the GS configurations from Cottiner's paper are used. +To have a uniform sence of precision through looking at delta factor, the value is defined as delta factor per atom. +However, since it is hard to define delta per/atom for oxides, ACWF does not use per/atom value to represent results. +It uses the nu factor which was defined in the ACWF paper. + +For the oxides, it needs oxygen pseudopotential first, same as nitrides. +The verification needs to run for all know oxygen/nitrigen pseudopotentials filst. However, the cutoffs of them are not known and the cutoffs are input for the precision measure. +So the very first run is the convergence test on all oxygen/nitrigen pseudopotentials. +Once the recommended cutoffs are known, the precision measure can be run for all oxygen/nitrigen elements. + +In the convergence verification, there are many options to choose from for what configuration to use. But it is redundant to use all of them, we what the configuration that gives the largest recommended cutoff energy for the pseudopotential. +After tests (show test results, which in `sssp-verify-scripts`), we found that the for non-magnetic elements, the Diamond configuration that gives the largest cutoff energy. +For magnetic elements, the GS configuration calculation with magnetization turned on for the bulk (in cohesive energy which usually give the largest recommended cutoff, where the atomic calculation still don't have magnetization turned on and it is not needed because the pseudopotential is generated in the close shell approximiation (??)) that gives the largest cutoff energy. + +## Phonon frequencies specification + +For some elements, we have neglected the first n frequencies in the summation above, because the frequencies are negative and/or with strong oscillations as function of the cutoff for all the considered pseudos). +We have neglected the first 4 frequencies for H and I, 12 for N and Cl, 6 for O and ??SiF4 (which replaces F)??. + +## bands distance compare specification + + +### bands distance of magnetic structures + +The bands of magnetic structure has one more dimension to distinguish up and down spins. +In bands distance comparing, I simply reduce the array along the last axis e.g. does not distinguish the spins but +merge eigenvalues (sorted) of the same kpoints. + +### bands distance protocol specifications + +There are three kinds of kpoint distance (`kpoints_distance_scf`, `kpoints_distance_bands` and `kpoints_distance_band_strcuture` respectively) for bands measure workflow and two for bands distance convergence workflow where the band structure is not calculated in convergence verification. + +In the production protocol, `kpoints_distance_scf` and `kpoints_distance_bands` are set to `0.15`. +We choose a uniform k-grid for bands distance comparison, in the full Brillouin zone and with symmetry reduction which not implemented in previous version. +After applying symmetry reduction, it is able to compute with more dense grids. +Because, choosing a high-symmetry path could result in an unsatisfactory arbitrary choice, +as different recipes for the standardisation of paths have been introduced in the recent literature and interesting features of the band structure may occur far from the high-symmetry lines (such as Weyl points). +A uniform mesh is also more appropriate from the point of view of electron’s nearsightedness if the energy eigenvalues are known on a sufficiently fine uniform k-points mesh, it is possible to get an exact real-space representation of the Hamiltonian in a Wannier function basis and then interpolate to an arbitrary fine mesh. + +## Parameters of protocol + +### Specific parameters for magnetic elements + +For atomic energy calculated for cohesive energy, it is hard to converge for magnetic elements with untreated parameters. +The following extra parameters are added for the calculation: + +``` +"SYSTEM": { + "nspin": 2, + "starting_magnetization": { + self.ctx.element: 0.5, + }, +}, +"ELECTRONS": { + "diagonalization": 'cg', + "mixing_beta": 0.5, + "electron_maxstep": 200, +}, +``` + +## Resource options and parallelization + +## parallelization for atomic calculation + +In case of atomic calculation running on a machine with too many CPUs, the `npool` and `ndiag` is explicitly set to 1 for atomic calculation. +Since there is only one kpoint in atomic case, there is no efficient lost of this parallelization setting. + +Because using too many `mpiprocs` (128 in EIGER) in atomic calculation would cause spurious issue the calculation terminate and not being handled. +The maximum number of mpiprocs is set to `32`. + +### Walltime settings + +The max wallclock seconds are set from the `options` input parameters from verification workflow. +This option will then pass to all the inside pw and ph calculation process as the `metadata.options` setting. +The `options` dict has the format of: + +```python +{ + "resources": { + "num_machines": 1, + "num_mpiprocs_per_machine": 36, + }, + "max_wallclock_seconds": 1800, # 30 min + "withmpi": True, +} + +``` +where the `max_wallclock_seconds` is exactly used for pw calculation while for ph calculation the value is set to 4 times of value since the ph calculation roughly estimated to elapse 4 times slower that pw calculation of the corresponding pw calculation to finish. +For atomic calculation in cohesive energy evaluation of lanthanides, the `max_wallclock_seconds` also set to 4 times otherwise it may not finished after 5 times of restart. + + +## Configurations + +Different verifications use different structure configurations. +For all precision measure verification, the configurations are all compatible with the ACWF. +While for bands measure and convergence workflow, the configurations used are set in file `statics/cif/mapping.json`. +The principles are for bands measure, using the configurations from Cottiner's paper since they are the groud state structures exist in real wolrd. +And for lanthanoids using the Nitrides from Wenzowitch paper for bands measure and convergence otherwise hard to converge in scf calculation. + +But the structures used for convergence verfication are varias. +The lanthanides still using the nitrides from Wenzovitch paper. +We keep on using GS nature configuration from Cottiner's paper, but convert them to primitive with pymatgen (for magnetic elements, no primitive convert process but still refine with `pymatgen`). +Maybe the flourine (F) still have thekproblem mentioned in legacy SSSP that hard to convergence (SCF convergence), will rollback to use SiF4 for it. + +## Work chains clean policy + +It is very delegate of how to set the remote folder clean in pseudopotential verification, since the verification consist of workflows with lots of sub processes and create huge amount of remote files, although the single calculations are small and resource non-stringent. +If the work chains are not cleaned, the number of remote files will increase rapidly and disk quota in remote machine will soon being run out. +On the contrast, if clean too early would make caching machanism not used and therefore waste resource for same calculations. +To trait off above two side of contradiction, the clean policy is designed as: + - set to the precision measures are cleaned right after its workchain are finished. + - set to clean remote workdir right after the evaluate work chains, but only clean calcjobs that are not cached from. Since (see [#150](https://github.com/aiidateam/aiida-sssp-workflow/pull/150) for detail) cached calcjob node share remote path with its nonmenon, the nonmenon nodes by `_caching` should clean itself in the last. + - set calcjob nodes of `_caching` work chain to be cleaned only by calling from verefication work chain in its terminate step rather than do itself. + +For other convergence work chain, they used nodes cached from `_caching` workchain and will clean themself right after it is finished. +The nodes create from other cached nodes (which have `_aiida_cached_from` extra attributes) from convergence work chain never used for furthur caching except for testing mode. + +This partially solve the caching issue of bands calculation ([issue #138](https://github.com/aiidateam/aiida-sssp-workflow/issues/138). +But same as ph.x calculation, is subsequent step failed and previous step cleaned, it will still failed to continue. +In phonon, the workaround is to check if the remote folder is empty. +This has the expense of even the ph.x calculation finished ok, the previous step clean will force the scf prepare calculation to run again so to sure the ph.x get its parent_folder not empty. +Also implemented in [#150](https://github.com/aiidateam/aiida-sssp-workflow/pull/150), the force running of `_caching` workflow is applied. To make sure the second run of phonon_frequencies and bands convergence workflow will use the `parant_folder` that are not empty. The expense of such strategy is the `_caching` always need to be run for second run of verification, but since in principle not always to run second time and it bring huge advantage to make the second run more robust. + +The clean policy of big verification work chain is controlled by `test_mode`. +It will do clean as described above or do not clean anything so it can be checked afterwards. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..ef879e4a --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,9 @@ +site_name: Solid State Standard Pseudopotential Toolkit +nav: + - Home: index.md + - Specification: spec.md + - Web App: gui.md +theme: + name: material + logo: assets/logo.png + favicon: assets/favicon.ico