Diffpack Documentation

Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

DegFreeFE Class Reference

degree of freedom manager for finite element linear systems. More...

#include <DegFreeFE.h>

Inheritance diagram for DegFreeFE::

HandleId List of all members.

Public Methods

 DegFreeFE (const GridFE &grid, int ndof_per_node=1)
 DegFreeFE (FieldsFE &collection)
 DegFreeFE (FieldFE &f)
 DegFreeFE ()
 ~DegFreeFE ()
bool redim (const GridFE &grid, int ndof_per_node=1)
bool redim (FieldsFE &collection)
bool redim (FieldFE &f)
bool generalNumbering () const
bool specialNumbering () const
void printNumbering (Os os) const
bool ok () const
bool update ()
GridFE& grid ()
const GridFE& grid () const
int getNoDofInElm (int e) const
int getNoEqsInElm (int e) const
int getTotalNoDof () const
int getTotalNoEqs () const
int loc2glob (int e, int element_dof) const
int loc2globDof (int e, int element_dof) const
int loc2globEqs (int e, int element_dof) const
void loc2glob (VecSimple(int) &l2g, int e) const
void loc2globDof (VecSimple(int) &l2g, int e) const
void loc2globEqs (VecSimple(int) &l2g, int e) const
int getNoDofPerNode () const
int globalDegFree (int field_value_no, int field_no) const
void attachTestFuncDescription (const BasisFuncGrid &test_functions)
bool noEssBC () const
bool getEssBC (int iglobdof, NUMT &ebc_value) const
void getEssBC (VecSimple(bool) &essential_dof) const
void printEssBC (Os os, int output_level=1)
void initEssBC ()
void fillEssBC (int globdof, NUMT ebc_value)
void fillEssBC (int field_dof, int field_no, NUMT ebc_value)
void insertEssBC (VecSimple(NUMT) &u, bool account4multiplicity=false)
void updateMatrixPrm (Matrix(prm_NUMT) &mat_prm)
void fillEssBC2zero ()
void unfillEssBC2zero ()
bool zeroInterpretationOfEssBC () const
void field2vec (const FieldFE &f, Vec(NUMT) &x)
void vec2field (const Vec(NUMT) &x, FieldFE &f)
void field2vec (const FieldsFE &f, Vec(NUMT) &x)
void vec2field (const Vec(NUMT) &x, FieldsFE &f)
int fields2dof (int field_dof, int field_no) const
void dof2fields (int global_dof, int &field_dof, int &field_no) const
int computeHalfBandwidth ()
int getHalfBandwidth ()
void initAssemble ()
void modifyMatDue2essBC (bool onoff)
bool modifyMatDue2essBC () const
void modifyVecDue2essBC (bool onoff)
bool modifyVecDue2essBC () const
void symmModDue2essBC (bool onoff)
bool symmModDue2essBC () const
void unitMatDiagonalDue2essBC (bool onoff)
bool unitMatDiagonalDue2essBC () const
void keepDofDue2essBC (bool onoff)
bool keepDofDue2essBC () const
 COPY_CONSTRUCTOR (DegFreeFE)
 ASSIGNMENT_OPERATOR (DegFreeFE)

Public Attributes

Handle(FieldsFE) fields
Handle(GridFE) mesh
Vec(NUMT) b_mod
VecSimple(int) nelm_contr

Detailed Description

degree of freedom manager for finite element linear systems.

NAME: DegFreeFE - degree of freedom manager for finite element linear systems

DESCRIPTION:

The class relates degrees of freedom in a linear system to the nodal values of discrete finite element fields. By degrees of freedom we mean the unknowns in a linear system associated with some finite element discretization of a system of partial differential equations. For example, when solving a scalar partial differential equation (e.g. Poisson''s equation) by the finite element method, there is usually one degree of freedom associated with each node in the finite element mesh. When solving a vector equation in `$`d`$` dimensions there are `$`d`$` component fields. The relation between, for example, component no `$`j`$` at node `$`k`$` and the corresponding global degree of freedom in the linear system is computed by a "DegFreeFE" object. The class is simple to use for both isoparametric and non-isoparametric element meshes.

Sometimes one creates stiffness matrices and corresponding vectors where the number of unknowns differ from the number of equations. This is a frequent situation with mixed finite element methods in combination with sophisticated linear solvers (utilizing a block matrix structure) or in combination with explicit time integration. Normally, class "DegFreeFE" assumes that the number of equations equals the number of degrees of freedoms (unknowns), but the interface shows that there are two different functions for these quantities. In the case where the trial functions are of another type than the test functions, one can attach a "BasisFuncGrid", reflecting the test functions, to the "DegFreeFE" object. This "BasisFuncGrid" will be used for obtaining information about the number of equations (and the "getNoTotalEqs" and "getNoEqsInElm" functions will base their information on quantities found by the "BasisFuncGrid" description of the test functions). This way of computing the number of equations is only legal for scalar element fields and the general numbering, that is, the "DegFreeFE" object must be initialized by the constructor or "redim" function that takes a "FieldsFE" object with only one component. Note that the mapping from local to global degrees of freedom, as provided by the "loc2glob" function, is limited to the case where the number of unknowns equals the number of equations. In the more general case, the functions "loc2globDof" and "loc2globEqs" must be used. There are overloaded cases of "loc2glob", "loc2globDof" and "loc2globEqs" to fill all nodes for an element at once.

The "DegFreeFE" class may also mark the degrees of freedom that are subjected to essential boundary conditions. Class "ElmMatVec" uses "DegFreeFE" for this purpose. Moreover, the bandwidth of the coefficient matrix in the associated system of linear equations can be calculated. Note that it is assumed that the size of this system equals the total number of degrees of freedom in the associated "DegFreeFE" object. That is, if a vector equation is solved sequentially, component by component, a "DegFreeFE" object with one degree of freedom per node should be used for each component equation.

Constructor & Destructor Documentation

DegFreeFE::DegFreeFE ( const GridFE & grid,
int ndof_per_node = 1 )
 

The mostly used constructor is aimed at isoparametric elements and takes a "GridFE" object as argument. The number of degrees of freedom at every node can optionally be given, by default there is one unknown per node. Note that this constructor implies the so called special numbering. This numbering scheme leads to "m(i-1)+j" as the global degree of freedom number for the "j"th unknown in global node "i", assuming a total of "m" nodes. For further details see the document "Mixed Finite Elements in Diffpack; Software Tools and Fast Iterative Solvers".

The other constructor is aimed at the general case where one can have a vector field with components defined over different types of non-isoparametric elements. The vector field is represented in terms of a "FieldsFE" object, holding all the scalar fields that are involved in the numbering of degrees of freedom in the linear system. This "FieldsFE" object is the argument in the constructor. Note that this constructor implies the the so called general numbering when the degrees of freedom are assigned numbers in this "DegFreeFE" object, see the document referred above for details. Of course, this "FieldsFE" object can be very simple, e.g., holding "n" "FieldFE" objects over isoparametric elements. In this case one can also use the constructor that takes the "GridFE" object as argument. In more complicated situations, the "FieldsFE" object can hold "FieldFE" objects that have different "BasisFuncGrid". For example, when solving Navier-Stokes-like equations, the "FieldsFE" may hold a velocity field over isoparametric elements and a pressure field over non-isoparametric elements.

There is a constructor with no arguments. It performs no initialization, but one can at a later time call one of the "redim" functions. These correspond exactly to the other two constructors.

DegFreeFE::DegFreeFE ( FieldsFE & collection )
 

See documentation of one of the overloaded constructor.

DegFreeFE::DegFreeFE ( FieldFE & f )
 

See documentation of one of the overloaded constructor.

DegFreeFE::DegFreeFE ( ) [inline]
 

See documentation of one of the overloaded constructor.

DegFreeFE::~DegFreeFE ( )
 

Member Function Documentation

DegFreeFE::ASSIGNMENT_OPERATOR ( DegFreeFE )
 

DegFreeFE::COPY_CONSTRUCTOR ( DegFreeFE )
 

void DegFreeFE::attachTestFuncDescription ( const BasisFuncGrid & test_functions )
 

int DegFreeFE::computeHalfBandwidth ( )
 

as "getHalfBandwidth" but the computation of the bandwidth is enforced (that is, the local variable containing the bandwidth is not used).

void DegFreeFE::dof2fields ( int global_dof,
int & field_dof,
int & field_no ) const
 

this is the inverse function of "fields2dof". The input arguments to "fields2dof" are the return values of "dof2fields" and vice versa.

void DegFreeFE::field2vec ( const FieldsFE & f,
Vec(NUMT) & x )
 

See documentation of one of the overloaded functions.

void DegFreeFE::field2vec ( const FieldFE & f,
Vec(NUMT) & x )
 

given a field, the function loads the field into a "Vec" that can be used in a linear system. Recall that the main purpose of the "DegFreeFE" class is to administer the numbering of field values versus unknowns in associated linear systems, and "field2vec" (and "vec2field") contains basic functionality for switching between "Vec" and "FieldFE" or "FieldsFE" representations. The numbering of the components in a vector and a field representation has a simple relation if the special numbering technique is used. For the general numbering technique, the details of the numbering strategy is documented elsewhere. Note that if the general numbering is used, the "field2vec" and "vec2field" functions that take a "FieldFE" argument cannot be used; one must always communicate with the "DegFreeFE" object through a "FieldsFE" object (e.g. the object that was given as the "collection" argument when initializing the "DegFreeFE" object). (The "vec2field" and "field2vec" functions that take a "FieldFE" argument will result in a fatal error if the general numbering is chosen). The "field2vec" and "vec2field" functions are very efficient since they use either very simple formulas or pre-computed internal tables for switching between vector and field formats.

int DegFreeFE::fields2dof ( int field_dof,
int field_no ) const
 

See documentation of one of the overloaded functions.

void DegFreeFE::fillEssBC ( int field_dof,
int field_no,
NUMT ebc_value )
 

See documentation of one of the overloaded functions.

void DegFreeFE::fillEssBC ( int globdof,
NUMT ebc_value )
 

sets an essential boundary condition at a degree of freedom.

void DegFreeFE::fillEssBC2zero ( )
 

forces all essential boundary condition values to be interpreted as zero. If the system of linear equations have an unknown which is a correction vector, special care must be taken. This is the case when e.g. Newton''s method is used for solving systems of nonlinear equations. In each linear problem it is assumed that the total solution has its boundary conditions inserted and that the correction vector must have zeroes for all entries where the value is known. That is, in the modification of element matrices one must set the essential condition to be zero. The "ElmMatVec enforceEssBC" function calls the "zeroInterpretationOfEssBC" of "DegFreeFE" for determining whether the user has indicated to the "DegFreeFE" object that all non-zero essential boundary condition values are to be interpreted as if they were zero. When Newton''s method is used, it is important that the programmer calls the "fillEssBC2zero" function of the "DegFreeFE" class object prior to any "enforceEssBC".

bool DegFreeFE::generalNumbering ( ) const [inline]
 

void DegFreeFE::getEssBC ( VecSimple(bool) & essential_dof ) const
 

See documentation of one of the overloaded functions.

bool DegFreeFE::getEssBC ( int iglobdof,
NUMT & ebc_value ) const
 

returns "true" if a global (system) degree of freedom number is subjected to an essential boundary condition. The boundary value is available as an argument to the function. There is an overloaded version that fills a vector of booleans according to whether there is an essential dof or not.

int DegFreeFE::getHalfBandwidth ( )
 

computes the bandwidth of the coefficient matrix in a linear system associated with the grid and the degrees of freedom. The 

       number to be returned is `$`\max_e i-j|+1`$`, where `$`e`$`
freedom numbers in that element (i.e., `$`i`$` and `$`j`$` are unknowns in the element). The function returns a local variable containing the bandwidth if the number of degrees of freedom in the object has not changed. Hence, the function is quite efficient.

int DegFreeFE::getNoDofInElm ( int e ) const [inline]
 

returns the total number of degrees of freedom in a specified element. (Actually, the present version of "DegFreeFE" utilize the basic assumption in the present implementation of "BasisFuncGrid", namely that all elements must be of the same type. Then the number of degrees of freedom in an element is independent of the "e" argument).

int DegFreeFE::getNoDofPerNode ( ) const [inline]
 

returns the number of degrees of freedom at a specified node. If positive, the special numbering of the unknowns is used and the return value equals the constant number of degrees of freedom per node. A return value equal to zero implies the general numbering and the function has no application in this case (except for testing that the special numbering features do not apply).

int DegFreeFE::getNoEqsInElm ( int e ) const [inline]
 

same as "getNoDofInElm", but for the number of equations.

int DegFreeFE::getTotalNoDof ( ) const [inline]
 

returns the total number of degrees of freedom in the (total) coupled global system of algebraic equations. This will normally be the total number of unknowns in the system. For a problem involving a scalar function over isoparametric elements, the return value of "getTotalNoDof" is simply the number of nodes.

int DegFreeFE::getTotalNoEqs ( ) const [inline]
 

same as "getTotalNoDof", but for the number of equations.

int DegFreeFE::globalDegFree ( int field_value_no,
int field_no ) const [inline]
 

this is a synonym for "fields2dof" and included for backward compatibility.

const GridFE & DegFreeFE::grid ( ) const
 

See documentation of one of the overloaded functions.

GridFE & DegFreeFE::grid ( )
 

gives access to the associated grid.

void DegFreeFE::initAssemble ( )
 

initializes the "DegFreeFE" object prior to an assembly process. This means that "b_mod" and "nelm_contr" are reset to zero, if these vectors are used (the vectors are used only if "modifyVecDue2essBC()" is false - in that case the vectors hold information about the modifications of the right hand side due to essential boundary conditions). See also the "insertEssBC" function.

void DegFreeFE::initEssBC ( )
 

a function that erases all essential boundary conditions (usually called prior to "fillEssBC").

void DegFreeFE::insertEssBC ( VecSimple(NUMT) & u,
bool account4multiplicity = false )
 

inserts essential boundary conditions in a vector. This is useful for start vectors for linear or nonlinear solvers and when incorporating essential boundary conditions after a linear system is computed. Here are some comments regarding the latter application. When "modifyVecDue2essBC()" is false, the modifications of the right hand side due to essential boundary conditions are not performed at the element level. Instead the modifications is stored in internal arrays ("b_mod" and "nelm_contr") for later use. The "insertEssBC" function utilizes the stored information and inserts the correct boundary values in the "rhs" argument. The argument "account4multiplicity" is by default true, which means that the inserted value and its position are found by "getEssBC" and then multiplied by the number of elements contributing to this degree of freedom. Usually, the modifications of the coefficient matrix due to essential boundary are accomplished at the element level (since that is much more straightforward for, e.g., sparse matrices) and the ""unit"" values on the main diagonal are then not 1, but "n", where "n" is the number of elements contributing to the degree of freedom in question. The modifications of the right hand side must reflect this and the necessary information is provided by "nelm_contr". The updating of "b_mod" and "nelm_contr" is usually done by "ElmMatVec enforceEssBC".

bool DegFreeFE::keepDofDue2essBC ( ) const [inline]
 

See documentation of one of the overloaded functions.

void DegFreeFE::keepDofDue2essBC ( bool onoff )
 

essential boundary conditions can be removed from the linear system to reduce the system size. This function indicates whether degrees of freedom that are known (due to essential boundary conditions) should be kept (default) or eliminated. NOTE: At present, elimination is not yet implemented!

See also some common documentation under function "modifyMatDue2essBC".

void DegFreeFE::loc2glob ( VecSimple(int) & l2g,
int e ) const
 

See documentation of one of the overloaded functions.

int DegFreeFE::loc2glob ( int e,
int element_dof ) const
 

returns the global degree of freedom number corresponding to local degree of freedom "element_dof" in element number "e". Note that "element_dof" runs from 1 to the total number of degrees of freedom in the element (as given by "getNoDofInElm"). The "loc2glob" function assumes that the number of unknowns and the number of equations are the same. In the case where rectangular matrices are involved and these two numbers differ (that is, a "BasisFuncGrid" describing the test functions has been attached to the "DegFreeFE" object), one must use "loc2globDof" and "loc2globEqs" for the degree of freedom and equation numbering, respectively. (The former is just a call to "loc2glob"; in other words, the "loc2glob" function represents the local-global degree of freedom mapping that `can` be used for the equations in the special case where the number of equations equals the number of unknowns). The "loc2glob", "loc2globDof" and "loc2globEqs" functions are mostly used by class "ElmMatVec" and possibly by general matrix sparsity pattern computation routines.

void DegFreeFE::loc2globDof ( VecSimple(int) & l2g,
int e ) const [inline]
 

See documentation of one of the overloaded functions.

int DegFreeFE::loc2globDof ( int e,
int element_dof ) const [inline]
 

see the description of the "loc2globEqs" function.

void DegFreeFE::loc2globEqs ( VecSimple(int) & l2g,
int e ) const [inline]
 

See documentation of one of the overloaded functions.

int DegFreeFE::loc2globEqs ( int e,
int element_dof ) const [inline]
 

see the description of the "loc2glob" function. Overloaded versions of "loc2glob", "loc2globEqs" and "loc2globDof" redim and fill the whole local-global vector at once.

bool DegFreeFE::modifyMatDue2essBC ( ) const [inline]
 

See documentation of one of the overloaded functions.

void DegFreeFE::modifyMatDue2essBC ( bool onoff )
 

indicator for modification of the coefficient matrix in the linear system due to essential boundary conditions. The function is used by "ElmMatVec enforceEssBC" to check if the element matrix should be manipulated or not. The function that takes the "bool onoff" argument is used to select modification ("ON") or no modification ("OFF"). It is usually called from the programmer's simulation code. Since the use of these indicator functions are in the finite element assembly process, the call must be performed prior to the call to "FEM makeSystem". The other version of the indicator function returns a "bool", and this function is used by "ElmMatVec enforceEssBC".

The following documentation applies to all the "...Due2essBC" functions:

These functions control the implementation of essential boundary conditions in the linear system. By default, all these modes are "ON", that is, the functions return true boolean values. The programmer can set the modes "ON" or "OFF" to control the modifications of the linear system in detail. Especially in problems with time independent coefficients in the PDEs, where the finite element assembly process can be avoided at every time step, it is necessary to control the modifications of various components of the linear system. This is documented elsewhere (see the book H. P. Langtangen "Computational Partial Differential Equations; Numerical Methods and Diffpack Programming" or the book ""Numerical Solution of Partial Differential Equations; Models, Algorithms, and Software"").

bool DegFreeFE::modifyVecDue2essBC ( ) const [inline]
 

See documentation of one of the overloaded functions.

void DegFreeFE::modifyVecDue2essBC ( bool onoff )
 

indicator for modification of the right hand side in the linear system due to essential boundary conditions. See the documentation of "modifyMatDue2essBC" for more information. The "modifyVecDue2essBC" automatically assembles all the contributions to the right hand side corresponding to subtractions of columns of the coefficient matrix. The contributions are available as the "Vec(NUMT)" vector "b_mod". Moreover, the values of the unknowns are available from the function "getEssBC". With "b_mod" and "getEssBC" it is easy to enforce the essential boundary conditions in the right hand side data structure at any stage in the computations.

See also some common documentation under function "modifyMatDue2essBC".

bool DegFreeFE::noEssBC ( ) const [inline]
 

returns true if the "DegFreeFE" objects has no essential boundary conditions set.

bool DegFreeFE::ok ( ) const
 

void DegFreeFE::printEssBC ( Os os,
int output_level = 1 )
 

prints the degrees of freedom where essential boundary conditions are assigned. This function is particularly useful when debugging simulators as one can check that the programmer''s assignment of essential boundary conditions in a "DegFreeFE" object is correct. This information can then be compared to the solution to check that the boundary conditions propagate through the whole simulation. There is an optional argument to "printEssBC" that decides the level of output (or verbosity). A value of 0 makes the output as compact as possible, the value 1 is standard, and 2 will print the coordinates of the point at which a degree of freedom is associated.

void DegFreeFE::printNumbering ( Os os ) const
 

prints the numbering of the global degrees of freedom as they are computed by the "DegFreeFE" class. The output is written element by element, local node by local node etc. This function may be of great help to gain a complete understanding of the numbering techniques. Make a simple grid with few elements, study the output of "printNumbering" and make a sketch of the grid and the degrees of freedom locations on a piece of paper.

bool DegFreeFE::redim ( FieldFE & f )
 

See documentation of one of the overloaded functions.

bool DegFreeFE::redim ( FieldsFE & collection )
 

See documentation of one of the overloaded functions.

bool DegFreeFE::redim ( const GridFE & grid,
int ndof_per_node = 1 )
 

redefines the object (performs the same operations as one of the constructors).

bool DegFreeFE::specialNumbering ( ) const [inline]
 

bool DegFreeFE::symmModDue2essBC ( ) const [inline]
 

See documentation of one of the overloaded functions.

void DegFreeFE::symmModDue2essBC ( bool onoff )
 

indicator for symmetric modification of the linear system due to essential boundary conditions. If degree of freedom number i is known, equation number i in the linear system is replaced by the boundary condition. However, such a modification destroys the symmetry of the coefficient matrix. If "symmModDue2essBC" is "ON", zeroes will also be introduced in column number i in the coefficient matrix. This additional symmetric modification also requires the right hand side to be modified (column no i in the coefficient matrix times the known solution value must be subtracted from the right hand side).

Note that the "modify" functions tell the finite element tools (class "ElmMatVec") whether it is allowed at all to modify (touch) the arrays in the linear system. The "symmModDue2essBC" function tells the tools if the implementation of the boundary conditions are to be done in a symmetric or non-symmetric way.

See also some common documentation under function "modifyMatDue2essBC".

void DegFreeFE::unfillEssBC2zero ( )
 

essential boundary condition values are interpreted as their original values.

bool DegFreeFE::unitMatDiagonalDue2essBC ( ) const [inline]
 

See documentation of one of the overloaded functions.

void DegFreeFE::unitMatDiagonalDue2essBC ( bool onoff )
 

indicates if 1.0 is set on the diagonal of the coefficient matrix in the position where there is an essential boundary condition (this is the normal choice). Otherwise, 0.0 is set on the diagonal (this is convenient if the coefficient matrix is on the form "A=M+a*K", where "K" and "M" are computed separately - "M" may have 1.0 on the diagonal and "K" may have 0.0 such that the sum "M+a*K" implements the essential boundary condition correctly).

See also some common documentation under function "modifyMatDue2essBC".

bool DegFreeFE::update ( )
 

void DegFreeFE::updateMatrixPrm ( Matrix(prm_NUMT) & mat_prm )
 

fill in correct dimensions of a "Matrix_prm" object, based on the current grid information.

void DegFreeFE::vec2field ( const Vec(NUMT) & x,
FieldsFE & f )
 

See documentation of one of the overloaded functions.

void DegFreeFE::vec2field ( const Vec(NUMT) & x,
FieldFE & f )
 

given a "Vec" from a linear system (e.g., the solution), the function loads the vector into a field. See "field2vec".

bool DegFreeFE::zeroInterpretationOfEssBC ( ) const [inline]
 

returns "true" if essential boundary conditions are to be treated as zero values (in e.g. Newton''s method). In other words, the function returns "true" if "fillEssBC2zero" has been called and not yet been cleared by "unfillEssBC2zero". Note that only the last call to "fillEssBC2zero" or "unfillEssBC2zero" is remembered.

Member Data Documentation

Vec(NUMT) DegFreeFE::b_mod
 

Handle(FieldsFE) DegFreeFE::fields
 

Handle(GridFE) DegFreeFE::mesh
 

VecSimple(int) DegFreeFE::nelm_contr
 

The documentation for this class was generated from the following file:
Copyright © 2003 inuTech GmbH. All rights reserved.