* consistent orientation of faces. See the todo entries below for more
* detailed caveats.
*
- * Implementation of Nédélec elements, conforming with the space
- * H<sup>curl</sup>. These elements generate vector fields with tangential
- * components continuous between mesh cells.
+ * Implementation of Nédélec elements. The Nédélec
+ * space is designed to solve problems in which the solution only lives in the
+ * space
+ * $H^\text{curl}=\{ {\mathbf u} \in L_2: \text{curl}\, {\mathbf u} \in L_2\}$,
+ * rather than in the more commonly used space
+ * $H^1=\{ u \in L_2: \nabla u \in L_2\}$. In other words, the solution must
+ * be a vector field whose curl is square integrable, but for which the
+ * gradient may not be square integrable. The typical application for this
+ * space (and these elements) is to the Maxwell equations and corresponding
+ * simplifications, such as the reduced version of the Maxwell equation
+ * that only involves the electric field $\mathbf E$ which has to satisfy
+ * the equation $\text{curl}\, \text{curl}\, {\mathbf E} = 0$ in the
+ * time independent case when no currents are present, or the equation
+ * $\text{curl}\,\text{curl}\,{\mathbf A} = 4\pi{\mathbf j}$ that the
+ * magnetic vector potential $\mathbf A$ has to satisfy in the
+ * time independent case.
*
- * We follow the convention that the degree of Nédélec elements
- * denotes the polynomial degree of the largest complete polynomial subspace
- * contained in the Nédélec space. This leads to the
- * consistently numbered sequence of spaces
+ * The defining
+ * characteristic of functions in $H^\text{curl}$ is that they are in
+ * general discontinuous -- but that if you draw a line in 2d (or a
+ * surface in 3d), then the <i>tangential</i> component(s) of the vector
+ * field must be continuous across the line (or surface) even though
+ * the normal component may not be. As a consequence, the
+ * Nédélec element is constructed in such a way that (i) it is
+ * @ref vector_valued "vector-valued", (ii) the shape functions are
+ * discontinuous, but (iii) the tangential component(s) of the vector field
+ * represented by each shape function are continuous across the faces
+ * of cells.
+ *
+ * Other properties of the Nédélec element are that (i) it is
+ * @ref GlossPrimitive "not a primitive element"; (ii) the shape functions
+ * are defined so that certain integrals over the faces are either zero
+ * or one, rather than the common case of certain point values being
+ * either zero or one. (There is, however, the FE_RaviartThomasNodal
+ * element that uses point values.)
+ *
+ * We follow the commonly used -- though confusing -- definition of the "degree"
+ * of Nédélec elements. Specifically, the "degree" of the element
+ * denotes the polynomial degree of the <i>largest complete polynomial
+ * subspace</i> contained in the finite element space, even if the space may
+ * contain shape functions of higher polynomial degree. The lowest order element
+ * is consequently FE_Nedelec(0), i.e., the Raviart-Thomas element "of degree
+ * zero", even though the functions of this space are in general polynomials of
+ * degree one in each variable. This choice of "degree" implies that the
+ * approximation order of the function itself is <i>degree+1</i>, as with usual
+ * polynomial spaces. The numbering so chosen implies the sequence
* @f[
* Q_{k+1}
* \stackrel{\text{grad}}{\rightarrow}
* \stackrel{\text{div}}{\rightarrow}
* DGQ_{k}
* @f]
- * Consequently, approximation order of the Nédélec space equals the value
- * <i>degree</i> given to the constructor. In this scheme, the lowest order
- * element would be created by the call FE_Nedelec<dim>(0). Note that this
- * follows the convention of Brezzi and Raviart, though not the one used in
- * the original paper by Nédélec.
+ * Note that this follows the convention of Brezzi and Raviart,
+ * though not the one used in the original paper by Nédélec.
*
* This class is not implemented for the codimension one case (<tt>spacedim !=
* dim</tt>).