Dense Singular Value Decomposition

S3L_gen_svd

Description

S3L_gen_svd computes the singular value of a parallel array A and, optionally, the right and/or left singular vectors. On exit, S contains the singular values. If requested, U and V contain the left and right singular vectors, respectively.

If A, U, and V are two-dimensional arrays, S3L_gen_svd is more efficient when A, U and V are allocated on the same process grid and the same block size is used along both axes. When A, U, and V have more than two dimensions, S3L_gen_svd is more efficient when axis_r, axis_c and axis_s are local (that is, are not distributed).

Syntax

The C and Fortran syntax for S3L_gen_svd are shown below.

C/C++ Syntax

Example 8-79

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_gen_svd(A, U, S, V, jobu, jobv, axis_r, axis_c, axis_s)
    S3L_array_t        A
    S3L_array_t        U
    S3L_array_t        S
    S3L_array_t        V
    char               jobu
    char               jobv
    int                axis_r
    int                axis_c
    int                axis_s

F77/F90 Syntax

Example 8-80

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_gen_svd(A, U, S, V, jobu, jobv, axis_r, axis_c, axis_s, ier)
    integer*8          A
    integer*8          U
    integer*8          S
    integer*8          V
    character*1       jobu
    character*1       jobv
    integer*4         axis_r
    integer*4         axis_c
    integer*4         axis_s
    integer*4         ier

Input

• A - S3L array handle describing a parallel array of type S3L_double or S3L_float. In the 2D case, A is an m x n array. If A has more than two dimensions, axis_r and axis_c correspond to the axes of A whose extents are m and n, respectively.

• U - If jobu = V, U is a parallel array of dimensions m x min(m,n). Otherwise, U is not referred to. If U has more than two dimensions, axis_r and axis_c correspond to the axes of U whose extents are m and n, respectively. On output, U is overwritten with the left singular vectors (see the Output section).

• S - S3L array handle describing a parallel array (vector) of length min(m,n). If S is multidimensional, axis_s corresponds to the axis of S whose extent is min(m,n).

• V - If jobu = V, this is an S3L array handle describing a parallel array of dimensions min(m,n) x n. Otherwise, V is not referenced. If V has more than two dimensions, axis_r and axis_c correspond to the axes of V whose extents are m and n, respectively. On output, V is overwritten with the right singular vectors (see the Output section).

• jobu - Specifies options for computing all or part of the matrix U, as follows:

  • jobu = V - The first min(m,n) columns of U (the left singular vectors) are returned in the array U.

  • jobu = N - No columns of U (no left singular vectors) are computed.

• jobv - Specifies options for computing all or part of the matrix V, as follows:

  • jobv = V - The first min(m,n) rows of V (the right singular vectors) are returned in the array V.

  • jobv = N - No rows of V (no right singular vectors) are computed.

• axis_r - This is the axis of arrays A, U, and V such that the extent of array A along axis_r is m, the extent of array U along axis_r is m, and the extent of array V along axis_r is min(m,n).

• axis_c - This is the axis of arrays A, U, and V such that the extent of array A along axis_c is n, the extent of array U along axis_c is min(m,n), and the extent of array V along axis_c is n.

• axis_s - This is the axis of array S along which the length is equal to min(m,n).

Output

This function uses the following arguments for output:

• U - On output, U is overwritten with the left singular vectors.

• S - On output, S is overwritten with the singular values.

• V - On output, V is overwritten with the right singular vectors.

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

Error Handling

On success, S3L_gen_svd returns S3L_SUCCESS.

S3L_gen_svd performs generic checking 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_AXISNUM - An axis argument is invalid; that is, it is either:

  • Less than 0 (C/C++) or less than 1 (F77/F90).

  • Greater than the rank of the referenced array.

  • axis_r is equal to axis_c.

• S3L_ERR_MATCH_DTYPE - The arrays are not the same data type.

• S3L_ERR_MATCH_RANK - The arrays are not the same rank.

• S3L_ERR_MATCH_EXTENTS - The extents of the arrays are not compatible.

• S3L_ERR_ARG_DTYPE - The data types of the array arguments are not float or double.

• S3L_ERR_ARG_OP - jobv is not one of V or N.

• S3L_ERR_SVD_FAIL - The svd algorithm failed to converge.

Examples

../examples/s3l/svd/ex_svd.c
../examples/s3l/svd-f/ex_svd.f