Extracting/distributing a hyperslab

Each set of hyperslab get/put routines has two functions: one which operates on a single hyperslab, and another which gets/puts hyperslabs for a list of variables. Depending on the actual hyperslab implementation it might be more efficient to operate on a list of grid variables using Hyperslab_GetList()/Hyperslab_PutList() rather than doing sequential calls to Hyperslab_Get()/Hyperslab_Put() with individual grid variables.

CCTK_INT Hyperslab_Get (CCTK_POINTER_TO_CONST GH,
                        CCTK_INT       mapping_handle,
                        CCTK_INT       proc,
                        const CCTK_INT vindex,
                        const CCTK_INT timelevel,
                        const CCTK_INT hdatatype,
                        void          *hdata);

CCTK_INT Hyperslab_GetList (CCTK_POINTER_TO_CONST GH,
                            CCTK_INT        mapping_handle,
                            CCTK_INT        num_arrays,
                            const CCTK_INT *procs      /* num_arrays */,
                            const CCTK_INT *vindices   /* num_arrays */,
                            const CCTK_INT *timelevels /* num_arrays */,
                            const CCTK_INT *hdatatypes /* num_arrays */,
                            void *const    *hdata      /* num_arrays */,
                            CCTK_INT       *retvals    /* num_arrays */);

CCTK_INT Hyperslab_Put (CCTK_POINTER_TO_CONST GH,
                        CCTK_INT              mapping_handle,
                        CCTK_INT              proc,
                        CCTK_INT              vindex,
                        CCTK_INT              timelevel,
                        CCTK_INT              hdatatype,
                        CCTK_POINTER_TO_CONST hdata);

CCTK_INT Hyperslab_PutList (CCTK_POINTER_TO_CONST       GH,
                            CCTK_INT                    mapping_handle,
                            CCTK_INT                    num_arrays,
                            const CCTK_INT             *procs      /* num_arrays */,
                            const CCTK_INT             *vindices   /* num_arrays */,
                            const CCTK_INT             *timelevels /* num_arrays */,
                            const CCTK_INT             *hdatatypes /* num_arrays */,
                            const CCTK_POINTER_TO_CONST hdata      /* num_arrays */,
                            CCTK_INT                   *retvals    /* num_arrays */);

Function arguments:

• CCTK_POINTER_TO_CONST GH
  The reference to the CCTK grid hierarchy.

  In a C implementation, this should be a pointer of type const cGH *.

• CCTK_INT mapping_handle
  The handle for the hyperslab mapping as returned by a previous call to one of the hyperslab mapping routines.

• CCTK_INT num_arrays
  The total number of input arrays to get/put a hyperslab from/to.

  This must be a positive integer and match the number of array elements in the arguments following.

• CCTK_INT proc
  const CCTK_INT *procs
  The (list of) processor(s) which will receive/provide the hyperslab data.

  For Hyperslab_GetXXX(), there may be either exactly one processor providing the hyperslab data (in this case, its processor ID must be given in proc), or all all processors will get the extracted hyperslab data (an invalid (i.e., negative) processor ID should be given as proc, or procs is passed as a NULL pointer). For Hyperslab_PutXXX(), there may only be one processor providing the hyperslab data to be distributed to all others.

• CCTK_INT vindex
  const CCTK_INT *vindices
  The (list of) CCTK variable(s) to get/put a hyperslab from/to.

  The grid variables are given by their CCTK indices; their domain decomposition must match the template variable as given in a previous hyperslab mapping routine call.

• CCTK_INT timelevel
  const CCTK_INT *timelevels
  The (list of) timelevel(s) for the grid variable(s) to get/put a hyperslab from/to.

  Each element in the timelevels array matches its entry in the vindices array argument. If timelevels is passed as a NULL pointer then all timelevels for the list operation will default to 0 (denoting the current timelevel).

• CCTK_INT hdatatype
  const CCTK_INT *hdatatypes
  The (list of) CCTK data type(s) of the hyperslab data.

  The hyperslab data to be extracted/distributed may be given in a data type which is different to its corresponding grid variable. For this case, the requested hyperslab data type must be specified explicitely. The hyperslab routines will then do the neccessary data type conversions either by using a user-supplied data type conversion function (as specified in the conversion_fn argument to the hyperslab mapping routines), or by choosing a built-in predefined data type conversion function. convert the input array datatypes to some output array datatype.

  A negative value for hdatatype or type or passing a NULL pointer for the hdatatypes argument indicates that both the grid variable and its corresponding hyperslab have the same CCTK data type so that no type conversion is necessary.

• (const) void *hdata
  (const) void *const *hdata
  The (list of) user-supplied buffer(s) to store the extracted hyperslabs for each input variable (for a get operation) or to read the hyperslab data from (for a put operation).

  This argument is only evaluated on processors which are part of the hyperslab mapping.

• CCTK_INT *retvals
  User-provided array to store the status of each individual get/put operation in a Hyperslab_XXXList() call.

  Each element in the retvals array will contain the status of the corresponding hyperslab operation on grid variable i. If retvals is passed as a NULL pointer then no status codes for individual hyperslab operations will be passed back to the caller.

Return Codes for these routines (according to the Cactus Code conventions:

• 0 for success
• negative for some error condition (to be defined by an actual implementation of the Hyperslab_GetXXX()/Hyperslab_PutXXX() routines)