Blueprint polyhedral documentation

[nselliott]

In the example for the new polyhedral schema:

    #
    #         0
    #        /|\
    #       / | \ <- e0
    #      /  |  \
    #     /_.-3-._\
    #    1.,  |  ,.4
    #     \ `'2'` /
    #      \  |  /
    # e1 -> \ | /
    #        \|/
    #         5
    #|

    topologies:
      topology:
        coordset: coords
        type: unstructured
        elements:
          shape: polyhedral
          connectivity: [0, 1, 2, 3, 4, 0, 5, 6, 7, 8]
          sizes: [5, 5]
          offsets: [0, 5]
        subelements:
          shape: polygonal
          connectivity: [1, 2, 4, 3, 1, 2, 0, 2, 4, 0, 4, 3, 0, 3, 1, 0, 1, 2, 5, 2, 4, 5, 4, 3, 5, 3, 1, 5]
          sizes: [4, 3, 3, 3, 3, 3, 3, 3, 3]
          offsets: [0, 4, 7, 10, 13, 16, 19, 22, 25]

The elements/connectivity array should be [0, 1, 2, 3, 4, 5, 1, 2, 3, 4], as there are no vertices 6-8.

Related question: Are there any rules for the ordering of the vertices for one element in the connectivity array? In particular I am wondering about elements that are more complicated that regular tets/hexes. Or does any order work as long as the faces are set up correctly in the subelements schema?

[cyrush]

@xjrc can you take a look at this, for the typo -- seems like a small fix we can slip into https://github.com/LLNL/conduit/pull/617.

@nselliott, as far as I know, we don't have strict rules about the windings, etc -- however some part of conduit strive to make choices in a consistent way. I think it's an important detail that we haven't tackled yet.

[cyrush]

@nselliott I think this example might be correct, it's true there are no vertices 6-8, however the polyhedra are composed of the polygons, of which there are 9?

[nselliott]

@cyrush All this time I have been interpreting the elements/connectivity array as consisting of vertices, but now I just re-checked the original discussion where @xjrc introduced this schema and I see that I was wrong. I have some code fixes of my own to make because of this.

I would suggest that this example is confusing because it uses elements that each have both five vertices and five faces, and the first element is composed of both vertices [0,1,2,3,4] and faces [0,1,2,3,4], so it's not immediately obvious that the connectivity array is using the numbers to represent faces rather than vertices. Perhaps an example with hexahedral elements would be more clear?

[cyrush]

I agree we should update with an example with different face counts to avoid confusion. We will tackle this post 0.6.0.