S3L_set_array_element, S3L_get_array_element, S3L_set_array_element_on_proc, and S3L_get_array_element_on_proc

Description

The four subroutines described in this section enable the user to alter (set) and retrieve (get) individual elements of an array. Two of these subroutines also allow the user to know which process will participate in the set/get activity.

S3L_set_array_element assigns the value stored in val to a specific element of a distributed S3L array, whose global coordinates are specified by coor. The val variable is colocated with the array subgrid containing the target element.

Because an S3L array is distibuted across a set of processes, each process has a subsection of the global array local to it. These array subsections are also referred to as array subgrids.

For example, if a parallel array is distributed across four processes, P0 - P3, and coor specifies an element in the subgrid that is local to P2, the val that is located on P2 will be the source of the value used to set the target element.

S3L_get_array_element is similar to S3L_set_array_element, but operates in the opposite direction. It assigns the value stored in the element specified by coor to val on every process. Since S3L_get_array_element broadcasts the element value to every process, upon completion, every process contains the same value in val.

S3L_set_array_element_on_proc specifies which process will be the source of the value to be assigned to the target element. That is, the argument pnum specifies the MPI rank of a particular process. The value of the variable val on that process will be assigned to the target element--that is, the element whose coordinates are specified by coor.

The MPI rank of a process is defined in the global communicator MPI_COMM_WORLD.

S3L_get_array_element_on_proc updates the variable val on the process whose MPI rank is supplied in pnum, using the element whose indices are given in coor as the source for the update.

Syntax

The C and Fortran syntax for S3L_set_array_element and its related routines are shown below.

C/C++ Syntax

Example 7-33

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_set_array_element(a, coor, val)
S3L_get_array_element(a, coor, val)
S3L_set_array_element_on_proc(a, coor, val, pnum)
S3L_get_array_element_on_proc(a, coor, val, pnum)
    S3L_array_t           a
    int                   coor
    void                  val
    int                   pnum

F77/F90 Syntax

Example 7-34

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_set_array_element(a, coor, val, ier)
S3L_get_array_element(a,
coor, val, ier)
S3L_set_array_element_on_proc(a, coor, val, pnum, ier)
S3L_set_array_element_on_proc(a, coor, val, pnum, ier)
    integer*8              a
    integer*4              coor
    <type>                 val
    integer*4              pnum
    integer*4              ier

where <type> is one of: integer*4, real*4, real*8, complex*8, or complex*16.

Input

S3L_set_array_element and S3L_get_array_element accept the following arguments as input:

• a - Array handle describing the parallel array containing the element of interest.

• coor - Integer vector specifying the coordinates of an element of the distributed array a. This value follows zero-based notation for C/C++ programs and one-based notation for F77/F90 programs.

• val - Variable that holds the value to be assigned to an element of an array or that accepts the value of that element.

• pnum - Integer variable specifying the MPI rank of a process to supply or accept the value val. pnum is only used with S3L_set_array_element_on_proc and S3L_get_array_element_on_proc.

Output

These functions use the following argument for output:

• ier (Fortran only) - When called from a Fortran program, these functions return error status in ier.

Error Handling

On success, these functions return S3L_SUCCESS.

In addition, the following conditions will cause these functions to return the associated error code and terminate.

• S3L_ERR_ARG_DTYPE - The data type of array a is not one of:

  • S3L_integer

  • S3L_float

  • S3L_double

  • S3L_complex

  • S3L_double_complex

• S3L_ERR_ARG_COOR - The supplied coordinates are not valid; that is, they do not specify an element of a.

Examples

../examples/s3l/utils/cshift_reduce.c
../examples/s3l/utils-f/cshift_reduce.f