1. To-Do Items
This is a “to-do” file for while we are working on creating the first version of the Open MPI RST / Sphinx docs. It will not be included in the final documentation.
1.1. Things that have changed in v5.0
Need to update these docs to reflect:
What specifically does
--disable-io-romio
do?Do we still have AMCA files?
Do we still have
--tune
files?Document this new breakpoint functionality: https://github.com/open-mpi/ompi/commit/f97d081cf9b540c5a79e00aecee17b25e8c123ad
Add that we do support “single dash”
mpirun
options, but we don’t want people to do that.Document v5.0.x’s backwards-compatibility relationship with v4.x (including ABI and
mpirun
command line options). It will likely be:C bindings are ABI compatible
Fortran
mpif.h
should be ok (but probably bears checking).Fortran module ABIs may have changed. These definitely need checking (e.g., w.r.t.
MPI_Status
and friends…?).MPI-1 deleted functions are always included in the library
Per Brian: the behavior is the same as Open MPI 4.x. The deleted functions are not declared in mpi.h unless Open MPI was compiled with
--enable-mpi1-compatibility
.
This is not really a change in v5.0, but it probably has changed (because of PRTE) since v4.x, so: we need to document how to use
MPI_Comm_join
andMPI_Publish_name
+MPI_Comm_accept
/MPI_Lookup_name
+MPI_Comm_connect
. See https://github.com/open-mpi/ompi/issues/10222
1.2. Other random to-do items
Add a note somewhere about “These HTML docs are available at docs.open-mpi.org and in distribution tarballs in
docs/_build/html/index.html
.Add a section about debugging and removal of MPIR, yadda yadda yadda (at least some of this can come from the “parallel debugging” FAQ section).
Can we make a new “.. knownissues::” directive (etc.) for the NEWS file that does the same thing as “.. attention::”, but says “Known Issues” instead of “Attention”.
Reading the Python docs style guide, it kinda implies we can do that kind of thing…?
Make “setting an MCA param” docs prominent in the doc (this already exists somewhere, but we need to make it prominent).
https://github.com/open-mpi/ompi/issues/7668 (ORTE –> PRRTE user-visible changes)
Add docs about mpirun launch vs. direct launch.
Finish folding in all FAQ topics into the main document.
1.3. Man page to-dos
man-openmpi/man1/mpirun.1.rst
is currently essentially an RST-ified version of OMPI v4.1’smpirun(1)
man page. There has been some light editing:Eliminiated all
-foo
optionsModernized some of the examples
Much more work needs to be done to update it for all the PRTE changes since Open MPI v4.1.x.
It’s possible that a lot of tokens in the RST man pages should be
tokens
.Look for “See the ___ section” text and create appropriate cross references.
There’s some shmem man pages with list that have incorrect indentation in the RST, which results in odd line break, extra bold face, and strange indentation. Example: man-openshmem/man3/shmem_double_prod_to_all.3.html – look for the description of “target”.
It looks like much of the cross-linking that we have in the MPI man pages (e.g., when one MPI API is mentioned on a page, it automatically links to the man page for that API) doesn’t exist in the OSHMEM pages.
Some of our code blocks have line numbers, others do not. I think I prefer to have the line numbers, but don’t feel too strongly about it.
Ensure somewhere that it is documented – probably in the networking section? – that it is necessary for resource manager daemons to have their /etc/security limits set properly for locked memory.
1.4. Josh Hursey notes
1.4.1. Running MPI Applications Notes
- Reviewing:
https://ompi–8329.org.readthedocs.build/en/8329/faq/running-mpi-apps.html
- 10.8.21
Is aggressive mode really determined by the slot count provided by PRRTE? Or is it determined by a query to hwloc with a reference ot the number of processes per node. It just surprises me that this part of OMPI is controlled by PRRTE instead of something more generic that might work with, say, Slurm direct launch via srun.