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

[Patrick Sanan]

Am Do., 7. Feb. 2019 um 15:21 Uhr schrieb Hapla Vaclav <
vaclav.hapla at erdw.ethz.ch>:

>
>
> On 7 Feb 2019, at 15:10, Patrick Sanan via petsc-dev <
> petsc-dev at mcs.anl.gov> wrote:
>
> (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.
>
>
> Let me take e.g.
>
> https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatTranspose.html
> as an example.
>
> So you mean that
>   Collective on Mat
> could be replaced by just
>   Collective
> which would implicitly mean
>   Collective [on Mat mat argument]
>
> That's perhaps quite a good idea!
>
> Note that it's an information also for users, so this interpretation note
> about probably shouldn't be mentioned _only_ in the dev manual.
>
That's a good point - I don't think collectivity as used in the man pages
is explicitly defined anywhere outside of the dev manual.

>
> Cheers,
> Vaclav
>
>
>
> 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/2399dbf6/attachment.html>