Space Class Reference

Represents a finite element space over a domain. More...

#include <space.h>

Inherited by H1Space, HcurlSpace, HdivSpace, and L2Space.

Classes
struct	BaseComponent
struct	ElementData
union	NodeData
Public Member Functions
	Space (Mesh mesh, Shapeset shapeset)
virtual	~Space ()
virtual void	free ()
void	set_bc_types (BCType(*bc_type_callback)(int marker))
	Sets the BC types callback function.
void	set_essential_bc_values (scalar(*bc_value_callback_by_coord)(int ess_bdy_marker, double x, double y))
	Sets the BC values callback function, which takes absolute boundary coordinates.
void	set_essential_bc_values (scalar(bc_value_callback_by_edge)(EdgePos ep))
	Sets the BC values callback function, which takes parametric edge position.
virtual void	set_element_order (int id, int order)
	Sets element polynomial order.
int	get_element_order (int id) const
	Returns element polynomial order.
void	set_uniform_order (int order, int marker=H2D_ANY)
	Sets the same polynomial order for all elements in the mesh.
void	set_default_order (int tri_order, int quad_order=0)
	Sets the order automatically assigned to all newly created elements. (The order of these is normally undefined and has to be set explicitly.).
void	copy_orders (Space *space, int inc=0)
	Copies element orders from another space. 'inc' is an optional order increase. If the source space has a coarser mesh, the orders are distributed recursively. This is useful for reference solution spaces.
virtual int	get_edge_order (Element *e, int edge)
	Internal. Obtains the order of an edge, according to the minimum rule.
virtual int	assign_dofs (int first_dof=0, int stride=1)
	Builds basis functions and assigns DOF numbers to them.
int	get_num_dofs () const
	Returns the number of basis functions contained in the space.
int	get_max_dof () const
	Returns the DOF number of the last basis function.
Shapeset *	get_shapeset () const
Mesh *	get_mesh () const
void	set_mesh (Mesh *mesh)
virtual Space *	dup (Mesh *mesh) const =0
	Creates a copy of the space. For internal use (see RefSystem).
bool	is_up_to_date () const
	Returns true if the space is ready for computation, false otherwise.
void	distribute_orders (Mesh mesh, int parents)
	Sets polynomial orders to elements created by Mesh::regularize() using "parents".
void	get_element_assembly_list (Element e, AsmList al)
	Obtains an assembly list for the given element.
void	get_edge_assembly_list (Element e, int edge, AsmList al)
	Obtains an edge assembly list (contains shape functions that are nonzero on the specified edge).
int	get_seq () const
	Internal. Used by LinSystem to detect changes in the space.
virtual int	get_type () const =0
	Internal. Return type of this space (H1 = 0, Hcurl = 1, Hdiv = 2, L2 = 3).
Public Attributes
Mesh *	mesh
	FE mesh.
NodeData *	ndata
	node data table
int	nsize
int	ndata_allocated
	number of items in ndata, allocated space
ElementData *	edata
	element data table
int	esize
BCType(*	bc_type_callback )(int)
scalar(*	bc_value_callback_by_coord )(int ess_bdy_marker, double x, double y)
scalar(*	bc_value_callback_by_edge )(EdgePos *ep)
Protected Member Functions
virtual int	get_edge_order_internal (Node *en)
virtual void	resize_tables ()
	Updates internal node and element tables.
void	H2D_CHECK_ORDER (int order)
void	copy_orders_recurrent (Element *e, int order)
virtual void	reset_dof_assignment ()
	Resets assignment of DOF to an unassigned state.
virtual void	assign_vertex_dofs ()=0
virtual void	assign_edge_dofs ()=0
virtual void	assign_bubble_dofs ()=0
virtual void	get_vertex_assembly_list (Element e, int iv, AsmList al)=0
virtual void	get_edge_assembly_list_internal (Element e, int ie, AsmList al)=0
virtual void	get_bubble_assembly_list (Element e, AsmList al)
void	copy_callbacks (const Space *space)
void	precalculate_projection_matrix (int nv, double *&mat, double &p)
virtual scalar *	get_bc_projection (EdgePos *ep, int order)=0
void	update_edge_bc (Element e, EdgePos ep)
void	update_bc_dofs ()
virtual void	update_constraints ()
	Called by Space to update constraining relationships between shape functions due to hanging nodes in the mesh. As this is space-specific, this function is reimplemented in H1Space and HcurlSpace.
virtual void	post_assign ()
	Auxiliary function the descendants may implement to perform additional tasks after the DOFs have been assigned.
	H2D_API_USED_STL_VECTOR (void *)
void	free_extra_data ()
void	propagate_zero_orders (Element *e)
Protected Attributes
Shapeset *	shapeset
int	default_tri_order
int	default_quad_order
int	first_dof
int	next_dof
int	stride
int	seq
int	mesh_seq
bool	was_assigned
double **	proj_mat
double *	chol_p
std::vector< void * >	extra_data
Static Protected Attributes
static const int	H2D_UNASSIGNED_DOF = -2
	DOF which was not assigned yet.
static const int	H2D_CONSTRAINED_DOF = -1
	DOF which is constrained.

Detailed Description

Represents a finite element space over a domain.

The Space class represents a finite element space over a domain defined by 'mesh', spanned by basis functions constructed using 'shapeset'. It serves as a base class for H1Space, HcurlSpace and L2Space, since most of the functionality is common for all the spaces.

There are four main functions the Space class provides:

It handles the Dirichlet boundary conditions. The user sets a callback determining which markers represent the Dirichlet part of the boundary (by returning BC_ESSENTIAL) and which markers represent the Neumann and Newton parts (BC_NATURAL). It is also possible to return the value BC_NONE, which supresses all BC processing on such part of the boundary. The callback is set by the function set_bc_types().

On Dirichlet edges the Space class calls another callback, set by either of the two functions set_essential_bc_values(). The obtained scalar values are projected onto the available edge shape functions on each edge. This way the Dirichlet lift is obtained, which matches as closely as possible the user-defined boundary data. Two kinds of value callback functions are defined: the first provides the absolute coordinates on the edge in question, while the second is supposed to return the Dirichlet value based on two vertex indices and a parameter in the range [0,1], representing the position on the edge. The user can set any one of the two callbacks, whichever suits her better. If both are set, the "EdgePos" one takes precedence.

If one or more of the BC callbacks are not set, default ones are used. The default BC type is BC_NATURAL for the whole boundary (see the function static int default_bc_type(int marker) in space.cpp). The default BC value is zero for all markers.
It stores element polynomial degrees, or 'orders'. All active elements need to have an order set for the Space to be valid. Individual orders can be set by calling set_element_order(). You can also set the same order for all elements using set_uniform_order(). Quadrilateral elements can have different orders in the vertical and horizontal directions. It is therefore necessary to form the order using the macro H2D_MAKE_QUAD_ORDER() when calling the aforementioned functions.
It builds and enumerates the basis functions. After all element orders have been set, you must call the function assign_dofs(). This function assigns the DOF (degree-of- freedom) numbers to basis functions, starting with 'first_dof' (optional parameter). It also determines constraining relationships in the mesh due to hanging nodes and builds constrained basis functions. The total number of basis functions can then be obtained by calling get_num_dofs(). Standard basis functions are assigned positive numbers from 'first_dof' to ('first_dof' + (get_num_dofs() - 1) * 'stride'). All shape functions belonging to the Dirichlet lift are assigned DOF number of -1. This way the Dirichlet lift becomes a (virtual) basis function. This simplifies assembling.
Finally, and most importantly, the Space is able to deliver a list of shape functions existing on each element. Such a list is called an "assembly list" and is represented by the class AsmList. The assembly list contains the triplets (idx, dof, coef). 'idx' is the shape function index, as understood by the Shapeset. 'dof' is the number of the basis function, whose part the shape function forms. 'coef' is a real constant, with which the shape function must be multiplied in order to fit into the basis function. This is typically 1, but can be less than that for constrained functions. Constrained vertex functions can belong to more than one basis functions. This results in more triplets with the same 'idx'. However, the assembling procedure or the Solution class do not have to worry about that. For instance, the Solution class simply obtains the values of all shape functions contained in the list, multiplies them by 'coef', and forms a linear combination of them by taking the solution vector values at the 'dof' positions. This way the solution to the PDE is obtained.

Space is an abstract class and cannot be instatiated. Use one of the specializations H1Space, HcurlSpace or L2Space instead.

The handling of irregular meshes is desribed in H1Space and HcurlSpace.

Constructor & Destructor Documentation

Space::Space	(	Mesh *	mesh,
		Shapeset *	shapeset
	)

Space::~Space ( ) [virtual]

Member Function Documentation

virtual void Space::assign_bubble_dofs ( ) [protected, pure virtual]

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

int Space::assign_dofs	(	int	first_dof = `0`,
		int	stride = `1`
	)			`[virtual]`

Builds basis functions and assigns DOF numbers to them.

This functions must be called after assigning element orders, and before using the space in a computation, otherwise an error will occur.

Parameters:

	first_dof	[in] The DOF number of the first basis function.
	stride	[in] The difference between the DOF numbers of successive basis functions.

Returns:: The number of basis functions contained in the space.

Todo:: Find out whether the following code this is crucial. If uncommented, this enforces 0 order for all sons if the base element has 0 order. In this case, an element with 0 order means an element which is left out from solution.

virtual void Space::assign_edge_dofs ( ) [protected, pure virtual]

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

virtual void Space::assign_vertex_dofs ( ) [protected, pure virtual]

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

void Space::copy_callbacks ( const Space * space ) [protected]

void Space::copy_orders	(	Space *	space,
		int	inc = `0`
	)

Copies element orders from another space. 'inc' is an optional order increase. If the source space has a coarser mesh, the orders are distributed recursively. This is useful for reference solution spaces.

void Space::copy_orders_recurrent	(	Element *	e,
		int	order
	)			`[protected]`

void Space::distribute_orders	(	Mesh *	mesh,
		int *	parents
	)

Sets polynomial orders to elements created by Mesh::regularize() using "parents".

virtual Space* Space::dup ( Mesh * mesh ) const [pure virtual]

Creates a copy of the space. For internal use (see RefSystem).

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

void Space::free ( ) [virtual]

void Space::free_extra_data ( ) [protected]

virtual scalar* Space::get_bc_projection	(	EdgePos *	ep,
		int	order
	)			`[protected, pure virtual]`

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

void Space::get_bubble_assembly_list	(	Element *	e,
		AsmList *	al
	)			`[protected, virtual]`

Reimplemented in HdivSpace.

void Space::get_edge_assembly_list	(	Element *	e,
		int	edge,
		AsmList *	al
	)

Obtains an edge assembly list (contains shape functions that are nonzero on the specified edge).

virtual void Space::get_edge_assembly_list_internal	(	Element *	e,
		int	ie,
		AsmList *	al
	)			`[protected, pure virtual]`

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

int Space::get_edge_order	(	Element *	e,
		int	edge
	)			`[virtual]`

Internal. Obtains the order of an edge, according to the minimum rule.

Reimplemented in L2Space.

int Space::get_edge_order_internal ( Node * en ) [protected, virtual]

void Space::get_element_assembly_list	(	Element *	e,
		AsmList *	al
	)

Obtains an assembly list for the given element.

int Space::get_element_order ( int id ) const

Returns element polynomial order.

int Space::get_max_dof ( ) const [inline]

Returns the DOF number of the last basis function.

Mesh* Space::get_mesh ( ) const [inline]

int Space::get_num_dofs ( ) const [inline]

Returns the number of basis functions contained in the space.

int Space::get_seq ( ) const [inline]

Internal. Used by LinSystem to detect changes in the space.

Shapeset* Space::get_shapeset ( ) const [inline]

virtual int Space::get_type ( ) const [pure virtual]

Internal. Return type of this space (H1 = 0, Hcurl = 1, Hdiv = 2, L2 = 3).

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

virtual void Space::get_vertex_assembly_list	(	Element *	e,
		int	iv,
		AsmList *	al
	)			`[protected, pure virtual]`

Implemented in H1Space, HcurlSpace, HdivSpace, and L2Space.

Space::H2D_API_USED_STL_VECTOR ( void * ) [protected]

void Space::H2D_CHECK_ORDER ( int order ) [protected]

bool Space::is_up_to_date ( ) const [inline]

Returns true if the space is ready for computation, false otherwise.

virtual void Space::post_assign ( ) [inline, protected, virtual]

Auxiliary function the descendants may implement to perform additional tasks after the DOFs have been assigned.

Reimplemented in H1Space.

void Space::precalculate_projection_matrix	(	int	nv,
		double **&	mat,
		double *&	p
	)			`[protected]`

void Space::propagate_zero_orders ( Element * e ) [protected]

void Space::reset_dof_assignment ( ) [protected, virtual]

Resets assignment of DOF to an unassigned state.

void Space::resize_tables ( ) [protected, virtual]

Updates internal node and element tables.

Since meshes only contain geometric information, the Space class keeps two tables with FEM-related information. The first one, 'ndata', contains DOF numbers and other things for each node. The second table, 'edata', holds element orders and bubble DOF numbers. Both tables are directly indexed by the node and element id's. The function resize_tables() is called to check whether the tables are large enough to contain all node and element id's, and to reallocate them if not.

Reimplemented in L2Space.

void Space::set_bc_types ( BCType(*)(int marker) bc_type_callback )

Sets the BC types callback function.

void Space::set_default_order	(	int	tri_order,
		int	quad_order = `0`
	)

Sets the order automatically assigned to all newly created elements. (The order of these is normally undefined and has to be set explicitly.).

void Space::set_element_order	(	int	id,
		int	order
	)			`[virtual]`

Sets element polynomial order.

Reimplemented in HcurlSpace.

void Space::set_essential_bc_values ( scalar(*)(EdgePos *ep) bc_value_callback_by_edge )

Sets the BC values callback function, which takes parametric edge position.

void Space::set_essential_bc_values ( scalar(*)(int ess_bdy_marker, double x, double y) bc_value_callback_by_coord )

Sets the BC values callback function, which takes absolute boundary coordinates.

void Space::set_mesh ( Mesh * mesh )

void Space::set_uniform_order	(	int	order,
		int	marker = `H2D_ANY`
	)

Sets the same polynomial order for all elements in the mesh.

void Space::update_bc_dofs ( ) [protected]

virtual void Space::update_constraints ( ) [inline, protected, virtual]

Called by Space to update constraining relationships between shape functions due to hanging nodes in the mesh. As this is space-specific, this function is reimplemented in H1Space and HcurlSpace.

Reimplemented in H1Space, HcurlSpace, and HdivSpace.