Documentation of global variables

[zerothi]

Is your feature request related to a problem? Please describe.
The documentation rarely mentions any global variables, and they do not have their own entries.

For instance MPI_COMM_WORLD is sparsely mentioned, but will not have its own entry.

Describe the solution you'd like

I would like a block called Constants (or whatever) under section 7 man pages that describes some constants:

• MPI_COMM_WORLD
• MPI_COMM_SELF
• MPI_COMM_PARENT
• MPI_STATUS/STATUSES_IGNORE
• MPI_ANY_SOURCE/TAG
• ...

Additionally there are no default list of data-types:

• MPI_INT/INTEGER etc

[jsquyres]

This information is technically already in the MPI standard document as part of the appendixes. Is it worth repeating that information in our docs? (that's an honest question, not a snarky question)

Or would it be worth having a section 7 page saying "There are a whole bunch of constants, such as MPI_COMM_WORLD, that are all documented in the MPI Standard document (including link to the mpi-forum.org PDF) ..."?

Additionally, both man pages that are currently in section 5 ("file formats") should probably be in section 7 ("overview"). It would be worth moving those.

[zerothi]

This information is technically already in the MPI standard document as part of the appendixes. Is it worth repeating that information in our docs? (that's an honest question, not a snarky question)

I think so, lots of students (including my students) :) will search the API documentation for information, and they can't find information about such constants. We could guide them towards the standard, however the standard is more a documentation for implementers of MPI and less for users of MPI. This is not to say that the standard is not good for users of MPI (it definitely is). But users will generally find their information other places than the standard.

Or would it be worth having a section 7 page saying "There are a whole bunch of constants, such as MPI_COMM_WORLD, that are all documented in the MPI Standard document (including link to the mpi-forum.org PDF) ..."?

I think it would be better to have it in the documentation. Not much needs to be written, there aren't that many constants.

Additionally, both man pages that are currently in section 5 ("file formats") should probably be in section 7 ("overview"). It would be worth moving those.

I can't find your section 5 or the appendix here: https://www.open-mpi.org/doc/current/.
I can't find the appendix here: https://docs.open-mpi.org/en/v5.0.x/index.html

[jsquyres]

Sorry -- I might not have been clear:

• My references to "the appendixes" was to the MPI 4 doc appendixes. I.e., there's listing of all constants / types in the MPI 4 doc appendixes.
• When I talk about Open MPI docs, I'm only referring to the docs on the git main and v5.0.x branches (where we fundamentally revamped the docs and man pages to be much much better). On main/v5.0.x, there's some section 5 man pages that should really be in section 7. Here's the link to the v5.0.x docs -- it's the same for the main branch docs: https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man5/index.html

In terms of listing the constants: ok, good enough. If you're thinking mainly about lists of constants and their types, it might be better to generate these lists from the (still unofficial but from the same code that generated the MPI-4 PDF) MPI-4 Python export. That would also make it easier to maintain over time (i.e., no human would need to remember to add / remove constants from the list -- that would happen automatically as the upstream MPI Forum Python gets updated). We could simply choose which version of the MPI spec's Python to use here in Open MPI. Note that the MPI Forum Python only started for MPI-4.0 -- it doesn't exist for versions of the MPI spec before that. Open MPI's main/v5.0.x branches are close to the MPI-4.0 specification, but are not complete.

[zerothi]

Ok, I'll think about this and make a PR. :)
Thanks for your go!

[jsquyres]

Here's a presentation I gave to the Forum about the Pythonization effort a while ago to give you an overview of what I'm talking about. It changed a little after that, but most of what's in that presentation is still true / used in the >= MPI-4.0 docs.

If you want to work on generating stuff from the Python, we should get in touch with @martinruefenacht to find where the repo is that has the most recent work in this area.

[zerothi]

Ok, I would like to give it a try, (on main).

[jsquyres]

Ok, I would like to give it a try, (on main).

Great! FWIW: that's our general development scheme, anyway -- we develop on main, and then we cherry-pick to release branches.

[zerothi]

Yes, it was more to clarify my intent.

I'll wait for more information from @martinruefenacht

[martinruefenacht]

I believe the MPI Forum organization let's me give access to my own fork to external users so yes we can arrange for you to get access through that. The Pythonization work has not continued much since 2021 (day job is different now). However I will soon be receiving a student from Tony Skjellum to work with me on it so I can actually have someone do something.

We currently have a somewhat incomplete type system through the KINDS that we have. Constants are not in at all in the Python API of the MPI Standard, but this is the top on the TODO list.

So in respect to your top query, constants is a no go for about a month, after that we should have access programmatically (depending on how fast the student is). Datatypes in C/F90/F08 should be able to be extracted, but you won't get much meta data information at the moment. How about we arrange a meeting to discuss and give you a walk through? martin.ruefenacht@lrz.de if you want to email me.