CCTK Hyperslab API Specification

In general, a hyperslab get/put operation is done in a three-level scheme:

1. In a first step, a hyperslab mapping is defined by calling one of the following routines:
   Hyperslab_LocalMappingByIndex()
   Hyperslab_LocalMappingByPhys()
   Hyperslab_GlobalMappingByIndex()
   Hyperslab_GlobalMappingByPhys()
   There exists two complement sets of routines: one for the definition of local hyperslabs (which apply to a processor's local patch of a distributed grid variable only), and one for global hyperslabs (which spawn the entire grid).

   A mapping can be defined by either physical coordinates or by grid index points.

   All hyperslab mapping routines return an integer handle which refers to an internally allocated data structure describing the defined hyperslab.

2. With such a mapping, hyperslabs can then be extracted/distributed by one or more calls to Hyperslab_Get()
   Hyperslab_GetList()
   Hyperslab_Put()
   Hyperslab_PutList()
   There are routines for getting/putting a hyperslab from/to a single grid variable or from/to a list of variables.

3. Once all hyperslabs are done, the hyperslab mapping should be freed by a call to
   Hyperslab_FreeMapping().

If the Hyperslab_Get*()/Hyperslab_Put*() get passed a mapping for a global hyperslab, a global, synchronuous operation will be performed (i.e., it must be called in sync by every processor). All input arguments must be consistent between processors.