diff --git a/doc/images/nodes-vertices.png b/doc/images/nodes-vertices.png new file mode 100644 index 0000000000000000000000000000000000000000..8ee30bd8e29ff657eb8f2a6c2193956c40f9969b Binary files /dev/null and b/doc/images/nodes-vertices.png differ diff --git a/doc/images/nodes-vertices.xoj b/doc/images/nodes-vertices.xoj new file mode 100644 index 0000000000000000000000000000000000000000..fc0bb2950f4eafb2f1adc226b0b23c2f52ba7fc9 Binary files /dev/null and b/doc/images/nodes-vertices.xoj differ diff --git a/doc/mesh.rst b/doc/mesh.rst index 28a332cf5186b7b95e91baff1d336d545ee47f88..2eb79cbe14869b9624cfd655f65130c3bc3ac451 100644 --- a/doc/mesh.rst +++ b/doc/mesh.rst @@ -8,6 +8,40 @@ Mesh management .. automodule:: meshmode.mesh +Design of the Data Structure +---------------------------- + +Why does a :class:`Mesh` need to be broken into :class:`MeshElementGroup` instances? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Elements can be of different types (e.g. triangle, quadrilateral, +tetrahedron, what have you). In addition, elements may vary in the +polynomial degree used to represent them (see also below). + +All these bits of information could in principle be stored by element, +but having large, internally homogeneous groups is a good thing from an +efficiency standpoint. (So that you can, e.g., launch one GPU kernel to +deal with all order-3 triangles, instead of maybe having to dispatch +based on type and size inside the kernel) + +What is the difference between 'vertices' and 'nodes'? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Nodes exist mainly to represent the (potentially non-affine) deformation of +each element, by a one-to-one correspondence with +:attr:`MeshElementGroup.unit_nodes`. They are unique to each element. Vertices +on the other hand exist to clarify whether or not a point shared by two +elements is actually identical (or just happens to be "close"). This is done by +assigning (single, globally shared) vertex numbers and having elements refer to +them. + +Consider the following picture: + +.. image:: images/nodes-vertices.png + +Mesh Data Structure +------------------- + .. autoclass:: MeshElementGroup :members: :undoc-members: