Start of MPI parallel examples

docs/parallel/benchmarking.rst

@@ -112,20 +112,3 @@ Weak scaling from the same data set is shown here
      :height: 40ex
      :align: center
      :alt: Weak scaling for some SiC supercells.
-
-
-Distributed memory parallelism
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section coming soon!
-
-Topics to be discussed:
-
-* Parallel scaling of simple examples.
-
-* Parallel efficiency.
-
-* Use of the `Groups` keyword in DFTB+ to improve scaling and efficiency for
-  calculations with spin polarisation and/or k-points.
-
-* Effects of latency on code performance.

docs/parallel/index.rst

@@ -11,3 +11,4 @@ Parallel usage of DFTB+
    amdahl.rst
    compiling.rst
    benchmarking.rst
+   mpi.rst

docs/parallel/mpi.rst

@@ -0,0 +1,71 @@
+.. _sec-mpi:
+
+MPI parallel calculations
+=========================
+
+Architecture
+------------
+
+MPI parallel calculations can be run on shared memory machines, but
+for larger calculations, distributed memory systems are used. These
+consist of separate computing nodes (often with multiple processors)
+networked together, typically with a shared file and queuing system.
+
+Processor groups
+----------------
+
+* Use of the `Groups` keyword in DFTB+ to improve scaling and efficiency for
+  calculations with spin polarisation and/or k-points.
+
+
+Solvers
+-------
+
+ScaLAPACK solvers
+^^^^^^^^^^^^^^^^^
+
+The `QR`, `DivideAndConquer` and `RelativelyRobust` dense ScaLAPACK
+eigensolvers are available for the serial and MPI parallel
+DFTB+. However, if possible, we suggest using the ELSI solvers for
+their better performance and capabilities.
+
+ELSI solvers
+^^^^^^^^^^^^
+
+Some of the [ELSI]_ solvers which can be used are
+
+  +--------+-------------------+--------------------+---------------+
+  | Solver | Use case          | Scaling with atoms | Eigenvalues   |
+  +========+===================+====================+===============+
+  | ELPA   | General (dense)   | O(N :sup:`3` )     | available     |
+  +--------+-------------------+--------------------+---------------+
+  | PEXSI  | General (sparse)  | between            | not available |
+  |        |                   | O(N:sup:`2`) and   |               |
+  |        |                   | O(N)               |               |
+  +--------+-------------------+--------------------+---------------+
+  | NTPoly | Better for gapped | O(N)               | not available |
+  |        | systems (sparse)  |                    |               |
+  +--------+-------------------+--------------------+---------------+
+
+
+The PEXSI solver is not included in the condaforge binaries, but can
+be built separately.
+
+
+Examples
+--------
+
+
+
+Note about transport calculations
+---------------------------------
+
+For :ref:`electronic transport <sec-transport>`, MPI parallelism is also supported.
+
+
+References
+==========
+
+.. [ELSI] ELSI -- An open infrastructure for electronic structure
+           solvers, Yu *et al.* (2020) DOI: `j.cpc.2020.107459
+           <https://doi.org/10.1016/j.cpc.2020.107459>`_