/** @file mapper.h
 *  @brief Definitions for mapper objects.
 *
 * A mapper objects defines how and what to map between two grid families.
 * For example, a mapper object can be used to map the charge from
 * a @a cdr grid to a @a Poisson grid, or to map the @a potential of a Poisson
 * grid into one of the components of the @a electric field in a @a cdr grid.
 * For that, a mapper object has to implement some methods that tell us
 * how to map things in the cases\n
 * a) the source grid is coarser than the target grid (interpolation),\n
 * b) the source and the target are at the same level (copy),\n
 * c) the target grid is coarser (coarsening).
 */

#ifndef _MAPPER_H_

typedef struct mapper_t mapper_t;

#ifndef _INTERPOL2_H_
# include "interpol2.h"
#endif

#define _coarsen_params_ (mapper_t *mapper, grid_t *source, grid_t *target, \
			  int ir, int iz, int itheta)
#define _copy_params_ (mapper_t *mapper, grid_t *source, grid_t *target, \
		       int ir, int iz, int itheta)
#define _interpol_set_params_ (mapper_t *mapper, grid_t *source, \
			       interpol_t *interpol, int ir, \
			       int iz, int itheta)
#define _interpol_params_ (mapper_t *mapper, grid_t *source, grid_t *target, \
			   interpol_t *interpol, int ir, int iz, int itheta)


struct mapper_t {
  interpol_method_t *interpol_method;

  void (*coarsen) _coarsen_params_;
  void (*copy) _copy_params_;
  /* may return false if we are outside the source grid. */
  int (*interpol_set) _interpol_set_params_;

  void (*interpol) _interpol_params_;

  /* This is used for the interpolation of electric fields and indicates
   * the staggering of the cells.  When we call the interpolator to set
   * the stencil at coordinates pr, pz, the fine-grid cells whose value will
   * later be calculated ir, iz with
   *   pr << level_diff + shift_r << (level_diff - 1) <= ir 
   * < pr << level_diff + shift_r << (level_diff - 1)
   * 
   * (and the equivalent for iz). 
   * Hence note that for interpolation in not-staggered grids, 
   * (i.e. charge, densities, ...)
   * shift_r = shift_z = 0.
   */
  int shift_r, shift_z;

  /* We provide this extra member to allow the easy creation of different
   * mappers that share the same functions but have a slightly different
   * behaviour.  In particular this is used in cdr.c to define
   * different interpolators for each species.  In that case, extra is the
   * species index.
   */
  int extra;
};


/** Usually, we will define functions called xxxx_coarsen, xxxx_copy, etc
   to implement the above interface.  We define these macros to facilitate
   the declaration of such functions. */
#define decl_mapper_funcs(_VAR)				\
  void _VAR ## _coarsen _coarsen_params_;		\
  void _VAR ## _copy _copy_params_;			\
  int _VAR ## _interpol_set _interpol_set_params_;	\
  void _VAR ## _interpol _interpol_params_

/** Useful to init a staggered mapper object */
#define mk_mapper_staggered(_C, _INTERPOL_METHOD, _SHIFT_R, _SHIFT_Z)	\
  {_INTERPOL_METHOD, _C ## _coarsen, _C ## _copy,			\
      _C ## _interpol_set, _C ##_interpol, _SHIFT_R, _SHIFT_Z, 0}

/** Useful to init a mapper object */
#define mk_mapper(_C, _INTERPOL_METHOD)					\
  mk_mapper_staggered (_C, _INTERPOL_METHOD, 0, 0)

/** Mappers that only copy or interpolate. */
#define mk_mapper_down(_C, _INTERPOL_METHOD)				\
  {_INTERPOL_METHOD, NULL, _C ## _copy,					\
      _C ## _interpol_set, _C ##_interpol, 0, 0, 0}

#define _MAPPER_H_
#endif