Finite element access/FEValues classes

Collaboration diagram for Finite element access/FEValues classes:

Topics
	Handling vector valued problems

Namespaces
namespace	CellSimilarity
namespace	internal
namespace	FEValuesExtractors
namespace	FEValuesViews

Classes
class	internal::FEValuesImplementation::FiniteElementRelatedData< dim, spacedim >
class	FEValues< dim, spacedim >
class	FEFaceValuesBase< dim, spacedim >
class	FEFaceValues< dim, spacedim >
class	FESubfaceValues< dim, spacedim >
class	FEValuesBase< dim, spacedim >
struct	FEValuesExtractors::Scalar
struct	FEValuesExtractors::Vector
struct	FEValuesExtractors::SymmetricTensor< rank >
struct	FEValuesExtractors::Tensor< rank >
class	FEValuesViews::Scalar< dim, spacedim >
class	FEValuesViews::Vector< dim, spacedim >
class	FEValuesViews::SymmetricTensor< 2, dim, spacedim >
class	FEValuesViews::Tensor< 2, dim, spacedim >
class	internal::FEValuesImplementation::MappingRelatedData< dim, spacedim >
class	NonMatching::FEImmersedSurfaceValues< dim >

Enumerations
enum	UpdateFlags {   update_default = 0 , update_values = 0x0001 , update_gradients = 0x0002 , update_hessians = 0x0004 ,   update_3rd_derivatives = 0x0008 , update_boundary_forms = 0x0010 , update_quadrature_points = 0x0020 , update_JxW_values = 0x0040 ,   update_normal_vectors = 0x0080 , update_jacobians = 0x0100 , update_jacobian_grads = 0x0200 , update_inverse_jacobians = 0x0400 ,   update_covariant_transformation = 0x0800 , update_contravariant_transformation = 0x1000 , update_transformation_values = 0x2000 , update_transformation_gradients = 0x4000 ,   update_volume_elements = 0x10000 , update_jacobian_pushed_forward_grads = 0x100000 , update_jacobian_2nd_derivatives = 0x200000 , update_jacobian_pushed_forward_2nd_derivatives = 0x400000 ,   update_jacobian_3rd_derivatives = 0x800000 , update_jacobian_pushed_forward_3rd_derivatives = 0x1000000 , update_rescale = 0x2000000 , update_piola = update_volume_elements | update_contravariant_transformation ,   update_mapping }

Functions
template<typename StreamType >
StreamType &	operator<< (StreamType &s, const UpdateFlags u)
UpdateFlags	operator| (const UpdateFlags f1, const UpdateFlags f2)
UpdateFlags &	operator|= (UpdateFlags &f1, const UpdateFlags f2)
UpdateFlags	operator& (const UpdateFlags f1, const UpdateFlags f2)
UpdateFlags &	operator&= (UpdateFlags &f1, const UpdateFlags f2)

Detailed Description

The classes in this topic are used when one wants to assemble matrices or vectors. They link finite elements, quadrature objects, and mappings: the finite element classes describe a finite element space on a unit cell (i.e. the unit line segment, square, or cube [0,1]^d), the quadrature classes describe where quadrature points are located and what weight they have, and the mapping classes describe how to map a point from the unit cell to a real cell and back. Since integration happens at quadrature points on the real cell, and needs to know their location as well as the values and gradients of finite element shape functions at these points. The FEValues class coordinates getting this information. For integrations on faces (for example for integration on the boundary, or interfaces between cells), the FEFaceValues class offers similar functionality as the FEValues class does for cells. Finally, the FESubfaceValues class offers the possibility to ingrate on parts of faces if the neighboring cell is refined and the present cell shares only a part of its face with the neighboring cell. If vector-valued elements are used, the FEValues and related classes allow access to all vector components; if one wants to pick individual components, there are extractor classes that make this task simpler, as described in the Handling vector valued problems topic.

The last member of this group, the UpdateFlags enumeration, is used as an optimization: instead of letting the FEValues class compute every possible piece of data relating to a given finite element on a cell, you have to specify up front which information you are actually interested in. The UpdateFlags enumeration is used to offer symbolic names denoting what you want the FEValues class to compute.

All these classes are used in all tutorial programs from step-3 onward, and are described there in significant detail.

The actual workings of the FEValues class and friends is complicated because it has to be general yet efficient. The page on The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues attempts to give an overview of how this works.

In the grand scheme of things, the pieces of this topic interact with a variety of other parts of the library:

Enumeration Type Documentation

UpdateFlags

enum UpdateFlags

The enum type given to the constructors of FEValues, FEFaceValues and FESubfaceValues, telling those objects which data will be needed on each mesh cell.

Selecting these flags in a restrictive way is crucial for the efficiency of FEValues::reinit(), FEFaceValues::reinit() and FESubfaceValues::reinit(). Therefore, only the flags actually needed should be selected. It is the responsibility of the involved Mapping and FiniteElement to add additional flags according to their own requirements. For instance, most finite elements will add update_covariant_transformation if update_gradients is selected. By default, all flags are off, i.e. no reinitialization will be done.

You can select more than one flag by concatenation using the bitwise or operator|(UpdateFlags,UpdateFlags).

Use of these flags flags

More information on the use of this type both in user code as well as internally can be found in the documentation topics pages on The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues and How Mapping, FiniteElement, and FEValues work together.

Enumerator
update_default	No update.
update_values	Shape function values. Compute the values of the shape functions at the quadrature points on the real space cell. For the usual Lagrange elements, these values are equal to the values of the shape functions at the quadrature points on the unit cell, but they are different for more complicated elements, such as FE_RaviartThomas elements.
update_gradients	Shape function gradients. Compute the gradients of the shape functions in coordinates of the real cell.
update_hessians	Second derivatives of shape functions. Compute the second derivatives of the shape functions in coordinates of the real cell.
update_3rd_derivatives	Third derivatives of shape functions. Compute the third derivatives of the shape functions in coordinates of the real cell
update_boundary_forms	Outer normal vector, not normalized. Vector product of tangential vectors, yielding a normal vector with a length corresponding to the surface element; may be more efficient than computing both.
update_quadrature_points	Transformed quadrature points. Compute the quadrature points location in real cell coordinates. FEValues objects take the quadrature point locations on the reference cell as an argument of the constructor (via the Quadrature object). For most finite elements, knowing the location of quadrature points on the reference cell is all that is necessary to evaluate shape functions, evaluate the mapping, and other things. On the other hand, if you want to evaluate a right hand side function \(f(\mathbf x_q)\) at quadrature point locations \(\mathbf x_q\) on the real cell, you need to pass this flag to the FEValues constructor to make sure you can later access them. There are contexts other than FEValues (and related classes) that take update flags. An example is the DataPostprocessor class (and derived classes). In these cases, the update_quadrature_points flag is generally understood to update the location of "evaluation points", i.e., the physical locations of the points at which the solution is evaluated. As a consequence, the flag is misnamed in these contexts: No quadrature (i.e., computation of integrals) is involved, and consequently what is being updated is, in the context of DataPostprocessor, the member variable DataPostprocessorInputs::CommonInputs::evaluation_points.
update_JxW_values	Transformed quadrature weights. Compute the quadrature weights on the real cell, i.e. the weights of the quadrature rule multiplied with the determinant of the Jacobian of the transformation from reference to real cell.
update_normal_vectors	Normal vectors. Compute the normal vectors, either for a face or for a cell of codimension one. Setting this flag for any other object will raise an error.
update_jacobians	Volume element. Compute the Jacobian of the transformation from the reference cell to the real cell.
update_jacobian_grads	Gradient of volume element. Compute the derivatives of the Jacobian of the transformation.
update_inverse_jacobians	Volume element. Compute the inverse Jacobian of the transformation from the reference cell to the real cell.
update_covariant_transformation	Covariant transformation. Compute all values the Mapping needs to perform a contravariant transformation of vectors. For special mappings like MappingCartesian this may be simpler than update_inverse_jacobians.
update_contravariant_transformation	Contravariant transformation. Compute all values the Mapping needs to perform a contravariant transformation of vectors. For special mappings like MappingCartesian this may be simpler than update_jacobians.
update_transformation_values	Shape function values of transformation. Compute the shape function values of the transformation defined by the Mapping.
update_transformation_gradients	Shape function gradients of transformation. Compute the shape function gradients of the transformation defined by the Mapping.
update_volume_elements	Determinant of the Jacobian. Compute the volume element in each quadrature point.
update_jacobian_pushed_forward_grads	Compute the derivatives of the Jacobian of the transformation pushed forward to the real cell coordinates.
update_jacobian_2nd_derivatives	Compute the second derivatives of the Jacobian of the transformation.
update_jacobian_pushed_forward_2nd_derivatives	Compute the second derivatives of the Jacobian of the transformation pushed forward to the real cell coordinates.
update_jacobian_3rd_derivatives	Compute the third derivatives of the Jacobian of the transformation.
update_jacobian_pushed_forward_3rd_derivatives	Compute the third derivatives of the Jacobian of the transformation pushed forward to the real cell coordinates.
update_rescale	Update rescaling for Hermite elements.
update_piola	Values needed for Piola transform. Combination of the flags needed for Piola transform of Hdiv elements.
update_mapping	Combination of the flags that require a mapping calculation

Definition at line 63 of file fe_update_flags.h.

Function Documentation

operator<<()

template<typename StreamType >

StreamType & operator<< ( StreamType & s, const UpdateFlags u )

inline

Output operator which outputs update flags as a set of or'd text values.

The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues

Definition at line 250 of file fe_update_flags.h.

operator|()

UpdateFlags operator| ( const UpdateFlags f1, const UpdateFlags f2 )

inline

Global operator which returns an object in which all bits are set which are either set in the first or the second argument. This operator exists since if it did not then the result of the bit-or operator | would be an integer which would in turn trigger a compiler warning when we tried to assign it to an object of type UpdateFlags.

The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues

Definition at line 308 of file fe_update_flags.h.

operator|=()

UpdateFlags & operator|= ( UpdateFlags & f1, const UpdateFlags f2 )

inline

Global operator which sets the bits from the second argument also in the first one.

The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues

Definition at line 323 of file fe_update_flags.h.

operator&()

UpdateFlags operator& ( const UpdateFlags f1, const UpdateFlags f2 )

inline

Global operator which returns an object in which all bits are set which are set in the first as well as the second argument. This operator exists since if it did not then the result of the bit-and operator & would be an integer which would in turn trigger a compiler warning when we tried to assign it to an object of type UpdateFlags.

The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues

Definition at line 340 of file fe_update_flags.h.

operator&=()

UpdateFlags & operator&= ( UpdateFlags & f1, const UpdateFlags f2 )

inline

Global operator which clears all the bits in the first argument if they are not also set in the second argument.

The interplay of UpdateFlags, Mapping, and FiniteElement in FEValues

Definition at line 354 of file fe_update_flags.h.