library: libMatrix #include "TMatrixDBase.h"

# TMatrixDBase

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

## class TMatrixDBase : public TObject

| Inheritance Chart:

`TObject`

<-

`TMatrixDBase`

<-

`TMatrixD` |

`TMatrixDSparse` |

`TMatrixDSym` |

This is an abstract class, constructors will not be documented.
Look at the header to check for available constructors.

        private:

          Double_t* GetElements()

        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_nonzero = -1)
           static void DoubleLexSort(Int_t n, Int_t* first, Int_t* second, Double_t* data)
           static void IndexedLexSort(Int_t n, Int_t* first, Int_t swapFirst, Int_t* second, Int_t swapSecond, Int_t* index)

        public:

                          virtual ~TMatrixDBase()
            virtual TMatrixDBase& Abs()
            virtual TMatrixDBase& Apply(const TElementActionD& action)
            virtual TMatrixDBase& Apply(const TElementPosActionD& action)
                   static TClass* Class()
                     virtual void Clear(Option_t* option = "")
                 virtual Double_t ColNorm() const
                 virtual Double_t Determinant() const
                     virtual void Determinant(Double_t& d1, Double_t& d2) const
                     virtual void Draw(Option_t* option = "")
                 virtual Double_t E2Norm() 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()
                            Int_t GetColLwb() const
                            Int_t GetColUpb() const
                     virtual void GetMatrix2Array(Double_t* data, Option_t* option = "") const
          virtual const Double_t* GetMatrixArray() const
                virtual Double_t* GetMatrixArray()
                            Int_t GetNcols() const
                            Int_t GetNoElements() const
                            Int_t GetNrows() const
             virtual const Int_t* GetRowIndexArray() const
                   virtual Int_t* GetRowIndexArray()
                            Int_t GetRowLwb() const
                            Int_t GetRowUpb() const
            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
                         Double_t GetTol() const
            virtual TMatrixDBase& InsertRow(Int_t row, Int_t col, const Double_t* v, Int_t n = -1)
                             void Invalidate()
                  virtual TClass* IsA() const
                           Bool_t IsOwner() const
                   virtual Bool_t IsSymmetric() const
                           Bool_t IsValid() const
                             void MakeValid()
                 virtual Double_t Max() const
                 virtual Double_t Min() const
                    virtual Int_t NonZeros() const
                         Double_t Norm1() const
            virtual TMatrixDBase& NormByDiag(const TVectorD& v, Option_t* option = "D")
                         Double_t NormInf() const
                           Bool_t operator!=(Double_t val) const
                 virtual Double_t operator()(Int_t rown, Int_t coln) const
                virtual Double_t& operator()(Int_t rown, Int_t coln)
                           Bool_t operator<(Double_t val) const
                           Bool_t operator<=(Double_t val) const
                    TMatrixDBase& operator=(const TMatrixDBase&)
                           Bool_t operator==(Double_t val) const
                           Bool_t operator>(Double_t val) const
                           Bool_t operator>=(Double_t val) const
                     virtual void Print(Option_t* name = "") const
            virtual TMatrixDBase& Randomize(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)
                 virtual Double_t RowNorm() const
            virtual TMatrixDBase& SetColIndexArray(Int_t* data)
            virtual TMatrixDBase& SetMatrixArray(const Double_t* data, Option_t* option = "")
            virtual TMatrixDBase& SetRowIndexArray(Int_t* data)
            virtual TMatrixDBase& SetSub(Int_t row_lwb, Int_t col_lwb, const TMatrixDBase& source)
                         Double_t SetTol(Double_t tol)
            virtual TMatrixDBase& Shift(Int_t row_shift, Int_t col_shift)
                     virtual void ShowMembers(TMemberInspector& insp, char* parent)
            virtual TMatrixDBase& Sqr()
            virtual TMatrixDBase& Sqrt()
                     virtual void Streamer(TBuffer& b)
                             void StreamerNVirtual(TBuffer& b)
                 virtual Double_t Sum() const
            virtual TMatrixDBase& UnitMatrix()
            virtual TMatrixDBase& Zero()

### Data Members

        protected:

             Int_t fNrows      number of rows
             Int_t fNcols      number of columns
             Int_t fRowLwb     lower bound of the row index
             Int_t fColLwb     lower bound of the col index
             Int_t fNelems     number of elements in matrix
             Int_t fNrowIndex  length of row index array (= fNrows+1) wich is only used for sparse matrices
          Double_t fTol        sqrt(epsilon); epsilon is smallest number number so that  1+epsilon > 1
            Bool_t fIsOwner    !default kTRUE, when Use array kFALSE

        public:

                       static const enum TMatrixDBase:: kSizeMax
                       static const enum TMatrixDBase:: kWorkMax
           static const TMatrixDBase::EMatrixStatusBits kStatus
          static const TMatrixDBase::EMatrixCreatorsOp1 kZero
          static const TMatrixDBase::EMatrixCreatorsOp1 kUnit
          static const TMatrixDBase::EMatrixCreatorsOp1 kTransposed
          static const TMatrixDBase::EMatrixCreatorsOp1 kInverted
          static const TMatrixDBase::EMatrixCreatorsOp1 kAtA
          static const TMatrixDBase::EMatrixCreatorsOp2 kMult
          static const TMatrixDBase::EMatrixCreatorsOp2 kTransposeMult
          static const TMatrixDBase::EMatrixCreatorsOp2 kInvMult
          static const TMatrixDBase::EMatrixCreatorsOp2 kMultTranspose
          static const TMatrixDBase::EMatrixCreatorsOp2 kPlus
          static const TMatrixDBase::EMatrixCreatorsOp2 kMinus

## Class Description

     Linear Algebra Package
     ----------------------

     The present package implements all the basic algorithms dealing
     with vectors, matrices, matrix columns, rows, diagonals, etc.
     In addition eigen-Vector analysis and several matrix decomposition
     have been added (LU,QRH,Cholesky and SVD) . The decompositions are
     used in matrix inversion, equation solving.

     For a dense matrix, elements are arranged in memory in a ROW-wise
     fashion . For (n x m) matrices where n*m <=kSizeMax (=25 currently)
     storage space is available on the stack, thus avoiding expensive
     allocation/deallocation of heap space . However, this introduces of
     course kSizeMax overhead for each matrix object . If this is an
     issue recompile with a new appropriate value (>=0) for kSizeMax

     Sparse matrices are also stored in row-wise fashion but additional
     row/column information is stored, see TMatrixDSparse source for
     additional details .

     Another way to assign and store matrix data is through Use
     see for instance stressLinear.cxx file .

     Unless otherwise specified, matrix and vector indices always start
     with 0, spanning up to the specified limit-1. However, there are
     constructors to which one can specify aribtrary lower and upper
     bounds, e.g. TMatrixD m(1,10,1,5) defines a matrix that ranges,
     nad that can be addresses, from 1..10, 1..5 (a(1,1)..a(10,5)).

     The present package provides all facilities to completely AVOID
     returning matrices. Use "TMatrixD A(TMatrixD::kTransposed,B);"
     and other fancy constructors as much as possible. If one really needs
     to return a matrix, return a TMatLazy object instead. The
     conversion is completely transparent to the end user, e.g.
     "TMatrixD m = THaarMatrixD(5);" and _is_ efficient.

     Since TMatrixD et al. are fully integrated in ROOT they of course
     can be stored in a ROOT database.

     For usage examples see $ROOTSYS/test/stressLinear.cxx

     Acknowledgements
     ----------------
     1. Oleg E. Kiselyov
      First implementations were based on the his code . We have diverged
      quite a bit since then but the ideas/code for lazy matrix and
      "nested function" are 100% his .
      You can see him and his code in action at http://okmij.org/ftp
     2. Chris R. Birchenhall,
      We adapted his idea of the implementation for the decomposition
      classes instead of our messy installation of matrix inversion
      His installation of matrix condition number, using an iterative
      scheme using the Hage algorithm is worth looking at !
      Chris has a nice writeup (matdoc.ps) on his matrix classes at
       ftp://ftp.mcc.ac.uk/pub/matclass/
     3. Mark Fischler and Steven Haywood of CLHEP
      They did the slave labor of spelling out all sub-determinants
       for Cramer inversion  of (4x4),(5x5) and (6x6) matrices
      The stack storage for small matrices was also taken from them
     4. Roldan Pozo of TNT (http://math.nist.gov/tnt/)
      He converted the EISPACK routines for the eigen-vector analysis to
      C++ . We started with his implementation
     5. Siegmund Brandt (http://siux00.physik.uni-siegen.de/~brandt/datan
      We adapted his (very-well) documented SVD routines

     How to efficiently use this package
     -----------------------------------

     1. Never return complex objects (matrices or vectors)
        Danger: For example, when the following snippet:
            TMatrixD foo(int n)
            {
               TMatrixD foom(n,n); fill_in(foom); return foom;
            }
            TMatrixD m = foo(5);
        runs, it constructs matrix foo:foom, copies it onto stack as a
        return value and destroys foo:foom. Return value (a matrix)
        from foo() is then copied over to m (via a copy constructor),
        and the return value is destroyed. So, the matrix constructor is
        called 3 times and the destructor 2 times. For big matrices,
        the cost of multiple constructing/copying/destroying of objects
        may be very large. *Some* optimized compilers can cut down on 1
        copying/destroying, but still it leaves at least two calls to
        the constructor. Note, TMatLazy (see below) can construct
        TMatrixD m "inplace", with only a _single_ call to the
        constructor.

     2. Use "two-address instructions"
            "void TMatrixD::operator += (const TMatrixD &B);"
        as much as possible.
        That is, to add two matrices, it's much more efficient to write
            A += B;
        than
            TMatrixD C = A + B;
        (if both operand should be preserved,
            TMatrixD C = A; C += B;
        is still better).

     3. Use glorified constructors when returning of an object seems
        inevitable:
            "TMatrixD A(TMatrixD::kTransposed,B);"
            "TMatrixD C(A,TMatrixD::kTransposeMult,B);"

        like in the following snippet (from $ROOTSYS/test/vmatrix.cxx)
        that verifies that for an orthogonal matrix T, T'T = TT' = E.

        TMatrixD haar = THaarMatrixD(5);
        TMatrixD unit(TMatrixD::kUnit,haar);
        TMatrixD haar_t(TMatrixD::kTransposed,haar);
        TMatrixD hth(haar,TMatrixD::kTransposeMult,haar);
        TMatrixD hht(haar,TMatrixD::kMult,haar_t);
        TMatrixD hht1 = haar; hht1 *= haar_t;
        VerifyMatrixIdentity(unit,hth);
        VerifyMatrixIdentity(unit,hht);
        VerifyMatrixIdentity(unit,hht1);

     4. Accessing row/col/diagonal of a matrix without much fuss
        (and without moving a lot of stuff around):

            TMatrixD m(n,n); TVectorD v(n); TMatrixDDiag(m) += 4;
            v = TMatrixDRow(m,0);
            TMatrixColumn m1(m,1); m1(2) = 3; // the same as m(2,1)=3;
        Note, constructing of, say, TMatrixDDiag does *not* involve any
        copying of any elements of the source matrix.

     5. It's possible (and encouraged) to use "nested" functions
        For example, creating of a Hilbert matrix can be done as follows:

        void foo(const TMatrixD &m)
        {
          TMatrixD m1(TMatrixD::kZero,m);
          struct MakeHilbert : public TElementPosActionD {
            void Operation(Double_t &element) { element = 1./(fI+fJ-1); }
          };
          m1.Apply(MakeHilbert());
        }

        of course, using a special method THilbertMatrixD() is
        still more optimal, but not by a whole lot. And that's right,
        class MakeHilbert is declared *within* a function and local to
        that function. It means one can define another MakeHilbert class
        (within another function or outside of any function, that is, in
        the global scope), and it still will be OK. Note, this currently
        is not yet supported by the interpreter CINT.

        Another example is applying of a simple function to each matrix
        element:

        void foo(TMatrixD &m,TMatrixD &m1)
        {
          typedef  double (*dfunc_t)(double);
          class ApplyFunction : public TElementActionD {
            dfunc_t fFunc;
            void Operation(Double_t &element) { element=fFunc(element); }
          public:
            ApplyFunction(dfunc_t func):fFunc(func) {}
          };
          ApplyFunction x(TMath::Sin);
          m.Apply(x);
        }

        Validation code $ROOTSYS/test/vmatrix.cxx and vvector.cxx contain
        a few more examples of that kind.

     6. Lazy matrices: instead of returning an object return a "recipe"
        how to make it. The full matrix would be rolled out only when
        and where it's needed:
           TMatrixD haar = THaarMatrixD(5);
        THaarMatrixD() is a *class*, not a simple function. However
        similar this looks to a returning of an object (see note #1
        above), it's dramatically different. THaarMatrixD() constructs a
        TMatLazy, an object of just a few bytes long. A
        "TMatrixD(const TMatLazy &recipe)" constructor follows the
        recipe and makes the matrix haar() right in place. No matrix
        element is moved whatsoever!

void DoubleLexSort(Int_t n,Int_t *first,Int_t *second,Double_t *data)

void IndexedLexSort(Int_t n,Int_t *first,Int_t swapFirst, Int_t *second,Int_t swapSecond,Int_t *index)

TMatrixDBase& SetMatrixArray(const Double_t *data,Option_t *option)

     Copy array data to matrix . It is assumed that array is of size >= fNelems
     (=)))) fNrows*fNcols
     option indicates how the data is stored in the array:
     option =
              'F'   : column major (Fortran) m[i][j] = array[i+j*fNrows]
              else  : row major    (C)       m[i][j] = array[i*fNcols+j] (default)

Bool_t IsSymmetric() const

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

     Copy matrix data to array . It is assumed that array is of size >= fNelems
     (=)))) fNrows*fNcols
     option indicates how the data is stored in the array:
     option =
              'F'   : column major (Fortran) array[i+j*fNrows] = m[i][j]
              else  : row major    (C)       array[i*fNcols+j] = m[i][j] (default)

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

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

TMatrixDBase& Shift(Int_t row_shift,Int_t col_shift)

     Shift the row index by adding row_shift and the column index by adding
     col_shift, respectively. So [rowLwb..rowUpb][colLwb..colUpb] becomes
     [rowLwb+row_shift..rowUpb+row_shift][colLwb+col_shift..colUpb+col_shift]

TMatrixDBase& Zero()

TMatrixDBase& Abs()

     Take an absolute value of a matrix, i.e. apply Abs() to each element.

TMatrixDBase& Sqr()

     Square each element of the matrix.

TMatrixDBase& Sqrt()

     Take square root of all elements.

TMatrixDBase& UnitMatrix()

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

TMatrixDBase& NormByDiag(const TVectorD &v,Option_t *option)

     option:
     "D"   :  b(i,j) = a(i,j)/sqrt(abs*(v(i)*v(j)))  (default)
     else  :  b(i,j) = a(i,j)*sqrt(abs*(v(i)*v(j)))  (default)

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.

Double_t E2Norm() const

     Square of the Euclidian norm, SUM{ m(i,j)^2 }.

Int_t NonZeros() const

     Compute the number of elements != 0.0

Double_t Sum() const

     Compute sum of elements

Double_t Min() const

     return minimum matrix element value

Double_t Max() const

     return maximum vector element value

void Draw(Option_t *option)

     Draw this matrix using an intermediate histogram
     The histogram is named "TMatrixD" by default and no title

void Print(Option_t *name) const

     Print the matrix as a table of elements .

TMatrixDBase& Apply(const TElementActionD &action)

TMatrixDBase& Apply(const TElementPosActionD &action)

     Apply action to each element of the matrix. To action the location
     of the current element is passed.

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

     randomize matrix element values

void Streamer(TBuffer &R__b)

     Stream an object of class TMatrixDBase.

### Inline Functions

                       void ~TMatrixDBase()
                  Double_t* GetElements()
                       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_nonzero = -1)
                      Int_t GetRowLwb() const
                      Int_t GetRowUpb() const
                      Int_t GetNrows() const
                      Int_t GetColLwb() const
                      Int_t GetColUpb() const
                      Int_t GetNcols() const
                      Int_t GetNoElements() const
                   Double_t GetTol() const
            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)
                   Double_t SetTol(Double_t tol)
                       void Clear(Option_t* option = "")
                       void Invalidate()
                       void MakeValid()
                     Bool_t IsValid() const
                     Bool_t IsOwner() const
              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
              TMatrixDBase& SetSub(Int_t row_lwb, Int_t col_lwb, const TMatrixDBase& source)
              TMatrixDBase& ResizeTo(Int_t nrows, Int_t ncols, Int_t nr_nonzeros = -1)
              TMatrixDBase& ResizeTo(Int_t row_lwb, Int_t row_upb, Int_t col_lwb, Int_t col_upb, Int_t nr_nonzeros = -1)
                   Double_t Determinant() const
                       void Determinant(Double_t& d1, Double_t& d2) const
                   Double_t NormInf() const
                   Double_t Norm1() const
                   Double_t operator()(Int_t rown, Int_t coln) const
                  Double_t& operator()(Int_t rown, Int_t coln)
                     Bool_t operator==(Double_t val) const
                     Bool_t operator!=(Double_t val) const
                     Bool_t operator<(Double_t val) const
                     Bool_t operator<=(Double_t val) const
                     Bool_t operator>(Double_t val) const
                     Bool_t operator>=(Double_t val) const
                    TClass* Class()
                    TClass* IsA() const
                       void ShowMembers(TMemberInspector& insp, char* parent)
                       void StreamerNVirtual(TBuffer& b)
              TMatrixDBase& operator=(const TMatrixDBase&)

Last update: root/matrix:$Name: $:$Id: TMatrixDBase.cxx,v 1.17 2004/10/23 20:19:04 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *