BandMatrix (Smile Math 1.0.3 API)

java.lang.Object
- smile.math.matrix.BandMatrix

All Implemented Interfaces:

IMatrix
```
public class BandMatrix
extends Object
implements IMatrix
```
A band matrix is a sparse matrix, whose non-zero entries are confined to a diagonal band, comprising the main diagonal and zero or more diagonals on either side.
In numerical analysis, matrices from finite element or finite difference problems are often banded. Such matrices can be viewed as descriptions of the coupling between the problem variables; the bandedness corresponds to the fact that variables are not coupled over arbitrarily large distances. Such matrices can be further divided - for instance, banded matrices exist where every element in the band is nonzero. These often arise when discretizing one-dimensional problems. Problems in higher dimensions also lead to banded matrices, in which case the band itself also tends to be sparse. For instance, a partial differential equation on a square domain (using central differences) will yield a matrix with a half-bandwidth equal to the square root of the matrix dimension, but inside the band only 5 diagonals are nonzero. Unfortunately, applying Gaussian elimination (or equivalently an LU decomposition) to such a matrix results in the band being filled in by many non-zero elements. As sparse matrices lend themselves to more efficient computation than dense matrices, there has been much research focused on finding ways to minimize the bandwidth (or directly minimize the fill in) by applying permutations to the matrix, or other such equivalence or similarity transformations.
From a computational point of view, working with band matrices is always preferential to working with similarly dimensioned dense square matrices. A band matrix can be likened in complexity to a rectangular matrix whose row dimension is equal to the bandwidth of the band matrix. Thus the work involved in performing operations such as multiplication falls significantly, often leading to huge savings in terms of calculation time and complexity.
Given a n-by-n band matrix with m₁ rows below the diagonal and m₂ rows above. The matrix is compactly stored in an array A[0,n-1][0,m₁+m₂]. The diagonal elements are in A[0,n-1][m₁]. Subdiagonal elements are in A[j,n-1][0,m₁-1] with j > 0 appropriate to the number of elements on each subdiagonal. Superdiagonal elements are in A[0,j][m₁+1,m₂+m₂] with j < n-1 appropriate to the number of elements on each superdiagonal.

Author:

Haifeng Li

Constructor Summary

Constructors
Constructor and Description
`BandMatrix(int n, int m)` Constructor of an n-by-n band-diagonal matrix A with m subdiagonal rows and m superdiagonal rows.
`BandMatrix(int n, int m1, int m2)` Constructor of an n-by-n band-diagonal matrix A with m₁ subdiagonal rows and m₂ superdiagonal rows.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`asolve(double[] b, double[] x)` Solve A_d * x = b for the preconditioner matrix A_d.
`void`	`atx(double[] x, double[] y)` y = A' * x
`void`	`atxpy(double[] x, double[] y)` y = A' * x + y
`void`	`atxpy(double[] x, double[] y, double b)` y = A' * x + b * y
`void`	`ax(double[] x, double[] y)` y = A * x
`void`	`axpy(double[] x, double[] y)` y = A * x + y
`void`	`axpy(double[] x, double[] y, double b)` y = A * x + b * y
`void`	`decompose()` LU decomposition.
`double`	`det()` Returns the matrix determinant.
`double`	`eigen(double[] v)` Returns the largest eigen pair of matrix with the power iteration under the assumptions A has an eigenvalue that is strictly greater in magnitude than its other its other eigenvalues and the starting vector has a nonzero component in the direction of an eigenvector associated with the dominant eigenvalue.
`EigenValueDecomposition`	`eigen(int k)` Returns the k largest eigen pairs.
`double`	`get(int i, int j)` Returns the entry value at row i and column j.
`void`	`improve(double[] b, double[] x)` Iteratively improve a solution to linear equations.
`int`	`ncols()` Returns the number of columns.
`int`	`nrows()` Returns the number of rows.
`void`	`set(int i, int j, double x)` Set the entry value at row i and column j.
`void`	`solve(double[] b)` Solve A*x = b.
`void`	`solve(double[] b, double[] x)` Solve A*x = b.
`BandMatrix`	`transpose()` Returns the matrix transpose.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - BandMatrix
```
public BandMatrix(int n,
          int m)
```
    Constructor of an n-by-n band-diagonal matrix A with m subdiagonal rows and m superdiagonal rows.
    
    Parameters:
    n - the dimensionality of matrix.
    m - the number of subdiagonal and superdiagonal rows.
  - BandMatrix
```
public BandMatrix(int n,
          int m1,
          int m2)
```
    Constructor of an n-by-n band-diagonal matrix A with m₁ subdiagonal rows and m₂ superdiagonal rows.
    
    Parameters:
    n - the dimensionality of matrix.
    m1 - the number of subdiagonal rows.
    m2 - the number of superdiagonal rows.
- Method Detail
  - nrows
```
public int nrows()
```
    Description copied from interface: IMatrix
    
    Returns the number of rows.
    
    Specified by:
    
    nrows in interface IMatrix
  - ncols
```
public int ncols()
```
    Description copied from interface: IMatrix
    
    Returns the number of columns.
    
    Specified by:
    
    ncols in interface IMatrix
  - get
```
public double get(int i,
         int j)
```
    Description copied from interface: IMatrix
    
    Returns the entry value at row i and column j.
    
    Specified by:
    
    get in interface IMatrix
  - set
```
public void set(int i,
       int j,
       double x)
```
    Description copied from interface: IMatrix
    
    Set the entry value at row i and column j.
    
    Specified by:
    
    set in interface IMatrix
  - transpose
```
public BandMatrix transpose()
```
    Returns the matrix transpose.
    
    Returns:
    the transpose of matrix.
  - eigen
```
public double eigen(double[] v)
```
    Returns the largest eigen pair of matrix with the power iteration under the assumptions A has an eigenvalue that is strictly greater in magnitude than its other its other eigenvalues and the starting vector has a nonzero component in the direction of an eigenvector associated with the dominant eigenvalue.
    
    Parameters:
    v - is the non-zero initial guess of the eigen vector on input. On output, it is the eigen vector corresponding largest eigen value.
    
    Returns:
    the largest eigen value.
  - eigen
```
public EigenValueDecomposition eigen(int k)
```
    Returns the k largest eigen pairs. Only works for symmetric matrix.
  - det
```
public double det()
```
    Returns the matrix determinant.
  - decompose
```
public void decompose()
```
    LU decomposition.
  - ax
```
public void ax(double[] x,
      double[] y)
```
    Description copied from interface: IMatrix
    
    y = A * x
    
    Specified by:
    
    ax in interface IMatrix
  - axpy
```
public void axpy(double[] x,
        double[] y)
```
    Description copied from interface: IMatrix
    
    y = A * x + y
    
    Specified by:
    
    axpy in interface IMatrix
  - axpy
```
public void axpy(double[] x,
        double[] y,
        double b)
```
    Description copied from interface: IMatrix
    
    y = A * x + b * y
    
    Specified by:
    
    axpy in interface IMatrix
  - atx
```
public void atx(double[] x,
       double[] y)
```
    Description copied from interface: IMatrix
    
    y = A' * x
    
    Specified by:
    
    atx in interface IMatrix
  - atxpy
```
public void atxpy(double[] x,
         double[] y)
```
    Description copied from interface: IMatrix
    
    y = A' * x + y
    
    Specified by:
    
    atxpy in interface IMatrix
  - atxpy
```
public void atxpy(double[] x,
         double[] y,
         double b)
```
    Description copied from interface: IMatrix
    
    y = A' * x + b * y
    
    Specified by:
    
    atxpy in interface IMatrix
  - asolve
```
public void asolve(double[] b,
          double[] x)
```
    Description copied from interface: IMatrix
    
    Solve A_d * x = b for the preconditioner matrix A_d. The preconditioner matrix A_d is close to A and should be easy to solve for linear systems. This method is useful for preconditioned conjugate gradient method. The preconditioner matrix could be as simple as the trivial diagonal part of A in some cases.
    
    Specified by:
    
    asolve in interface IMatrix
  - solve
```
public void solve(double[] b)
```
    Solve A*x = b. b will be overwritten with the solution vector on output.
    
    Parameters:
    b - a vector with as many rows as A.
    
    Throws:
    
    RuntimeException - if matrix is singular.
  - solve
```
public void solve(double[] b,
         double[] x)
```
    Solve A*x = b.
    
    Parameters:
    b - a vector with as many rows as A.
    x - is output vector so that L*U*X = b(piv,:)
    
    Throws:
    
    RuntimeException - if matrix is singular.
  - improve
```
public void improve(double[] b,
           double[] x)
```
    Iteratively improve a solution to linear equations.
    
    Parameters:
    b - right hand side of linear equations.
    x - a solution to linear equations.

Class BandMatrix

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BandMatrix

BandMatrix

Method Detail

nrows

ncols

get

set

transpose

eigen

eigen

det

decompose

ax

axpy

axpy

atx

atxpy

atxpy

asolve

solve

solve

improve