meshio Mesh() data structure

meshio's Mesh API

Nomenclature

• Point: An n-dimensional point, mostly 2D planar (x,y) OR 3D volumetric (x,y,z) coordinates. Also known as a node.

• Cell: For example,

  0D vertex, or

  1D line segment, or

  2D planar polygon, e.g. triangle or quadrilateral (also known as a face), or

  3D volumetric element, e.g. tetrahedron or hexahedron

A cell is specified by a list of indices of its points (or corners), i.e. integer indices into some list of points.

The Mesh object

A mesh = meshio.read(...) statement will return a meshio Mesh object.
The user is free to examine, extract, and modify the contents of this object's data members (structures).

Likewise, a user may create a Mesh object from her own data structures, using the Mesh()
constructor, then assigning or appending further data to the Mesh data members.

The Mesh object (class) has the following data members:

Mesh.points

Mesh.points - A 2D NumPy ndarray of point coordinates.
This is one array for all mesh entities within the Mesh object

np.shape(mesh.points)
=> (npts, 2) - 2D planar (x,y) coordinates 
OR
=> (npts, 3) - 3D volumetric (x,y,z) coordinates

In particular, 2D and 3D points cannot be mixed.

The Mesh(points,...) constructor will convert any array-like argument for points, e.g.:

points = [
    [0.0, 0.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 0.0, 1.0],
]

into its internal ndarray type.

Mesh.cells

Mesh.cells - A list [] of CellBlocks.

CellBlock (a meshio class)

CellBlock is a collections.namedtuple-type 2-tuple: (type, data) with named fields:

• CellBlock.type a string denoting the cell type, e.g. 'triangle', out of a given list, e.g., 'line', 'triangle', 'quad', 'tetra', 'pyramid', 'wedge', 'hexahedron'

• CellBlock.data a NumPy 2D ndarray(,dtype=int) of integer indices into the Mesh.points array.

   np.shape(cellBlock.data)
   => (ncells, points_per_cell)  

where ncells is the number of cells in the particular CellBlock, and points_per_cell is the number (cardinality) of point indices needed to specify the (Cellblock).type of cell, e.g. 3 points for a "triangle".

The Mesh(points, cells...) constructor will convert any array-like argument for each CellBlock's data, e.g.:

cells = [("triangle", [[0, 1, 2]])]

into its internal ndarray type.

Multiple CellBlocks in Mesh.cells

In many cases, there is only one CellBlock in the list Mesh.cells, i.e.:

(type, indices_array) = mesh.cells[0]

However, certain applications may find it useful to use multiple CellBlocks. Also,
a number of file formats support some sort of 'block' format. Depending on a file_format's
meshio.read() implementation, one might see e.g. triangle faces distributed over several
(possibly non-contiguous) CellBlocks. (Each of their CellBlock.data arrays will/must
share the same global index base into the common Mesh.points array).

A convenience function for getting all cells of a particular type, distributed
across any/all CellBlocks into one returned indices array or CellBlock is:

data = mesh.get_cells_type("triangle")
# OR
cellblock = meshio.CellBlock("triangle", mesh.get_cells_type("triangle"))

(There is a similar function for retrieving cell_data, as discussed later below.)

Mesh.point_data

Mesh.point_data is a dictionary {} of key: value, where the

• keys are the variable names (arbitrary strings), e.g. "T", "Temperature", "P", "Pressure", and
• a value is a NumPy ndarray of corresponding values for the Mesh.points. All values have shape (num_points, ...) (a meshio.read() for some file_format, e.g. 'Tecplot', may coerce these values to dtype=float).

To retrieve the "temperature" of the third point:

mesh.point_data["temperature"][2]
# => 273.2

Mesh.cell_data

Mesh.cell_data is a dictionary {} of key: value, where the

• keys are the variable names (arbitrary strings), e.g. "T", "Temperature", "P", "Pressure"
  (these needn't be the same variable names as for any Mesh.point_data), and

• a value is a list [] of NumPy ndarrays, each being
  the corresponding values across (assigned to each of) a Mesh.cells's CellBlock.

  The Mesh.cell_data['varname'] value list are the same length as the number of CellBlocks
  in the Mesh.cells list. (This is enforced by the Mesh() constructor, if used).
  An ndarray of values (Mesh.cell_data['varname'][i]) for the ith list entry should be the same length as
  the number of cells in the corresponding ith CellBlock (Mesh.cells[i].data).

To retrieve, for example, the "temperature" of the 4th cell of the first CellBlock:

mesh.cell_data["temperature"][0][3]
# => 300.2

A convenience function for getting all cell_data arrays for a particular cell type,
and variable name, into one returned values array is:

values = mesh.get_cell_data("temperature", "triangle") 

Mesh.point_sets

TODO

Mesh.cell_sets

TODO