[petsc-dev] uninformative docs for DMPlexGetStratumIS and DMPlexGetStratumSize

[Matthew Knepley]

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


>     "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.

    Matt


> DMPlexSetLabelValue?  Stripping the extra layer of interfaces sounds
> great to me.
>
> Geoffrey
>



-- 
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20131120/82344230/attachment.html>