Improve FEM API

[campospinto]

When trying to improve the compatibility between single and multi-patch simulations, I noticed a few issues with the Fem user interface. Below is a list, with some suggestions for improvement.

First a reminder of the different types of Fem spaces:

    - class psydac.fem.vector.ProductFemSpace:

      used for Vh = multi-patch FEM space
      
      then:
        
        - Vh.spaces[i] = FEM space on patch i
        - Vh.vector_space is of class psydac.linalg.block.BlockVectorSpace
          
    - class psydac.fem.vector.VectorFemSpace:
      
      used for Vh = single-patch, vector-valued FEM space
      
      then: 
      
        - Vh.spaces[i] = FEM space for (logical) component i
        - Vh.vector_space is of class psydac.linalg.block.BlockVectorSpace
        
    - class psydac.fem.tensor.TensorFemSpace:

      used for Vh = single-patch, scalar-valued tensor product FEM space 

      then:
      
        - Vh.spaces[i] = spline space along (logical) axis i
        - Vh.vector_space is of class psydac.linalg.stencil.StencilVectorSpace
      
    - class psydac.fem.splines.SplineSpace:

      used for Vh = scalar spline space on interval
      
      then: 
      
        - Vh has no attribute 'spaces' 
        - Vh.vector_space is of class 'psydac.linalg.stencil.StencilVectorSpace'

Then, a list of some problems that I saw:

1. name ProductFemSpace is ambiguous: seems to be used only for multi-patch spaces, but a space of vector-valued fields
   (a VectorFemSpace) is also a product of FEM spaces...

   -> rename as MultipatchFemSpace ?

2. "product" ambiguity is made worse by the flag function Vh.is_product which means either multi-patch or vector-valued
   (see for instance in the FemField constructor where its is understood as vector-valued...)

   -> replace by Vh.is_multipatch and Vh.is_vector_valued ?

3. also the ProductFemSpace constructor may not return a ProductFemSpace, so the code is not easy to follow.

   -> use factory function instead ?

4. Vh.spaces may return different types of spaces (as seen above) which makes the code not always easy to read, and hampers the single/multi-patch compatibility

   ->: add helper attributes? eg

   • Vh.patch_spaces[i]:
     if Vh is multi-patch space (ie ProductFemSpace), returns FEM space on patch i
     if Vh is single-patch (anything else) returns itself (and raise Error if i>0 ?)

   • Vh.component_spaces[i]:
     if Vh is multi-patch space (ie ProductFemSpace), raise error
     if Vh is single-patch, vector-valued (ie VectorFemSpace) returns space of component i
     if Vh is single-patch, scalar-valued (ie TensorFemSpace) returns itself (or error? only if i>0?)

   • Vh.axis_spaces[i]:
     if Vh is single-patch, scalar-valued tensor-product (ie TensorFemSpace), returns space for axis i
     else raise Error ?

5. a similar problem occurs for a multipatch/vector-valued FemField uh (uh.fields may correspond to patch or component fields)

   -> add helper functions? eg

   • uh.patch_field(i):
     if uh is a multi-patch field returns FEM field on patch i
     else returns itself (raise error if i>0 ?)

   • Vh.component_field(i):
     needed ?

6. several function or class docstrings indicate types of arguments which are wrong,
   eg:

   "L2 : SplineSpace" in class Projector_L2(GlobalProjector)

   "Vh : TensorFemSpace" in function construct_hcurl_conforming_projection
   (in feec.multipatch.non_matching_operators)

   -> better review of MR, use type hints, asserts ?

7. the class DiscreteDerhamMultipatch is a subclass of DiscreteDerham (single patch by default)
   but it does not implement all the basic methods.
   In particular, the derivatives method which returns the differential operators is not implemented.

-> all the make sure that all the functions of DiscreteDerham are well implemented for DiscreteDerhamMultipatch.
In particular, for a multipatch dR sequence the derivatives should return the broken_derivatives (as operators, matrices).
should be understood as broken ones

8. the DiffOperator class does not subclass FemLinearOperator, although they are very similar

-> Doing so will probably simplify a few things. Also,to_sparse_matrix (to convert a FemLinearOperator to sparse scipy format)
can probably be merged with tosparse

9. the folder structure for single and multi-patch feec is not consistent:
   • DiscreteDerhamMultipatch in feec/multipatch/api
   • DiscreteDerham in api/feec

-> move the DiscreteDerhamMultipatch api in api/broken_feec ? Or api/feec/broken ?
(original idea was that classes defined in the api directory are exposed to the user)

There is also a related problem in Sympde:

10. domain.interior.args returns objects of different types:

    • for a multi-patch domain: the subdomains as a tuple of logical domains
    • for a single patch domain: the name of the unique subdomain (the domain itself), as a tuple of strings,

    -> this is probably because domain.interior is a Union of subdomains.
    To fix this without changing how Unions are handled in Sympde, we could add a function/attribute domain.subdomains which always returns the subdomains as a tuple of logical domains