Documentation: run-time changes v4.1.x --> v5.0.x

[jsquyres]

Originally taken from the "to-do" section in the Open MPI docs:

• Update mpirun man page #11730
  • Eliminiated all -foo options
  • Modernized 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.
• Document new breakpoint functionality #11731
• Add that we do support “single dash” mpirun options, but we don’t want people to do that.
• We need to document how to use MPI_Comm_join and MPI_Publish_name + MPI_Comm_accept / MPI_Lookup_name + MPI_Comm_connect after PRRTE changes. #11732
  • See master/v5.0.x: missing documentation on MPI_Comm_join/Publish usage (client/server pattern) #10222
• Add a section about debugging and removal of MPIR #11733
• ORTE -> PRRTE changes for users need to be documented, users educated #7668 (ORTE –> PRRTE user-visible changes)
• Add docs about mpirun launch vs. direct launch. #11734
• Investigate and document current behavior of "aggressive" mode #11735
  • This is an old link to section 10.8.21 -- it may or may not be correct https://ompi–8329.org.readthedocs.build/en/8329/faq/running-mpi-apps.html
  • Is "aggressive" mode really determined by the slot count provided by PRRTE? Or is it determined by a query to hwloc with a reference to 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.
• From Ralph's comment on singleton mode with v4.x fails when MCA binding policy is "numa" on AMD hardware #11097:
  • singleton mode with v4.x fails when MCA binding policy is "numa" on AMD hardware #11097 (comment)

[qkoziol]

Working on this

[qkoziol]

Does the "don't use single dash" command-line options apply to using '-n' in the examples in the man page? i.e. should I replace them with '--n' (or '--np') ?

I've replaced '-H' with '--host'.

[qkoziol]

Is there a definition for all of these keywords anywhere?

"* --map-by <object>: Map to the specified object, defaults to
package. Supported options include slot, hwthread, core,
L1cache, L2cache, L3cache, package, numa,
node, seq, rankfile, pe-list=#, and ppr.
Any object can include modifiers by adding a : and any combination
of the following:
"

[rhc54]

Does the "don't use single dash" command-line options apply to using '-n' in the examples in the man page? i.e. should I replace them with '--n' (or '--np') ?

No - the -n is mandated in the MPI standard, as is -np

Is there a definition for all of these keywords anywhere?

I doubt it - you might look to see if there is a "terminology" section as that would be the most likely place to find it.

[qkoziol]

On review, I see that the mpirun man page (https://docs.open-mpi.org/en/main/man-openmpi/man1/mpirun.1.html ) covers exit status behavior in section 19.1.2.6.19 and return value in section 19.1.2.8. These seem like they should be merged into one section (probably into 19.1.2.8, since it already has the more significant heading in the manpage. Thoughts?

[qkoziol]

There's too many diverse actions in this meta-issue and it's going to create a terrible PR (eventually). I'm going to break them into separate issues so that they can be tackled in smaller bites. I'll apply the same tags (to start) and assign the one(s) I've been working on to myself.

[qkoziol]

Closing this, in favor of the smaller, more focused that track individual items.