[petsc-dev] uninformative docs for DMPlexGetStratumIS and DMPlexGetStratumSize

[Geoffrey Irving]

On Wed, Nov 20, 2013 at 6:22 PM, Matthew Knepley <knepley at gmail.com> wrote:
> On Wed, Nov 20, 2013 at 6:58 PM, Geoffrey Irving <irving at naml.us> wrote:
>>
>> On Wed, Nov 20, 2013 at 3:49 PM, Matthew Knepley <knepley at gmail.com>
>> wrote:
>> > On Tue, Nov 19, 2013 at 4:35 PM, Geoffrey Irving <irving at naml.us> wrote:
>> >>
>> >> The documentation for DMPlexGetStratumIS helpfully explains that the
>> >> "value" argument is
>> >>
>> >>     - value - The stratum value
>> >
>> > This is exactly right. A DMLabel is a map from value --> {set of
>> > integers}.
>> > There are no builtin semantics on the values.
>> >
>> >> One has to look in DMPlexStratify to find that the value is probably
>> >> (the word "value" isn't actually used) either the dimension or the
>> >> codimension.  But not which!
>> >
>> > DMPlexStratify() builds a DMLabel called "depth". The values in this
>> > label
>> > are point depths in the mesh graph.
>>
>> Can I fix the documentation for DMPlexStatify to say this?  Currently
>> it says it "might" do something like that:
>
>
> Yes

Done.  I merged this with my typo fixes as irving/doc-cleanup, as per
Jed's request.

>>     "The normal association for the point grade is element dimension
>> (or co-dimension). For instance, all vertices would
>>   have depth 0, and all edges depth 1. Likewise, all cells heights
>> would have height 0, and all faces height 1."
>>
>> >> The documentation for DMPlexStratify seems to imply that the meaning
>> >> of the stratum value is up to the user.  Is that right?  If so it
>> >> makes it hard to design robust libraries; the library would have to
>> >> either know how the DMPlex was created or reverse engineer the
>> >> dimension 0 stratum from the coordinate section (or similar
>> >> hideousness).
>> >>
>> >> If there is a convention, can I add it to the documentation of
>> >> DMPlexGetStratumIS and DMPlexGetStratumSize?
>> >
>> > These are documenting the generic DMLabel interface. These functions are
>> > in fact just the delegator pattern, where they dispatch to the named
>> > label. I
>> > am considering just eliminating all of them in favor of DMGetLabel().
>>
>> Thanks for the explanations.  Is there a reason why you use the word
>> "Stratum" here but "Value" elsewhere in the label interface, such as
>
> Yes, value refers to the integer which maps to a stratum, which is a set of
> integers.

Thanks, that makes sense.

Geoffrey