From a8f52de72a9d368cb7034b77e51c134c05468b09 Mon Sep 17 00:00:00 2001
From: Daniel Garcia-Sanchez <daniel.garcia-sanchez@insp.upmc.fr>
Date: Tue, 10 Sep 2019 23:25:43 +0200
Subject: [PATCH] Clarify the degree of the elements NedelecSZ and Nedelec

---
 include/deal.II/fe/fe_nedelec.h    | 14 ++++++++++----
 include/deal.II/fe/fe_nedelec_sz.h | 13 +++++++++++--
 source/fe/fe_nedelec_sz.cc         | 12 ++++++------
 3 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/include/deal.II/fe/fe_nedelec.h b/include/deal.II/fe/fe_nedelec.h
index 65f3f0adbe..b208cb79ba 100644
--- a/include/deal.II/fe/fe_nedelec.h
+++ b/include/deal.II/fe/fe_nedelec.h
@@ -114,10 +114,16 @@ class FE_Nedelec : public FE_PolyTensor<dim>
 {
 public:
   /**
-   * Constructor for the N&eacute;d&eacute;lec element of given @p order.
-   * The maximal polynomial degree of the shape functions is
-   * <code>order+1</code> (in each variable; the total polynomial degree
-   * may be higher).
+   * Constructor for the Nedelec element of given @p order. The maximal
+   * polynomial degree of the shape functions is `order+1` (in each variable;
+   * the total polynomial degree may be higher). If `order = 0`, the element is
+   * linear and has degrees of freedom only on the edges. If `order >=1` the
+   * element has degrees of freedom on the edges, faces and volume. For example
+   * the 3D version of FE_Nedelec has 12 degrees of freedom for `order = 0`
+   * and 54 for `degree = 1`. It is important to have enough quadrature points
+   * in order to perform the quadrature with sufficient accuracy.
+   * For example [QGauss<dim>(order + 2)](@ref QGauss) can be used for the
+   * quadrature formula, where `order` is the order of FE_Nedelec.
    */
   FE_Nedelec(const unsigned int order);
 
diff --git a/include/deal.II/fe/fe_nedelec_sz.h b/include/deal.II/fe/fe_nedelec_sz.h
index 57de49d51f..43250ddd04 100644
--- a/include/deal.II/fe/fe_nedelec_sz.h
+++ b/include/deal.II/fe/fe_nedelec_sz.h
@@ -77,9 +77,18 @@ public:
                 "FE_NedelecSZ is only implemented for dim==spacedim!");
 
   /**
-   * Constructor for an element of given @p degree.
+   * Constructor for the NedelecSZ element of given @p order. The maximal
+   * polynomial degree of the shape functions is `order+1` (in each variable;
+   * the total polynomial degree may be higher). If `order = 0`, the element is
+   * linear and has degrees of freedom only on the edges. If `order >=1` the
+   * element has degrees of freedom on the edges, faces and volume. For example
+   * the 3D version of FE_NedelecSZ has 12 degrees of freedom for `order = 0`
+   * and 54 for `degree = 1`. It is important to have enough quadrature points
+   * in order to perform the quadrature with sufficient accuracy.
+   * For example [QGauss<dim>(order + 2)](@ref QGauss) can be used for the
+   * quadrature formula, where `order` is the order of FE_NedelecSZ.
    */
-  FE_NedelecSZ(const unsigned int degree);
+  FE_NedelecSZ(const unsigned int order);
 
   virtual UpdateFlags
   requires_update_flags(const UpdateFlags update_flags) const override;
diff --git a/source/fe/fe_nedelec_sz.cc b/source/fe/fe_nedelec_sz.cc
index b60fdc07c1..d1dc78ba20 100644
--- a/source/fe/fe_nedelec_sz.cc
+++ b/source/fe/fe_nedelec_sz.cc
@@ -21,14 +21,14 @@ DEAL_II_NAMESPACE_OPEN
 
 // Constructor:
 template <int dim, int spacedim>
-FE_NedelecSZ<dim, spacedim>::FE_NedelecSZ(const unsigned int degree)
+FE_NedelecSZ<dim, spacedim>::FE_NedelecSZ(const unsigned int order)
   : FiniteElement<dim, dim>(
-      FiniteElementData<dim>(get_dpo_vector(degree),
+      FiniteElementData<dim>(get_dpo_vector(order),
                              dim,
-                             degree + 1,
+                             order + 1,
                              FiniteElementData<dim>::Hcurl),
-      std::vector<bool>(compute_num_dofs(degree), true),
-      std::vector<ComponentMask>(compute_num_dofs(degree),
+      std::vector<bool>(compute_num_dofs(order), true),
+      std::vector<ComponentMask>(compute_num_dofs(order),
                                  std::vector<bool>(dim, true)))
 {
   Assert(dim >= 2, ExcImpossibleInDim(dim));
@@ -43,7 +43,7 @@ FE_NedelecSZ<dim, spacedim>::FE_NedelecSZ(const unsigned int degree)
     }
 
   // Generate the 1-D polynomial basis.
-  create_polynomials(degree);
+  create_polynomials(order);
 }
 
 
-- 
2.39.5