Documentation: random Open MPI v4.1.x --> v5.0.x changes

[jsquyres]

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

• Document what MPI-4.0 items are supported, e.g., sessions, persistent communication, ...
• What specifically does --disable-io-romio do?
• Do we still have AMCA files?
• Do we still have --tune files?
• 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.
  • This is a reversal from what we previously publicly stated would happen in Open MPI v5.0.x
  • 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.
• 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.
• Make “setting an MCA param” docs prominent in the doc (this already exists somewhere, but we need to make it prominent).

William (Removed FAQ item as it's covered under #11363)

[wckzhang]

For - Make “setting an MCA param” docs prominent in the doc (this already exists somewhere, but we need to make it prominent). how do you want it to be more prominent? It's not too hard to find on sidebar it's under "8. The Modular Component Architecture (MCA)" as "8.2 Setting MCA parameter values." It seems to be fairly prominent unless your intention is to have it be one of the numbered items on the sidebar

[jsquyres]

@wckzhang Put yourself in the mindset of an Open MPI newbie: will they find these docs? Setting an MCA param is a common thing to do. Should we put it in one of the "quick start" pages (or have a new quick start for it, or ...?). Suggestions and proposals are welcome here.

[wckzhang]

Hmm, I'm not sure a user would know what an MCA parameter is unless they read about MCA, maybe in the quick start guide there can be a section after launch MPI such as "Customize run-time options." which can link to the setting MCA parameter doc

[wckzhang]

#11459 - For Make “setting an MCA param” docs prominent in the doc (this already exists somewhere, but we need to make it prominent).

[wckzhang]

It looks like "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." was completed already, see f33d3d4 I'm going to mark that as completed

[wckzhang]

#11468 - For What specifically does --disable-io-romio do? I'm not sure if I fulfilled the intention behind this todo. Added a link to the ROMIO doc in the --disable-io-romio option and added detail in the description that it is an implementation of the internal io framework.

[wckzhang]

I looked into Document v5.0.x’s backwards-compatibility relationship with v4.x (including ABI and mpirun command line options). It will likely be: yesterday but waiting on merging/test status of - #11365 before I write anything

[wckzhang]

It looks like --am option still works, but it's deprecated and users should instead use --tune. I can add a section in the set mca params for this

[wckzhang]

I'm a little confused about this section:

MPI-1 deleted functions are always included in the library.
This is a reversal from what we previously publicly stated would happen in Open MPI v5.0.x
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.

Are deleted MPI-1 functions "always" included or only when compiled with "--enable-mpi1-compatibility"?

[wckzhang]

@jsquyres are you aware of the full list of MPI-4.0 items that are supported - or do you know who would know? I'm not aware of what items we have implemented

[wckzhang]

ABI compatibility was added in this PR: #11486

[wckzhang]

Found:

MPI-4.0 updates and additions:

Support for MPI Sessions has been added.

Added partitioned communication using persistent sends and persistent receives.

Added persistent collectives to the MPI_ namespace (they were previously available via the MPIX_ prefix).

Added MPI_Isendrecv() and its variants.

Added support for MPI_Comm_idup_with_info().

Added support for MPI_Info_get_string().

Added support for initial_error_handler and the ERRORS_ABORT infrastructure.

Added error handling for “unbound” errors to MPI_COMM_SELF.

Made MPI_Comm_get_info(), MPI_File_get_info(), and MPI_Win_get_info() compliant to the standard.

Droped unknown/ignored info keys on communicators, files, and windows.

Initial implementations of MPI_COMM_TYPE_HW_GUIDED and MPI_COMM_TYPE_HW_GUIDED added.

in the news, not sure if it's comprehensive but I will refer to this information for the documentation.

[wckzhang]

Added subsection containing MPI-4.0 features - #11498

[wckzhang]

This is a reversal from what we previously publicly stated would happen in Open MPI v5.0.x
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 section has already been completed. See - 3.5.2. Removed MPI APIs

[qkoziol]

@jsquyres - I believe this can be closed as completed. Can you please confirm?

[qkoziol]

Ping @jsquyres - Is this ready to close?

[jsquyres]

Given the amount of time it's taken for me to reply, it would probably be best if someone else verifies that each of the check marks in the description on this issue are actually complete.

[wenduwan]

I will double check.

[wenduwan]

Docs LGTM