Wonton Concepts

Wrappers

Mesh and state or data associated with the mesh are fundamental data structures in any physics based application. In general, the application has its own native data structures with its native interface for data access.

This makes it harder to design generic libraries that can work with different applications with different native APIs. One way to overcome this problem is to access data through a wrapper. A wrapper is an implementation of an interface to the native interface and can be used to avoid data copy between application and the library if the wrapper interface provides the essential queries required by the library.

Both Portage and Tangram are templated on mesh and state wrapper types ensuring that any application code can use them regardless of their native API while avoiding data copy.

Wonton primarily serves two purposes:

  1. It defines a common interface to access mesh and field data from any application.
  2. It serves as a repository of example wrappers, specifically to the Jali mesh framework, FleCSI Burton Mesh Specialization and couple of native mesh/state wrappers.

We now describe the common interface and its design.

Mesh Wrapper Design

The mesh wrappers are designed to use a Curiously Recurring Template Pattern (CRTP) over a base class called AuxMeshTopology. The basic mesh wrapper for a particular framework implements methods for various mesh queries. We will discuss the motivation and use for using CRTP design in the next section. Here we provide an overview of what methods the basic mesh wrapper must provide.

The wrapper class must support cells, faces and nodes and adjacency queries between these entities. In 2D, faces are the same as edges and in 1D, faces are the same as nodes. The mesh wrapper class is expected to support the following methods:

  1. Basic
    • int space_dimension() const; // dimensionality of mesh points (1, 2, 3)
    • int num_owned_cells() const;
    • int num_ghost_cells() const;
    • int num_owned_faces() const;
    • int num_ghost_faces() const;
    • int num_owned_nodes() const;
    • int num_ghost_nodes() const;
    • int get_global_id(int const id, Entity_kind const kind) const;
  2. Type information (see for details on Wonton types)
  3. Topology queries
    • void cell_get_faces_and_dirs(int const cellid, std::vector<int> *cfaces, std::vector<int> *cfdirs) const; Here the cfdirs conveys the directions in which the faces are used by the cell. If the natural normal of the face points out of the cell, its direction should be returned as 1, if not, it should be returned as -1
    • void cell_get_nodes(int const cellid, std::vector<int> *cnodes) const;
    • void face_get_nodes(int const faceid, std::vector<int> *fnodes) const;
    • void node_get_cells(int const nodeid, Wonton::Entity_type etype, std::vector<int> *ncells) const;
    • template<long D> void node_get_coordinates(int const nodeid, Wonton::Point<D> *pp) const;

AuxMeshTopology

The basic mesh wrapper provides access to the standard entity types and their topological and geometrical information. However, advanced non-standard types such as sides, corners, etc., may not be provided by the mesh framework. Such advanced types are required for some particular algorithms such as nodal remapping, remapping methods for entities with non-planar faces, etc.

Using the CRTP design allows extending the base mesh to support construction of such advanced topological types. Since AuxMeshTopology needs to make some queries about the basic topology, CRTP is used to allow this kind of mutual invocation from the Derived wrapper type.

Using the CRTP design, the basic mesh framework wrapper looks something like

class Basic_Mesh_Wrapper : public AuxMeshTopology<Basic_Mesh_Wrapper> {...};

In this way, the Basic_Mesh_Wrapper can use its own methods, or defer to AuxMeshTopology to perform more advanced queries.

The definitions of the non-standard subcell entities that the AuxMeshTopology constructs are as follows:

  • 1D: A side is a line segment from a node to the cell. Wedges and corners are the same as the sides.
  • 2D: A side is a triangle formed by the two nodes of an edge/face and the cell center. A wedge is half of a side formed by one node of the edge, the edge center and the cell center. A corner is a quadrilateral formed by the two wedges in a cell at a node.
  • 3D: A side is a tet formed by the two nodes of an edge, a face center and a cell center. A wedge is half a side, formed by a node of the edge, the edge center, the face center and the cell center. A corner is formed by all the wedges of a cell at a node.
auxentities.svg
Illustration for 2D auxiliary entities

In addition to the advanced mesh entities (sides, wedges, and corners), AuxMeshTopology also computes some advanced connectivity information. An example is Wonton::AuxMeshTopology::node_get_cell_adj_nodes(), which, given a node index in the mesh, returns a vector of all the nodes that are attached to all cells attached to the given node. AuxMeshTopology additionally creates iterators over all the various types of mesh entities, provides geometric information (e.g. volumes, centroids, etc.) of the mesh entities, and a method to determine if an entitiy is on the domain boundary (needed for limiting in higher-order remaps).

If one does not use AuxMeshTopology to help extend their mesh wrapper's functionality, one should ensure that their mesh wrapper at least has the same public functions as AuxMeshTopology. For this reason, it is advised to utilize AuxMeshTopology where possible, but to defer to one's own mesh framework wrapper when more efficient methods are available.

Current Support

At present, Wonton provides the following wrappers to external frameworks:

  1. Jali
  2. FleCSI Burton Specialization

Wonton also provides two native mesh and state managers and their wrappers:

  1. Simple Mesh and State: A very light-weight, serial, 2D/3D Cartesian mesh and its state.
  2. Flat Mesh and State: A native framework used internally for redistributing mesh/state data across partitions.

State Wrappers

There is no equivalent of AuxMeshTopology for state wrappers. This is simply because the requirements of a state manager are much less than those of the mesh framework. In particular, the state wrappers need to know how to add data, get data, and query things like the size of the data and where the data lives (Wonton::CELL or Wonton::NODE).

Types

Wonton currently provides the following enumerated types:

  1. Entity_kind: The type of mesh entity.
    • ALL_KIND, ANY_KIND, UNKNOWN_KIND, NODE, EDGE, FACE, CELL, SIDE, WEDGE, CORNER, FACET, BOUNDARY_FACE, PARTICLE
  2. Entity_type: The parallel type of a given entity.
    • TYPE_UNKNOWN, DELETED, PARALLEL_OWNED, PARALLEL_GHOST, BOUNDARY_GHOST, ALL
  3. Element_type: The cell type
    • UNKNOWN_TOPOLOGY, TRI, QUAD, POLYGON, TET, PRISM, PYRAMID, HEX, POLYHEDRON
  4. Field_type: Whether the state i.e. the field is a mesh or multi-material field.
    • UNKNOWN_TYPE_FIELD, MESH_FIELD, MULTIMATERIAL_FIELD

Wonton also provides types for Points, Vectors and Matrices. These are advanced types with the following operators and methods:

  • Point:
    • Operators: [], -p, p+t, c*p, p/c
    • Methods: asV (convert Point to Vector)
  • Vector:
    • Operators: [], -V, V+U, V-U, sV, V/s,
    • Methods: norm, one_norm, max_norm, normalize, is_zero, dot, cross, MaxComponent
  • Matrix:
    • Initialization: Using constant value, from vector of vectors, copy
    • Operators: M = M + C, M = M - C, M = c*M, [], M = M*_v_, M = A*B
    • Methods: inverse, solve (QR decomposition based), data (return matrix data)

Algorithms

  • SVD: Double precision SVD routine. Takes an m-by-n matrix A and decomposes it into UDV, where U, V are left and right orthogonal transformation matrices, and D is a diagonal matrix of singular values.
  • lsfits: Computes a least squares gradient from a set of values. The first point is assumed to be the point where the gradient must be computed and the first value is assumed to the value at this reference point.