Add the create_magnetic_configuration function

Here we add the `create_magnetic_configuration` calculation function, which
returns a new `StructureData` with the required kinds as well as a `Dict` node
with the corresponding magnetic moments for each kind, based on the input
structure and magnetic moments per site.

To create the new list of kinds, the algorithm loops over all the elements
in the structure and makes a list of the sites with that element and their
corresponding magnetic moment. Next, it splits this list in three lists:

* Zero magnetic moments: Any site that has an absolute magnetic moment 
  lower than `ztol`
* Positive magnetic moments
* Negative magnetic moments

The algorithm then sorts the positive and negative lists from large to small
absolute value, and loops over each list. New magnetic kinds will be created
when the absolute difference between the magnetic moment of the current
kind and the site exceeds `atol`.

The positive and negative magnetic moments are handled separately to
avoid assigning two sites with opposite signs in their magnetic moment to
the same kind and make sure that each kind has the correct magnetic
moment, i.e. the largest magnetic moment in absolute value of the sites
corresponding to that kind.

To make it easier to pass the magnetic moments between calculations, a new
tool is added to `PwCalculation`: `get_magnetic_configuration`. This will
check the final magnetic moments from the calculation, create a new
`StructureData` if necessary, and return the structure and dictionary that
maps the kinds to the magnetic moments.

A new tutorial is added on "Magnetic configurations" that explains how to work
with spin-polarised calculations in the plugin.

docs/Makefile

@@ -28,6 +28,7 @@ all: clean html view
 
 clean:
 	rm -rf $(BUILDDIR)
+	rm -rf $(shell find . -type d -wholename "*/reference/api/auto")
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/source/_static/aiida-custom.css

@@ -112,6 +112,19 @@ div.admonition :last-child {
 div.highlight-bash div.highlight {
     background-color: aliceblue;
 }
+
 div.highlight-console div.highlight {
     background-color: aliceblue;
 }
+
+.aiida-green {
+    color: #32B805;
+}
+
+.aiida-blue {
+    color: #0496DE;
+}
+
+.aiida-orange {
+    color: #FF7D16;
+}

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

@@ -26,14 +26,33 @@ img.logo__image {
     font-size: 40px!important;
 }
 
-img.aiida-logo {
+img.aiida-sidebar-logo {
     height: 40px!important;
 }
 
+img.aiida-logo {
+    width: 20px;
+    padding-bottom: 3px;
+}
+
 .fa {
     color: var(--pst-color-primary);
 }
 
 .bd-search {
     padding: 0 1rem;
 }
+
+.tutor-footer {
+    padding-top: 0rem;
+    border-top: none!important;
+}
+
+.footer-table {
+    margin-bottom: 0rem;
+    border-color: transparent;
+}
+
+.footer-table td:last-child {
+    text-align: right;
+}

docs/source/_templates/icon-links.html

@@ -30,7 +30,7 @@
     aria-label="{{ theme_icon_links_label }}">
     <li class="nav-item">
         <a href="https://aiida.net/">
-            <img src="{{ pathto('_static/logo_aiida.svg', 1) }}" alt="AiiDA" class="aiida-logo">
+            <img src="{{ pathto('_static/logo_aiida.svg', 1) }}" alt="AiiDA" class="aiida-sidebar-logo">
         </a>
     </li>
     {%- for icon_link in theme_icon_links -%}

docs/source/conf.py

@@ -30,9 +30,6 @@
 
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -55,12 +52,6 @@
     'aiida_pseudo': ('http://aiida-pseudo.readthedocs.io/en/latest/', None),
 }
 
-myst_enable_extensions = [
-    'deflist',
-    'colon_fence',
-    'substitution'
-]
-
 # Settings for the `autoapi.extenstion` automatically generating API docs
 filepath_docs = pathlib.Path(__file__).parent.parent
 filepath_src = filepath_docs.parent / 'src'
@@ -90,6 +81,32 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ['**.ipynb_checkpoints', 'reference/api/auto/aiida_quantumespresso/index.rst']
 
+# -- MyST options
+
+myst_enable_extensions = [
+    'deflist',
+    'colon_fence',
+    'substitution',
+    'attrs_inline',
+    'substitution'
+]
+
+myst_substitutions = {
+    'aiida_logo': '<img src="../_static/logo_aiida.svg" alt="aiida" class="aiida-logo">',
+    'create_magnetic_configuration': \
+        '{func}`~aiida_quantumespresso.calculations.functions.create_magnetic_configuration.create_magnetic_configuration`',
+    'get_builder_from_protocol': \
+        '{meth}`~aiida_quantumespresso.workflows.pw.base.PwBaseWorkChain.get_builder_from_protocol`',
+    'get_magnetic_configuration': \
+        '{meth}`~aiida_quantumespresso.tools.calculations.pw.PwCalculationTools.get_magnetic_configuration`',
+    'nspin': '[`nspin`](https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm412)',
+    'PwBaseWorkChain': '{class}`~aiida_quantumespresso.workflows.pw.base.PwBaseWorkChain`',
+    'PwCalculation': '{class}`~aiida_quantumespresso.calculations.pw.PwCalculation`',
+    'SpinType': '{class}`~aiida_quantumespresso.common.types.SpinType`',
+    'starting_magnetization': '[`starting_magnetization`](https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm299)',
+    'StructureData': '{class}`~aiida.orm.StructureData',
+}
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/source/howto/calculations/ph.md

@@ -16,18 +16,18 @@ In order to run a `ph.x` calculation, you first need to have completed a `pw.x`
 See the [tutorial](#tutorials-pw-through-api) or [how-to guide](#howto-calculations-pw) for more information.
 :::
 
-Once you have successfully run a `PwCalculation` you can run a `ph.x` calculation through the `PhCalculation` plugin as follows:
+Once you have successfully run a {{ PwCalculation }} you can run a `ph.x` calculation through the `PhCalculation` plugin as follows:
 
 ```{literalinclude} ../../tutorials/include/scripts/run_ph_basic.py
 :language: python
 ```
 
-Note that you will have to replace `IDENTIFIER_PW_CALCULATION` with the identifier (pk or UUID) of the completed `PwCalculation`.
+Note that you will have to replace `IDENTIFIER_PW_CALCULATION` with the identifier (pk or UUID) of the completed {{ PwCalculation }}.
 
 ## How to define input file parameters
 
 The `ph.x` code supports many parameters that can be defined through the input file, as shown on the [official documentation](https://www.quantum-espresso.org/Doc/INPUT_PH.html).
-Parameters that are part of the `INPUTPH` card should be specified through the `parameters` input of the `PwCalculation` plugin.
+Parameters that are part of the `INPUTPH` card should be specified through the `parameters` input of the {{ PwCalculation }} plugin.
 The parameters are specified using a Python dictionary, for example:
 
 ```python

docs/source/howto/calculations/pw.md

@@ -18,7 +18,7 @@ Examples of these properties include ground-state energy and one-electron (Kohn-
 
 ## How to launch a `pw.x` calculation
 
-Below is a script with a basic example of how to run a `pw.x` calculation through the `PwCalculation` plugin that computes the electronic ground state of an fcc silicon crystal:
+Below is a script with a basic example of how to run a `pw.x` calculation through the {{ PwCalculation }} plugin that computes the electronic ground state of an fcc silicon crystal:
 
 ```{literalinclude} ../../tutorials/include/scripts/run_pw_basic.py
 :language: python
@@ -30,7 +30,7 @@ Note that you may have to change the name of the code that is loaded using `load
 
 The `pw.x` code supports many parameters that can be defined through the input file, as shown on the [official documentation](https://www.quantum-espresso.org/Doc/INPUT_PW.html).
 The parameters are divided into section or "cards".
-Parameters that are part of cards that start with an ampersand (`&`) should be specified through the `parameters` input of the `PwCalculation` plugin.
+Parameters that are part of cards that start with an ampersand (`&`) should be specified through the `parameters` input of the {{ PwCalculation }} plugin.
 The parameters are specified using a Python dictionary, where each card is its own sub-dictionary, for example:
 
 ```python
@@ -78,13 +78,15 @@ These include:
 Defining them anyway will result in an exception when launching the calculation.
 :::
 
+(howto-calculations-pw-multidimensional-parameters)=
+
 ### Multidimensional parameters
 
 The input format of `pw.x` contains various keywords that do not simply take the format of a key value pair, but rather there will some indices in the key itself.
 Take for example the [`starting_magnetization`](https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm287) keyword of the `SYSTEM` card.
 The starting magnetization value needs to be applied to a specific species and therefore the index `i` is required to be able to make this distinction.
 
-The `PwCalculation` plugin makes this easy as it will do the conversion from kind name to species index automatically.
+The {{ PwCalculation }} plugin makes this easy as it will do the conversion from kind name to species index automatically.
 This allows you to specify a starting magnetization value by using a dictionary notation, where the key is the kind name to which it should be applied.
 For example, if you have a structure with the kind `Co` and want it to have a given starting magnetization, one can add the following in the parameter data dictionary:
 
@@ -171,7 +173,7 @@ Assuming the input structure contained the kinds `Ni` and `Fe`, which would have
 ## How to define pseudopotentials
 
 Each `pw.x` calculation requires a pseudopotential to be specified for each kind in the structure.
-These pseudopotentials can be specified in the `PwCalculation` plugin through the `pseudos` input namespace.
+These pseudopotentials can be specified in the {{ PwCalculation }} plugin through the `pseudos` input namespace.
 This input takes a dictionary, where the keys are the kind names and the values are instances of the {class}`~aiida_pseudo.data.pseudo.upf.UpfData` data plugin of the {{ aiida_pseudo }} plugin package.
 For example, if the input structure is a `GaAs` crystal, the pseudopotentials could be specified as follows:
 
@@ -263,7 +265,7 @@ builder.settings = Dict({'GAMMA_ONLY': True})
 ## How to fix the coordinates of atoms
 
 Quantum ESPRESSO pw.x allows to optionally fix the coordinates of atoms during relaxation and molecular-dynamics simulations.
-This functionality is enabled in `PwCalculation` through the `FIXED_COORDS` setting which is a list of length equal to the number of sites in the input structure.
+This functionality is enabled in {{ PwCalculation }} through the `FIXED_COORDS` setting which is a list of length equal to the number of sites in the input structure.
 Each element is a list of length three containing booleans, where `True` means that the position of the site in that direction should be fixed.
 For example:
 
@@ -277,7 +279,7 @@ All other coordinates are allowed to change.
 
 ## How to retrieve additional files
 
-The `PwCalculation` plugin will retrieve the most important and common output files by default.
+The {{ PwCalculation }} plugin will retrieve the most important and common output files by default.
 To retrieve additional output files, specify the list of files in the `ADDITIONAL_RETRIEVE_LIST` key in the `settings` input:
 
 ```python
@@ -288,13 +290,13 @@ builder.settings = Dict({'ADDITIONAL_RETRIEVE_LIST': ['custom-file.txt', 'some-o
 
 ## How to analyze the results
 
-When a `PwCalculation` is completed, there are quite a few possible analyses to perform.
+When a {{ PwCalculation }} is completed, there are quite a few possible analyses to perform.
 
 ### How to check the SCF accuracy during the self-consistent cycle
 
 During the self-consistent field cycle, the difference in energy of the newly computed charge density and the starting one is computed and stored.
 It can easily be retrieved through the {meth}`~aiida_quantumespresso.tools.calculations.pw.PwCalculationTools.get_scf_accuracy` method.
-This method can be accessed directly through the ``tools`` of a completed ``PwCalculation`` node:
+This method can be accessed directly through the `tools` of a completed {{ PwCalculation }} node:
 
 ```python
 In [1]: node = load_node(IDENTIFIER)