Skip to content

README.md

Latest commit

 

History

History
164 lines (104 loc) · 5.14 KB

README.md

File metadata and controls

164 lines (104 loc) · 5.14 KB

diagonal

Return a view of the diagonal of a matrix (or stack of matrices).

For an M-by-N matrix A, the k-th diagonal is defined as

$$D_k = \{\, A_{i,j} : j - i = k \,\}$$

where k = 0 corresponds to the main diagonal, k > 0 corresponds to the super-diagonals (above the main diagonal), and k < 0 corresponds to the sub-diagonals (below the main diagonal). For example, given the matrix

$$A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}$$

the main diagonal is [ a_{0,0}, a_{1,1}, a_{2,2} ], the super-diagonal k = 1 is [ a_{0,1}, a_{1,2} ], and the sub-diagonal k = -1 is [ a_{1,0}, a_{2,1} ].

Usage

var diagonal = require( '@stdlib/ndarray/base/diagonal' );

diagonal( x, dims, k, writable )

Returns a view of the diagonal of a matrix (or stack of matrices) x.

var array = require( '@stdlib/ndarray/array' );

var x = array( [ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ], [ 7.0, 8.0, 9.0 ] ] );
// returns <ndarray>[ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ], [ 7.0, 8.0, 9.0 ] ]

var y = diagonal( x, [ 0, 1 ], 0, false );
// returns <ndarray>[ 1.0, 5.0, 9.0 ]

The function accepts the following arguments:

  • x: input ndarray.
  • dims: dimension indices defining the plane in which to extract the diagonal.
  • k: diagonal offset.
  • writable: boolean indicating whether the returned ndarray should be writable.

Notes

  • The order of the dimension indices contained in dims matters. The first element specifies the row-like dimension. The second element specifies the column-like dimension.
  • Each provided dimension index must reside on the interval [-ndims, ndims-1].
  • The diagonal offset k is interpreted as column - row. Accordingly, when k = 0, the function returns the main diagonal; when k > 0, the function returns the diagonal above the main diagonal; and when k < 0, the function returns the diagonal below the main diagonal.
  • The returned ndarray is a view of the input ndarray. Accordingly, writing to the original ndarray will mutate the returned ndarray and vice versa.
  • The writable parameter only applies to ndarray constructors supporting read-only instances.

Examples

var uniform = require( '@stdlib/random/uniform' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var diagonal = require( '@stdlib/ndarray/base/diagonal' );

// Create a stack of matrices:
var x = uniform( [ 2, 3, 3 ], -10.0, 10.0, {
    'dtype': 'float64'
});
console.log( 'X: ', ndarray2array( x ) );

// Extract the main diagonals of the stack:
var y = diagonal( x, [ 1, 2 ], 0, false );
console.log( ndarray2array( y ) );

// Extract the super-diagonals of the stack:
y = diagonal( x, [ 1, 2 ], 1, false );
console.log( ndarray2array( y ) );

// Extract the sub-diagonals of the stack:
y = diagonal( x, [ 1, 2 ], -1, false );
console.log( ndarray2array( y ) );