meshio API docs?

[frankeye]

Hi, perhaps due to my newbie blindness but I can't find any Mesh class usage docs. The site readme.md is helpful regarding examples/use of meshio for reading/writing a mesh from basic array data. But upon reading and being returned a Mesh object, I'm needing to scan the _mesh.py source to determine how to use the Mesh in my application code. It's not that hard to figure out, but some ambiguities such as below can be perplexing w/o deeper dives:

• Are all cells of certain type (e.g. 'triangle') guaranteed to be in one “i-th” mesh.cells[i], or might they be distributed over several cells[] list elements? Source of ambiguity: _mesh.py: get_cells_type(): use of np.concatenate()

I wouldn't mind contributing a basic API writeup for the meshio site, if provided with some pointers.
Thanks!

[nschloe]

Are all cells of certain type (e.g. 'triangle') guaranteed to be in one “i-th” mesh.cells[i], or might they be distributed over several cells[] list elements? Source of ambiguity: _mesh.py: get_cells_type(): use of np.concatenate()

Many file formats support some sort of "block" formatting, so there can be two separate triangle blocks after another. get_cells_type("triangle") gets all triangle blocks merged.

I wouldn't mind contributing a basic API writeup for the meshio site, if provided with some pointers.

Some other people want documentation, too (#883), so that'd be appreciated.

[frankeye]

Hi Nico,

Attached is 1st draft. I can go further but first wanted to get your feedback/confirmation of acceptable direction.

meshio-mesh-api.zip

[nschloe]

Can you add a Wiki page https://github.com/nschloe/meshio/wiki? (Not sure about the permissions here.)

[frankeye]

I just "saved" it there as a page.

[nschloe]

Perfect. I've edited some thing; feel free to keep it going.

[frankeye]

@tianyikillua:

Per discussion, there is a new Wiki page https://github.com/nschloe/meshio/wiki documenting the Mesh() class/API. I had intended to add in docs for .point_sets and .cell_sets but got confused trying to follow from your initial #352 proposal through all the development path discussions. If you care to provide those docs, here is where I left off with my own (private) draft:

Mesh.point_sets, Mesh.cell_sets

For one or more variable name keys (strings), these entities provide
metadata about (any) particular Mesh.point_data[key] array and
respectively Mesh.cell_data[key][:] arrays' values, specifically intended for integer {(,dtype=int)} values.
A user, application or mesh.read() implementation may consider such an integer value as a
set id (identifier). {BUT WHAT ABOUT FLOAT COERCION???}

For a particular set id value, its entry in Mesh.point_sets and respectively Mesh.cell_sets can be bound to
one or more set names (strings). Now onto how such binding is done:

Mesh.point_sets, Mesh.cell_sets is a dictionary {} of key: value, i.e. the dict:

• keys are the aforementioned set names (arbitrary strings), e.g. "Part1", "Top", "Side",
  and
• a value is a list [], with another list [] entry for each of the Mesh.cells's CellBlocks,.
  Each interior list (for a CellBlock) contains the set id values of those cells.

{Possible confusions: while these Mesh class members were under development, they were previously
named point_tags or cell_tags, node_sets or element_sets}.