.. Documentation for the header file dolfin/fem/Form.h

.. _programmers_reference_cpp_fem_form:

Form.h
======

.. note::
    
    The documentation on this page was automatically extracted from the
    DOLFIN C++ code and may need to be edited or expanded.
    

.. cpp:class:: Form

    *Parent class(es)*
    
        * :cpp:class:`Hierarchical<Form>`
        
    Base class for UFC code generated by FFC for DOLFIN with option -l.
    
    A note on the order of trial and test spaces: FEniCS numbers
    argument spaces starting with the leading dimension of the
    corresponding tensor (matrix). In other words, the test space is
    numbered 0 and the trial space is numbered 1. However, in order
    to have a notation that agrees with most existing finite element
    literature, in particular
    
        a = a(u, v)
    
    the spaces are numbered from right to
    
        a: V_1 x V_0 -> R
    
    .. note::
    
        Figure out how to write this in math mode without it getting
        messed up in the Python version.
    
    This is reflected in the ordering of the spaces that should be
    supplied to generated subclasses. In particular, when a bilinear
    form is initialized, it should be initialized as
    
    .. code-block:: c++
    
        a(V_1, V_0) = ...
    
    where ``V_1`` is the trial space and ``V_0`` is the test space.
    However, when a form is initialized by a list of argument spaces
    (the variable ``function_spaces`` in the constructors below, the
    list of spaces should start with space number 0 (the test space)
    and then space number 1 (the trial space).


    .. cpp:function:: Form(std::size_t rank, std::size_t num_coefficients)
    
        Create form of given rank with given number of coefficients
        
        *Arguments*
            rank (std::size_t)
                The rank.
            num_coefficients (std::size_t)
                The number of coefficients.


    .. cpp:function:: Form(std::shared_ptr<const ufc::form> ufc_form, std::vector<std::shared_ptr<const FunctionSpace>> function_spaces)
    
        Create form (shared data)
        
        *Arguments*
            ufc_form (ufc::form)
                The UFC form.
            function_spaces (std::vector<:cpp:class:`FunctionSpace`>)
                Vector of function spaces.


    .. cpp:function:: std::size_t rank() const
    
        Return rank of form (bilinear form = 2, linear form = 1,
        functional = 0, etc)
        
        *Returns*
            std::size_t
                The rank of the form.


    .. cpp:function:: std::size_t num_coefficients() const
    
        Return number of coefficients
        
        *Returns*
            std::size_t
                The number of coefficients.


    .. cpp:function:: std::size_t original_coefficient_position(std::size_t i) const
    
        Return original coefficient position for each coefficient (0 <= i < n)
        
        *Returns*
            std::size_t
                The position of coefficient i in original ufl form coefficients.


    .. cpp:function:: std::vector<std::size_t> coloring(std::size_t entity_dim) const
    
        Return coloring type for colored (multi-threaded) assembly of form
        over a mesh entity of a given dimension
        
        *Arguments*
            entity_dim (std::size_t)
                Dimension.
        
        *Returns*
            std::vector<std::size_t>
                Coloring type.


    .. cpp:function:: void set_mesh(std::shared_ptr<const Mesh> mesh)
    
        Set mesh, necessary for functionals when there are no function spaces
        
        *Arguments*
            mesh (:cpp:class:`Mesh`)
                The mesh.


    .. cpp:function:: std::shared_ptr<const Mesh> mesh() const
    
        Extract common mesh from form
        
        *Returns*
            :cpp:class:`Mesh`
                Shared pointer to the mesh.


    .. cpp:function:: std::shared_ptr<const FunctionSpace> function_space(std::size_t i) const
    
        Return function space for given argument
        
        *Arguments*
            i (std::size_t)
                Index
        
        *Returns*
            :cpp:class:`FunctionSpace`
                Function space shared pointer.


    .. cpp:function:: std::vector<std::shared_ptr<const FunctionSpace>> function_spaces() const
    
        Return function spaces for arguments
        
        *Returns*
            std::vector<:cpp:class:`FunctionSpace`>
                Vector of function space shared pointers.


    .. cpp:function:: void set_coefficient(std::size_t i, std::shared_ptr<const GenericFunction> coefficient)
    
        Set coefficient with given number (shared pointer version)
        
        *Arguments*
            i (std::size_t)
                The given number.
            coefficient (:cpp:class:`GenericFunction`)
                The coefficient.


    .. cpp:function:: void set_coefficient(std::string name, std::shared_ptr<const GenericFunction> coefficient)
    
        Set coefficient with given name (shared pointer version)
        
        *Arguments*
            name (std::string)
                The name.
            coefficient (:cpp:class:`GenericFunction`)
                The coefficient.


    .. cpp:function:: void set_coefficients(std::map<std::string, std::shared_ptr<const GenericFunction>> coefficients)
    
        Set all coefficients in given map. All coefficients in the
        given map, which may contain only a subset of the coefficients
        of the form, will be set.
        
        *Arguments*
            coefficients (std::map<std::string, :cpp:class:`GenericFunction`>)
                The map of coefficients.


    .. cpp:function:: void set_some_coefficients(std::map<std::string, std::shared_ptr<const GenericFunction>> coefficients)
    
        Set some coefficients in given map. Each coefficient in the
        given map will be set, if the name of the coefficient matches
        the name of a coefficient in the form.
        
        This is useful when reusing the same coefficient map for
        several forms, or when some part of the form has been
        outcommented (for testing) in the UFL file, which means that
        the coefficient and attaching it to the form does not need to
        be outcommented in a C++ program using code from the generated
        UFL file.
        
        *Arguments*
            coefficients (std::map<std::string, :cpp:class:`GenericFunction`>)
                The map of coefficients.


    .. cpp:function:: std::shared_ptr<const GenericFunction> coefficient(std::size_t i) const
    
        Return coefficient with given number
        
        *Arguments*
            i (std::size_t)
                Index
        
        *Returns*
            :cpp:class:`GenericFunction`
                The coefficient.


    .. cpp:function:: std::shared_ptr<const GenericFunction> coefficient(std::string name) const
    
        Return coefficient with given name
        
        *Arguments*
            name (std::string)
                The name.
        
        *Returns*
            :cpp:class:`GenericFunction`
                The coefficient.


    .. cpp:function:: std::vector<std::shared_ptr<const GenericFunction>> coefficients() const
    
        Return all coefficients
        
        *Returns*
            std::vector<:cpp:class:`GenericFunction`>
                All coefficients.


    .. cpp:function:: std::size_t coefficient_number(const std::string & name) const
    
        Return the number of the coefficient with this name
        
        *Arguments*
            name (std::string)
                The name.
        
        *Returns*
            std::size_t
                The number of the coefficient with the given name.


    .. cpp:function:: std::string coefficient_name(std::size_t i) const
    
        Return the name of the coefficient with this number
        
        *Arguments*
            i (std::size_t)
                The number
        
        *Returns*
            std::string
                The name of the coefficient with the given number.


    .. cpp:function:: std::shared_ptr<const MeshFunction<std::size_t>> cell_domains() const
    
        Return cell domains (zero pointer if no domains have been
        specified)
        
        *Returns*
            :cpp:class:`MeshFunction` <std::size_t>
                The cell domains.


    .. cpp:function:: std::shared_ptr<const MeshFunction<std::size_t>> exterior_facet_domains() const
    
        Return exterior facet domains (zero pointer if no domains have
        been specified)
        
        *Returns*
            std::shared_ptr<:cpp:class:`MeshFunction` <std::size_t>>
                The exterior facet domains.


    .. cpp:function:: std::shared_ptr<const MeshFunction<std::size_t>> interior_facet_domains() const
    
        Return interior facet domains (zero pointer if no domains have
        been specified)
        
        *Returns*
            :cpp:class:`MeshFunction` <std::size_t>
                The interior facet domains.


    .. cpp:function:: std::shared_ptr<const MeshFunction<std::size_t>> vertex_domains() const
    
        Return vertex domains (zero pointer if no domains have been
        specified)
        
        *Returns*
            :cpp:class:`MeshFunction` <std::size_t>
                The vertex domains.


    .. cpp:function:: void set_cell_domains(std::shared_ptr<const MeshFunction<std::size_t>> cell_domains)
    
        Set cell domains
        
        *Arguments*
            cell_domains (:cpp:class:`MeshFunction` <std::size_t>)
                The cell domains.


    .. cpp:function:: void set_exterior_facet_domains(std::shared_ptr<const MeshFunction<std::size_t>> exterior_facet_domains)
    
        Set exterior facet domains
        
        *Arguments*
            exterior_facet_domains (:cpp:class:`MeshFunction` <std::size_t>)
                The exterior facet domains.


    .. cpp:function:: void set_interior_facet_domains(std::shared_ptr<const MeshFunction<std::size_t>> interior_facet_domains)
    
        Set interior facet domains
        
        *Arguments*
            interior_facet_domains (:cpp:class:`MeshFunction` <std::size_t>)
                The interior facet domains.


    .. cpp:function:: void set_vertex_domains(std::shared_ptr<const MeshFunction<std::size_t>> vertex_domains)
    
        Set vertex domains
        
        *Arguments*
            vertex_domains (:cpp:class:`MeshFunction` <std::size_t>)
                The vertex domains.


    .. cpp:function:: std::shared_ptr<const ufc::form> ufc_form() const
    
        Return UFC form shared pointer
        
        *Returns*
            ufc::form
                The UFC form.


    .. cpp:function:: void check() const
    
        Check function spaces and coefficients


    .. cpp:function:: Equation operator==(const Form& rhs) const
    
        Comparison operator, returning equation lhs == rhs


    .. cpp:function:: Equation operator==(int rhs) const
    
        Comparison operator, returning equation lhs == 0