Declaring S3L Arrays

Sun S3L provides two subroutines for declaring S3L arrays: S3L_declare and S3L_declare_detailed. The library also includes the S3L_DefineArray interface, which maintains compatibility with the Sun HPC 2.0 release of Sun S3L.

S3L_declare and S3L_declare_detailed perform the same function, except that S3L_declare_detailed provides additional arguments that allow more detailed control over the array features. Both require the programmer to specify

• The array's rank

• The array's extents

• The array's type

• Which axes will be distributed and which will be local (kept in a single block on one process).The method by which the array is to be allocated.

In addition, S3L_declare_detailed allows the programmer to specify the following array features:

• The starting address of the local subgrid. This value is used only if the programmer elects to allocate array subgrids explicitly by disabling automatic array allocation. The block size to be used in distributing the array along each axis. The programmer has the option of letting Sun S3L choose a default blocksize.Which processes contain the start of each array axis. Again, the programmer can let Sun S3L specify default processes. To use this option, the programmer must specify a particular process grid, rather than using one provided by Sun S3L.

The following F77 example allocates a 100 x 100 x 100 double-precision array.

Example 2-2

integer*8 a,pg_a
integer*4 ext_a(3), block_a(3), local_a(3)
ext_a(1) = 100
ext_a(2) = 100
ext_a(3) = 100
local_a(1) = 1
local_a(2) = 0
local_a(3) = 0
call s3l_declare_detailed(a,0,3,ext_a,S3L_double,block_a,
    -1,local_a,pg_a,S3L_USE_MALLOC,ier)

The S3L array a is distributed along each axis of the process grid. The block sizes for the three axes are specified in block_a. Because local_a is set to 1, the first axis of a will be local to the first process in the process grid's first axis. The second and third axes of a are distributed along the corresponding axes of the process grid.

If local_a had been set to 0 instead, all three array axes would be distributed along their respecitive process grid axes.

For more information about this function see "S3L_declare_detailed " or the S3L_declare_detailed(3) man page.

The simpler and more compact S3L_declare involves fewer parameters and always block-distributes the arrays. The following C program example allocates a one-dimensional, double-precision array of length 1000.

Example 2-3

#include <s3l/s3l-c.h>
int local,ext,ier:
S3L_array_t A;
local = 0:
ext = 1000:
ier = S3L_declare(&A,1,&ext,S3L_double,&local,S3L_USE_MALLOC);

This example illustrates use of the array_is_local parameter. This parameter consists of an array containing one element per axis. Each element of the array is either 1 or 0, depending on whether the corresponding array axis should be local to a process or distributed. If array_is_local(i) is 0, the array axis i will be distributed along the corresponding axis of the process grid. If it is 1, array axis i will not be distributed. Instead, the extent of that process grid axis will be regarded as 1 and the array axis will be local to the process.

In this S3L_declare example, the array has only one axis, so array_is_local has a single value, in this case 0. If the program containing this code is run on six processes, Sun S3L will associate a one-dimensional process grid of length 6 with the S3L array A. It will set the block size of the array distribution to ceiling(1000/6)=167. As a result, processes 0 though 4 will have 167 local array elements and process 5 will have 165.

If array_is_local had been set to 1, the entire array would have been allocated to process 0.