Current situation

Currently in SymPDE there are two separate class hierarchies. The first one is internal to SymPDE and is used for symbolic mapping objects, which can be either undefined or analytic:

1. Undefined mappings are determined only by their name (a string) and by dim (an integer which represents the number of parametric dimensions);
2. Analytic mappings also carry explicit symbolic expressions for the coordinates (x, y, z), which are stored in the class attribute _expressions.

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

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

The second class hierarchy is for mappings whose coordinates (x, y, z) can be evaluated 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 unique argument to the constructor, and uses the lambdify function of SymPy to generate standard Python functions from the symbolic expressions of the given object.

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 (abstract: interface for "callable" mappings)
         |
         | — > CallableMapping
         |
           — > SplineMapping [psydac]
                     |
                      — > NurbsMapping [psydac]

In Psydac one deals with symbolic Mapping objects which "correspond to" spline or NURBS mappings. To represent this relationship, we attach a SplineMapping to an undefined Mapping object, thanks to the method Mapping.set_callable_mapping(F : BasicCallableMapping). Successive calls to get_callable_mapping will return the given object.

Of course this can be done with pure SymPDE mappings, as in

F_symb = PolarMapping(...)
F_eval = CallableMapping(F_symb)    # explicit, but...
F_symb.set_callable_mapping(F_eval) # easy to forget!

To avoid having to remember the last command, we can call the method Mapping.get_callable_mapping on the second line, because when called on an analytic mapping, it simply returns CallableMapping(self) and stores the result internally. Hence:

F_symb = PolarMapping(...)
F_eval = F_symb.get_callable_mapping()

The circular relationship between the classes Mapping and [Basic]CallableMapping is the main source of complexity which we would like to address in this PR.

Proposed improvement

This PR aims at cleaning the Psydac-SymPDE mapping interface. There is now only one mapping hierarchy

                                  SplineMapping    -->   NURBS
                               /    (Psydac)            (Psydac)
                              / 
IndexBase  -->  BaseMapping - 
 (SymPy)         (SymPDE)     \
                               \
                                BaseAnalyticMapping   -->  PolarMapping, AffineMapping, IdentityMapping ... 
                                     (SymPDE)                (SymPDE)      (SymPDE)        (SymPDE)

The main features are :

• getting rid of callable mappings. You can now deal with analytic or spline mappings and do point / domain / array / meshgrid - wise evaluations.

• All the symbolic calculus features in the previous Mapping class are preserved in BaseMapping. It's essentially the same constructor.

• BaseAnalyticMapping is just BaseMapping constructor added with the lambdify_sympde functions, to make evaluation methods.

In this branch, instantiating spline mapping and analytic mapping is like previously.

Improvements may be done : the meshgrid evaluation method doesn't support the sparse meshgrid format.