New structure for mapping classes in sympde and psydac

[campospinto]

This issue is a follow-up on the work done during Patrick Lagarrigue's internship on the mapping classes in sympde and psydac, see for instance PR #429 and the discussion in Sympde PR#168

The objective is to have a simpler and more consistent structure for mapping classes, to simplify their user interface (and their development)

Current structure

Currently there are two separate class hierarchies for mappings:

• The first one is internal to sympde and is used for symbolic mapping objects, which may be undefined
  (they have a name and a dimension but no specific expressions) or analytic (carrying an explicit symbolic expressions for the coordinates (x, y, z) as a function of the logical ones, which are stored in the class attribute _expressions).

The base class of this hierarchy belongs to the sympy library, hence the objects instantiated are also compatible with sympy. The class inheritance diagram is:

IndexedBase [sympy]
     |
      — > BasicMapping [sympde]
               |
                — > Mapping [sympde]
                       |
                         — > IdentityMapping, AffineMapping, PolarMapping, ... 

• The second class hierarchy runs across sympde and psydac, it is for "callable" mappings, which can be called at a point in the logical domain or at multiple points at once. Here the base class belongs to sympde and is the abstract class BasicCallableMapping, which defines an interface (i.e. the signature of all methods) for the concrete subclasses which can be instantiated.

In particular, sympde provides the concrete subclass CallableMapping which takes an analytic Mapping object as argument to the constructor, and generates standard Python functions from the symbolic expressions of the given mapping.

All mappings in psydac are "callable", i.e. they can be evaluated at a point. In order to make them interchangeable with sympde callable mappings, all mapping classes in psydac subclass the same abstract class BasicCallableMapping. Hence the class inheritance diagram for the second hierarchy is:

BasicCallableMapping [sympde] (abstract: interface for "callable" mappings)
         |
         | — > CallableMapping [sympde]
         |
           — > SplineMapping [psydac]
                     |
                      — > NurbsMapping [psydac]

Proposed structure

A desirable structure should have a unique mapping hierarchy, for instance:

IndexedBase [sympy]
  |
   -> SymbolicMapping [sympde]
        | \
        |  -> DefinedMapping [sympde] (abstract, point-evaluable)
        |      | \
        |      |  -> AnalyticMapping [sympde]
        |      |      |
        |      |      -> PolarMapping, AffineMapping, IdentityMapping, ...
        |      |
        |      -> SplineMapping [psydac]
        |             |
        |             -> NurbsMapping [psydac]
        |
        -> StructuralMapping [sympde] (abstract, symbolic/non-point-evaluable)
               |
               -> InverseMapping, InterfaceMapping, MultiPatchMapping

Here,

• the base class belongs again to the sympy library (this may be discussed)

• the first subclass in sympde is for "symbolic mappings", that is, mappings essentially represented by a symbol. They may only have a name and a dimension, and can be used to define a symbolic mapped domain.

• the class StructuralMapping collects symbolic mapping objects that are not point-evaluable (for example interface and multipatch structures).

• the class DefinedMapping plays a role of an abstract class, it corresponds to mappings that can actually be evaluated on logical points (previously called "callable" mappings). They may be either defined by expressions (analytical mappings) or spline/nurbs coefficients on a tensor-product grid.

• the class StructuralMapping is not very specfic, it should be refined (InterfaceMapping and MultiPatchMapping seem to be essentially containers for different patch mappings, and InverseMapping does not seem to be used anywhere)

[campospinto]

This new structure is currently under implementation in the branches new_mappings_2 (psydac) and new_mappings_2 (sympde). Two parallel draft PRs will be open when their state stabilises. In the meantime, we may discuss here the desired strategy.