fixes to MPI calling scripts in simple tutorial, and corresponding example calling script

Author: jlnav

docs/tutorials/local_sine_tutorial.rst

@@ -36,8 +36,6 @@ need to write a new allocation function.
         If your system doesn't allow you to perform these installations, try adding
         ``--user`` to the end of each command.
 
-        .. _NumPy: https://www.numpy.org/
-        .. _Matplotlib: https://matplotlib.org/
 
     .. tab-item:: 2. Generator
 
@@ -385,37 +383,41 @@ need to write a new allocation function.
 
         **Modifying the script**
 
-        Only a few changes are necessary to make our code MPI-compatible. Note the following:
+        Only a few changes are necessary to make our code MPI-compatible. For starters,
+        comment out the ``libE_specs`` definition:
 
         .. code-block:: python
             :linenos:
             :lineno-start: 7
 
-            libE_specs = LibeSpecs()  # class will autodetect MPI runtime
+            # libE_specs = LibeSpecs(nworkers=4, comms="local")
 
-        So that only one process executes the graphing and printing portion of our code,
-        modify the bottom of the calling script like this:
+        We'll be parameterizing our MPI runtime with a ``parse_args=True`` argument to
+        the ``Ensemble`` class instead of ``libE_specs``. We'll also use an ``ensemble.is_manager``
+        attribute so only the first MPI rank runs the data-processing code.
+
+        The bottom of your calling script should now resemble:
 
         .. code-block:: python
             :linenos:
-            :lineno-start: 27
+            :lineno-start: 28
+
+            # replace libE_specs with parse_args=True. Detects MPI runtime
+            ensemble = Ensemble(sim_specs, gen_specs, exit_criteria, parse_args=True)
 
-            ensemble = Ensemble(sim_specs, gen_specs, exit_criteria, libE_specs)
             ensemble.add_random_streams()
+
             if __name__ == "__main__":
-                ensemble.run()
 
-                if ensemble.is_manager:  # only True on rank 0
-                    H = ensemble.H
-                    print([i for i in H.dtype.fields])
-                    print(H)
+                ensemble.run()  # start the ensemble. Blocks until completion.
 
-                    import matplotlib.pyplot as plt
+                if ensemble.is_manager:  # only True on rank 0
+                    history = ensemble.H  # start visualizing our results
 
                     colors = ["b", "g", "r", "y", "m", "c", "k", "w"]
 
-                    for i in range(1, nworkers + 1):
-                        worker_xy = np.extract(H["sim_worker"] == i, H)
+                    for i in range(1, ensemble.nworkers + 1):
+                        worker_xy = np.extract(history["sim_worker"] == i, history)
                         x = [entry.tolist()[0] for entry in worker_xy["x"]]
                         y = [entry for entry in worker_xy["y"]]
                         plt.scatter(x, y, label="Worker {}".format(i), c=colors[i - 1])
@@ -448,8 +450,10 @@ need to write a new allocation function.
         libEnsemble use-case within our
         :doc:`Electrostatic Forces tutorial <./executor_forces_tutorial>`.
 
+.. _Matplotlib: https://matplotlib.org/
 .. _MPI: https://en.wikipedia.org/wiki/Message_Passing_Interface
 .. _MPICH: https://www.mpich.org/
 .. _mpi4py: https://mpi4py.readthedocs.io/en/stable/install.html
+.. _NumPy: https://www.numpy.org/
 .. _here: https://www.mpich.org/downloads/
 .. _examples/tutorials/simple_sine: https://github.com/Libensemble/libensemble/tree/develop/examples/tutorials/simple_sine

examples/tutorials/simple_sine/calling_mpi.py

@@ -1,55 +1,52 @@
 import matplotlib.pyplot as plt
 import numpy as np
-from mpi4py import MPI
-from tutorial_gen import gen_random_sample
-from tutorial_sim import sim_find_sine
+from gen import gen_random_sample
+from sim import sim_find_sine
 
-from libensemble.libE import libE
-from libensemble.tools import add_unique_random_streams
+from libensemble import Ensemble
+from libensemble.specs import ExitCriteria, GenSpecs, SimSpecs
 
-libE_specs = {"comms": "mpi"}  # 'nworkers' removed, 'comms' now 'mpi'
+# libE_specs = LibeSpecs(nworkers=4, comms="local")
 
-nworkers = MPI.COMM_WORLD.Get_size() - 1  # one process belongs to manager
-is_manager = MPI.COMM_WORLD.Get_rank() == 0  # manager process has MPI rank 0
-
-gen_specs = {
-    "gen_f": gen_random_sample,  # Our generator function
-    "out": [("x", float, (1,))],  # gen_f output (name, type, size).
-    "user": {
-        "lower": np.array([-3]),  # random sampling lower bound
-        "upper": np.array([3]),  # random sampling upper bound
-        "gen_batch_size": 5,  # number of values gen_f will generate per call
+gen_specs = GenSpecs(
+    gen_f=gen_random_sample,  # Our generator function
+    out=[("x", float, (1,))],  # gen_f output (name, type, size)
+    user={
+        "lower": np.array([-3]),  # lower boundary for random sampling
+        "upper": np.array([3]),  # upper boundary for random sampling
+        "gen_batch_size": 5,  # number of x's gen_f generates per call
     },
-}
+)
+
+sim_specs = SimSpecs(
+    sim_f=sim_find_sine,  # Our simulator function
+    inputs=["x"],  # Input field names. "x" from gen_f output
+    out=[("y", float)],  # sim_f output. "y" = sine("x")
+)
+
+exit_criteria = ExitCriteria(sim_max=80)  # Stop libEnsemble after 80 simulations
 
-sim_specs = {
-    "sim_f": sim_find_sine,  # Our simulator function
-    "in": ["x"],  # Input field names. 'x' from gen_f output
-    "out": [("y", float)],  # sim_f output. 'y' = sine('x')
-}
+ensemble = Ensemble(sim_specs, gen_specs, exit_criteria, parse_args=True)
 
-persis_info = add_unique_random_streams({}, nworkers + 1)  # Initialize manager/workers random streams
+ensemble.add_random_streams()  # setup the random streams unique to each worker
 
-exit_criteria = {"sim_max": 80}  # Stop libEnsemble after 80 simulations
+if __name__ == "__main__":
 
-H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info, libE_specs=libE_specs)
+    ensemble.run()  # start the ensemble. Blocks until completion.
 
-# Some (optional) statements to visualize our History array
-# Only the manager process should execute this
-if is_manager:
-    print([i for i in H.dtype.fields])
-    print(H)
+    if ensemble.is_manager:  # only True on rank 0
+        history = ensemble.H  # start visualizing our results
 
-    colors = ["b", "g", "r", "y", "m", "c", "k", "w"]
+        colors = ["b", "g", "r", "y", "m", "c", "k", "w"]
 
-    for i in range(1, nworkers + 1):
-        worker_xy = np.extract(H["sim_worker"] == i, H)
-        x = [entry.tolist()[0] for entry in worker_xy["x"]]
-        y = [entry for entry in worker_xy["y"]]
-        plt.scatter(x, y, label=f"Worker {i}", c=colors[i - 1])
+        for i in range(1, ensemble.nworkers + 1):
+            worker_xy = np.extract(history["sim_worker"] == i, history)
+            x = [entry.tolist()[0] for entry in worker_xy["x"]]
+            y = [entry for entry in worker_xy["y"]]
+            plt.scatter(x, y, label="Worker {}".format(i), c=colors[i - 1])
 
-    plt.title("Sine calculations for a uniformly sampled random distribution")
-    plt.xlabel("x")
-    plt.ylabel("sine(x)")
-    plt.legend(loc="lower right")
-    plt.savefig("tutorial_sines.png")
+        plt.title("Sine calculations for a uniformly sampled random distribution")
+        plt.xlabel("x")
+        plt.ylabel("sine(x)")
+        plt.legend(loc="lower right")
+        plt.savefig("tutorial_sines.png")