From e6cab24704ee87a54c5edd0990c4ee46fe4e2e38 Mon Sep 17 00:00:00 2001 From: bangerth Date: Wed, 22 Sep 2010 21:03:21 +0000 Subject: [PATCH] Work a bit on the documentation and state order of indices. git-svn-id: https://svn.dealii.org/trunk@22121 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/deal.II/include/fe/fe_values.h | 578 ++++++++++++++----------- 1 file changed, 321 insertions(+), 257 deletions(-) diff --git a/deal.II/deal.II/include/fe/fe_values.h b/deal.II/deal.II/include/fe/fe_values.h index c26b382a4a..2e144be49e 100644 --- a/deal.II/deal.II/include/fe/fe_values.h +++ b/deal.II/deal.II/include/fe/fe_values.h @@ -1875,43 +1875,56 @@ class FEValuesBase : protected FEValuesData, //@} - /// @name FunctionAccess Access to values of global finite element functions + /// @name Access to values and derivatives of global finite element fields //@{ /** - * Returns the values of the - * finite element function - * characterized by - * fe_function restricted to - * the cell, face or subface - * selected the last time the - * reinit function of the - * derived class was called, at - * the quadrature points. + * Returns the values of a finite + * element function restricted to + * the current cell, face or + * subface selected the last time + * the reinit function + * of the derived class was + * called, at the quadrature + * points. * - * If the present cell is not an - * active one the interpolated - * function values are returned. + * If the present cell is not + * active then values are + * interpolated to the current + * cell and point values are + * computed from that. * - * To get values of - * multi-component elements, - * there is another + * This function may only be used + * if the finite element in use + * is a scalar one, i.e. has only + * one vector component. To get + * values of multi-component + * elements, there is another * get_function_values() below, * returning a vector of vectors * of results. * - * This function may only be used if the - * finite element in use is a scalar one, - * i.e. has only one vector component. If - * it is a vector-valued one, then use - * the other get_function_values() - * function. + * @param[in] fe_function A + * vector of values that + * describes (globally) the + * finite element function that + * this function should evaluate + * at the quadrature points of + * the current cell. * - * The function assumes that the - * values object already has the - * correct size. + * @param[out] values The values + * of the function specified by + * fe_function at the quadrature + * points of the current cell. + * The object is assume to + * already have the correct size. + * + * @post values[q] + * will contain the value of the + * field described by fe_function + * at the $q$th quadrature point. * - * The actual data type of the + * @note The actual data type of the * input vector may be either a * Vector<T>, * BlockVector<T>, or one @@ -1929,27 +1942,27 @@ class FEValuesBase : protected FEValuesData, std::vector& values) const; /** - * Access to vector valued finite - * element functions. - * * This function does the same as * the other * get_function_values(), but * applied to multi-component - * elements. + * (vector-valued) elements. The + * meaning of the arguments is as + * explained there. * - * The actual data type of the - * input vector may be either a - * Vector<T>, - * BlockVector<T>, or one - * of the sequential PETSc or - * Trilinos vector wrapper - * classes. It represents a - * global vector of DoF values - * associated with the DofHandler - * object with which this - * FEValues object was last - * initialized. + * @post values[q] + * is a vector of values of the + * field described by fe_function + * at the $q$th quadrature + * point. The size of the vector + * accessed by + * values[q] equals + * the number of components of + * the finite element, + * i.e. values[q](c) + * returns the value of the $c$th + * vector component at the $q$th + * quadrature point. */ template void get_function_values (const InputVector &fe_function, @@ -2099,28 +2112,60 @@ class FEValuesBase : protected FEValuesData, VectorSlice > > values, const bool quadrature_points_fastest) const; + //@} + /// @name Access to gradients of global finite element fields + //@{ + /** - * Compute the gradients of the finite - * element function characterized - * by @p fe_function restricted to - * @p cell at the quadrature points. + * Compute the gradients of a + * finite element at the + * quadrature points of a + * cell. This function is the + * equivalent of the + * corresponding + * get_function_values() function + * (see there for more + * information) but evaluates the + * finite element field's + * gradient instead of its value. * - * If the present cell is not an active - * one the interpolated function values - * are returned. + * This function may only be used + * if the finite element in use + * is a scalar one, i.e. has only + * one vector component. There is + * a corresponding function of + * the same name for + * vector-valued finite elements. * - * This function may only be used if the - * finite element in use is a scalar one, - * i.e. has only one vector component. If - * it is a vector-valued one, then use - * the other get_function_gradients() - * function. + * @param[in] fe_function A + * vector of values that + * describes (globally) the + * finite element function that + * this function should evaluate + * at the quadrature points of + * the current cell. + * + * @param[out] gradients The gradients + * of the function specified by + * fe_function at the quadrature + * points of the current cell. + * The gradients are computed + * in real space (as opposed to + * on the unit cell). + * The object is assume to + * already have the correct size. * - * The function assumes that the - * @p gradients object already has the - * right size. + * @post + * gradients[q] will + * contain the gradient of the + * field described by fe_function + * at the $q$th quadrature + * point. gradients[q][d] + * represents the derivative in + * coordinate direction $d$ at + * quadrature point $q$. * - * The actual data type of the + * @note The actual data type of the * input vector may be either a * Vector<T>, * BlockVector<T>, or one @@ -2132,75 +2177,57 @@ class FEValuesBase : protected FEValuesData, * object with which this * FEValues object was last * initialized. - * - * The output are the gradients - * of the function represented by - * these DoF values, as computed - * in real space (as opposed to - * on the unit cell). */ template void get_function_gradients (const InputVector &fe_function, std::vector > &gradients) const; /** - * @deprecated Use - * get_function_gradients() instead. - */ - template - void get_function_grads (const InputVector &fe_function, - std::vector > &gradients) const; - - /** - * Compute the gradients of the finite - * element function characterized - * by @p fe_function restricted to - * @p cell at the quadrature points. - * - * If the present cell is not an active - * one the interpolated function values - * are returned. - * - * The function assumes that the - * @p gradients object already has the - * right size. - * * This function does the same as - * the other get_function_values(), - * but applied to multi-component - * elements. - * - * The actual data type of the - * input vector may be either a - * Vector<T>, - * BlockVector<T>, or one - * of the sequential PETSc or - * Trilinos vector wrapper - * classes. It represents a - * global vector of DoF values - * associated with the DofHandler - * object with which this - * FEValues object was last - * initialized. + * the other + * get_function_gradients(), but + * applied to multi-component + * (vector-valued) elements. The + * meaning of the arguments is as + * explained there. * - * The output are the gradients - * of the function represented by - * these DoF values, as computed - * in real space (as opposed to - * on the unit cell). + * @post + * gradients[q] is a + * vector of gradients of the + * field described by fe_function + * at the $q$th quadrature + * point. The size of the vector + * accessed by + * gradients[q] + * equals the number of + * components of the finite + * element, + * i.e. gradients[q][c] + * returns the gradient of the + * $c$th vector component at the + * $q$th quadrature + * point. Consequently, + * gradients[q][c][d] + * is the derivative in + * coordinate direction $d$ of + * the $c$th vector component of + * the vector field at quadrature + * point $q$ of the current cell. */ template void get_function_gradients (const InputVector &fe_function, std::vector > > &gradients) const; - /** - * @deprecated Use - * get_function_gradients() instead. + * Function gradient access with + * more flexibility. see + * get_function_values() with + * corresponding arguments. */ template - void get_function_grads (const InputVector &fe_function, - std::vector > > &gradients) const; + void get_function_gradients (const InputVector& fe_function, + const VectorSlice >& indices, + std::vector >& gradients) const; /** * Function gradient access with @@ -2211,28 +2238,33 @@ class FEValuesBase : protected FEValuesData, template void get_function_gradients (const InputVector& fe_function, const VectorSlice >& indices, - std::vector >& gradients) const; + VectorSlice > > > gradients, + bool quadrature_points_fastest = false) const; /** * @deprecated Use * get_function_gradients() instead. */ template - void get_function_grads (const InputVector& fe_function, - const VectorSlice >& indices, - std::vector >& gradients) const; + void get_function_grads (const InputVector &fe_function, + std::vector > &gradients) const; /** - * Function gradient access with - * more flexibility. see - * get_function_values() with - * corresponding arguments. + * @deprecated Use + * get_function_gradients() instead. */ template - void get_function_gradients (const InputVector& fe_function, - const VectorSlice >& indices, - VectorSlice > > > gradients, - bool quadrature_points_fastest = false) const; + void get_function_grads (const InputVector &fe_function, + std::vector > > &gradients) const; + + /** + * @deprecated Use + * get_function_gradients() instead. + */ + template + void get_function_grads (const InputVector& fe_function, + const VectorSlice >& indices, + std::vector >& gradients) const; /** * @deprecated Use @@ -2244,27 +2276,62 @@ class FEValuesBase : protected FEValuesData, std::vector > >& gradients, bool quadrature_points_fastest = false) const; + //@} + /// @name Access to Hessians (second derivatives) of global finite element fields + //@{ + /** * Compute the tensor of second - * derivatives of the finite - * element function characterized - * by @p fe_function restricted - * to @p cell at the quadrature - * points. + * derivatives of a finite + * element at the quadrature + * points of a cell. This + * function is the equivalent of + * the corresponding + * get_function_values() function + * (see there for more + * information) but evaluates the + * finite element field's second + * derivatives instead of its + * value. * - * The function assumes that the - * @p hessians object - * already has the correct size. + * This function may only be used + * if the finite element in use + * is a scalar one, i.e. has only + * one vector component. There is + * a corresponding function of + * the same name for + * vector-valued finite elements. * - * This function may only be used if the - * finite element in use is a scalar one, - * i.e. has only one vector component. If - * it is a vector-valued one, then use - * the other - * get_function_hessians() - * function. + * @param[in] fe_function A + * vector of values that + * describes (globally) the + * finite element function that + * this function should evaluate + * at the quadrature points of + * the current cell. + * + * @param[out] hessians The Hessians + * of the function specified by + * fe_function at the quadrature + * points of the current cell. + * The Hessians are computed + * in real space (as opposed to + * on the unit cell). + * The object is assume to + * already have the correct size. + * + * @post hessians[q] + * will contain the Hessian of + * the field described by + * fe_function at the $q$th + * quadrature + * point. gradients[q][i][j] + * represents the $(i,j)$th + * component of the matrix of + * second derivatives at + * quadrature point $q$. * - * The actual data type of the + * @note The actual data type of the * input vector may be either a * Vector<T>, * BlockVector<T>, or one @@ -2276,54 +2343,43 @@ class FEValuesBase : protected FEValuesData, * object with which this * FEValues object was last * initialized. - * - * The output are the second - * derivatives of the function - * represented by these DoF - * values, as computed in real - * space (as opposed to on the - * unit cell). */ template void get_function_hessians (const InputVector& fe_function, std::vector >& hessians) const; - /** - * Compute the tensor of second - * derivatives of the finite - * element function characterized - * by @p fe_function restricted to - * @p cell at the quadrature points. - * - * The function assumes that the - * @p hessians object already has - * the right size. - * * This function does the same as - * the other one with the same - * name, but applies to - * vector-valued finite elements. - * - * The actual data type of the - * input vector may be either a - * Vector<T>, - * BlockVector<T>, or one - * of the sequential PETSc or - * Trilinos vector wrapper - * classes. It represents a - * global vector of DoF values - * associated with the DofHandler - * object with which this - * FEValues object was last - * initialized. + * the other + * get_function_hessians(), but + * applied to multi-component + * (vector-valued) elements. The + * meaning of the arguments is as + * explained there. * - * The output are the second derivatives - * of the function represented by - * these DoF values, as computed - * in real space (as opposed to - * on the unit cell). + * @post hessians[q] + * is a vector of Hessians of the + * field described by fe_function + * at the $q$th quadrature + * point. The size of the vector + * accessed by + * hessians[q] + * equals the number of + * components of the finite + * element, + * i.e. hessians[q][c] + * returns the Hessian of the + * $c$th vector component at the + * $q$th quadrature + * point. Consequently, + * values[q][c][i][j] + * is the $(i,j)$th component of + * the matrix of second + * derivatives of the $c$th + * vector component of the vector + * field at quadrature point $q$ + * of the current cell. */ template void @@ -2375,35 +2431,66 @@ class FEValuesBase : protected FEValuesData, std::vector > >&, bool = false) const; - /** - * Compute the (scalar) Laplacian - * of the finite element function - * characterized by @p - * fe_function restricted to @p - * cell at the quadrature - * points. The Laplacian output - * vector is equivalent to - * getting - * trace(hessians), - * where hessian would - * be the output of the - * get_function_hessians() - * function. + * Compute the (scalar) Laplacian (i.e. the trace of the tensor of second + * derivatives) of a finite + * element at the quadrature + * points of a cell. This + * function is the equivalent of + * the corresponding + * get_function_values() function + * (see there for more + * information) but evaluates the + * finite element field's second + * derivatives instead of its + * value. * - * The function assumes that the - * @p laplacians object - * already has the correct size. + * This function may only be used + * if the finite element in use + * is a scalar one, i.e. has only + * one vector component. There is + * a corresponding function of + * the same name for + * vector-valued finite elements. * - * This function may only be used if the - * finite element in use is a scalar one, - * i.e. has only one vector component. If - * it is a vector-valued one, then use - * the other - * get_function_laplacians() + * @param[in] fe_function A + * vector of values that + * describes (globally) the + * finite element function that + * this function should evaluate + * at the quadrature points of + * the current cell. + * + * @param[out] laplacians The Laplacians + * of the function specified by + * fe_function at the quadrature + * points of the current cell. + * The Laplacians are computed + * in real space (as opposed to + * on the unit cell). + * The object is assume to + * already have the correct size. + * + * @post laplacians[q] + * will contain the Laplacian of + * the field described by + * fe_function at the $q$th + * quadrature + * point. gradients[q][i][j] + * represents the $(i,j)$th + * component of the matrix of + * second derivatives at + * quadrature point $q$. + * + * @post For each component of + * the output vector, there holds + * laplacians[q]=trace(hessians[q]), + * where hessians would + * be the output of the + * get_function_hessians() * function. * - * The actual data type of the + * @note The actual data type of the * input vector may be either a * Vector<T>, * BlockVector<T>, or one @@ -2415,65 +2502,44 @@ class FEValuesBase : protected FEValuesData, * object with which this * FEValues object was last * initialized. - * - * The output are the traces of - * the second derivatives - * (i.e. Laplacians) of the - * function represented by these - * DoF values, as computed in - * real space (as opposed to on - * the unit cell). */ template void get_function_laplacians (const InputVector& fe_function, std::vector& laplacians) const; - /** - * Compute the (scalar) Laplacian - * of the finite element function - * characterized by @p - * fe_function restricted to @p - * cell at the quadrature - * points. The Laplacian output - * vector is equivalent to - * getting - * trace(hessians), with - * hessian corresponding - * to the output of the - * get_function_hessians() - * function. - * - * The function assumes that the - * @p laplacians object - * already has the correct size. - * * This function does the same as - * the other one with the same - * name, but applies to - * vector-valued finite elements. + * the other + * get_function_laplacians(), but + * applied to multi-component + * (vector-valued) elements. The + * meaning of the arguments is as + * explained there. * - * The actual data type of the - * input vector may be either a - * Vector<T>, - * BlockVector<T>, or one - * of the sequential PETSc or - * Trilinos vector wrapper - * classes. It represents a - * global vector of DoF values - * associated with the DofHandler - * object with which this - * FEValues object was last - * initialized. + * @post laplacians[q] + * is a vector of Laplacians of the + * field described by fe_function + * at the $q$th quadrature + * point. The size of the vector + * accessed by + * laplacians[q] + * equals the number of + * components of the finite + * element, + * i.e. laplacians[q][c] + * returns the Laplacian of the + * $c$th vector component at the + * $q$th quadrature + * point. * - * The output are the traces of - * the second derivatives (i.e. - * Laplacians) of the function - * represented by these DoF - * values, as computed in real - * space (as opposed to on the - * unit cell). + * @post For each component of + * the output vector, there holds + * laplacians[q][c]=trace(hessians[q][c]), + * where hessians would + * be the output of the + * get_function_hessians() + * function. */ template void @@ -2519,8 +2585,6 @@ class FEValuesBase : protected FEValuesData, const VectorSlice >& indices, std::vector >& laplacians, bool quadrature_points_fastest = false) const; - - //@} /** @@ -4108,9 +4172,9 @@ namespace FEValuesViews return symmetrize(return_value); } } - - - + + + template inline typename SymmetricTensor<2, dim, spacedim>::value_type -- 2.39.5