Merge pull request #803 from DLWoodruff/console-scripts

Add console-script entry points for the main drivers

Author: bknueven

README.md

@@ -35,11 +35,11 @@ Here are two methods that seem to work well for installation, at least when cons
    ```
    Run the line aborve after cloning and moving to the repo root directory.
 
-To test your installation, cd to the directory where you installed mpi-sppy
-(it is called ``mpi-sppy``) and then give this command.
+To test your installation, give this command (once mpi-sppy is installed
+it works from any directory):
 
 ```
-mpirun -n 2 python -m mpi4py mpi_one_sided_test.py
+mpirun -n 2 mpi-sppy-one-sided-test
 ```
 
 If you don't see any error messages, you might have an MPI
@@ -55,6 +55,26 @@ Installing mpi-sppy
 It is possible to pip install mpi-sppy; however, most users are better off
 getting the software from Github because it is under active development.
 
+Command-line programs
+---------------------
+
+Installing mpi-sppy — whether with `pip install mpi-sppy` or with
+`pip install -e .` from a clone (the recommended way to work from source) —
+puts a few console scripts on your `PATH`, so you can run the main drivers
+without locating the files in your environment:
+
+- `mpi-sppy-generic-cylinders` — the general-purpose driver, equivalent to
+  `python -m mpisppy.generic_cylinders` (see the `generic_cylinders` docs).
+- `mpi-sppy-mrp-generic` — the sequential-sampling (MRP) driver, equivalent
+  to `python -m mpisppy.mrp_generic`.
+- `mpi-sppy-one-sided-test` — the MPI one-sided diagnostic shown above.
+
+For multi-rank parallel runs, the `python -m mpi4py` module form is still
+recommended (e.g. `mpiexec -np 3 python -m mpi4py -m
+mpisppy.generic_cylinders ...`) so that mpi4py installs its
+abort-on-exception handler; a bare `mpiexec -np 3 mpi-sppy-generic-cylinders
+...` runs, but a failure on one rank may leave the others hanging.
+
 Citing mpi-sppy
 ---------------
 If you find mpi-sppy useful in your work, we kindly request that you cite the following

doc/src/generic_cylinders.rst

@@ -8,6 +8,23 @@ run mpi-sppy. It provides command-line access to the hub-and-spoke
 system, the extensive form solver, confidence intervals, and many
 other features without requiring you to write a driver program.
 
+.. note::
+   Installing mpi-sppy (with ``pip install mpi-sppy`` or with
+   ``pip install -e .`` from a clone) puts a console script named
+   ``mpi-sppy-generic-cylinders`` on your ``PATH``. It is equivalent to
+   ``python -m mpisppy.generic_cylinders``, so in every example below you
+   can substitute ``mpi-sppy-generic-cylinders`` for the
+   ``python -m mpisppy.generic_cylinders`` prefix, e.g.::
+
+       mpi-sppy-generic-cylinders --module-name farmer --num-scens 3 --EF --EF-solver-name gurobi
+
+   For multi-rank parallel runs, prefer the ``python -m mpi4py`` module
+   form shown below (``mpiexec -np 3 python -m mpi4py -m
+   mpisppy.generic_cylinders ...``): mpi4py's runner aborts all ranks if
+   one raises an exception, whereas a bare
+   ``mpiexec -np 3 mpi-sppy-generic-cylinders ...`` runs but may leave
+   the other ranks hanging when one fails.
+
 Your Model File (Module)
 ------------------------
 

doc/src/install_mpi.rst

@@ -20,11 +20,10 @@ Here are two methods that seem to work well for installation, at least when cons
 
    * ``pip install -e .[mpi]`` (after cloning and moving to the repo root directory)
 
-To test
-your installation, cd to the directory where you installed mpi-sppy
-(it is called ``mpi-sppy``) and then give this command.
+To test your installation, give this command (once mpi-sppy is
+installed it works from any directory):
 
-``mpirun -n 2 python -m mpi4py mpi_one_sided_test.py``
+``mpirun -n 2 mpi-sppy-one-sided-test``
 
 If you don't see any error messages, you might have an MPI
 installation that will work well. Note that even if there is

doc/src/quick_start.rst

@@ -350,13 +350,13 @@ top of the cloned ``mpi-sppy`` repository; step 1 changes into
    You should see the solver print progress and the script print an
    optimal objective value. This check does *not* use MPI.
 
-3. **MPI works** (only if you installed MPI and ``mpi4py``). Still in
-   ``examples/farmer``, run the bundled one-sided MPI test (its path is
-   given relative to ``examples/farmer``):
+3. **MPI works** (only if you installed MPI and ``mpi4py``). Run the
+   bundled one-sided MPI test (the console script is on your ``PATH``
+   after installation, so no path is needed):
 
    .. code-block:: text
 
-      mpiexec -n 2 python -m mpi4py ../../mpi_one_sided_test.py
+      mpiexec -n 2 mpi-sppy-one-sided-test
 
    If you see no error messages, your MPI installation should be
    suitable. Then confirm the full hub-and-spoke flow with a short PH

doc/src/seqsamp.rst

@@ -19,6 +19,15 @@ The recommended way to run sequential sampling is with
 ``mpisppy.mrp_generic``.  Like ``generic_cylinders.py``, it takes
 a ``--module-name`` argument pointing to your model module.
 
+.. note::
+   Installing mpi-sppy (with ``pip install mpi-sppy`` or with
+   ``pip install -e .`` from a clone) puts the console script
+   ``mpi-sppy-mrp-generic`` on your ``PATH``; it is equivalent to
+   ``python -m mpisppy.mrp_generic`` and can be used in place of that
+   prefix in the examples below. For the ``--xhat-method cylinders``
+   (multi-rank) case, prefer the ``python -m mpi4py`` module form so
+   that mpi4py's abort-on-exception handler is installed.
+
 Your model module must provide the same functions required by
 ``generic_cylinders``: ``scenario_creator``, ``scenario_names_creator``,
 ``kw_creator``, ``inparser_adder``, and ``scenario_denouement``.

mpi_one_sided_test.py

@@ -24,7 +24,7 @@
 def main():
     if mpi.COMM_WORLD.Get_size() == 1:
         print("ERROR: This script must be run with multiple MPI processes using mpirun or mpiexec, e.g.:", file=sys.stderr)
-        print("       mpirun -n 2 python -m mpi4py mpi_one_sided_test.py", file=sys.stderr)
+        print("       mpirun -n 2 mpi-sppy-one-sided-test", file=sys.stderr)
         sys.exit(2) # Exit status 2: command line usage error
 
     rank = mpi.COMM_WORLD.Get_rank()

mpisppy/generic_cylinders.py

@@ -27,7 +27,7 @@
 
 
 ##########################################################################
-if __name__ == "__main__":
+def main():
     if len(sys.argv) == 1:
         print("The python model file module name (no .py) must be given.")
         print("usage, e.g.: python -m mpi4py ../../mpisppy/generic_cylinders.py --module-name farmer --help")
@@ -145,3 +145,7 @@ def scenario_denouement(rank, sname, s):
                           scenario_denouement, bundle_wrapper=bundle_wrapper)
         if mmw_requested(cfg):
             do_mmw(fname, cfg, wheel=wheel)
+
+
+if __name__ == "__main__":
+    main()

mpisppy/mrp_generic.py

@@ -73,7 +73,7 @@ def parse_mrp_args(m):
 
 
 ##########################################################################
-if __name__ == "__main__":
+def main():
     if len(sys.argv) == 1:
         print("The python model file module name (no .py) must be given.")
         print("usage, e.g.: python -m mpisppy.mrp_generic --module-name farmer"
@@ -101,3 +101,7 @@ def parse_mrp_args(m):
             root_nonants = np.array(xhat["ROOT"])
             np.save(f"{cfg.solution_base_name}.npy", root_nonants)
             print(f"Wrote xhat to {cfg.solution_base_name}.npy")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -34,6 +34,17 @@ download = "https://github.com/Pyomo/mpi-sppy"
 documentation = "https://mpi-sppy.readthedocs.io"
 tracker = "https://github.com/Pyomo/mpi-sppy/issues"
 
+# Console entry points: pip creates a launcher on the user's PATH for each,
+# so pip-installed users can run these drivers without knowing where the
+# files landed in site-packages.  Each target is an importable module:callable.
+# For real multi-rank parallel runs the module form is still recommended so
+# the mpi4py runner installs its abort-on-exception handler, e.g.:
+#   mpiexec -np 3 python -m mpi4py -m mpisppy.generic_cylinders --module-name farmer ...
+[project.scripts]
+mpi-sppy-generic-cylinders = "mpisppy.generic_cylinders:main"
+mpi-sppy-mrp-generic = "mpisppy.mrp_generic:main"
+mpi-sppy-one-sided-test = "mpi_one_sided_test:main"
+
 [project.optional-dependencies]
 doc = [
     "sphinx",
@@ -52,3 +63,13 @@ pandas = [
 plot = [
     "matplotlib",
 ]
+
+# Explicit package/module declaration.  Matches the previous find_packages()
+# result (only the mpisppy package and its subpackages) and additionally
+# installs the top-level mpi_one_sided_test.py so its console script can
+# import it.
+[tool.setuptools]
+py-modules = ["mpi_one_sided_test"]
+
+[tool.setuptools.packages.find]
+include = ["mpisppy", "mpisppy.*"]