class TUnfold: public TObject

 reset all data members

 delete old results (if any)
 this function is virtual, so derived classes may flag their results
 ad non-valid as well

 set all matrix pointers to zero

 main unfolding algorithm. Declared virtual, because other algorithms
 could be implemented

 Purpose: unfold y -> x
 Data members required:
     fA:  matrix to relate x and y
     fDA: uncorelated (e.g. statistical) errors on fA
     fY:  measured data points
     fX0: bias on x
     fBiasScale: scale factor for fX0
     fV:  inverse of covariance matrix for y
     fLsquared: regularisation conditions
     fTau: regularisation strength
 Data members modified:
     fEinv: inverse of the covariance matrix of x
     fE:    covariance matrix of x
     fX:    unfolded data points
     fAx:   estimate of y from x
     fChi2A:  contribution to chi**2 from y-fAx
     fChi2L:  contribution to chi**2 from L*(x-x0)
     fRhoMax: maximum global correlation coefficient
     fRhoAvg: average global correlation coefficient
 return code:
     fRhoMax   if(fRhoMax>=1.0) then the unfolding has failed!

 Calculate chi**2 and maximum global correlation
 Data members required:
   fY,fAx,fV,fX,fX0,fBiasScale,fTau,fLsquared
 Data members modified:
   fChi2A,fChi2L,fRhoMax,fRhoAvg

 calculate the product v# a v
 where v# is the transposed vector v
    a: a matrix
    v: a vector

 calculate the product of two sparse matrices
    a,b: two sparse matrices, where a.GetNcols()==b.GetNrows()
 this is a replacement for the call
    new TMatrixDSparse(a,TMatrixDSparse::kMult,b);

 multiply a transposed Sparse matrix with another Sparse matrix
    a:  sparse matrix (to be transposed
    b:  sparse matrix
 this is a replacement for the call
    new TMatrixDSparse(TMatrixDSparse(TMatrixDSparse::kTransposed,a),
                       TMatrixDSparse::kMult,b)

 multiply a Sparse matrix with a non-sparse matrix
    a:  sparse matrix
    b:  non-sparse matrix
 this is a replacement for the call
    new TMatrixDSparse(a,TMatrixDSparse::kMult,b);

 a replacement for
     dest += f*src

 get the inverse of a sparse matrix
    A: the original matrix
 this is a replacement of the call
    new TMatrixD(TMatrixD::kInverted, a);
 the matrix inversion is optimized for the case
 where a large submatrix of A is diagonal

 invert the matrix A
 the inversion is done with pre-conditioning
 all rows and columns are normalized to sqrt(abs(a_ii*a_jj))
 such that the diagonals are equal to 1.0
 This type of preconditioning improves the numerival results
 for the symmetric, positive definite matrices which are
 treated here in the context of unfolding

 set up unfolding matrix and initial regularisation scheme
    hist_A:  matrix that describes the migrations
    histmap: mapping of the histogram axes to the unfolding output
    regmode: global regularisation mode
 data members initialized to something different from zero:
    fA: filled from hist_A
    fDA: filled from hist_A
    fX0: filled from hist_A
    fLsquared: filled depending on the regularisation scheme
 Treatment of overflow bins
    Bins where the unfolding input (Detector level) is in overflow
    are used for the efficiency correction. They have to be filled
    properly!
    Bins where the unfolding output (Generator level) is in overflow
    are treated as a part of the generator level distribution.
    I.e. the unfolding output could have non-zero overflow bins if the
    input matrix does have such bins.

 delete all data members

 initialize alternative bias from histogram
 modifies data member fX0

 add regularisation on the size of bin i
    bin: bin number
    scale: size of the regularisation
 return value: number of conditions which have been skipped
 modifies data member fLsquared

 add regularisation on the difference of two bins
   left_bin: 1st bin
   right_bin: 2nd bin
   scale: size of the regularisation
 return value: number of conditions which have been skipped
 modifies data member fLsquared

 add regularisation on the curvature through 3 bins (2nd derivative)
   left_bin: 1st bin
   center_bin: 2nd bin
   right_bin: 3rd bin
   scale_left: scale factor on center-left difference
   scale_right: scale factor on right-center difference
 return value: number of conditions which have been skipped
 modifies data member fLsquared

 set regulatisation on a 1-dimensional curve
   start: first bin
   step:  distance between neighbouring bins
   nbin:  total number of bins
   regmode:  regularisation mode
 return value:
   number of errors (i.e. conditions which have been skipped)
 modifies data member fLsquared

 set regularisation on a 2-dimensional grid of bins
     start: first bin
     step1: distance between bins in 1st direction
     nbin1: number of bins in 1st direction
     step2: distance between bins in 2nd direction
     nbin2: number of bins in 2nd direction
 return value:
   number of errors (i.e. conditions which have been skipped)
 modifies data member fLsquared

 Do unfolding of an input histogram
   tau_reg: regularisation parameter
   input:   input distribution with errors
   scaleBias:  scale factor applied to the bias
 Data members required:
   fA, fX0, fLsquared
 Data members modified:
   those documented in SetInput()
   and those documented in DoUnfold(Double_t)
 Return value:
   maximum global correlation coefficient
   NOTE!!! return value >=1.0 means error, and the result is junk

 Overflow bins of the input distribution are ignored!

 Define the input data for subsequent calls to DoUnfold(Double_t)
   input:   input distribution with errors
   scaleBias:  scale factor applied to the bias
   oneOverZeroError: for bins with zero error, this number defines 1/error.
 Return value: number of bins with bad error
                 +10000*number of unconstrained output bins
         Note: return values>=10000 are fatal errors,
               for the given input, the unfolding can not be done!
 Data members modified:
   fY, fV, fBiasScale, fNdf
 Data members cleared
   fEinv, fE, fX, fAx

 Unfold with given value of regularisation parameter tau
     tau: new tau parameter
 required data members:
     fA:  matrix to relate x and y
     fY:  measured data points
     fX0: bias on x
     fBiasScale: scale factor for fX0
     fV:  inverse of covariance matrix for y
     fLsquared: regularisation conditions
 modified data members:
     fTau and those documented in DoUnfold(void)

 scan the L curve
   nPoint: number of points to scan
   tauMin: smallest tau value to study
   tauMax: largest tau value to study
   lCurve: the L curve as graph
   logTauX: output spline of x-coordinates vs tau for the L curve
   logTauY: output spline of y-coordinates vs tau for the L curve
 return value: the coordinate number (0..nPoint-1) with the "best" choice
     of tau

 retreive unfolding result as histogram
   name:  name of the histogram
   title: title of the histogram
   x0,x1: lower/upper edge of histogram.
          if (x0>=x1) then x0=0 and x1=nbin are used

 retreive bias as histogram
   name:  name of the histogram
   title: title of the histogram
   x0,x1: lower/upper edge of histogram.
          if (x0>=x1) then x0=0 and x1=nbin are used

 retreive unfolding result folded back by the matrix
   name:  name of the histogram
   title: title of the histogram
   y0,y1: lower/upper edge of histogram.
          if (y0>=y1) then y0=0 and y1=nbin are used

 retreive input distribution
   name:  name of the histogram
   title: title of the histogram
   y0,y1: lower/upper edge of histogram.
          if (y0>=y1) then y0=0 and y1=nbin are used

 retreive full matrix of correlation coefficients
   name:  name of the histogram
   title: title of the histogram
   x0,x1: lower/upper edge of histogram.
          if (x0>=x1) then x0=0 and x1=nbin are used

 retreive full error matrix
   name:  name of the histogram
   title: title of the histogram
   x0,x1: lower/upper edge of histogram.
          if (x0>=x1) then x0=0 and x1=nbin are used

 retreive matrix of global correlation coefficients
   name:  name of the histogram
   title: title of the histogram
   x0,x1: lower/upper edge of histogram.
          if (x0>=x1) then x0=0 and x1=nbin are used

 retreive ix of regularisation conditions squared
   name:  name of the histogram
   title: title of the histogram
   x0,x1: lower/upper edge of histogram.
            if (x0>=x1) then x0=0 and x1=nbin are used

 return regularisation parameter

 return maximum global correlation
 Note: return value>1.0 means the unfolding has failed

 return average global correlation

 return chi**2 contribution from matrix A

 return chi**2 contribution from regularisation conditions

 return number of degrees of freedom

 return number of parameters

 return value on x axis of L curve

 return value on y axis of L curve

 get output distribution, cumulated over several bins
   output: output histogram
   binMap: for each bin of the original output distribution
           specify the destination bin. A value of -1 means that the bin
           is discarded. 0 means underflow bin, 1 first bin, ...
        binMap[0] : destination of underflow bin
        binMap[1] : destination of first bin

 get output error matrix, cumulated over several bins
   ematrix: output error matrix histogram
   binMap: for each bin of the original output distribution
           specify the destination bin. A value of -1 means that the bin
           is discarded. 0 means underflow bin, 1 first bin, ...
        binMap[0] : destination of underflow bin
        binMap[1] : destination of first bin

 get global correlation coefficients and inverted error matrix,
 cumulated over several bins
   rhoi: global correlation histogram
   ematrixinv: inverse of error matrix (if pointer==0 it is not returned)
   binMap: for each bin of the original output distribution
           specify the destination bin. A value of -1 means that the bin
           is discarded. 0 means underflow bin, 1 first bin, ...
        binMap[0] : destination of underflow bin
        binMap[1] : destination of first bin

 return value: average global correlation

 get correlation coefficient matrix, cumulated over several bins
   rhoij:  correlation coefficient matrix histogram
   binMap: for each bin of the original output distribution
           specify the destination bin. A value of -1 means that the bin
           is discarded. 0 means underflow bin, 1 first bin, ...
        binMap[0] : destination of underflow bin
        binMap[1] : destination of first bin