From ee550b63ba6a58629243b3515d9e1eed5ec41f4d Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 11 Nov 2015 15:32:15 -0600 Subject: [PATCH] Update documentation of FiniteElement::shape_*. The updated documentation makes it clearer what implementations are supposed to do if they overload these functions, and what the default implementation already does. It also fixes incorrect references in shape_3rd/4th_derivatives(). --- include/deal.II/fe/fe.h | 76 +++++++++++++++++++++++++++++++---------- 1 file changed, 58 insertions(+), 18 deletions(-) diff --git a/include/deal.II/fe/fe.h b/include/deal.II/fe/fe.h index 4fd17ef699..8190c41b49 100644 --- a/include/deal.II/fe/fe.h +++ b/include/deal.II/fe/fe.h @@ -654,9 +654,17 @@ public: * ExcShapeFunctionNotPrimitive. In that case, use the * shape_value_component() function. * - * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the - * FiniteElement under consideration depends on the shape of the cell in - * real space. + * Implementations of this function should throw an exception of type + * ExcUnitShapeValuesDoNotExist if the shape functions of the + * FiniteElement under consideration depend on the shape of the cell in + * real space, i.e., if the shape functions are not defined by + * mapping from the reference cell. Some non-conforming elements are + * defined this way, as is the FE_DGPNonparametric class, to name just + * one example. + * + * The default implementation of this virtual function does exactly + * this, i.e., it simply throws an exception of type + * ExcUnitShapeValuesDoNotExist. */ virtual double shape_value (const unsigned int i, const Point &p) const; @@ -682,9 +690,17 @@ public: * should throw an exception of type ExcShapeFunctionNotPrimitive. In that * case, use the shape_grad_component() function. * - * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the - * FiniteElement under consideration depends on the shape of the cell in - * real space. + * Implementations of this function should throw an exception of type + * ExcUnitShapeValuesDoNotExist if the shape functions of the + * FiniteElement under consideration depend on the shape of the cell in + * real space, i.e., if the shape functions are not defined by + * mapping from the reference cell. Some non-conforming elements are + * defined this way, as is the FE_DGPNonparametric class, to name just + * one example. + * + * The default implementation of this virtual function does exactly + * this, i.e., it simply throws an exception of type + * ExcUnitShapeValuesDoNotExist. */ virtual Tensor<1,dim> shape_grad (const unsigned int i, const Point &p) const; @@ -710,9 +726,17 @@ public: * an exception of type ExcShapeFunctionNotPrimitive. In that case, use the * shape_grad_grad_component() function. * - * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the - * FiniteElement under consideration depends on the shape of the cell in - * real space. + * Implementations of this function should throw an exception of type + * ExcUnitShapeValuesDoNotExist if the shape functions of the + * FiniteElement under consideration depend on the shape of the cell in + * real space, i.e., if the shape functions are not defined by + * mapping from the reference cell. Some non-conforming elements are + * defined this way, as is the FE_DGPNonparametric class, to name just + * one example. + * + * The default implementation of this virtual function does exactly + * this, i.e., it simply throws an exception of type + * ExcUnitShapeValuesDoNotExist. */ virtual Tensor<2,dim> shape_grad_grad (const unsigned int i, const Point &p) const; @@ -736,11 +760,19 @@ public: * than one non-zero component (which we refer to with the term non- * primitive), then derived classes implementing this function should throw * an exception of type ExcShapeFunctionNotPrimitive. In that case, use the - * shape_grad_grad_component() function. + * shape_3rd_derivative_component() function. * - * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the - * FiniteElement under consideration depends on the shape of the cell in - * real space. + * Implementations of this function should throw an exception of type + * ExcUnitShapeValuesDoNotExist if the shape functions of the + * FiniteElement under consideration depend on the shape of the cell in + * real space, i.e., if the shape functions are not defined by + * mapping from the reference cell. Some non-conforming elements are + * defined this way, as is the FE_DGPNonparametric class, to name just + * one example. + * + * The default implementation of this virtual function does exactly + * this, i.e., it simply throws an exception of type + * ExcUnitShapeValuesDoNotExist. */ virtual Tensor<3,dim> shape_3rd_derivative (const unsigned int i, const Point &p) const; @@ -764,11 +796,19 @@ public: * than one non-zero component (which we refer to with the term non- * primitive), then derived classes implementing this function should throw * an exception of type ExcShapeFunctionNotPrimitive. In that case, use the - * shape_grad_grad_component() function. - * - * An ExcUnitShapeValuesDoNotExist is thrown if the shape values of the - * FiniteElement under consideration depends on the shape of the cell in - * real space. + * shape_4th_derivative_component() function. + * + * Implementations of this function should throw an exception of type + * ExcUnitShapeValuesDoNotExist if the shape functions of the + * FiniteElement under consideration depend on the shape of the cell in + * real space, i.e., if the shape functions are not defined by + * mapping from the reference cell. Some non-conforming elements are + * defined this way, as is the FE_DGPNonparametric class, to name just + * one example. + * + * The default implementation of this virtual function does exactly + * this, i.e., it simply throws an exception of type + * ExcUnitShapeValuesDoNotExist. */ virtual Tensor<4,dim> shape_4th_derivative (const unsigned int i, const Point &p) const; -- 2.39.5