Interpolation Interfaces
------------------------

Authors: Thomas Radke
Date: Feb 2001
Status: Under discussion

We need to change the interface for interpolation operators.


The flesh will provide two routines for interpolation:

 - CCTK_InterpGV
   for interpolating distributed CCTK arrays 
   (ie. grid functions or arrays)

 - CCTK_InterpLocalArrays
   for interpolating local arrays
   We can still decide on a better name for this routine.


Their general interfaces are as follows:

  int CCTK_InterpGV (cGH *GH,
                     int operator_handle,
                     int coord_system_handle,
                     int num_points,
                     int num_in_array_indices,
                     int num_out_arrays,
                     ...)

  To make the old CCTK_Interp routine really general
  it now gets passed the grid coordinates it should
 work on. The first design was to pass the number of
  grid dimensions followed by the list of grid coordinate 
  variables (given by their indices to have all the
  information on data types, decomposition, ghostzones,
  etc.).
  I had the idea that one could simply name the
  coordinate system instead - as you do for all the
  CCTK_CoordXXX routines. We could use this also for
  the Hyperslab interface and in the I/O thorns.
  The disadvantage of it -could- be that you need to
  define a coordinate system first. But this is the
  case for all the places where the interpolator is 
  called now - "cart3d" is used everywhere.
  It might be confusing for people to call this
  routine without passing the "number of dimensions"
  information explicitely because the arrays in the
  variable argument list have to be of that dimension.
  Do you think we can sell this to the developers ?
  The coordinate system is passed as an integer 
  handle in order to make it working for the fortran 
  wrappers as well. So we'd need new flesh routines 

    int CCTK_CoordSystemHandle (const char *systemname);
    const char *CCTK_CoordSystemName (int handle);

  The rest of the arguments to CCTK_InterpGV is the
  same as for the old CCTK_InterpGF - the input
  arrays are passed by their indices so that I have
  all the information about them.
  This limits the routine to CCTK variables.
  If - in the far future hopefully - thorn developers
  manage their own distributed arrays we need to think
  about it again...

  int CCTK_InterpLocalArrays (cGH *GH,
                              int operator_handle,
                              int num_points,
                              int num_dims,
                              int num_in_arrays,
                              int num_out_arrays,
                              ...)

  This routine doesn't get passed a coordinate system
  handle because it's supposed to work on local
  arrays only. For that we have to tell it the number
  of dimensions, the dimensions themselfs as an array
  of pointers plus the types of those arrays.
  Also the input arrays are passed in as pointers with
  their types attached.

  The new C-implementation of a PUGH-based interpolator
  would now go into thorn PUGHInterp.
  To make clear what kind of interpolation it does I let
  it register itself with the name "regular uniform cartesian"
  Is this the correct terminus for that ?
  Also, since the actual interpolation routine is called
  for both local arrays and processor-local patches of
  global arrays, I decided to register it as one single
  operator - CCTK_InterpRegisterOperator takes two
  function pointers then. Do you think there might be
  implementations which can interpolate local arrays
  but not global ones or vice versa ?


Open questions:

1) Although it's working I didn't commit all the stuff yet.
   I was thinking about how to keep compatibility with the 
   old stuff. PUGHInterp and Interp don't conflict, also
   the new flesh interface - except for the registration.
   On the other hand, I changed AHFinder and Extract already 
   to make them working with the new interface and would 
   commit these changes as well.
   There's still a problem in IDAxiBrillBH but I believe
   it's not an interpolator issue - Ryoji seems to mix
   2D interpolation with 2D-3D transformation. We'll fix
   that tomorrow hopefully.
   So the only thing people would have to do themself after
   updating Cactus is to replace Interp by PUGHInterp in
   their thornlists and parameter files.
   Do you know any other people using the interpolator
   in their private thorns ?
   Do you think we still need the old interfaces then ?

2) For all grid variables which are passed by their indices
   the current timelevel is taken implicitely.
   Do we want users to pass in this information ?