[petsc-dev] Man pages usage of "Collective on XXX"

[Patrick Sanan]

(Forgot to reply-all before)

I'd propose to update the guidelines in the dev manual to say that unless
otherwise specified, collectivity is wrt the communicator associated with
the PETSc object in the first argument slot.


Am Do., 7. Feb. 2019 um 10:35 Uhr schrieb Patrick Sanan <
patrick.sanan at gmail.com>:

>
>
> Am Mi., 6. Feb. 2019 um 21:09 Uhr schrieb Matthew Knepley via petsc-dev <
> petsc-dev at mcs.anl.gov>:
>
>> On Wed, Feb 6, 2019 at 3:03 PM Dave May via petsc-dev <
>> petsc-dev at mcs.anl.gov> wrote:
>>
>>> * I notice that most man pages will say
>>>   Collective on <type>
>>> e.g.
>>>
>>> https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMDA/DMDACreate.html
>>>
>>> * Some others say
>>>   Collective on <implementation-name>
>>>
>>> e.g.
>>>
>>> https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMDA/DMDACreateNaturalVector.html
>>>
>>> or
>>>
>>>
>>> https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMCompositeAddDM.html
>>>
>>> In the former, at least the word "DMDA" gets linked back to the
>>> implementation, whilst in the latter "DMComposite" does not.
>>>
>>> Should "Collective on <implementation-name>" be avoided?
>>> It is potentially somewhat unclear given that the name of the
>>> implementation does not appear anywhere in the arg  list (type or variable
>>> name).
>>>
>>> That said, "collective on <type>" could be similarly criticized if a
>>> method existed with two args of the same type.
>>>
>>> * Many of the methods in this file
>>>
>>>   www.mcs.anl.gov/petsc/petsc-current/src/dm/impls/shell/dmshell.c.html
>>>
>>> simply say "Collective" (without a type or implementation name), or they
>>> say "Logically Collective on XXX"
>>>
>>> I do realize that there is a pattern that the statement "collective on
>>> xxx" or "not collective" applies (implicitly) to the first argument of any
>>> PETSc function call (at least that I've come across) so possibly just
>>> indicating the method as "Collective" might suffice (assuming (i) there is
>>> a pattern and (ii) everyone knows about the pattern).
>>>
>>> Q: Should I make a PR to unify these man pages (and any others I spot)
>>> to just say "Collective on <type>"?
>>>
>>
>> This has always bugged me. It should say, I think, 'Collective on <arg
>> name>", or "Logically collective on <arg name>".
>>
>
> I agree - ultimately I think we're just trying to say "this operation is
> [logically] collective wrt the MPI communicator associated with object
> XXX", so specifying this with respect to an argument makes the most sense.
> Right now the dev manual says "class XXX" which seems potentially ambiguous
> (for instance you could have two arguments for local/global Vecs living on
> different communicators).
>
> In terms of reducing clutter and making things more maintainable, I would
> support explicitly adopting the convention that if no argument is specified
> (e.g. just "Collective"), then this refers to the first argument - I think
> this is very intuitive for class methods (e.g. DMFoo(DM dm,..,) is going to
> be collective or not wrt the communicator associated with "dm").
>
>
>>   Thanks,
>>
>>      Matt
>>
>>
>>> Thanks,
>>>   Dave
>>>
>>>
>>>
>>
>> --
>> What most experimenters take for granted before they begin their
>> experiments is infinitely more interesting than any results to which their
>> experiments lead.
>> -- Norbert Wiener
>>
>> https://www.cse.buffalo.edu/~knepley/
>> <http://www.cse.buffalo.edu/~knepley/>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190207/b00db9d0/attachment.html>