src/doc/en/thematic_tutorials/numerical_sage/mpi4py.rst: Remove use of install_package; some formatting

Author: Matthias Koeppe

src/doc/en/thematic_tutorials/numerical_sage/mpi4py.rst

@@ -1,37 +1,20 @@
 mpi4py
 ======
 
-MPI which stands for message passing interface is a common library
-for parallel programming. There is a package mpi4py that builds on
-the top of mpi, and lets arbitrary python objects be passed between
-different processes. These packages are not part of the default
-sage install. To install them do
+MPI, which stands for Message Passing Interface, is a common library
+for parallel programming. There is a package ``mpi4py`` that builds on
+the top of MPI, and lets arbitrary python objects be passed between
+different processes. These packages are not available from the
+Sage distribution. Install ``openmpi`` using your distribution's
+package manager. Then install ``mpi4py`` using
 
 .. skip
 
 ::
 
-    sage: optional_packages()
+    sage: !pip install mpi4py
 
-Find the package name openmpi-\* and mpi4py-\*and do
-
-.. skip
-
-::
-
-    sage: install_package('openmpi-*')
-    sage: install_package('mpi4py-*')
-
-Note that openmpi takes a while to compile (15-20 minutes or so).
-Openmpi can be run on a cluster, however this requires some set up
-so that processes on different machines can communicate (though if
-you are on a cluster this is probably already set up). The simplest
-case is if you are on a shared memory or multicore system where
-openmpi will just work with no configuration from you. To be
-honest, I have never tried to run mpi4py on a cluster, though there
-is much information about these topics online.
-
-Now, the way that mpi works is you start a group of mpi processes,
+Now, the way that MPI works is you start a group of MPI processes,
 all of the processes run the same code. Each process has a rank,
 that is a number that identifies it. The following pseudocode
 indicates the general format of MPI programs.
@@ -48,9 +31,9 @@ indicates the general format of MPI programs.
     else if my rank is n+1:
        ....
 
-Each processes looks for what it's supposed to do (specified by its
-rank) and processes can send data and receive data. Lets give an
-example. Create a script with the following code in a file mpi_1.py
+Each process looks for what it's supposed to do (specified by its
+rank), and processes can send data and receive data. Let's give an
+example. Create a script with the following code in a file ``mpi_1.py``
 
 .. CODE-BLOCK:: python
 
@@ -59,18 +42,19 @@ example. Create a script with the following code in a file mpi_1.py
     print("hello world")
     print("my rank is: %d"%comm.rank)
 
-To run it you can do (from the command line in your sage
+To run it you can do (from the command line in your Sage
 directory)
 
 .. CODE-BLOCK:: shell-session
 
-    ./local/bin/mpirun -np 5 ./sage -python mpi_1.py
+    mpirun -np 5 ./sage -python mpi_1.py
+
+The command ``mpirun -np 5`` starts 5 copies of a program under MPI. In
+this case we have 5 copies of Sage in pure Python mode run the
+script ``mpi_1.py``. The result should be 5 "hello worlds" plus 5 distinct ranks.
 
-The command mpirun -np 5 starts 5 copies of a program under mpi. In
-this case we have 5 copies of sage in pure python mode run the
-script mpi_1.py. The result should be 5 "hello worlds" plus 5 distinct ranks.
-The two most important mpi operations are sending and receiving.
-Consider the following example which you should put in a script mpi_2.py
+The two most important MPI operations are sending and receiving.
+Consider the following example which you should put in a script ``mpi_2.py``
 
 .. CODE-BLOCK:: python
 
@@ -86,20 +70,20 @@ Consider the following example which you should put in a script mpi_2.py
     print("I received this:")
     print(data)
 
-The same command as above with mpi_1.py replaced by mpi_2.py will
+The same command as above with ``mpi_1.py`` replaced by ``mpi_2.py`` will
 produce 5 outputs and you will see each process creates an array and
 then passes it to the next guy (where the last guy passes to the
-first.) Note that MPI.size is the total number of mpi
-processes. MPI.COMM WORLD is the communication world.
+first.) Note that ``MPI.size`` is the total number of MPI
+processes. ``MPI.COMM_WORLD`` is the communication world.
 
 There are some subtleties regarding MPI to be aware of. Small sends
 are buffered. This means if a process sends a small object it will
 be stored by openmpi and that process will continue its execution
 and the object it sent will be received whenever the destination
-executes a receive. However, if an object is large a process will
+executes a receive. However, if an object is large, a process will
 hang until its destination executes a corresponding receive. In
-fact the above code will hang if [rank]\*5 is replaced by
-[rank]\*500. It would be better to do
+fact, the above code will hang if ``[rank]*5`` is replaced by
+``[rank]*500``. It would be better to do
 
 .. CODE-BLOCK:: python
 
@@ -126,8 +110,8 @@ ready to receive and then he will send and process 2 will be
 waiting to receive, etc. This will not lock regardless of how large
 of an array we pass.
 
-A common idiom is to have one process, usually the one with rank 0
-act as a leader. That processes sends data out to the other
+A common idiom is to have one process, usually the one with rank 0,
+act as a leader. That process sends data out to the other
 processes and processes the results and decides how further
 computation should proceed. Consider the following code
 
@@ -148,18 +132,18 @@ computation should proceed. Consider the following code
     print("I got this array:")
     print(v)
 
-The scatter command takes a list and evenly divides it amongst all
+The ``scatter`` command takes a list and evenly divides it amongst all
 the processes. Here the root process creates a matrix (which is
-viewed as a list of rows) and then scatters it to everybody (roots
-sendbuf is divided equally amongst the processes). Each process
-prints the row it got. Note that the scatter command is executed by
-everyone, but when root executes it, it acts as a send and a
-receive (root gets one row from itself), while for everyone else it
-is just a receive.
-
-There is a complementary gather command that collects results from
-all the processes into a list. The next example uses scatter and
-gather together. Now the root process scatters the rows of a
+viewed as a list of rows) and then scatters it to everybody (root's
+``sendbuf`` is divided equally amongst the processes). Each process
+prints the row it got. Note that the ``scatter`` command is executed by
+everyone, but when root executes it, it acts as a ``send`` and a
+``receive`` (root gets one row from itself), while for everyone else it
+is just a ``receive``.
+
+There is a complementary ``gather`` command that collects results from
+all the processes into a list. The next example uses ``scatter`` and
+``gather`` together. Now the root process scatters the rows of a
 matrix, each process then squares the elements of the row it gets.
 Then the rows are all gathered up again by the root process who
 collects them into a new matrix.
@@ -185,9 +169,9 @@ collects them into a new matrix.
     if comm.rank==0:
         print(numpy.array(recvbuf))
 
-There is also a broadcast command that sends a single object to
+There is also a ``broadcast`` command that sends a single object to
 every process. Consider the following small extension. This is the
-same as before, but now at the end the root process sends everyone
+same as before, but now at the end, the root process sends everyone
 the string "done", which is printed out.
 
 .. CODE-BLOCK:: python