# The high-level generic assembly module in *GetFEM*¶

## Description¶

The high level generic assembly module of *GetFEM* and its generic weak form language (GWFL) is a key module which allows to describe weak formulation of partial differential equation problems. See the description of the language in the user documentation section Compute arbitrary terms - high-level generic assembly procedures - Generic Weak-Form Language (GWFL).

## Files¶

File(s) | Description |
---|---|

`getfem_generic_assembly.h` |
Main header for exported definitions. Only this header has to be included to use the generic assembly. Other headers of the module are for internal use only. |

`getfem_generic_assembly_tree.h` and `getfem_generic_assembly_tree.cc` |
Definition of the tree structure and basic operations on it, including reading an assembly string and transform it in a syntax tree and make the invert transformation of a tree into a string. |

`getfem_generic_assembly_function_and_operators.h` and `getfem_generic_assembly_function_and_operators.cc` |
Definition of redefined function and nonlinear operator of GWFL. |

`getfem_generic_assembly_semantic.h` and `getfem_generic_assembly_semantic.cc` |
Semantic analysis and enrichment of the syntax tree. Include some operations such as making the derivation of a tree with respect to a variable or computing the tree corresponding to the gradient of an expression. |

`getfem_generic_assembly_workspace.cc` |
Methodes of the workspace object (defined in `getfem_generic_assembly.h` ). |

`getfem_generic_assembly_compile_and_exec.h` and `getfem_generic_assembly_compile_and_exec.cc` |
Definition of the optimized instructions, compilation into a sequel of optimize instructions and execution of the instructions on Gauss point/interpolation points. |

`getfem_generic_assembly_interpolation.cc` |
Interpolation operations and interpolate transformations. |

## A few implementation details¶

The assembly string is transformed in an assembly tree by a set of function in `src/getfem_generic_assembly.cc`

. The process has 6 steps:

- Lexical analysis with the procedure
`ga_get_token(...)`

.- Syntax analysis and transformation into a syntax tree by
`ga_read_string(...)`

.- Semantic analysis, simplification (pre-computation) of constant expressions and enrichment of the tree by
`ga_semantic_analysis(...)`

.- Symbolic (automatic) differentiation of an assembly tree by
`ga_derivative(...)`

- Symbolic (automatic) gradient computation of an assembly tree by
`ga_gradient(...)`

- Compilation in a sequence of instructions with optimizations by
`ga_compile(...)`

.- Execution of the sequence of instructions and assembly by
`ga_exec(...)`

.

These steps are performed only once at the beginning of the assembly. The final tree is compiled in a sequence of optimized instructions which are executed on each Gauss point of each element. The compilation performed some optimizations : repeated terms are automatically detected and evaluated only once, simplifications if the mesh has uniform type of elements, simplifications for vectorized fnite element methods.

Moreover, there is specifics function for interpolation operations (ga_interpolation(…), ga_interpolation_exec(…), ga_interpolation_Lagrange_fem, ga_interpolation_mti, ga_interpolation_im_data, …)

## Assembly tree¶

Assembly strings are transformed into assembly trees by `ga_read_string(...)`

. Assembly trees are syntax trees that are progressively enriched in information in the differents steps (semantic analysis, derivation, compilation).

The object `ga_tree`

represents an assembly tree. It is a copyable object that only contains a pointer to the root of the tree. Each tree node is an object `ga_tree_node`

that contains the main following information:

- node_type (function, variable value, variable gradient, operation …)
- operation type for operation nodes.
- assembly tensor: used at execution time by optimized instructions to compute the intermediary results. The final result is in the assembly string of the root node at the end of the execution (for each Gauss point).
- term type: value, order one term (ith order one test functions), order two term (with order two test functions) or with both order one and order two test functions (tangent term).
- variable name of tests functions for order 1 or 2 terms.
- pointer to the parent node.
- pointers to the children nodes.

For example, the assembly tree for the assembly string “a*Grad_Test2_u.Grad_Test_u” for the stiffness matrix of a Laplacian problem can be represented as follows with its assembly tensors at each node:

## Assembly tensors¶

Assembly tensors are represented on each node by a `bgeot::tensor<double>`

object. However, there is a specific structure in `src/getfem_generic_assembly.cc`

for assembly tensors because there is several format of assembly tensors :

Normal tensor. The first and second indices may represent the test function local indices if the node represent a first or second order term. Remember that in

*GetFEM*all tensors are stored with a Fortran order. This means that for instance t for a \(N\times P\times Q\) tensor one has`t(i, j, k) = t[i + j*N + k*N*P]`

.Copied tensor. When a node is detected to have exactly the same expression compared to an already compiled one, the assembly tensor will contain a pointer to the assembly tensor of the already compiled node. The consequence is that no unnecessary copy is made.

Sparse tensor with a listed sparsity. When working with a vector field, the finite element method is applied on each component. This results on vector base functions having only one nonzero component and some components are duplicated. The tensor are fully represented because it would be difficul to gain in efficiency with that kind of small sparse tensor format. However, some operation can be optimized with the knoledge of a certain sparsity (and duplication). This can change the order of complexity of a reduction. In order to allows this gain in efficiency, the tensor are labellised with some known sparsity format (vectorisation and format coming from operation applied on vectorized tensors). This results in a certain number of sparsity formats that are listed below:

1: Vectorized base sparsity format: The tensor represent a vectorized value. Each value of the condensed tensor is repeated on \(Q\) components of the vectorized tensor. The mesh dimensions is denoted \(N\). For instance if \(\varphi_i\) are the \(M\) local base functions on an element and the evaluation is on a Gauss point \(x\), then the non vectorized tensor is \(\bar{t}(i) = \varphi_i(x)\) and the vectorized one is \(t(j,k) = \varphi_{j/Q}(x) \delta_{k, j \mbox{ mod } Q}\) where \(j/M\) is the integer division. For \(M=2\), \(Q=2\) and \(N=3\) the components of the two tensors are represented in the following table

Scalar tensor Vectorized tensor \(\bar{t}(i) = \varphi_i(x)\) \(t(j,k) = \varphi_{j/Q}(x) \delta_{k, (j \mbox{ mod } Q)}\) \([\varphi_0(x), \varphi_1(x)]\) \([\varphi_0(x), 0, \varphi_1(x), 0, 0, \varphi_0(x), 0, \varphi_1(x)]\) 2: Grad condensed format

Scalar tensor Vectorized tensor \(\bar{t}(i,j) = \partial_j\varphi_i(x)\) \(t(k,l,m) = \partial_m\varphi_{k/Q}(x) \delta_{l, (m \mbox{ mod } Q)}\) \([\partial_0\varphi_0(x), \partial_0\varphi_1(x),\) \(\partial_1\varphi_0(x), \partial_1\varphi_1(x),\) \(\partial_2\varphi_0(x), \partial_2\varphi_1(x)]\) 3: Hessian condensed format

10: Vectorized mass: the tensor represent a scalar product of two vectorised base functions. This means a tensor \(t(\cdot,\cdot)\) where \(t(i*Q+k, j*Q+l) = 0\) for \(k \ne l\) and \(t(i*Q+k, j*Q+k)\) are equals for \(0 \le k < Q\).

## Optimized instructions¶

Optimized instructions for variable evaluation, operations, vector and matrix assembly … to be described.

## Predefined functions¶

- Some predefined scalar functions are available in GWFL in order to describe a weak formulation (or also to make basic algebraic computations). This is limited to scalar functions of one or two arguments. Due to the automatic differentiation used to obtain the tangent system of described problems, the derivative each function have to be available. The principle retained is the following: For each predefined function is available:
- A C++ function which computes the value given the argument(s).
- The support of the function in the first each argument in term of a (possibly infinite) interval (this is for simplification of expressions).
- The string corresponding of the derivative in terms of already known functions

A new predefined function is easy to add. See init_predefined_functions() in file `src/getfem_generic_assembly.cc`

. + describe how to give the derivative …

## Predefined nonlinear operators¶

to be described …

## State¶

Stable.

## Perspectives¶

- Is a certain extension to complex data possible ?
- More simplifications : study the possibility to automatically factorize some terms (for instance scalar ones) to reduce the number of operations.