doc/user/doxygen/doxfiles/appendix/interpkernel.dox

   1 /*!
   2 \page interpkernel Interpolation kernel - Implementation notes
   3
   4 \section InterpKerIntro Introduction
   5
   6 The main purpose of this module is to propose a set of algorithms for
   7 mesh interpolation \b fully \b independent \b of \b the \b mesh \b data structure to
   8 support several type of format. This component is parametrized as
   9 much as possible using C++ templates.
  10 For the moment only interpolators for unstructured meshes are present in
  11 the %interpolation kernel.
  12
  13 \section InterpKerMainArchitecture Main architecture of interpolation kernel.
  14
  15 In the %interpolation kernel, algorithms that computes the intersection \f$ T_i\cap S_j\f$ given the locations and geometries of source cell \f$ S_j \f$
  16 and target cell \f$ T_i \f$ are called \ref InterpKerIntersectors.
  17
  18 As can be seen in \ref InterpKerRemapGlobal "the theory of interpolation", all the proposed interpolators aim at
  19 filling the interpolation matrix W (which is generally sparse). For each pair (i,j), \f$ W_{ij} \f$ is obtained
  20 by calling the desired intersector. The problem is that each call to this algorithm
  21 is CPU-expensive.
  22 To reduce the computational time, a first filtering is done to detect
  23 pairs (i,j) \f$ W_{ij} \f$ is obviously equal to 0. It is typically the case when a cell in the source mesh
  24 is too far from an another cell in the target mesh each.
  25
  26 So for a given type of interpolation, the computation of W is
  27 performed in two steps :
  28
  29 -# A filtering process reduces the number of pairs of elements for which the calculation
  30 must be carried out by eliminating the pairs whose bounding boxes do not intersect.
  31 -# For all remaining pairs, call the appropriate \ref InterpKerIntersectors "cell intersector"
  32
  33 Whatever its dimension and type, each interpolator inherits from INTERP_KERNEL::Interpolation which is a
  34 template (CRTP) class than enable an easy access to the main API without useless CPU cost.
  35
  36 \subsection InterpKerMeshType class MeshType
  37
  38 Each Interpolators and Intersectors are parametrized (templated in
  39 C++ language) with \c class \c MeshType . This type of generalization
  40 has been chosen to reduce at maximum overhead. \n
  41 Thanks to this principle intersectors and interpolators are usable
  42 with \b several \b mesh \b formats such as \c MED or \c VTK, \b without \b performance \b loss.
  43 \c MeshType is a concept that should strictly fulfilled the following
  44 rules :
  45
  46 - Const values / Types
  47   - MyConnType : represents type of connectivity index. This is typically \c int or \c long \c int .
  48   - MY_SPACEDIM : space dimension. Dimension relative to coordinates.
  49   - MY_MESHDIM : the dimension of all cells in meshes.
  50   - My_numPol : policy of numbering. C Format ( \f$ [0,n-1] \f$ ) or FORTRAN ( \f$ [1,n] \f$ ).
  51 - Methods
  52   -# \code void getBoundingBox(double *boundingBox) const \endcode
  53   -# \code INTERP_KERNEL::NormalizedCellType getTypeOfElement(MyConnType eltId) const \endcode
  54   -# \code unsigned char getNumberOfNodesOfElement(MyConnType eltId) const \endcode
  55   -# \code unsigned long getNumberOfNodes() const \endcode
  56   -# \code unsigned long getNumberOfElements() const \endcode
  57   -# \code const MyConnType *getConnectivityPtr() const \endcode
  58   -# \code const double *getCoordinatesPtr() const \endcode
  59   -# \code const MyConnType *getConnectivityIndexPtr() const \endcode
  60   -# \code void releaseTempArrays() \endcode
  61 - Formats of arrays
  62   - the array returned by \c getCoordinatesPtr must be a \b full \b interlace array.
  63   - the arrays returned by \c getConnectivityPtr and \c getConnectivityIndexPtr must be with the same principle as it is \ref MEDCouplingUMeshNodalConnectivity "implemented in MEDCouplingUMesh". Of course the numbering format may change according to \a My_numPol policy.
  64
  65 Note that the array format for connectivity is kept close to MED. It is
  66 close to VTK format too but slightly different. So it may require for the VTK side a copy
  67 on wrap. To avoid this copy of a part of the connectivity structure, an iterator should be used.
  68
  69 \subsection InterpKerMatrixType class MatrixType
  70
  71 As already said, the matrix returned by interpolator is typically a sparse matrix. Instances of
  72 \c class \c MatrixType are used to store the resulting interpolation matrix. To be able to be filled by the interpolator the \c MatrixType class has to match the following concept :
  73
  74 - Methods
  75   -# \code void resize(uint nbrows) \endcode
  76   -# \code Row &operator [] (uint irow) \endcode
  77
  78 \c class \c Row has to match at least the following concept :
  79
  80 - Methods
  81   - \code void insert(const std::pair<int,T>& myPair) \endcode
  82
  83 Note that \c std::vector\c < \c std::map<int,double> > is a candidate for \c MatrixType.
  84
  85 */