TL: completed tutorial for parallel SDC with Dedalus

Author: tlunet

pySDC/playgrounds/dedalus/README.md

@@ -4,7 +4,7 @@
 
 > :warning: This is only compatible with the latest version of Dedalus
 
-## Usage Example
+## Dedalus with pySDC
 
 See [demo.py](./scratch.py) for a first demo script using pySDC to apply SDC on the Advection equation.
 
@@ -103,7 +103,7 @@ Then `uSol` contains a list of `Fields` that represent the final solution of the
 See an other example with the [Burger equation](./burger.py)
 
 
-## Use a pySDC based time-integrator within Dedalus
+## SDC time-integrator for Dedalus
 
 This playground also provide a standalone SDC solver that can be used directly,
 see the [demo file for the Burger equation](./burger_ref.py).
@@ -131,4 +131,58 @@ while solver.proceed:
     solver.step(timestep)
 ```
 
-A full example script for the 2D Rayleigh-Benard Convection problem can be found [here](./rayleighBenardSDC.py).
+A full example script for the 2D Rayleigh-Benard Convection problem can be found [here](./rayleighBenardSDC.py).
+
+## Time-parallel SDC time-integrator for Dedalus
+
+Two MPI implementations of SDC time-integrators for 
+Dedalus are provided in `pySDC.playground.dedalus.sdc`, 
+that allow to run computations on $M$ parallel process,
+$M$ being the number of quadrature nodes.
+
+1. `SDCIMEX_MPI` : each rank compute the solution on one quadrature node, the initial tendencies and $MX_0$ are computed by rank 0 only and broadcasted to all other time ranks.
+2. `SDCIMEX_MPI2` : each rank compute the solution on one quadrature node, and the final state solution from time rank $M-1$ is broadcasted to all nodes at the end of the time-step as initial solution.
+
+While both implementations provide the same results as the `SpectralDeferredCorrectionIMEX` class 
+(up to machine precision), `SDCIMEX_MPI2` does minimize
+the amount of communication between time ranks, and may slightly improve performance on some clusters.
+
+> ⚠️ Only diagonal SDC preconditioning can be used with SDC
+
+**Example of use :**
+
+Here is a template for a Dedalus run script :
+
+```python
+import numpy as np
+import dedalus.public as d3
+
+from pySDC.playgrounds.dedalus.sdc import SDCIMEX_MPI
+
+SDCIMEX_MPI.setParameters(
+    nNodes=4, implSweep="MIN-SR-FLEX", explSweep="PIC", initSweep="COPY"
+)
+gComm, sComm, tComm = SDCIMEX_MPI.initSpaceTimeComms()
+
+coords = ... # Dedalus coordinate, e.g : d3.CartesianCoordinates('x', 'y', 'z')
+distr = d3.Distributor(coords, dtype=np.float64, comm=sComm)
+problem = d3.IVP(...) # rest of problem definition ...
+
+# Solver
+solver = problem.build_solver(SDCIMEX_MPI)
+# rest of solver settings ...
+```
+
+The `gComm`, `sComm` and `tComm` variables are `mpi4py.MPI.Intracomm` communicator objects, respectively for the _global_, _space_ and _time_ communicators.
+They provide methods as `Get_rank()` or `Barrier()` that
+can be used within the script.
+
+To run the script, simply do :
+
+```bash
+mpirun -n $NPROCS python script.py
+```
+
+Where `NPROCS` is a multiple of the number of quadrature nodes used with SDC, 4 in the example script.
+Note that the same template can be used with the 
+`SDCIMEX_MPI2` class.