Skip to content

README.md

Latest commit

 

History

History
406 lines (276 loc) · 12.3 KB

README.md

File metadata and controls

406 lines (276 loc) · 12.3 KB

dgetc2

LAPACK routine to compute the LU factorization with complete pivoting of the general N-by-N matrix A.

The dgetc2 routine computes an LU factorization of with complete pivoting a real N-by-N matrix A. The factorization has the form:

$$A = P L U Q$$

where P and Q are permutation matrices, L is lower triangular with unit diagonal elements and U is upper triangular.

For a 5-by-5 matrix A, elements are stored in three arrays:

$$A = \left[ \begin{array}{rrrrr} a_{1,1} & a_{1,2} & a_{1,3} & a_{1,4} & a_{1,5} \\\ a_{2,1} & a_{2,2} & a_{2,3} & a_{2,4} & a_{2,5} \\\ a_{3,1} & a_{3,2} & a_{3,3} & a_{3,4} & a_{3,5} \\\ a_{4,1} & a_{4,2} & a_{4,3} & a_{4,4} & a_{4,5} \\\ a_{5,1} & a_{5,2} & a_{5,3} & a_{5,4} & a_{5,5} \end{array} \right]$$

After factorization, the elements of L and U are used to update A, where:

  • The unit diagonal elements of L are not stored.
  • If $U_{kk}$ appears to be less than SMIN, $U_{kk}$ is given the value of SMIN, i.e., giving a nonsingular perturbed system.

The resulting L and U matrices have the following structure:

$$L = \left[ \begin{array}{rrrrr} 0 & 0 & 0 & 0 & 0 \\\ l_{2,1} & 0 & 0 & 0 & 0 \\\ l_{3,1} & l_{3,2} & 0 & 0 & 0 \\\ l_{4,1} & l_{4,2} & l_{4,3} & 0 & 0 \\\ l_{5,1} & l_{5,2} & l_{5,3} & l_{5,4} & 0 \end{array} \right]$$ $$U = \left[ \begin{array}{rrrrr} u_{1,1} & u_{1,2} & u_{1,3} & u_{1,4} & u_{1,5} \\\ 0 & u_{2,2} & u_{2,3} & u_{2,4} & u_{2,5} \\\ 0 & 0 & u_{3,3} & u_{3,4} & u_{3,5} \\\ 0 & 0 & 0 & u_{4,4} & u_{4,5} \\\ 0 & 0 & 0 & 0 & u_{5,5} \end{array} \right]$$

where the values of L and U are stored in A, as follows:

$$A_{out} = L + U$$

Usage

var dgetc2 = require( '@stdlib/lapack/base/dgetc2' );

dgetc2( order, N, A, LDA, IPIV, JPIV )

Computes the LU factorization with complete pivoting of the general n-by-n matrix A.

var Float64Array = require( '@stdlib/array/float64' );
var Int32Array = require( '@stdlib/array/int32' );
var dgetc2 = require( '@stdlib/lapack/base/dgetc2' );

var A = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 10.0 ] );
var IPIV = new Int32Array( 3 );
var JPIV = new Int32Array( 3 );

/*
    A = [
        [ 1.0, 4.0, 7.0  ],
        [ 2.0, 5.0, 8.0  ],
        [ 3.0, 6.0, 10.0 ]
    ]
*/

dgetc2( 'column-major', 3, A, 3, IPIV, JPIV );
// A => <Float64Array>[ 10, 0.7, 0.8, 3, ~-1.1, ~0.36, 6, ~-0.2, ~0.27 ]
// JPIV = <Int32Array>[ 3, 3, 3 ]
// IPIV = <Int32Array>[ 3, 3, 3 ]

The function has the following parameters:

  • order: storage layout.
  • N: number of columns in matrix A.
  • A: input matrix (overwritten by L and U) stored in linear memory as a Float64Array.
  • LDA: stride of the first dimension of A (a.k.a., leading dimension of the matrix A).
  • IPIV: vector of pivot indices for rows as a Int32Array.
  • JPIV: vector of pivot indices for columns as a Int32Array.

The function returns the status code info.

Note that indexing is relative to the first index. To introduce an offset, use typed array views.

var Float64Array = require( '@stdlib/array/float64' );
var Int32Array = require( '@stdlib/array/int32' );
var dgetc2 = require( '@stdlib/lapack/base/dgetc2' );

// Initial arrays...
var A0 = new Float64Array( [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 10.0 ] );
var IPIV0 = new Int32Array( 4 );
var JPIV0 = new Int32Array( 4 );

/*
    A = [
        [ 1.0, 4.0, 7.0  ],
        [ 2.0, 5.0, 8.0  ],
        [ 3.0, 6.0, 10.0 ]
    ]
*/

// Create offset views...
var A = new Float64Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var IPIV = new Int32Array( IPIV0.buffer, IPIV0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var JPIV = new Int32Array( JPIV0.buffer, JPIV0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

dgetc2( 'column-major', 3, A, 3, IPIV, JPIV );
// A0 => <Float64Array>[ 0, 10, 0.7, 0.8, 3, ~-1.1, ~0.36, 6, ~-0.2, ~0.27 ]
// JPIV0 = <Int32Array>[ 0, 3, 3, 3 ]
// IPIV0 = <Int32Array>[ 0, 3, 3, 3 ]

dgetc2.ndarray( N, A, sa1, sa2, oa, IPIV, si, oi, JPIV, sj, oj )

Computes the LU factorization with complete pivoting of the general n-by-n matrix A using alternative indexing semantics.

var Float64Array = require( '@stdlib/array/float64' );
var Int32Array = require( '@stdlib/array/int32' );
var dgetc2 = require( '@stdlib/lapack/base/dgetc2' );

var A = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 10.0 ] );
var IPIV = new Int32Array( 3 );
var JPIV = new Int32Array( 3 );

/*
    A = [
        [ 1.0, 4.0, 7.0  ],
        [ 2.0, 5.0, 8.0  ],
        [ 3.0, 6.0, 10.0 ]
    ]
*/

dgetc2.ndarray( 3, A, 1, 3, 0, IPIV, 1, 0, JPIV, 1, 0 );
// A => <Float64Array>[ 10, 0.7, 0.8, 3, ~-1.1, ~0.36, 6, ~-0.2, ~0.27 ]
// JPIV = <Int32Array>[ 3, 3, 3 ]
// IPIV = <Int32Array>[ 3, 3, 3 ]

The function has the following parameters:

  • N: number of columns in matrix A.
  • A: input matrix (overwritten by L and U) stored in linear memory as a Float64Array.
  • sa1: stride of the first dimension of A.
  • sa2: stride of the second dimension of A.
  • oa: index offset for A.
  • IPIV: vector of pivot indices for rows as a Int32Array.
  • si: stride length for IPIV.
  • oi: index offset for IPIV.
  • JPIV: vector of pivot indices for columns as a Int32Array.
  • sj: stride length for JPIV.
  • oj: index offset for JPIV.

While typed array views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example,

var Float64Array = require( '@stdlib/array/float64' );
var Int32Array = require( '@stdlib/array/int32' );
var dgetc2 = require( '@stdlib/lapack/base/dgetc2' );

// Initial arrays...
var A = new Float64Array( [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 10.0 ] );
var IPIV = new Int32Array( 4 );
var JPIV = new Int32Array( 4 );

/*
    A = [
        [ 1.0, 4.0, 7.0  ],
        [ 2.0, 5.0, 8.0  ],
        [ 3.0, 6.0, 10.0 ]
    ]
*/

dgetc2.ndarray( 3, A, 1, 3, 1, IPIV, 1, 1, JPIV, 1, 1 );
// A => <Float64Array>[ 0, 10, 0.7, 0.8, 3, ~-1.1, ~0.36, 6, ~-0.2, ~0.27 ]
// JPIV = <Int32Array>[ 0, 3, 3, 3 ]
// IPIV = <Int32Array>[ 0, 3, 3, 3 ]

Notes

  • A should have dimension (LDA, N) and is overwritten with the factors L and U from the factorization A = P*L*U*Q, the unit diagonal elements of L are not stored.
  • If U(k, k) appears to be less than SMIN, U(k, k) is given the value of SMIN, i.e., giving a nonsingular perturbed system.
  • IPIV should have N elements and is overwritten with the pivot indices; for 1 <= i <= N, row i of the matrix has been interchanged with row IPIV(i).
  • JPIV should have N elements and is overwritten with the pivot indices; for 1 <= i <= N, column i of the matrix has been interchanged with column JPIV(i).
  • Returns 0 on successful exit and if returns k, U(k, k) is likely to produce overflow if we try to solve for x in Ax = b. So U is perturbed to avoid the overflow.
  • dgetc2() corresponds to the LAPACK function dgetc2.

Examples

var Float64Array = require( '@stdlib/array/float64' );
var Int32Array = require( '@stdlib/array/int32' );
var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
var dgetc2 = require( '@stdlib/lapack/base/dgetc2' );

var N = 3;
var LDA = 3;

var A = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 10.0 ] );

console.log( 'The n-by-n matrix A to be factored:' );
console.log( ndarray2array( A, [ LDA, N ], [ 1, N ], 0, 'column-major' ) );

var IPIV = new Int32Array( N );
var JPIV = new Int32Array( N );

// Perform the `A = LU` factorization:
var info = dgetc2( 'column-major', N, A, LDA, IPIV, JPIV );

console.log( 'The factors L and U from the factorization:' );
console.log( ndarray2array( A, [ LDA, N ], [ 1, N ], 0, 'column-major' ) );

C APIs

Usage

TODO

TODO

TODO.

TODO

TODO

TODO

Examples

TODO