library: libMatrix #include "TMatrixDSparse.h"

# TMatrixDSparse

class description - source file - inheritance tree (.pdf)

## class TMatrixDSparse : public TMatrixDBase

| Inheritance Chart:
`TObject`
| <- | `TMatrixDBase`
| <- | `TMatrixDSparse` |

        protected:

          virtual void Allocate(Int_t nrows, Int_t ncols, Int_t row_lwb = 0, Int_t col_lwb = 0, Int_t init = 0, Int_t nr_nonzeros = 0)
                  void AMinusB(const TMatrixDSparse& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void AMinusB(const TMatrixDSparse& a, const TMatrixD& b, Int_t constr = 1)
                  void AMinusB(const TMatrixD& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void AMultB(const TMatrixDSparse& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void AMultB(const TMatrixDSparse& a, const TMatrixD& b, Int_t constr = 1)
                  void AMultB(const TMatrixD& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void AMultBt(const TMatrixDSparse& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void AMultBt(const TMatrixDSparse& a, const TMatrixD& b, Int_t constr = 1)
                  void AMultBt(const TMatrixD& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void APlusB(const TMatrixDSparse& a, const TMatrixDSparse& b, Int_t constr = 1)
                  void APlusB(const TMatrixDSparse& a, const TMatrixD& b, Int_t constr = 1)
                  void APlusB(const TMatrixD& a, const TMatrixDSparse& b, Int_t constr = 1)

        public:

                                        TMatrixDSparse()
                                        TMatrixDSparse(Int_t nrows, Int_t ncols)
                                        TMatrixDSparse(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb)
                                        TMatrixDSparse(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, Int_t nr_nonzeros, Int_t* row, Int_t* col, Double_t* data)
                                        TMatrixDSparse(const TMatrixDSparse& another)
                                        TMatrixDSparse(const TMatrixD& another)
                                        TMatrixDSparse(TMatrixDBase::EMatrixCreatorsOp1 op, const TMatrixDSparse& prototype)
                                        TMatrixDSparse(const TMatrixDSparse& a, TMatrixDBase::EMatrixCreatorsOp2 op, const TMatrixDSparse& b)
                         TMatrixDSparse GetSub(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, Option_t* option = "S") const
                                virtual ~TMatrixDSparse()
                         static TClass* Class()
                           virtual void Clear(Option_t* = "")
                       virtual Double_t ColNorm() const
                           virtual void ExtractRow(Int_t row, Int_t col, Double_t* v, Int_t n = -1) const
                   virtual const Int_t* GetColIndexArray() const
                         virtual Int_t* GetColIndexArray()
                           virtual void GetMatrix2Array(Double_t* data, Option_t* option = "") const
                virtual const Double_t* GetMatrixArray() const
                      virtual Double_t* GetMatrixArray()
                   virtual const Int_t* GetRowIndexArray() const
                         virtual Int_t* GetRowIndexArray()
                  virtual TMatrixDBase& GetSub(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, TMatrixDBase& target, Option_t* option = "S") const
                  virtual TMatrixDBase& InsertRow(Int_t row, Int_t col, const Double_t* v, Int_t n = -1)
                        virtual TClass* IsA() const
                         virtual Bool_t IsSymmetric() const
                                   void Mult(const TMatrixDSparse& a, const TMatrixDSparse& b)
                          virtual Int_t NonZeros() const
                  virtual TMatrixDBase& NormByDiag(const TVectorD&, Option_t*)
                       virtual Double_t operator()(Int_t rown, Int_t coln) const
                      virtual Double_t& operator()(Int_t rown, Int_t coln)
                        TMatrixDSparse& operator*=(Double_t val)
                        TMatrixDSparse& operator*=(const TMatrixDSparse& source)
                        TMatrixDSparse& operator*=(const TMatrixD& source)
                        TMatrixDSparse& operator+=(Double_t val)
                        TMatrixDSparse& operator+=(const TMatrixDSparse& source)
                        TMatrixDSparse& operator+=(const TMatrixD& source)
                        TMatrixDSparse& operator-=(Double_t val)
                        TMatrixDSparse& operator-=(const TMatrixDSparse& source)
                        TMatrixDSparse& operator-=(const TMatrixD& source)
                        TMatrixDSparse& operator=(const TMatrixD& source)
                        TMatrixDSparse& operator=(const TMatrixDSparse& source)
                        TMatrixDSparse& operator=(Double_t val)
          const TMatrixDSparseRow_const operator[](Int_t rown) const
                      TMatrixDSparseRow operator[](Int_t rown)
                  virtual TMatrixDBase& Randomize(Double_t alpha, Double_t beta, Double_t& seed)
                virtual TMatrixDSparse& RandomizePD(Double_t alpha, Double_t beta, Double_t& seed)
                  virtual TMatrixDBase& ResizeTo(Int_t nrows, Int_t ncols, Int_t nr_nonzeros = -1)
                  virtual TMatrixDBase& ResizeTo(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, Int_t nr_nonzeros = -1)
                          TMatrixDBase& ResizeTo(const TMatrixDSparse& m)
                       virtual Double_t RowNorm() const
                  virtual TMatrixDBase& SetColIndexArray(Int_t* data)
                  virtual TMatrixDBase& SetMatrixArray(const Double_t* data, Option_t* = "")
                  virtual TMatrixDBase& SetMatrixArray(Int_t nr_nonzeros, Int_t* irow, Int_t* icol, Double_t* data)
                  virtual TMatrixDBase& SetRowIndexArray(Int_t* data)
                        TMatrixDSparse& SetSparseIndex(Int_t nelem_new)
                        TMatrixDSparse& SetSparseIndex(const TMatrixDBase& another)
                        TMatrixDSparse& SetSparseIndexAB(const TMatrixDSparse& a, const TMatrixDSparse& b)
                  virtual TMatrixDBase& SetSub(Int_t row_lwb, Int_t col_lwb, const TMatrixDBase& source)
                           virtual void ShowMembers(TMemberInspector& insp, char* parent)
                           virtual void Streamer(TBuffer& b)
                                   void StreamerNVirtual(TBuffer& b)
                        TMatrixDSparse& T()
                        TMatrixDSparse& Transpose(const TMatrixDSparse& source)
                  virtual TMatrixDBase& UnitMatrix()
                        TMatrixDSparse& Use(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, Int_t nr_nonzeros, Int_t* pRowIndex, Int_t* pColIndex, Double_t* pData)
                        TMatrixDSparse& Use(Int_t nrows, Int_t ncols, Int_t nr_nonzeros, Int_t* pRowIndex, Int_t* pColIndex, Double_t* pData)
                        TMatrixDSparse& Use(TMatrixDSparse& a)
                  virtual TMatrixDBase& Zero()

### Data Members

        protected:

             Int_t* fRowIndex  [fNrowIndex] row index
             Int_t* fColIndex  [fNelems]    column index
          Double_t* fElements  [fNelems]

## Class Description

     TMatrixDSparse

     Implementation of a general sparse matrix in the Harwell-Boeing
     format

     Besides the usual shape/size decsriptors of a matrix like fNrows,
     fRowLwb,fNcols and fColLwb, we also store a row index, fRowIndex and
     column index, fColIndex only for those elements unequal zero:

     fRowIndex[0,..,fNrows]:    Stores for each row the index range of
                                the elements in the data and column array
     fColIndex[0,..,fNelems-1]: Stores the column number for each data
                                element != 0

     As an example how to access all sparse data elements:

     for (Int_t irow = 0; irow < fNrows; irow++) {
       const Int_t sIndex = fRowIndex[irow];
       const Int_t eIndex = fRowIndex[irow+1];
       for (Int_t index = sIndex; index < eIndex; index++) {
         const Int_t icol = fColIndex[index];
         const Double_t data = fElements[index];
         printf("data(%d,%d) = %.4e\n",irow+fRowLwb,icol+fColLwb,data);
       }
     }

     When checking whether sparse matrices are compatible (like in an
     assigment !), not only the shape parameters are compared but also
     the sparse structure through fRowIndex and fColIndex .

     Several methods exist to fill a sparse matrix with data entries.
     Most are the same like for dense matrices but some care has to be
     taken with regard to performance. In the constructor, always the
     shape of the matrix has to be specified in some form . Data can be
     entered through the following methods :
     1. constructor
        TMatrixDSparse(Int_t row_lwb,Int_t row_upb,Int_t col_lwb,
                       Int_t col_upb,Int_t nr_nonzeros,
                       Int_t *row, Int_t *col,Double_t *data);
        It uses SetMatrixArray(..), see below
     2. copy constructors
     3. SetMatrixArray(Int_t nr,Int_t *irow,Int_t *icol,Double_t *data)
        where it is expected that the irow,icol and data array contain
        nr entries . Only the entries with non-zero data[i] value are
        inserted !
     4. TMatrixDSparse a(n,m); for(....) { a(i,j) = ....
        This is a very flexible method but expensive :
        - if no entry for slot (i,j) is found in the sparse index table
          it will be entered, which involves some memory management !
        - before invoking this method in a loop it is smart to first
          set the index table through a call to SetSparseIndex(..)
     5. SetSub(Int_t row_lwb,Int_t col_lwb,const TMatrixDBase &source)
        the matrix to be inserted at position (row_lwb,col_lwb) can be
        both dense or sparse .

TMatrixDSparse(Int_t no_rows,Int_t no_cols)

     Space is allocated for row/column indices and data, but the sparse structure
     information has still to be set !

TMatrixDSparse(Int_t row_lwb,Int_t row_upb,Int_t col_lwb,Int_t col_upb)

     Space is allocated for row/column indices and data, but the sparse structure
     information has still to be set !

TMatrixDSparse(Int_t row_lwb,Int_t row_upb,Int_t col_lwb,Int_t col_upb, Int_t nr,Int_t *row, Int_t *col,Double_t *data)

     Space is allocated for row/column indices and data. Sparse row/column index
     structure together with data is coming from the arrays, row, col and data, resp .

TMatrixDSparse(const TMatrixDSparse &another) : TMatrixDBase(another)

TMatrixDSparse(const TMatrixD &another) : TMatrixDBase(another)

TMatrixDSparse(EMatrixCreatorsOp1 op,const TMatrixDSparse &prototype)

     Create a matrix applying a specific operation to the prototype.
     Supported operations are: kZero, kUnit, kTransposed and kAtA

TMatrixDSparse(const TMatrixDSparse &a,EMatrixCreatorsOp2 op,const TMatrixDSparse &b)

     Create a matrix applying a specific operation to two prototypes.
     Supported operations are: kMult (a*b), kMultTranspose (a*b'), kPlus (a+b), kMinus (a-b)

void Allocate(Int_t no_rows,Int_t no_cols,Int_t row_lwb,Int_t col_lwb, Int_t init,Int_t nr_nonzeros)

     Allocate new matrix. Arguments are number of rows, columns, row lowerbound (0 default)
     and column lowerbound (0 default), 0 initialization flag and number of non-zero
     elements (only relevant for sparse format).

TMatrixDBase& InsertRow(Int_t rown,Int_t coln,const Double_t *v,Int_t n)

     Insert in row rown, n elements of array v at column coln

void ExtractRow(Int_t rown, Int_t coln, Double_t *v,Int_t n) const

     Store in array v, n matrix elements of row rown starting at column coln

void AMultBt(const TMatrixDSparse &a,const TMatrixDSparse &b,Int_t constr)

     General matrix multiplication. Create a matrix C such that C = A * B'.
     Note, matrix C is allocated for constr=1.

void AMultBt(const TMatrixDSparse &a,const TMatrixD &b,Int_t constr)

     General matrix multiplication. Create a matrix C such that C = A * B'.
     Note, matrix C is allocated for constr=1.

void AMultBt(const TMatrixD &a,const TMatrixDSparse &b,Int_t constr)

     General matrix multiplication. Create a matrix C such that C = A * B'.
     Note, matrix C is allocated for constr=1.

void APlusB(const TMatrixDSparse &a,const TMatrixDSparse &b,Int_t constr)

     General matrix addition. Create a matrix C such that C = A + B.
     Note, matrix C is allocated for constr=1.

void APlusB(const TMatrixDSparse &a,const TMatrixD &b,Int_t constr)

     General matrix addition. Create a matrix C such that C = A + B.
     Note, matrix C is allocated for constr=1.

void AMinusB(const TMatrixDSparse &a,const TMatrixDSparse &b,Int_t constr)

     General matrix subtraction. Create a matrix C such that C = A - B.
     Note, matrix C is allocated for constr=1.

void AMinusB(const TMatrixDSparse &a,const TMatrixD &b,Int_t constr)

     General matrix subtraction. Create a matrix C such that C = A - B.
     Note, matrix C is allocated for constr=1.

void AMinusB(const TMatrixD &a,const TMatrixDSparse &b,Int_t constr)

     General matrix subtraction. Create a matrix C such that C = A - B.
     Note, matrix C is allocated for constr=1.

void GetMatrix2Array(Double_t *data,Option_t * /*option*/) const

     Copy matrix data to array . It is assumed that array is of size >= fNelems

TMatrixDBase& SetMatrixArray(Int_t nr,Int_t *row,Int_t *col,Double_t *data)

     Copy nr elements from row/col index and data array to matrix . It is assumed
     that arrays are of size >= nr

TMatrixDSparse& SetSparseIndex(Int_t nelems_new)

     Increase/decrease the number of non-zero elements to nelems_new

TMatrixDSparse& SetSparseIndex(const TMatrixDBase &source)

     Use non-zero data of matrix source to set the sparse structure

TMatrixDSparse& SetSparseIndexAB(const TMatrixDSparse &a,const TMatrixDSparse &b)

     Set the row/column indices to the "sum" of matrices a and b
     It is checked that enough space has been allocated

TMatrixDBase& ResizeTo(Int_t nrows,Int_t ncols,Int_t nr_nonzeros)

     Set size of the matrix to nrows x ncols with nr_nonzeros non-zero entries
     if nr_nonzeros > 0 .
     New dynamic elements are created, the overlapping part of the old ones are
     copied to the new structures, then the old elements are deleted.

TMatrixDBase& ResizeTo(Int_t row_lwb,Int_t row_upb,Int_t col_lwb,Int_t col_upb, Int_t nr_nonzeros)

     Set size of the matrix to [row_lwb:row_upb] x [col_lwb:col_upb] with nr_nonzeros
     non-zero entries if nr_nonzeros > 0 .
     New dynamic elemenst are created, the overlapping part of the old ones are
     copied to the new structures, then the old elements are deleted.

TMatrixDSparse& Use(Int_t row_lwb,Int_t row_upb,Int_t col_lwb,Int_t col_upb, Int_t nr_nonzeros,Int_t *pRowIndex,Int_t *pColIndex,Double_t *pData)

TMatrixDBase& GetSub(Int_t row_lwb,Int_t row_upb,Int_t col_lwb,Int_t col_upb, TMatrixDBase &target,Option_t *option) const

     Get submatrix [row_lwb..row_upb][col_lwb..col_upb]; The indexing range of the
     returned matrix depends on the argument option:

     option == "S" : return [0..row_upb-row_lwb+1][0..col_upb-col_lwb+1] (default)
     else          : return [row_lwb..row_upb][col_lwb..col_upb]

TMatrixDBase& SetSub(Int_t row_lwb,Int_t col_lwb,const TMatrixDBase &source)

     Insert matrix source starting at [row_lwb][col_lwb], thereby overwriting the part
     [row_lwb..row_lwb+nrows_source-1][col_lwb..col_lwb+ncols_source-1];

TMatrixDSparse& Transpose(const TMatrixDSparse &source)

     Transpose a matrix.

TMatrixDBase& Zero()

TMatrixDBase& UnitMatrix()

     Make a unit matrix (matrix need not be a square one).

Double_t RowNorm() const

     Row matrix norm, MAX{ SUM{ |M(i,j)|, over j}, over i}.
     The norm is induced by the infinity vector norm.

Double_t ColNorm() const

     Column matrix norm, MAX{ SUM{ |M(i,j)|, over i}, over j}.
     The norm is induced by the 1 vector norm.

TMatrixDBase& Randomize(Double_t alpha,Double_t beta,Double_t &seed)

     randomize matrix element values

TMatrixDSparse& RandomizePD(Double_t alpha,Double_t beta,Double_t &seed)

     randomize matrix element values but keep matrix symmetric positive definite

### Inline Functions

                                     void ~TMatrixDSparse()
                                     void AMultB(const TMatrixDSparse& a, const TMatrixDSparse& b, Int_t constr = 1)
                                     void AMultB(const TMatrixDSparse& a, const TMatrixD& b, Int_t constr = 1)
                                     void AMultB(const TMatrixD& a, const TMatrixDSparse& b, Int_t constr = 1)
                                     void APlusB(const TMatrixD& a, const TMatrixDSparse& b, Int_t constr = 1)
                           TMatrixDSparse TMatrixDSparse(const TMatrixDSparse& a, TMatrixDBase::EMatrixCreatorsOp2 op, const TMatrixDSparse& b)
                          const Double_t* GetMatrixArray() const
                                Double_t* GetMatrixArray()
                             const Int_t* GetRowIndexArray() const
                                   Int_t* GetRowIndexArray()
                             const Int_t* GetColIndexArray() const
                                   Int_t* GetColIndexArray()
                            TMatrixDBase& SetRowIndexArray(Int_t* data)
                            TMatrixDBase& SetColIndexArray(Int_t* data)
                            TMatrixDBase& SetMatrixArray(Int_t nr_nonzeros, Int_t* irow, Int_t* icol, Double_t* data)
                            TMatrixDBase& ResizeTo(const TMatrixDSparse& m)
                                     void Clear(Option_t* = "")
                          TMatrixDSparse& Use(Int_t nrows, Int_t ncols, Int_t nr_nonzeros, Int_t* pRowIndex, Int_t* pColIndex, Double_t* pData)
                          TMatrixDSparse& Use(TMatrixDSparse& a)
                           TMatrixDSparse GetSub(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, Option_t* option = "S") const
                                   Bool_t IsSymmetric() const
                          TMatrixDSparse& T()
                                     void Mult(const TMatrixDSparse& a, const TMatrixDSparse& b)
                                    Int_t NonZeros() const
                            TMatrixDBase& NormByDiag(const TVectorD&, Option_t*)
                                 Double_t operator()(Int_t rown, Int_t coln) const
                                Double_t& operator()(Int_t rown, Int_t coln)
            const TMatrixDSparseRow_const operator[](Int_t rown) const
                        TMatrixDSparseRow operator[](Int_t rown)
                          TMatrixDSparse& operator=(const TMatrixD& source)
                          TMatrixDSparse& operator=(const TMatrixDSparse& source)
                          TMatrixDSparse& operator=(Double_t val)
                          TMatrixDSparse& operator-=(Double_t val)
                          TMatrixDSparse& operator+=(Double_t val)
                          TMatrixDSparse& operator*=(Double_t val)
                          TMatrixDSparse& operator+=(const TMatrixDSparse& source)
                          TMatrixDSparse& operator+=(const TMatrixD& source)
                          TMatrixDSparse& operator-=(const TMatrixDSparse& source)
                          TMatrixDSparse& operator-=(const TMatrixD& source)
                          TMatrixDSparse& operator*=(const TMatrixDSparse& source)
                          TMatrixDSparse& operator*=(const TMatrixD& source)
                                  TClass* Class()
                                  TClass* IsA() const
                                     void ShowMembers(TMemberInspector& insp, char* parent)
                                     void Streamer(TBuffer& b)
                                     void StreamerNVirtual(TBuffer& b)

Last update: root/matrix:$Name: $:$Id: TMatrixDSparse.cxx,v 1.18 2005/01/06 21:32:46 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *