Consistency of tools information interface variable information

[mpiforumbot]

Originally by kathrynmohror on 2013-07-24 08:59:28 -0500

---

The tools information interface allows an implementation return different information for the same variables across processes in a single job and across runs. This could be done for various reasons, e.g. heterogeneous hardware. This would be very confusing for tools.

We want to fix this by specifying that if a variable has the same name, it should have consistent meaning within and across runs.

[mpiforumbot]

Originally by kathrynmohror on 2013-11-11 17:55:18 -0600

---

As a first attempt, I added advice to implementors. Comments welcome.

Although this interface is flexible, implementations should strive for consistency in naming and definitions as much as possible. In particular, variables with the same name should have the same meaning across processes in a single job and across runs.

[mpiforumbot]

Originally by kathrynmohror on 2013-12-15 12:25:13 -0600

---

At the December 2013 forum meeting, we updated the advice to implementors:

Although this interface is flexible, implementations should strive for consistency in naming and definitions as much as possible. For example, variables with the same name should have the same meaning across all MPI processes in a single job.

[mpiforumbot]

Originally by moody20 on 2014-06-04 14:43:06 -0500

---

I like this wording better:

Across all connected processes, use of a given variable, category, or enumeration name must:

• Exhibit the same behavioral semantics.
• Return the same INOUT and OUT integer and enum values from the relevant MPI_T_*_GET_INFO function.
• If sufficiently long string length INOUT parameters are supplied, return the same string valued OUT parameters from the relevant MPI_T_*_GET_INFO function.
• Return a handle to an equivalent MPI object from the relevant MPI_T_*_GET_INFO function.

The above restrictions apply to control variables, performance variables of the same class, categories, and enumerations.

[mpiforumbot]

Originally by jsquyres on 2014-06-05 08:22:14 -0500

---

No, this is not quite right:

1. Performance variables must be distinguished by a (name, class) tuple -- not just names.
2. Your sentence before and after the bullet list seems to be the same...?

After our internal Cisco review, we wanted to change bullet 3 to be more like the others (it's conspicuously different in construction/form).

Should we defer this vote until Japan?

[mpiforumbot]

Originally by jsquyres on 2014-06-05 08:33:08 -0500

---

Martin and I talked -- let's defer this to Japan so that we have time to get the text right (and Kathryn is also unavailable this week; we need to get her input).

[mpiforumbot]

Originally by schulzm on 2014-08-07 09:20:01 -0500

---

Comments on the draft of 8/4 sent by Kathryn:

• Return the same INOUT and OUT integer and enum values from the relevant
  MPI_T_*_GET_INFO function.
  Should include datatype values
• If sufficiently long string length INOUT parameters are supplied, return the same
  string valued OUT parameters from the relevant MPI_T_*_GET_INFO function.
  -> functions
• Return a handle to an equivalent MPI object from the relevant MPI_T_*_GET_INFO
  function.
  This can be removed, INFO calls don’t return handles - we return only the type of MPI object, which is an integer and that is covered by the above
• Similarly, enumerations and categories in connected processes must also obey the above
  restrictions where applicable
  What about “for certain parameters” instead of “where applicable”
• Table:MPI_T_ENUM_GET_INFO should be removed from the table (we decided to allow different numbers in different processes to support Jeff’s use case)
• Table:MPI_T_ENUM_GET_ITEM is a bit strange here, since it is not an GET_INFO call and so doesn’t quite match the text above (minor detail, though)
• Table:MPI_T_ENUM_GET_INFO: we should either have value and name here or neither, if we keep name, it should be contents of name to be consistent
• Table:MPI_T_CVAR_GET_INFO: needs to include contents of name
• Table:MPI_T_PVAR_GET_INFO: needs to include contents of name
• Table:MPI_T_CATEGORY_GET_INFO: needs to include contents of name

[mpiforumbot]

Originally by kathrynmohror on 2014-11-24 11:27:54 -0600

---

Uploaded text for reading at December 2014 meeting in San Jose.

[mpiforumbot]

Originally by schulzm on 2014-12-11 03:13:21 -0600

---

Additional comment: Jeff suggested to remove the "also" in the three sentences about the equivalence of the descriptions for control variables, performance variables and categories. This is ticket 0 and should be applied when this ticket is added to the main MPI repo.

[mpiforumbot]

Originally by jsquyres on 2015-01-20 16:25:47 -0600

---

Looks good in the PDF sent around on Jan 5, 2015: http://lists.mpi-forum.org/mpiwg-tools/2015/01/1111.php.

However, I notice that you did not apply the ticket 0 change recommended in comment 10. Was there a reason for that?

[mpiforumbot]

Originally by kathrynmohror on 2015-01-27 17:28:32 -0600

---

Possibly I handed you a build without the change? Or maybe I misunderstood where you wanted it? Please look at the new pdf and see if I got the ticket 0 change.

[mpiforumbot]

Originally by RolfRabenseifner on 2015-02-05 04:13:39 -0600

---

I cannot see the changes that are done by this ticket.
The attached pdf has no Notation about that.
The maybe original pdf maybe now overwritten.

I cannot detect, whether this Change requires changes in the implementation or usage
of MPI libraries. In this case, a changelog entry is needed and still missing.

Please check.

[mpiforumbot]

Originally by kathrynmohror on 2015-02-08 10:24:51 -0600

---

Attachment added: tools-3.pdf (318.7 KiB)

[mpiforumbot]

Originally by kathrynmohror on 2015-02-08 10:37:42 -0600

---

Rolf, I attached a new pdf. I'm not sure why the last one did not have the change markings.

Change Log:

• Section 14.3, page 561, after line 22, new paragraph clarifying intent of variable names in the tools information interface.
• Section 14.3, page 561 in advice to users clarification on intent of variable names in the tools information interface.
• Section 14.3.3, page 563, new paragraph clarifying variable name equivalence in the tools information interface.
• Section 14.3.6, page 569 after line 12, clarification of parameters that must be identical for equivalent control variable names.
• Section 14.3.7, page 577 after line 22, clarification of parameters that must be identical for equivalent performance variable names.
• Section 14.3.8, page 586 after line 34, clarification of parameters that must be identical for equivalent category names.

[mpiforumbot]

Originally by RolfRabenseifner on 2015-02-08 22:33:26 -0600

---

Kathryn,

your changelog does not fit to the usual scheme. The scheme is always

-Section ... on page nnn.* or Sections ..., ..., and ... on pages nnn, mmm, and kkk. . [[BR]]
Text.

If the text is related to a function or constant or any entity that is in one of the index sections at the end of the book, this entity should be mentioned, because looking in the index tells that there is a changlog entry.
Here a starting Point - but you better know your content (highlighting only to show my changes):

• Section 14.3 on page 561.[[BR]]
  New paragraph and advice to users clarifying intent of variable names in the tools information interface.
• Section 14.3.3 on page 563.[[BR]]
  New paragraph clarifying variable name equivalence in the tools information interface.
• Section 14.3.6 on page 567 (i.e. not 569).[[BR]]
  In function MPI_T_CVAR_GET_INFO, clarification of parameters that must be identical for equivalent control variable names across connected processes.
• ...

[mpiforumbot]

Originally by kathrynmohror on 2015-02-09 08:37:49 -0600

---

Thanks Rolf. Trying again:

• Section 14.3 on page 561.
  New paragraph and advice to users clarifying intent of variable names in the tools information interface.
• Section 14.3.3 on page 563.
  New paragraph clarifying variable name equivalence in the tools information interface.
• Section 14.3.6 on page 567.
  In function MPI_T_CVAR_GET_INFO, clarification of parameters that must be identical for equivalent control variable names across connected processes.
• Section 14.3.7 on page 577.
  In function MPI_T_PVAR_GET_INFO, clarification of parameters that must be identical for equivalent performance variable names across connected processes.
• Section 14.3.8 on page 586.
  In function MPI_T_CATEGORY_GET_INFO, clarification of parameters that must be identical for equivalent category names across connected processes.

[mpiforumbot]

Originally by RolfRabenseifner on 2015-02-09 08:56:54 -0600

---

Can we put the last three together:

• Sections 14.3.6, 14.3.7, and 14.3.8 on pages 567, 577, 586. [[BR]]
  In functions MPI_T_CVAR_GET_INFO, MPI_T_PVAR_GET_INFO, and MPI_T_CATEGORY_GET_INFO, clarification of parameters that must be identical for equivalent control variable / performance variable / category names across connected processes.

[mpiforumbot]

Originally by kathrynmohror on 2015-02-09 09:08:24 -0600

---

Yes, combining them works.

[mpiforumbot]

Originally by jsquyres on 2015-12-08 11:54:18 -0600

---

This was included in MPI-3.1. Closing this ticket.