.TH "form" 2rheolef "Version 7.2" "rheolef" \" -*- nroff -*-
.ad l
.nh
.SH NAME
form \- finite element bilinear form (rheolef-7\&.2)
.SH "DESCRIPTION"
.PP
The form class groups four sparse matrix, associated to a bilinear form defined on two finite element spaces: 
.PP
.nf
   a: Uh*Vh   ----> IR
     (uh,vh)  +---> a(uh,vh)

.fi
.PP
 The \fCA\fP operator associated to the bilinear form is defined by: 
.PP
.nf
   A: Uh  ----> Vh
      uh  +---> A*uh

.fi
.PP
 where \fCuh\fP is a \fBfield(2)\fP, and \fCvh=A*uh in Vh\fP is such that \fCa(uh,vh)=dual(A*uh,vh)\fP for all \fCvh in Vh\fP and where \fCdual(\&.,\&.)\fP denotes the duality product between \fCVh\fP and its dual\&. Since \fCVh\fP is a finite dimensional space, its dual is identified to \fCVh\fP itself and the duality product is the euclidean product in \fCIR^dim(Vh)\fP\&. Also, the linear operator can be represented by a matrix\&.
.PP
In practice, bilinear forms are created by using the \fBintegrate(3)\fP function\&.
.PP
 
.SH "ALGEBRA"
.PP
Forms, as matrix, support standard algebra\&. Adding or subtracting two forms writes \fCa+b\fP and \fCa-b\fP, respectively, while multiplying by a scalar \fClambda\fP writes \fClambda*a\fP and multiplying two forms writes \fCa*b\fP\&. Also, multiplying a form by a field \fCuh\fP writes \fCa*uh\fP\&. The form inversion is not as direct as e\&.g\&. as \fCinv(a)\fP, since forms are very large matrix in practice: form inversion can be obtained via the \fBsolver(4)\fP class\&. A notable exception is the case of block-diagonal forms at the element level: in that case, a direct inversion is possible during the assembly process, see \fBintegrate_option(3)\fP\&.
.SH "REPRESENTATION"
.PP
The degrees of freedom (see \fBspace(2)\fP) are splited between \fIunknowns and blocked\fP, i\&.e\&. \fCuh=[uh\&.u,uh\&.b]\fP for any field \fCuh in Uh\fP\&. Conversely, \fCvh=[vh\&.u,vh\&.b]\fP for any field \fCvh in Vh\fP\&. Then, the form-field \fCvh=a*uh\fP operation is formally equivalent to the following matrix-vector block operations: 
.PP
.nf
    [ vh\&.u ]   [ a\&.uu  a\&.ub ] [ uh\&.u ]
    [      ] = [            ] [      ]
    [ vh\&.b ]   [ a\&.bu  a\&.bb ] [ uh\&.n ]

.fi
.PP
 or, after expansion: 
.PP
.nf
    vh\&.u = a\&.uu*uh\&.u + a\&.ub*vh\&.b
    vh\&.b = a\&.bu*uh\&.b + a\&.bb*vh\&.b

.fi
.PP
 i\&.e\&. the \fCA\fP matrix also admits a 2x2 block structure\&. Then, the \fCform\fP class is represented by four sparse matrix and the \fBcsr(4)\fP compressed format is used\&. Note that the previous formal relations for \fCvh=a*uh\fP writes equivalently within the Rheolef library as: 
.PP
.nf
    vh\&.set_u() = a\&.uu()*uh\&.u() + a\&.ub()*uh\&.b();
    vh\&.set_b() = a\&.bu()*uh\&.u() + a\&.bb()*uh\&.b();

.fi
.PP
 
.SH "IMPLEMENTATION"
.PP
This documentation has been generated from file main/lib/form\&.h
.PP
The \fCform\fP class is simply an alias to the \fC\fBform_basic\fP\fP class
.PP
.PP
.nf
typedef form_basic<Float,rheo_default_memory_model> form;
.fi
.PP
 
.PP
\fB\fP
.RS 4

.RE
.PP
The \fC\fBform_basic\fP\fP class provides an interface to four sparse matrix:
.PP
.PP
.nf
template<class T, class M>
class form_basic {
public :
// typedefs:

    typedef typename csr<T,M>::size_type    size_type;
    typedef T                               value_type;
    typedef typename scalar_traits<T>::type float_type;
    typedef geo_basic<float_type,M>         geo_type;
    typedef space_basic<float_type,M>       space_type;

// allocator/deallocator:

    form_basic ();
    form_basic (const form_basic<T,M>&);
    form_basic<T,M>& operator= (const form_basic<T,M>&);
 
    template<class Expr, class Sfinae = typename std::enable_if<details::is_form_lazy<Expr>::value, Expr>::type>
    form_basic (const Expr&);

    template<class Expr, class Sfinae = typename std::enable_if<details::is_form_lazy<Expr>::value, Expr>::type>
    form_basic<T,M>& operator= (const Expr&);

// allocators from initializer list (c++ 2011):

    form_basic (const std::initializer_list<details::form_concat_value<T,M> >& init_list);
    form_basic (const std::initializer_list<details::form_concat_line <T,M> >& init_list);

// accessors:

    const space_type& get_first_space() const;
    const space_type& get_second_space() const;
    const geo_type&   get_geo() const;
    bool is_symmetric() const;
    void set_symmetry (bool is_symm = true) const;
    bool is_definite_positive() const;
    void set_definite_positive (bool is_dp = true) const;
    bool is_symmetric_definite_positive() const;
    void set_symmetric_definite_positive() const;

    const communicator& comm() const;

// linear algebra:

    form_basic<T,M>  operator+  (const form_basic<T,M>& b) const;
    form_basic<T,M>  operator\-  (const form_basic<T,M>& b) const;
    form_basic<T,M>  operator*  (const form_basic<T,M>& b) const;
    form_basic<T,M>& operator*= (const T& lambda);
    field_basic<T,M> operator*  (const field_basic<T,M>& xh) const;
    field_basic<T,M> trans_mult (const field_basic<T,M>& yh) const;
    float_type operator () (const field_basic<T,M>& uh, const field_basic<T,M>& vh) const;

// io:

    odiststream& put (odiststream& ops, bool show_partition = true) const;
    void dump (std::string name) const;

// accessors & modifiers to unknown & blocked parts:

    const csr<T,M>&     uu() const { return _uu; }
    const csr<T,M>&     ub() const { return _ub; }
    const csr<T,M>&     bu() const { return _bu; }
    const csr<T,M>&     bb() const { return _bb; }
          csr<T,M>& set_uu()       { return _uu; }
          csr<T,M>& set_ub()       { return _ub; }
          csr<T,M>& set_bu()       { return _bu; }
          csr<T,M>& set_bb()       { return _bb; }
.fi
.PP
 
.PP
.nf
};
template<class T, class M> form_basic<T,M> trans (const form_basic<T,M>& a);
template<class T, class M> field_basic<T,M> diag (const form_basic<T,M>& a);
template<class T, class M> form_basic<T,M>  diag (const field_basic<T,M>& dh);

.fi
.PP
 
.SH AUTHOR
Pierre  Saramito  <Pierre.Saramito@imag.fr>
.SH COPYRIGHT
Copyright   (C)  2000-2018  Pierre  Saramito  <Pierre.Saramito@imag.fr>
GPLv3+: GNU GPL version 3 or later  <http://gnu.org/licenses/gpl.html>.
This  is  free  software:  you  are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.