Description of the different parts of the library

Gmm++ library

Description

Gmm++ is a linear algebra library which was originally designed to make an interface between the need in linear algebra procedures of Getfem++ and existing free linear algebra libraries (MTL, Superlu, Blas, Lapack originally). It rapidly evolves to an independent self-consistent library with its own vector and matrix types. It is now used as a base linear algebra library by several other projects (projet KDE, http://websvn.kde.org/trunk/kdesupport/gmm for instance).

However, it preserves the characteristic to be a potential interface for more specific packages. Any vector or matrix type having the minimum of compatibility can be used by generic algorithms of Gmm++ writing a linalg_traits structure.

A Gmm++ standalone version is distributed since release 1.5 of Getfem++ . It is however developed inside the Getfem++ project even though since release 3.0 it is completely independent of any Getfem++ file.

In addition to the linear algebra procedures, it furnishes also the following utilities to Getfem++ .

Fix some eventual compatibility problems in gmm_std.h.
Error, warning and trace management in gmm_except.h.
Some extended math definitions in gmm_def.h.

State

For the moment, Gmm++ cover the needs of Getfem++ concerning the basic linear algebra procedures.

Perspectives

There is potentatialy several points to be improved in Gmm++ (partial introduction of expression template for some base types of matrix and vectors, reflection on the way to represent in a more coherent manner sparse sub-vectors and sub-matrices, introduction of C++ concepts ...). However, since Gmm++ globally cover the needs of Getfem++ and since there exists some other project like Glas (http://glas.sourceforge.net/) to build a reference C++ library for linear algebra, a global reflection seems not necessary for the moment. This part is considered to be stabilized.

The current vocation of Gmm++ is to continue to collect generic algorithms and interfaces to some other packages in order to cover new needs of the whole project. The library is now frequently used as a separate package and has also the vocation to collect the contribution of any person who propose some improvements, new algorithms or new interfaces.

Mesh module

Description

This part of the library has the role to store and manage the meshes, i.e. a collection of elements (real elements) connected to each other by some of their faces. For that, it develops concepts of elements, elements of reference, structure of meshes, collection of nodes, geometric transformations, subpart of the boundary or subzone of the mesh.

There is no really effective meshing capabilities available for the moment in Getfem++ . The meshes of complex objects must be imported from existing meshers such as gmsh or GiD. Some importing functions of meshes have been written and can be easily extended for other formats.

The object which represents a mesh declared in the file getfem_mesh.h and which is used as a basis for handling of the mehses in Getfem++ manages also the possibility for the structures depending on a mesh (see MESHFEM and MESHIM modules) to react to the evolution of the mesh (addition or removal of elements ...).

State

The main C++ header files are

`bgeot_convex_structure.h`	Describes the structure of an element disregarding the coordinates of its vertices.
`bgeot_mesh_structure.h`	Describes the structure of a mesh disregarding the coordinates of the nodes.
`bgeot_node_tab.h`	A node container allowing the fast search of a node.
`bgeot_convex.h`	Describes an element with its vertices.
`bgeot_convex_ref.h`	Describe reference elements.
`bgeot_mesh.h`	Describes a mesh with the collection of node (but without the description of geometric transformations).
`bgeot_geometric_trans.h`	Describes geometric transformations.
`bgeot_geotrans_inv.h`	A tool to invert geometric transformations.
`getfem_mesh.h`	Fully describes a mesh (with the geometric transformations, subparts of the mesh, support for parallelization). Includes the Bank algorithm to refine a mesh.
`getfem_mesher.h`	An attempt to develop a mesher. To be use with care.

A prototype of mesher is in the files getfem_mesher.h and getfem_mesher.cc which makes it possible to mesh geometries defined by some level sets. However, the continuation of the development of this mesher is not planned for the moment because the project Getfem++ has vocation to focus on the finite element methods themselves.

Perspectives

For the moment, the module is split into two parts which lie into two different namespaces. Of course, It would be more coherent to gather the module in only one namespace (getfem).

(Note: The file bgeot_mesh.h could be renamed getfem_basic_mesh.h).

A possible work to do on this part would be to examine the manner of storing the meshes and possibly to make a bibliographical study on the manner of storing a mesh (for instance see [7]). It would be necessary to supplement documentation and to examine also the management of the events and the way in which the structures which depend on the mesh react to these events.

FEM module

Description

The FEM module is the part of Getfem++ which describes the finite elements at the element level and the degrees of freedom. Finite element methods can be of different types. They could be scalar or vectorial, polynomial, piecewise polynomial or non-polynomial, equivalent via the geometric transformation or not. Moreover, the description of the degrees of freedom have to be such that it is possible to gather the compatible degrees of freedom between two neighbor elements in a generic way (for instance connecting a Lagrange 2D element to another Lagrange 1D element).

State

The main files of the module are

`getfem_fem.h`	Abstract definition of a finite element and a degree of freedom. Interface for the exported functions of `getfem_fem.cc` and `getfem_fem_composite.cc`.
`getfem_fem.cc`	Definition of the polynomial finite elements and interface to get the descriptor on these elements (function `pfem fem_descriptor(std::string name)`).
`getfem_fem_composite.cc`	Definition of the piecewise polynomial finite elements.

The two files getfem_fem.cc and getfem_fem_composite.cc mainly contains all the finite element description for basic elements. A exhaustive list of the defined finite elements is given in Appendix A of the user documentation.

Some other files define some specific finite element such as getfem_fem_level_set.h which is a complex construction which allows to "cut" a existing element by one or several level sets (see the LEVELSET module).

The manner to describe the degrees of freedom globally satisfies the needing (connecting dof from an element to another in a generic way) but is a little bit obscure and too much complicated.

Conversely, the way to represent non-equivalent elements with the supplementary matrix M has proven its efficiency on several elements (Hermites elements, Argyris ...).

Perspectives

the principal dissatisfaction of this module is that description of the degrees of freedom is not completely satisfactory. It is the principal reason why one documentation on how to build an element from A to Z was not made for the moment because description of the degrees of freedom was conceived to be temporary. An effort of design is thus to be provided to completely stabilize this module mainly thus with regard to the description of degrees of freedom but also perhaps the description of finite elements which could be partially externalized in a similar way to the cubature methods , at least for the simplest finite elements (equivalent and polynomial finite elements).

CUBATURE module

Description

The CUBATURE module gives access to the numerical integration methods on reference elements. In fact it does not only contain some cubature formulas because it also give access to some exact integration methods. However, the exact integration methods are only usable for polynomial element and affine geometric transformations. This explain why exact integration methods are not widely used. The description of cubature formulas is done either directly in the file getfem_integration.h or via a description file in the directory cubature of Getfem++ . The addition of new cubature formulas in then very simple, it suffices to reference the element on which it is defined and the list of Gauss points in a file and add it to this directory. Additionally, In order to integrate terms defined on a boundary of a domain, the description should also contains the reference to a method of same order on each face of the element.

State

This module meets the present needs for the project and is considered as stabilized. The list of available cubature formulas is given in Appendix B of the user documentation.

Perspectives

No change needed for the moment. An effort could be done on the documentation to describe completely how to add a new cubature formula (format off descritption files).

MESHFEM module

to be done

Description

getfem_interface.cc. This is the bridge between the script language and the getfem interface. The function getfem_interface_main is exported as an extern "C" function, so this is a sort of c++ barrier between the script language and the getfem interface (exporting only a C interface avoids many compilation problems).
matlab/gfm_mex.c. The matlab interface. The only thing it knows about getfem is in getfem_interface.hh.
python/getfem_python.c. The python interface. The only thing it knows about getfem is in getfem_interface.hh.
gfi_array.h, gfi_array.c. Both gfm_mex.c and getfem_python.c need a simple convention on how to send and receive arrays, and object handles, from getfem_interface_main(). This file provide such functionnality.
getfemint_object.h. Not all getfem objects are exported, only a selected subset, mostly mesh, mesh_im, mesh_fem, slice, bricks, etc. They are all wrapped in a common interface, which is getfemint::getfem_object.
getfemint_mesh.h, getfemint_mesh_fem.h, .... All the wrapped getfem++ objects. Some of them are quite complicated (getfemint_gsparse which export some kind of mutable sparse matrix that can switch between different storage types, and real of complex elements).
gf_workspace.cc, gf_delete.cc. Memory management for getfem objects. There is a layer in getfemint::getfem_object which handles the dependency between for example a getfemint_mesh and a getfemint_mesh_fem. It makes sure that no object will be destroyed while there is still another getfem_object using it. The goal is to make sure that under no circumstances the user is able to crash getfem (and the host program, matlab or python) by passing incorrect argument to the getfem interface. It also provides a kind of workspace stack, which was designed to simplify handling and cleaning of many getfem objects in matlab (since matlab does not have 'object destructors').
getfemint.h, getfemint.cc. Define the mexarg_in, mexarg_out classes, which are used to parse the list of input and output arguments to the getfem interface functions. The name is not adequate anymore since any reference to "mex" has been moved into gfm_mex.c.
gf_mesh.cc, gf_mesh_get.cc, gf_mesh_set.cc, gf_fem.cc, .... All the functions exported be the getfem interfaces, sorted by object type (gf_mesh*, gf_mesh_fem*, gf_fem*), and then organized as one for the object construction (gf_mesh), one for the object modification (gf_mesh_set), and one for the object inquiry (gf_mesh_get). Each of these files contain one main function, that receives a mexargs_in and mexargs_out stack of arguments. It parses then, and usually interprets the first argument as the name of a subfunction (gf_mesh_get('nbpts') in matlab, or Mesh.nbpts() in python).
matlab/gfm_rpx_mexint.c. An alternative to gfm_mex.c which is used when the "-enable-matlab-rpc" is passed to the ./configure script. The main use for that is debugging the interface, since in that case, the matlab interface communicates via sockets with a "getfem_server" program, so it is possible to debug that server program, and identify memory leaks or anything else without having to mess with matlab (it is pain to debug).
python/getfem.base.py. The python interface is available as a 'getfem.py' file which is built during compilation. Its source file is getfem.base.py, it contains just the list of classes, and for each class the names of the member functions.

Adding a new function to the getfem interface: if one want to add a new function gf_mesh_get(m, "foobar", ...), then the main file to modify is gf_mesh_get.cc. Remember to check every argument passed to the function in order to make sure that the user cannot crash matlab or python when using that function.

Do not forget to add documentation for that function: in gf_mesh_get.cc, this is the documentation that appears in the matlab help files (that is when on type 'help gf_mesh_get' at the matlab prompt), and in the getfem_python autogenerated documentation. In order to have "foobar" as a member function of the python Mesh class, it is necessary to add it in the getfem.base.py file. It is also necessary to add documentation in the interface/doc/getfemmatlab.tex, which was at the beginning the only documentation available. It is still very matlab oriented, and a little bit redundant with the documentation embedded in gf_mesh_get.cc.