Least Squares Solver

S3L_gen_lsq

Description

If m >= n, S3L_gen_lsq finds the least squares solution of an overdetermined system. That is, it solves the least squares problem:

Example 8-75

minimize || B - A*X ||

On output, the first n rows of B hold the least squares solution X.

If m < n, S3L_gen_lsq finds the minimum norm solution of an underdetermined system:

Example 8-76

A * X = B(1:m,:)

On output, B holds the minimum norm solution X.

Syntax

The C and Fortran syntax for S3L_gen_lsq are shown below.

C/C++ Syntax

Example 8-77

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_gen_lsq(A, B, axis1, axis2)
    S3L_array_t        A
    S3L_array_t        B
    int                axis1
    int                axis1

F77/F90 Syntax

Example 8-78

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

Input

• A - S3L array handle that describes a parallel array of dimensions m x n. On output, its contents may be destroyed.

• B - S3L array handle that describes a parallel array of dimensions max(m,n) x nrhs. On output, its contents may be destroyed.

• axis1 - If A and B have more than two dimensions, axis1 denotes the dimension of A with extent m. Otherwise, it has to be 0 for C/C++ programs or 1 for F77/F90 programs.

• axis2 - If A and B have more that two dimensions, axis2 denotes the dimension of A with extent n. Otherwise, it has to be 0 for C/C++ programs or 1 for F77/F90 programs.

Output

This function uses the following argument for output:

• B - On output, B is overwritten by the result of the least squares problem.

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

Error Handling

On success, S3L_gen_lsq returns S3L_SUCCESS.

S3L_gen_lsq checks the validity of the array arguments. If an array argument is found to be corrupted or invalid, an error code 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.

  • axis1 is equal to axis2.

• S3L_ERR_MATCH_DTYPE - The array arguments are not all of the same type, as required.

• S3L_ERR_MATCH_RANK - Corresponding ranks of the array arguments do not match.

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

• S3L_ERR_ARG_DTYPE - The array arguments are not float or double, complex, or double precision complex.

Examples

../examples/s3l/lsq/ex_lsq.c
../examples/s3l/lsq-f/ex_lsq.f