Sun S3L 4.0 Software Programming Guide
|    
|
| Sun S3L 4.0 Software Programming Guide
|
|
| C H A P T E R 7 |
|
Sun S3L Toolkit Routines for Managing Dense Arrays |
This chapter describes a group of Sun S3L routines that are convenient for managing dense Sun S3L arrays. The descriptions are organized into the following sections:
S3L_declare and S3L_declare_detailed each creates a Sun S3L array handle that describes a Sun S3L array. Both support calling arguments that enable the user to specify:
S3L_declare_detailed supplies additional arguments that allow more detailed control over array mapping. This additional control applies to:
S3L_declare and S3L_declare_detailed have the following argument syntax:
S3L_declare(A, rank, extents, type, axis_is_local, atype, ier) S3L_declare_detailed(A, addr_a, rank, extents, type, blocksizes, proc_src, axis_is_local, pgrid, atype, ier) |
Upon exit, A contains a Sun S3L array handle for the Sun S3L array.
addr_a depends on the use of the atype argument. If atype is set to S3L_DONOT_ALLOCATE, addr_a will be taken as the starting address of the local (per process) portion of A. Otherwise, addr_a will be ignored. This argument is used only by S3L_declare_detailed.
rank specifies the number of dimensions the array will have.
extents is an integer vector whose length is equal to the number of dimensions in the array. Each element in extents specifies the extent of the corresponding array axis. The first element corresponds to the first axis, the second element to the second axis, and so forth. Axis indexing is zero-based for the C interface and one-based for the Fortran interface.
type specifies the array's data type, which must be one of the Sun S3L data types listed in Chapter 2.
blocksizes specifies the block sizes to be used in distributing the array axes. To select default block sizes, set blocksizes to NULL (C/C++) or to -1 (F77/F90).
proc_src is a vector whose length is at least equal to the rank of A. Each element of proc_src corresponds to an axis of the process grid and is the index for the start of the array axis allocated to that process grid axis. In other words, each proc_src element specifies the index value of the process that contains the first data element of the corresponding array axis.
axis_is_local is an integer vector that contains one element for each axis of A. Each element specifies, with a 0 or 1 value, whether the axis it represents will be distributed across multiple processes (0) or locally to a single process (1).
|
Note - The axis_is_local argument is used only if a process grid handle is not specified in this call. See the description of the pgrid argument below. |
Use the pgrid argument to request that Sun S3L associate A with a particular process grid. To do this, supply the handle of the desired process grid for this argument. If the process grid already exists, you can acquire its handle by calling S3L_get_attribute. If it does not already exist, you can create it by calling S3L_set_process_grid.
If you want Sun S3L to assign a default process grid to A, set pgrid to NULL (C/C++) or to 0 (F77/F90).
atype specifies how A will be allocated in memory. Use one of the following predefined values for this argument:
When S3L_USE_MMAP or S3L_USE_SHMGET is used on a 32-bit platform, the part of a Sun S3L array owned by a single SMP cannot exceed 2 gigabytes.
When S3L_USE_MALLOC or S3L_USE_MEMALIGN64 is used, the part of the array owned by any single process cannot exceed 2 gigabytes.
If these size restrictions are violated, an S3L_ERR_MEMALLOC will be returned. On 64-bit platforms, the upper bound is equal to the system's maximum available memory.
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for these routines, see the S3L_declare(3) and S3L_declare_detailed(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
The following F77 program example illustrates the use of S3L_declare with a 1D, double-precision array of length 1000:
include 's3l/s3l-f.h' include 's3l/s3l-errno-f.h' integer*4 local,ext,ier integer*8 A local = 0 ext = 1000 call s3l_declare(A,1,ext,S3L_double,local,S3L_USE_MALLOC,ier) |
In this example, the array has only one axis, so array_is_local contains a single element, whose value is 0, which means the axis will be distributed across multiple processes.
If the program containing this code is run on six processes, Sun S3L will associate a 1D process grid of length 6 with 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 instead been set to 1, the entire array would have been allocated to process 0.
Upon successful completion, S3L_declare returns a Sun S3L array handle, which subsequent Sun S3L calls can use as an argument to gain access to that array.
The following example illustrates the extra control that S3L_declare_detailed provides over array handle creation:
In this example, S3L_declare_detailed creates an array handle for a 3D, double-precision array. The extent of each array axis is 100.
Each axis of Sun S3L array A will be distributed, using block sizes specified in block_a.
Because local_a(1) 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 will be distributed along the second and third axes of the process grid.
If local_a(1) had been set to 0 instead, it would have been distributed across all processes in the process grid's first axis. That is, all three array axes would have been distributed across multiple processes along their respective process grid axes.
Examples showing S3L_declare in use can be found in:
/opt/SUNWhpc/examples/s3l/transpose/ex_trans1.c /opt/SUNWhpc/examples/s3l/grade-f/ex_grade.f |
Examples showing S3L_declare_detailed in use can be found in:
If your program includes arrays that are described by ScaLAPACK descriptors, you can use S3L_from_ScaLAPACK_desc to convert those descriptors into Sun S3L array handles.
Sun S3L also provides a routine, S3L_from_ScaLAPACK_desc, for converting Sun S3L array handles into ScaLAPACK array descriptors.
S3L_from_ScaLAPACK_desc has the following argument syntax:
S3L_from_ScaLAPACK_desc(s3ldesc, scdesc, data_type, address, ier) |
s3ldesc is the Sun S3L array handle that S3L_from_ScaLAPACK_desc produces on exit.
scdesc is the ScaLAPACK array descriptor.
data_type specifies the data type of the array.
address holds the starting address of the existing array subgrid.
|
Note - In Fortran programs, address should be either a pointer or the starting address of a local array, as determined by the loc(3F) function. |
If the call is made from a Fortran program, error status will be in ier.
S3L_to_ScaLAPACK_desc has the following argument syntax:
S3L_to_ScaLAPACK_desc(s3ldesc, scdesc, data_type, address, ier) |
s3ldesc contains the Sun S3L array handle that is to be converted to a ScaLAPACK array descriptor.
scdesc contains the ScaLAPACK array descriptor that is produced on exit.
data_type specifies the data type of the Sun S3L array. This must be one of the supported data types described in Chapter 2.
address holds the starting address of the existing array subgrid.
|
Note - In Fortran programs, address should be either a pointer or the starting address of a local array, as determined by the loc(3F) function. |
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for these routines, see the S3L_from_ScaLAPACK_desc(3) and S3L_to_ScaLAPACK_desc(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing S3L_from_ScaLAPACK_desc and S3L_to_ScaLAPACK_desc in use can be found in:
/opt/SUNWhpc/examples/s3l/utils/scalapack_conv.c /opt/SUNWhpc/examples/s3l/utils-f/scalapack_conv.f |
When a Sun S3L array is no longer needed, call S3L_free to deallocate the internal structures that describe the array. The routine has the following argument syntax:
S3L_free(a, ier) |
a is the array handle to be deallocated.
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for this routine, see the S3L_free(3) man page or the corresponding description in the Sun S3L Software Reference Manual.
Examples showing S3L_free in use can be found in:
/opt/SUNWhpc/examples/s3l/io/ex_print1.c /opt/SUNWhpc/examples/s3l/io-f/ex_print1.f |
S3L_read_array enables you to populate a Sun S3L array with data read from a file. The process with MPI rank 0 reads the data from a local file and distributes the data to all processes that have local subgrids of the Sun S3L array.
S3L_read_sub_array is similar to S3L_read_array, except it distributes the file data to specific sections of each axis of the Sun S3L array. Lower and upper bound arguments are available, which allow the specification of the first and last indices along each axis. A stride length greater than 1 can also be specified for any axes to produce noncontiguous indexing along the affected axes.
For both functions, the format of the file must be either ASCII or binary.
S3L_read_array and S3L_read_sub_array have the following argument syntax:
S3L_read_array(a, filename, format, ier) S3L_read_sub_array(a, lbounds, ubounds, strides, filename, format, ier) |
a is a Sun S3L array handle describing the Sun S3L array to be initialized. This array handle was returned by a previous call to either S3L_declare or S3L_declare_detailed.
lbounds is an integer vector that is used in calls to S3L_read_sub_array. Each element of lbounds corresponds to an axis of a and specifies the lower bound of the indices along the axis it represents. This lower-bound index marks the beginning of a subset of array elements along that axis that will be initialized. The default lower bound is:
ubounds is an integer vector that is used in calls to S3L_read_sub_array. Each element of ubounds corresponds to an axis of a and specifies the upper bound of the indices along the axis it represents. This upper-bound index marks the upper end of a subset of array elements along that axis that will be initialized. The default upper bound is:
strides is an integer vector that is used in calls to S3L_read_sub_array. Each element of strides corresponds to an axis of a and specifies a stride length to be used in indexing along that axis. The default stride length is 1, which produces contiguous indexing.
filename is a scalar character variable that specifies the name of the file to be read.
format is a scalar character variable used to specify the format of the data to be read. The value can be either ascii or binary.
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for these routines, see the S3L_read_array(3) and S3L_read_sub_array(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing S3L_read_array and S3L_read_sub_array in use can be found in:
/opt/SUNWhpc/examples/s3l/io/ex_io.c /opt/SUNWhpc/examples/s3l/io-f/ex_io.f |
S3L_write_array causes the process with MPI rank 0 to write a distributed Sun S3L array into a specified file. The file is local to the process with MPI rank 0.
S3L_write_sub_array writes a subset of the distributed Sun S3L array to a specified file. This subset is defined by arguments that specify the lower and upper bounds of the section of each axis to be written. A stride length greater than 1 can also be specified for any axes to produce noncontiguous indexing along the affected axes.
For both functions, the format of the file must be either ascii or binary.
S3L_write_array and S3L_write_sub_array have the following argument syntax:
S3L_write_array(a, filename, format, ier) S3L_write_sub_array(a, lbounds, ubounds, strides, filename, format, ier) |
a is a Sun S3L array handle describing the Sun S3L array to be written. This array handle was returned by a previous call to either S3L_declare or S3L_declare_detailed.
lbounds is an integer vector that is used in calls to S3L_write_sub_array. Each element of lbounds corresponds to an axis of a and specifies the lower bound of the indices along the axis it represents. This lower-bound index marks the beginning of a subset of array elements along that axis that will be written. The default lower bound is:
ubounds is an integer vector that is used in calls to S3L_write_sub_array. Each element of ubounds corresponds to an axis of a and specifies the upper bound of the indices along the axis it represents. This upper-bound index marks the upper end of a subset of array elements along that axis that will be written. The default upper bound is:
strides is an integer vector that is used in calls to S3L_write_sub_array. Each element of strides corresponds to an axis of a and specifies a stride length to be used in indexing along that axis. The default stride length is 1, which produces contiguous indexing.
filename is a scalar character variable that specifies the name of the file to be written to.
format is a scalar character variable used to specify the format of the data to be written. The value can be either ascii or binary.
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for these routines, see the S3L_write_array(3) and S3L_write_sub_array(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing S3L_write_array and S3L_write_sub_array in use can be found in:
/opt/SUNWhpc/examples/s3l/io/ex_io.c /opt/SUNWhpc/examples/s3l/io-f/ex_io.f |
S3L_print_array causes the process with MPI rank 0 to print the Sun S3L array described by the array handle a to standard output.
S3L_print_sub_array prints a specified subset of the Sun S3L array. This subset is defined by the lbounds, ubounds, and strides arguments. lbounds and ubounds specify the lower and upper boundaries for indexing along each axis. strides specifies the stride length to be used along each axis. It must be greater than zero.
S3L_print_array and S3L_print_sub_array have the following argument syntax:
S3L_print_array(a, ier) S3L_print_sub_array(a, lbounds, ubounds, strides, ier) |
a is a Sun S3L array handle describing the Sun S3L array to be printed. This array handle was returned by a previous call to either S3L_declare or S3L_declare_detailed.
lbounds is an integer vector that is used in calls to S3L_print_sub_array. Each element of lbounds corresponds to an axis of a and specifies the lower boundary of the indices along the axis it represents. This lower-bound index marks the beginning of a subset of array elements along that axis that will be printed. The default lower bound is:
ubounds is an integer vector that is used in calls to S3L_print_sub_array. Each element of ubounds corresponds to an axis of a and specifies the upper boundary of the indices along the axis it represents. This index marks the upper end of a subset of array elements along that axis that will be printed. The default upper bound is:
strides is an integer vector that is used in calls to S3L_print_sub_array. Each element of strides corresponds to an axis of a and specifies a stride length to be used in indexing along that axis. The default stride length is 1, which produces contiguous indexing.
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for these routines, see the S3L_print_array(3) and S3L_print_sub_array(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing S3L_print_array and S3L_print_sub_array in use can be found in:
/opt/SUNWhpc/examples/s3l/io/ex_print1.c /opt/SUNWhpc/examples/s3l/io/ex_io.c /opt/SUNWhpc/examples/s3l/io-f/ex_io.f |
S3L_copy_array copies the contents of Sun S3L array A into Sun S3L array B, which must have the same rank, extents, and data type as A.
S3L_copy_array_detailed copies a specified subset of Sun S3L array A into the corresponding section of Sun S3L array B. The subset of A to be copied is defined along each axis by the indices:
lbA(i), <= j <= ubA(i), with strides stA(i), i=0, rank-1 |
where lbA and ubA are the lower- and upper-bound indices of axes of A and stA is the indexing stride to be used along axes of A.
The array section of B is defined along each axis by the indices:
lbB(i), <= j <= ubB(i), with strides stB(i), i=0, rank-1 |
where lbB, ubB, and stB are analogous to lbA, ubA, and stA.
S3L_copy_array and S3L_copy_array_detailed have the following argument syntax:
S3L_copy_array(A, B, ier) S3L_copy_array_detailed(A, B, lbA, ubA, stA, lbB, ubB, stB, perm, ier) |
A is a Sun S3L array handle describing the Sun S3L array to be copied (the source array). This array handle was returned by a previous call to either S3L_declare or S3L_declare_detailed.
B is a Sun S3L array handle describing the Sun S3L array into which A is to be copied (the destination array). This array handle was returned by a previous call to either S3L_declare or S3L_declare_detailed.
B must have the same rank, extents, and data type as A.
lbA is an integer vector that is used in calls to S3L_copy_array_detailed . Each element of lbA corresponds to an axis of A and specifies the lower bound of the indices along the axis it represents. This lower-bound index marks the beginning of a subset of array elements along that axis that will be copied. The default lower bound is:
ubA is an integer vector that is used in calls to S3L_copy_array_detailed. Each element of ubA corresponds to an axis of A and specifies the upper bound of the indices along the axis it represents. This upper-bound index marks the upper end of a subset of array elements along that axis that will be copied. The default upper bound is:
stA is an integer vector that is used in calls to S3L_copy_array_detailed. Each element of stA corresponds to an axis of A and specifies a stride length to be used in indexing along that axis. The default stride length is 1, which produces contiguous indexing.
lbB, ubB, and stB have the same meaning for the destination array B as lbA, ubA, and stA have for source array A.
perm is an integer vector that is used in calls to S3L_copy_array_detailed. The first element of perm controls whether the other elements will be evaluated. It does so in the following way: If the first element is NULL (C interface) or negative (Fortran interface), perm is ignored. Otherwise, the other elements are evaluated.
Each of the other elements of perm correspond to an axis of B and specify whether the axis it represents will be permuted.
If the call is made from a Fortran program, error status will be in ier.
For detailed descriptions of the Fortran and C bindings for these routines, see the S3L_copy_array(3) and S3L_copy_array_detailed(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing S3L_copy_array in use can be found in:
/opt/SUNWhpc/examples/s3l/utils/copy_array.c /opt/SUNWhpc/examples/s3l/utils-f/copy_array.f |
Examples showing S3L_copy_array_detailed in use can be found in:
| Sun S3L 4.0 Software Programming Guide
| 817-0086-10 |
|
Copyright © 2003, Sun Microsystems, Inc. All rights reserved.