// SPDX-FileCopyrightText: Copyright © DUNE Project contributors, see file LICENSE.md in module root
// SPDX-License-Identifier: LicenseRef-GPL-2.0-only-with-DUNE-exception
/**
\page GeometryGenericGeometry Generic Geometries
@ingroup GeometryReferenceElements

\section GeometryGeometryIntroduction Introduction

In the following we will give a definition of reference
elements and subelement numbering. This is used to
define geometries by prescribing a set of points in
the space \f$ \mathbf{R}^w \f$.

The basic building block for these elements is given
by a recursion formula which assigns to each
set \f$ E \subset \mathbf{R}^d \f$ either 
a prism element 
\f$ E^\vert\subset \mathbf{R}^{d+1} \f$
or a pyramid element 
\f$ E^\circ\subset \mathbf{R}^{d+1} \f$ with
\f$ E^\vert = \lbrace (x,\bar{x}) \mid 
             x \in E, \bar{x} \in [0,1] \rbrace \f$ and
\f$ E^\circ = \lbrace ((1-\bar{x})x,\bar{x}) \mid 
             x \in E, \bar{x} \in [0,1] \rbrace \f$.
The recursion starts with a single point \f$ P_0=0\in\mathbf{R}^0 \f$.

For \f$ d=1,2,3 \f$ this leads to the following elements
- \f$ d=1 \f$: 
  \f$ L_1 = P_0^\vert = P_0^\circ = [0,1] \f$ is a line.
- \f$ d=2 \f$: 
  \f$ Q_2 = L_1^\vert \f$ is a cube and
  \f$ S_2 = L_1^\circ \f$ is a simplex.
- \f$ d=3 \f$: 
  \f$ Q_3 = Q_2^\vert \f$ is a cube,
  \f$ S_3 = S_2^\circ \f$ is a simplex,
  \f$ \mathrm{pyramid}_3 = Q_2^\circ \f$ is a pyramid, and
  \f$ \mathrm{prism}_3   = S_2^\vert \f$ is a prism.
.
In general if 
\f$ Q_d \f$ is a cube then \f$ Q_d^\vert \f$ is also a cube 
and if 
\f$ S_d \f$ is a simplex then \f$ S_d^\circ \f$ is also a simplex.

Based on the recursion formula we can also define 
a numbering of the subentities and also of the
sub-subentities of \f$ E^\vert \f$ or \f$ E^\circ \f$
based on a numbering of \f$ E \f$. For the
subentities of codimension \f$ c \f$ we use the numbering
- \f$ E^\vert \f$:
  the first numbers are assigned to the entities parallel
  to the \f$ x_d-\f$axis in the same order
  as the subentites of the same codimension in \f$ E \f$;
  then to the subentities of codimension \f$ c-1 \f$ 
  in the bottom followed by those in the top. 
- \f$ E^\circ \f$:
  in this case we first number the subentities of 
  codimension \f$ c-1 \f$ in the bottom, followed
  by each subentity based on a subentity of
  codimension \f$ c \f$ in \f$ E \f$.
.
For the subentity of codimension \f$ cc \f$
in a codimension \f$ c \f$ subentity \f$ E' \f$
we use the numbering induced by the 
numbering the reference element corresponding to
\f$ E' \f$.

Here is a graphical representation of the reference elements:
     -# <b>One-dimensional reference element. For d=1 the simplex and cube are identical</b>
       \image html gg_line.png
     -# <b>Two-dimensional reference simplex (a.k.a. triangle)</b>
	   \image html gg_triangle.png
     -# <b>Three-dimensional reference simplex (a.k.a. tetrahedron)</b>
       <table class="imagelist"><tr>
	   <td>\image html gg_tetrahedron.png "Face Numbering"</td>
	   <td>\image html gg_tetrahedron_edges.png "Edge Numbering"</td>
       </tr></table>
     -# <b>Two-dimensional reference cube (a.k.a. quadrilateral)</b>
	   \image html gg_quadrilateral.png
     -# <b>Three-dimensional reference cube (a.k.a. hexahedron)</b>
       <table class="imagelist"><tr>
       <td>\image html gg_hexahedron.png "Face Numbering"</td>
	   <td>\image html gg_hexahedron_edges.png "Edge Numbering"</td>
       </tr></table>
     -# <b>Prism reference element</b>
       <table class="imagelist"><tr>
	   <td>\image html gg_prism.png "Face Numbering"</td>
	   <td>\image html gg_prism_edges.png "Edge Numbering"</td>
       </tr></table>
     -# <b>Pyramid reference element</b>
       <table class="imagelist"><tr>
	   <td>\image html gg_pyramid.png "Face Numbering"</td>
	   <td>\image html gg_pyramid_edges.png "Edge Numbering"</td>
       </tr></table>
       
In addition to the numbering and the corner coordinates
of a reference element \f$ \hat{E} \f$ we also define the
barycenters \f$ b(\hat{E}) \f$,
the volume \f$ |\hat{E}| \f$ and the normals 
\f$ n_i(\hat{E}) \f$ 
to all codimension one subelements.

The recursion formula is also used to define mappings
from reference elements \f$ E \f$ to general polytop
given by a set of coordinates for the corner points -
together with the mapping \f$ \Phi \f$,
the transpose of the Jacobian 
\f$ D\Phi^T(x)\in\mathbf{R}^{d,w} \f$ is also 
defined where \f$ d \f$ is the dimension of the
reference element and \f$ w \f$ the dimension of
the coordinates. 
This suffices to define other necessary parts 
of a Dune geometry by LQ-decomposing \f$ D\Phi^T \f$:
let \f$ D\Phi^T(x) = LQ \f$ be given
with a lower diagonal matrix
\f$ L\in \mathbf{R}^{d,d} \f$
and a matrix \f$ Q\in\mathbf{R}^{d,w} \f$ which
satisfies \f$ Q Q^T = I \f$:
- Jacobian inverse transpose 
  \f[ D\Phi(x)^{-T}:=Q^T L^{-1}. \f]
- Integration element 
  \f[ \sqrt{\mathrm{det}(D\Phi(x)^T D\Phi(x))} =
      \sqrt{\mathrm{det}(LL^T)} = 
      \Pi_{i=1}^d l_{ii}. \f]
- Volume
  \f[ \int_{\hat{E}} \Pi_{i=1}^d l_{ii}(x) d\;x
      = |\hat{E}| \Pi_{i=1}^d l_{ii}(b(\hat{E})). \f]
  (Here some assumptions on the degree of 
   the integration element is used.)
.
The next sections describe the details of the construction.

\section GeometryGeometryTopology Reference Topology

We define the set \f$\mathcal{T}\f$ of reference topologies by the following 
rules:
- \f$\mathcal{T}\f$ contains an element \f$\mathbf{p}\f$ that we call the point
  topology.
- For \f$T \in \mathcal{T}\f$, \f$\mathcal{T}\f$ contains an element 
  \f$T^\vert\f$ that we call the prism over \f$T\f$.
- For \f$T \in \mathcal{T}\f$, \f$\mathcal{T}\f$ contains an element 
  \f$T^\circ\f$ that we call the pyramid over \f$T\f$.
.

For each reference topology \f$T\f$ we define the following values:

- \b Dimension:
The point topology has dimension zero and the dimension of 
a prism or a pyramid topology over \f$t\f$ has dimension  \f$d(t)+1\f$.
- \b Size:
For \f$c=0,\dots,d\f$ with \f$d=d(T)\f$ 
we define the number \f$s_c(T)\f$ through
  - \f$s_0(T)=1\f$.
  - If \f$T=t^\vert\f$ then 
    \f$s_d(T)=2s_{d-1}(t)\f$ and for
    \f$c\in \{1,\dots,d-1\}\f$ we have
    \f$s_c(T)=s_{c}(t)+2s_{c-1}(t)\f$.
  - If \f$T=t^\circ\f$ then 
    \f$s_d(T)=s_{d-1}(t)+1\f$ and for
    \f$c\in \{1,\dots,d-1\}\f$ we have
    \f$s_c(T)=s_{c-1}(t)+s_{c}(t)\f$.
  . 
- \b Subtopology:
Given a reference topology \f$T\f$ of dimension \f$d\f$ and a
codimension \f$c=0,\dots,d\f$ 
we now define the subtopology \f$S_{c,i}(T)\in\mathcal{T}\f$
for \f$i=1,\dots,s_c(T)\f$:
  - \f$S_{0,1}(T)=T\f$ and \f$S_{d,i}(T)=\mathbf{p}\f$
  - For \f$T=t^\vert\f$ and 
    \f$c\in \{1,\dots,d-1\}\f$
    we define using the abbreviations \f$p=s_{c}(t),q=s_{c-1}(t)\f$
    \f[S_{c,i}(T) = \left\{\begin{array}{ll}
                    S_{c,i}(t)^\vert  & \mbox{for}\; i=1,\dots,p, \\
                    S_{c-1,i-p}(t)    & \mbox{for}\; i=p+1,\dots,p+q, \\
                    S_{c-1,i-p-q}(t)  & \mbox{for}\; i=p+q+1,\dots,p+2q.
                    \end{array}\right.
    \f]
  - For \f$T=t^\circ\f$ and 
    \f$c\in \{1,\dots,d-1\}\f$
    we define using the abbreviations \f$p=s_{c}(t),q=s_{c-1}(t)\f$
    \f[S_{c,i}(T) = \left\{\begin{array}{ll}
                    S_{c-1,i}(t)       & \mbox{for}\; i=1,\dots,q, \\
                    S_{c,i-q}(t)^\circ & \mbox{for}\; i=q+1,\dots,q+p.
                    \end{array}\right.
    \f]
.

Notice that the number of vertices (i.e., subtopologies of
codimension\f$d(T)\f$) of a topology \f$T\f$ does not uniquely identify the
topology.
To see this, consider the topologies
\f$T_1 = \mathbf{p}^{\vert\vert\vert\circ\circ}\f$ and
\f$T_2 = \mathbf{p}^{\circ\circ\circ\circ\vert}\f$.
For these topologies we have \f$s_d( T_1 ) = s_d( T_2 ) = 10\f$.


\section GeometryGeometryElement Reference Domains

For each reference topology \f$T\f$ we associate the set of corners
\f$\mathcal{C}(T):=(p_i(T))_{1=1}^{s_d(T)}\subset\mathbf{R}^d(T)\f$ 
defined through 
- \f$T=\mathbf{p}\f$: \f$p_0(T)=0\in\mathbf{R}^0\f$
- \f$T=t^\vert\f$: \f$p_k(T)=(p_k(t),0),p_{d'+k}(T)=(p_k(t),1)\f$
  for \f$k=1,\dots,d'\f$, with \f$d'=s_d(t)\f$.
- \f$T=t^\circ\f$: \f$p_k(T)=(p_k(t),0)\f$ 
  for \f$k=1,\dots,d-1\f$ and \f$p_d(T)=e_d\f$ with
  \f$d=s_d(T)\f$
.
The convex hall of the set of points \f$\mathcal{C}(T)\f$ defines
the reference domain \f$\mathrm{domain}(T)\f$ for the reference topology \f$T\f$;
it follows that
- \f$\mathrm{domain}( \mathbf{p} ) := \lbrace 0 \rbrace \subset \mathbf{R}^0\f$,
- \f$\mathrm{domain}( T^\vert ) := \mathrm{domain}( T ) \times [0,1]\f$,
- \f$\mathrm{domain}( T^\circ )
  := \lbrace ((1-\bar{x})x,\bar{x}) \mid 
             x \in \mathrm{domain}( T ),
             \bar{x} \in [0,1] \rbrace\f$.
.

\section GeometryGeometryMappings Reference Elements and Mappings

A pair \f$E=(T,\Phi)\f$ of a topology \f$T\f$ and a map 
\f$\Phi:\mathrm{domain}( T ) \to \mathbf{R}^w\f$ with \f$w\geq d(T)\f$
is called an element. 

The reference element is the pair 
\f$E(T)=(T,{\rm id})\f$.

For a given set of points 
\f$\mathcal{C}:=(p_i)_{1=1}^{s_d(T)}\subset\mathbf{R}^w\f$
we define a mapping 
\f$\Phi_T(\mathcal{C},\cdot)\mathrm{domain}( T ) \to \mathbf{R}^w\f$
through \f$\Phi_T(\mathcal{C};p_i(T))=p_i\f$ for all
\f$p_i(T)\in \mathcal{C}(T)\f$. This mapping can be expressed using the
recursive definition of the reference topologies through:
- \f$\Phi_{\mathbf{p}}( (p_0) ; x ) = p_0\f$,
- \f$\Phi_{T^\vert}( (p_1,\ldots,p_{s_d(T^\vert)} ; (x,\bar{x}) )
  = (1 - \bar{x}) \Phi_T( p_1,\ldots,p_{s_d(T)} ; x )
    + \bar{x} \Phi_T( p_{s_d(T)+1},\dots,p_{s_d(T^\vert)} ; x )\f$
  with \f$x\in \mathrm{domain}( T )\f$ and \f$\bar{x}\in[0,1]\f$.
- \f$\Phi_{T^\circ}( p_1,\ldots,p_{s_d(T^\circ)}) ; (x,\bar{x}) )
  = (1 - \bar{x}) \Phi_T( p_1,\ldots,p_{s_d(T)-1} ; x )
    + \bar{x} p_{s_d(T^\circ)} \f$ 
  with \f$x\in \mathrm{domain}( T )\f$ and \f$\bar{x}\in[0,1]\f$.
.

\section GeometryGeometryNumbering Numbering of Subelements

Given a reference topology \f$T\f$, a codimension 
\f$c\in\{0,\dots,d(T)\}\f$ and
a subtopology \f$S_{c,i}(T)\f$ 
we define a subset of the corner set \f$\mathcal{C}(T)\f$
\f$ \mathcal{C}_{c,i}(T)=
    (p_{k_j}(T))_{j=1}^{s_{d(S_{c,i}(T)}(S_{c,i}(T))} \f$ 
given by the subsequence
\f$ \mathcal{K}_{c,i}(T)=(k_j)_{j=1}^{s_{d(S_{c,i}(T)}(S_{c,i}(T))} \f$
of \f$ \{1,dots,s_{d(T)}(T)\} \f$:

\f$ \mathcal{C}_{0,0}(T) = \mathcal{C}(T)\f$,
\f$ \mathcal{C}_{d(T),i}(T) = (p_i(T)) \f$,
and for \f$c\in\{1,\dots,d(T)-1\}\f$ we define
\f$ \mathcal{K}_{c,i}(T)=(k_j)_{j=1}^{s_{d(S_{c,i}(T)}(S_{c,i}(T))} \f$
through the recursion
  - \f$T=t^\vert\f$: \n
    For \f$ i=1,\dots,s_c(T) \f$
    we define
    \f$ \mathcal{K}_{c,i}(T)=(k_1,\dots,k_n,
                              k_1+s_{d(t)}(t)\dots,k_n+s_{d(t)}(t)) \f$
    with 
    \f$ \mathcal{K}_{c,i}(T)= \{k_1,\dots,k_n\} \f$. \n
    For \f$ i=s_(T)+1,\dots,s_c(T)+s_{c+1}(T) \f$
    we define
    \f$ \mathcal{K}_{c,i}(T)=(k_1,\dots,k_n) \f$
    with 
    \f$ \mathcal{K}_{c-1,i}(T)= \{k_1,\dots,k_n\} \f$. \n
    For \f$ i=s_c(T)+s_{c+1}(T)+1,\dots,s_c(T)+2s_{c+1}(T) \f$
    we define
    \f$ \mathcal{K}_{c,i}(T)=(k_1+s_{d(t)}(t),\dots,k_n+s_{d(t)}(t)) \f$
    with 
    \f$ \mathcal{K}_{c-1,i}(T)= \{k_1,\dots,k_n\} \f$.
  - \f$T=t^\circ\f$: \n
    For \f$ i=1,\dots,s_{c-1}(T) \f$ 
    we define
    \f$ \mathcal{K}_{c,i}(T)=(k_1,\dots,k_n) \f$
    with 
    \f$ \mathcal{K}_{c-1,i}(T)= \{k_1,\dots,k_n\} \f$. \n
    For \f$ i=s_{c-1}(T)+1,\dots,s_{c-1}(T)+s_c(T) \f$ 
    we define
    \f$ \mathcal{K}_{c,i}(T)=(k_1,\dots,k_n,s_{d(T)}(T)) \f$
    with 
    \f$ \mathcal{K}_{c-1,i}(T)= \{k_1,\dots,k_n\} \f$.
  .

Given these subsets we define subreference elements 
\f$E_{c,i}(T)=(S_{c,i}(T),\Phi_{c,i}(T))\f$
of \f$E(T)\f$ given by the following mapping
\f$ \Phi_{c,i}(T,\cdot)=\Phi(S_{c,i}(T),\mathcal{C}_{c,i}(T),\cdot) \f$.

Furthermore we define a numbering of the subreference
elements of each subreference element in \f$T\f$.
This is the number \f$ k=\mathrm{index}_{c,i,cc,ii}(T)\f$
for \f$c\in\{0,\dots,d(T)\}\f$,
\f$ i\in\{1,\dots,s_c(T)\} \f$, and
\f$ cc\in\{0,\dots,d(S_{c,i})\}\f$,
\f$ ii\in\{1,\dots,s_{cc}(S_{c,i})\} \f$ 
for which
\f[\Phi_{c,i}(S_{c,i}(T))\circ \Phi_{cc,ii}(S_{cc,ii}(S_{c,i}(T))) =
   \Phi_{c+cc,k}(T).\f]
*/
