Sun S3L 3.0 Programming and Reference Guide

Performing Operations on S3L Parallel Arrays

The toolkit functions described in this section enable the user to apply various kinds of operations on a parallel array's elements.

`S3L_array_op1`

Description

S3L_array_op1 applies a predefined unary (single-operand) operation to each element of an S3L parallel array. The S3L array handle argument, a, identifies the parallel array to be operated on and the op argument specifies the operation to be performed. The value of op must be:

S3L_OP_ABS - Replaces each element in a with its absolute value.

S3L_OP_MINUS - Replaces each element in a with its negative value.

S3L_OP_EXP - Replaces each element in the real or complex array a with its exponential.

Syntax

The C and Fortran syntax for S3L_array_op1 are shown below.

C/C++ Syntax

Example 7-19

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_array_op1(a, op)
    S3L_array_t         a
    int                 op

F77/F90

Example 7-20

include `s3l/s3l-f.h
include `s3l/s3l_errno-f.h'
subroutine
S3L_array_op1(a, op, ier)
    integer*8          a
    integer*4          op
    integer*4          ier

Input

S3L_array_op1 accepts the following arguments as input:

a - S3L array handle for the parallel array on which the operation will be performed.
op - Predefined constant specifying the operation to be applied. See the Description section for details.

Output

S3L_array_op1 uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_array_op1 returns error status in ier.

Error Handling

On success, S3L_array_op1 returns S3L_SUCCESS.

S3L_array_op1 performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code.

S3L_ERR_ARG_DTYPE - op is equal to S3L_OP_EXP but a is of integer type.

Examples

../examples/s3l/fft/ex_fft1.c
../examples/s3l/deconv-f/ex_deconv.f

Related Functions

S3L_array_op2(3)
S3L_array_scalar_op2(3)
S3L_reduce_scalar(3)

`S3L_array_op2`

Description

S3L_array_op2 applies the operation specified by op to elements of parallel arrays a and b, which must be of the same type and have the same distribution. The parameter op can be one of the following:

S3L_OP_MUL - a equals a .* b

S3L_OP_CMUL - a equals a .* conjg(b)

S3L_OP_DIV - a equals a ./ b

S3L_OP_MINUS - a equals a - b

S3L_OP_PLUS - a equals a + b

Note -
The operators ".*" and "./" denote pointwise multiplication and division of the elements in arrays a and b.

S3L_OP_MUL replaces each element in a with the elementwise product of multiplying a and b.

S3L_OP_CMUL performs the same operation as S3L_OP_MUL, except it multiplies each element in a by the conjugate of the corresponding element in b.

S3L_OP_DIV performs elementwise division of a by b, overwriting a with the integer (truncated quotient) results.

S3L_OP_MINUS performs elementwise subtraction of b from a, overwriting a with the differences.

S3L_OP_PLUS performs elementwise addition of a with b, overwriting a with the sum.

Syntax

The C and Fortran syntax for S3L_array_op2 are shown below.

C/C++ Syntax

Example 7-21

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_array_op2(a, b, op)
    S3L_array_t         a
    S3L_array_t         b
    int                 op

F77/F90 Syntax

Example 7-22

include `s3l/s3l-f.h
include `s3l/s3l_errno-f.h'
subroutine
S3L_array_op2(a, b, op, ier)
    integer*8          a
    integer*8          b
    integer*4          op
    integer*4          ier

Input

S3L_array_op2 accepts the following arguments as input:

a - S3L array handle for one of two parallel arrays to which the operation will be applied.
b - S3L array handle for the second of two parallel arrays to which the operation will be applied.
op - Predefined constant specifying the operation to be applied. See the Description section for details.

Output

S3L_array_op2 uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_array_op2 returns error status in ier.

Error Handling

On success, S3L_array_op2 returns S3L_SUCCESS.

S3L_array_op2 performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the function to terminate and return the associated error code:

S3L_ERR_MATCH_HOME - Both arrays are local but not on the same process.

S3L_ERR_MATCH_ALIGN - The arrays do not have the same subgrid sizes.

S3L_ERR_ARG_OP - An illegal operation was requested.

Examples

../examples/s3l/fft/ex_fft1.c
../examples/s3l/fft-f/ex_fft1.f

Related Functions

S3L_array_op1(3)
S3L_array_scalar_op2(3)
S3L_reduce_scalar(3)

`S3L_array_scalar_op2`

Description

S3L_array_scalar_op2 applies a binary operation to each element of an S3L array that involves the element and a scalar.

op determines which operation will be performed. It can be one of:

S3L_OP_MULT - pointwise multiplication.

S3L_OP_DIV - pointwise division.

S3L_OP_PLUS - pointwise addition.

S3L_OP_MINUS - pointwise subtraction.

S3L_OP_ASSIGN - assignment.

Syntax

The C and Fortran syntax for S3L_array_scalar_op2 are shown below.

C/C++ Syntax

Example 7-23

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_array_scalar_op2(a, scalar,
op)
    S3L_array_t         a
    void                *scalar
    int                 op

F77/F90 Syntax

Example 7-24

include `s3l/s3l-f.h
include `s3l/s3l_errno-f.h'
subroutine
S3L_array_scalar_op2(a, scalar, op, ier)
    integer*8          a
    <type>             scalar
    integer*4          op
    integer*4          ier

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

Input

S3L_array_scalar_op2 accepts the following arguments as input:

a - S3L array handle for the parallel array to which the operation will be applied.

scalar - Scalar value used as an operand in the operation applied to each element of a.

op - Predefined constant specifying the operation to be applied. See the Description section for details.

Output

S3L_array_scalar_op2 uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_array_scalar_op2 returns error status in ier.

Error Handling

On success, S3L_array_scalar_op2 returns S3L_SUCCESS.

S3L_array_scalar_op2 performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code:

S3L_ERR_ARG_OP - op is not one of: S3L_OP_MUL, S3L_OP_DIV, S3L_OP_PLUS, S3L_OP_MINUS, or S3L_OP_ASSIGN

Examples

../examples/s3l/fft/ex_fft1.c
../examples/s3l/fft-f/ex_fft1.f

Related Functions

S3L_array_op1(3)
S3L_array_op2(3)
S3L_reduce_scalar(3)

`S3L_cshift`

S3L_cshift performs a circular shift of a specified amount along a specified axis of the parallel array associated with array handle A. The argument axis indicates the dimension to be shifted, and index prescribes the shift distance.

Shift direction is upwards for positive index values and downward for negative index values.

For example, if A denotes a one-dimensional array of length n before the cshift, B denotes the same array after the cshift, and index is equal to 1, the array A will be circularly shifted upwards, as shown below:

For C Programs

B[1:n-1]=A[0:n-2], B[0]=A[n-1]

For Fortran Programs

B(2:n)=A(1:n-1), B(1)=A(n)

Syntax

The C and Fortran syntax for S3L_cshift are shown below.

C/C++ Syntax

Example 7-25

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_cshift(A, axis, index)
    S3L_array_t         A
    void                axis
    int                 index

F77/F90 Syntax

Example 7-26

include `s3l/s3l-f.h
include `s3l/s3l_errno-f.h'
subroutine
S3L_cshift(A, axis, index,
ier)
    integer*8          A
    integer*4          axis
    integer*4          index
    integer*4          ier

Input

S3L_cshift accepts the following arguments as input:

A - Array handle for the parallel array to be shifted.

axis - Specifies the axis along which the shift is to take place. This value must assume zero-based axis indexing when S3L_cshift is called from a C or C++ application and one-based indexing when called from an F77 or F90 application.
index - Specifies the shift distance. If the extent of the axis being shifted is N, legal values for index are: -N < index < N.

Output

S3L_cshift uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_cshift returns error status in ier.

Error Handling

On success, S3L_cshift returns S3L_SUCCESS.

S3L_cshift performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code:

S3L_ERR_ARG_AXISNUM - Invalid axis value.

S3L_ERR_INDX_INVALID - index value is out of range.

Examples

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

Related Functions

S3L_reduce
S3L_reduce_axis

`S3L_forall`

Description

S3L_forall applies a user-defined function to elements of a parallel Sun S3L array. and sets its values accordingly. Three different function types are supported. These types are described in Table 7-1.

Table 7-1 User-Defined Function Types for S3L_forall


fn_type	C Prototype	Fortran Interface
S3L_ELEM_FN1	void user_fn(void *elem_addr);	subroutine user_fn(a) <type> a end user_fn
S3L_ELEM_FNN	void user_fn(void *elem_addr, int n);	subroutine user_fn(a,n) <type> a integer*4 n end user_fn
S3L_ELEM_FN	void user_fn(void elem_addr, int coord);	subroutine user_fn(a, coord) <type> a

Here, <type> is one of: integer*4, integer*8, real*4, real*8, complex*8, or complex*16 and rank is the rank of the array.

For S3L_ELEM_FN1, the user function is applied to each element in the array.

For S3L_ELEM_FNN, the user function is supplied the local subgrid address and subgrid size and iterates over subgrid elements. This form delivers the highest performance because the looping over the elements is contained within the function call.

For S3L_INDEX_FN, the user function is applied to each element in the subarray specified by the triplets argument to S3L_forall. If the triplets argument is NULL in C/C++ or has a leading value of 0 in F77/F90, the whole array is implied. The user function may involve the global coordinates of the array element; these are contained in the coord argument. Global coordinates of array elements are 0-based for C programs and 1-based for Fortran programs.

Note -

When a Fortran program uses triplets, the length of first axis of the triplets must equal the rank of the array. Failure to meet this requirement can produce wrong results or a segmentation violation.

Note -

A subgrid is the portion of the parallel array that is owned by a process. A subarray is the portion of the parallel array that is described by a lower bound, an upper bound, and a stride in each dimension.

Syntax

The C and Fortran syntax for S3L_cshift are shown below.

C/C++ Syntax

Example 7-27

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_forall(a, user_fn, fn_type, triplets)
    S3L_array_t        a
    void               (*user_fn)()
    int                fn_type
    int                triplets[rank][3]

where rank is the rank of the array.

F77/F90 Syntax

Example 7-28

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_forall(a, user_fn, fn_type, triplets, ier)
    integer*8          a
    <external>         user_fn
    integer*4          fn_type
    integer*4          triplets(rank,3)
    integer*4          ier

where rank is the rank of the array.

Input

S3L_forall accepts the following arguments as input:

a - Parallel array to which the function will be applied.

user_fn - Pointer to the user-defined function.

fn_type - Predefined value specifying the class of functions to which the function belongs. See the Description section for a list of valid fn_type entries.

triplets - An integer vector that is used to restrict the function to a range of elements. A triplet takes the form:

inclusive lower bound inclusive upper bound stride

for each axis of the array. The stride must be positive. To apply the function to all the elements in the array, set triplets to NULL (C/C++) or to 0 (F77/F90).

Output

S3L_forall uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, S3L_forall returns error status in ier.

Error Handling

On success, S3L_forall returns S3L_SUCCESS.

S3L_forall performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code:

S3L_ERR_FORALL_INVFN - User-specified function is invalid. fn_type is not one of:
- S3L_ELEM_FN1
- S3L_ELEM_FNN
- S3L_INDEX_FN

S3L_ERR_INDX_INVALID - fn_type is S3L_INDEX_FN and one or more of the elements in the triplets argument has an invalid value.

Examples

../examples/s3l/forall/ex_forall.c
../examples/s3l/forall/ex_forall2.cc
../examples/s3l/forall-f/ex_forall.f

`S3L_reduce`

Description

S3L_reduce performs a predefined reduction function over all elements of a parallel array. The array is described by the S3L array handle argument A. The argument op specifiesthe type of reduction operations, which can be one of the following:

S3L_OP_SUM - Finds the sum of all the elements.

S3L_OP_MIN - Finds the smallest value among all the elements.

S3L_OP_MAX - Finds the largest value among all the elements.

Syntax

The C and Fortran syntax for S3L_reduce are shown below.

C/C++ Syntax

Example 7-29

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_reduce(A, op, res)
    S3L_array_t           A
    S3L_op_type           op
    void                  *res

F77/F90 Syntax

Example 7-30

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_reduce(A, op, res, ier)
    integer*8              A
    integer*4              op
    <type>                 res
    integer*4              ier

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

Input

S3L_reduce accepts the following arguments as input:

A - Array handle for the parallel array to be reduced.

op - Specifies the type of operation to be performed; it can be one of:
- S3L_OP_SUM
- S3L_OP_MIN
- S3L_OP_MAX

Output

S3L_reduce uses the following arguments for output:

res - Contains the result of the reduction function.

ier (Fortran only) - When called from a Fortran program, S3L_reduce returns error status in ier.

Error Handling

On success, S3L_reduce returns S3L_SUCCESS.

S3L_reduce performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

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

S3L_ERR_ARG_OP - Requested operation is not supported.

S3L_ERR_ARG_DTYPE - Invalid data type.

Examples

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

Related Functions

S3L_reduce_axis(3)

`S3L_reduce_axis`

Description

S3L_reduce_axis applies a predefined reduction operation along a given axis of a parallel S3L array. If n is the rank (number of dimensions) of a, the result b is a parallel array of rank n-1. The argument op specifies the operation to be performed. The value of op must be one of:

S3L_OP_SUM - The sum reduction operation is applied.

S3L_OP_MIN - The minimum reduction operation is applied.

S3L_OP_MAX - The maximum reduction operation is applied.

Syntax

The C and Fortran syntax for S3L_reduce_axis are shown below.

C/C++ Syntax

Example 7-31

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_reduce_axis(a, op, axis,
b)
    S3L_array_t           a
    S3L_op_type           op
    int                   axis
    S3L_array_t           b

F77/F90 Syntax

Example 7-32

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_reduce_axis(a, op, axis, b, ier)
    integer*8              a
    integer*4              op
    integer*4              axis
    integer*8              b
    integer*4              ier

Input

S3L_reduce_axis accepts the following arguments as input:

a - S3L array handle for the parallel array on which the operation will be applied.

op - Predefined constant specifying the operation to be applied.

axis - Specifies the axis along which the reduction will be performed. When S3L_reduce_axis is called from a C program, this value must reflect zero-based indexing of the array axes. If called from a Fortran program, it must reflect one-based indexing.

Output

S3L_reduce_axis uses the following arguments for output:

b - S3L array handle for the parallel array that will contain the result of the reduction.

ier (Fortran only) - When called from a Fortran program, S3L_reduce_axis returns error status in ier.

Error Handling

On success, S3L_reduce_axis returns S3L_SUCCESS.

S3L_reduce_axis performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause the function to terminate and return the associated error code:

S3L_ERR_ARG_OP - An illegal operation was requested.

S3L_ERR_MATCH_EXTENTS - The extents of a and b do not match. For example, if a is a 4D array with extents n1 x n2 x n3 x n4, and axis is equal to 2 (Fortran interface), b must be a 3D array with extents n1 x n3 x n4.

S3L_ERR_MATCH_RANK - The rank of b is not equal to rank of a minus 1.

S3L_ERR_ARG_AXISNUM - The axis specified is not valid; that is, it is either larger than the rank of the array or smaller than 1 (Fortran interface). For the C interface, the axis value would be equal to or larger than the rank of the array or smaller than 0.

Examples

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

Related Functions

S3L_reduce(3)

`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.

Note -

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.

Note -

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

`S3L_zero_elements`

Description

S3L_zero_elements sets to zero all elements of the S3L array whose array handle is A.

Syntax

The C and Fortran syntax for S3L_zero_elements are illustrated below.

C/C++ Syntax

Example 7-35

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_zero_elements(A)
    S3L_array_t        A

F77/F90 Syntax

Example 7-36

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_zero_elements(A, ier)
    integer*8              A
    integer*4              ier

Input

A - S3L internal array handle for the parallel array that is to be initialized to zero.

Output

This function uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_zero_elements returns S3L_SUCCESS.

S3L_zero_elements checks the arrays it accepts as argument. If the array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated code:

S3L_ERR_ARG_DTYPE - The data type of A is invalid.

Examples

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