[petsc-dev] uninformative docs for DMPlexGetStratumIS and DMPlexGetStratumSize

[Matthew Knepley]

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.


> 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().

    Matt


>
> 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/8473e7ad/attachment.html>