Matrix Storage. More...

#include <rmatrixstorage.h>

Collaboration diagram for RMatrixStorage:
[legend]

Public Member Functions

void Clear (double val=NAN)
 
void Close (void)
 
size_t GetNbCols (void) const
 
size_t GetNbCols (size_t line) const
 
size_t GetNbLines (void) const
 
bool HasInfo (void) const
 
void Init (double val)
 
void InitCol (size_t col, double val)
 
void InitLine (size_t line, double val)
 
void Load (RGenericMatrix &matrix)
 
void Open (const RString &baseuri, RGenericMatrix::tType type)
 
template<class S >
void PrintSparse (S &stream, const char *format="%E")
 
double Read (size_t i, size_t j)
 
void ReadInfo (size_t posinfo, char *buffer, size_t nb)
 
 RMatrixStorage (void)
 
void Save (const RGenericMatrix &matrix)
 
void VerifySize (size_t newlines, size_t newcols, bool fill=false, double val=NAN)
 
void Write (size_t i, size_t j, double val)
 
void WriteInfo (size_t posinfo, const char *buffer, size_t nb)
 
 ~RMatrixStorage (void)
 

Private Member Functions

void ExtendLowerFile (size_t newlines, size_t newcols, bool fill, double val)
 
void ExtendSparse (size_t newlines, size_t newcols)
 
void ExtendUpperFile (size_t newlines, size_t newcols, bool fill, double val)
 
size_t GetLowerPos (size_t i, size_t j)
 
size_t GetMaxDim (void) const
 
size_t GetUpperPos (size_t i, size_t j)
 
void ModifyFull (size_t newlines, size_t newcols, bool fill, double val)
 
double ReadMax (size_t i, size_t j)
 
double ReadSparse (size_t i, size_t j)
 
void ReCreateLowerFile (size_t newlines, size_t newcols, double val)
 
void ReCreateSparse (size_t newlines, size_t newcols, bool keepnull)
 
void ReCreateUpperFile (size_t newlines, size_t newcols, double val)
 
void SaveFull (const RGenericMatrix &matrix)
 
template<class cMatrix , class cVector , class cValue >
void SaveSparse (const RGenericMatrix &matrix)
 
void TruncLowerFile (size_t newlines, size_t newcols)
 
void TruncUpperFile (size_t newlines, size_t newcols)
 
void WriteMax (size_t i, size_t j, double val)
 
void WriteSparse (size_t i, size_t j, double val)
 

Private Attributes

RString BaseURI
 
RBinaryFile File1
 
RBinaryFile File2
 
RBinaryFile Index
 
size_t LasCol
 
size_t LastLine
 
bool LastWrite
 
bool Max
 
size_t NbCols
 
size_t NbLines
 
bool Sparse
 
RGenericMatrix::tType Type
 
bool Upper
 

Detailed Description

Matrix Storage.

The RMatrixStorage provides a class to store a matrix and retrieve a particular element.

For a full matrix (all elements must be stored), maximum 3 files are needed:

  1. File ".lower" contains the lower triangular part of the matrix. For a $4\cdot 4$ matrix, the values stored are (0,0), (1,0), (1,1), (2,0), (2,1), (2,2), (3,0), (3,1), (3,2) and (3,3).
  2. File ".upper" contains the upper triangular part of the matrix, For a $4\cdot 4$ matrix, the values stored are (0,1), (0,2), (1,2), (0,3), (1,3) and (2,3).
  3. File ".info" contains the size of the matrix and other information that the developer may add.

For a sparse matrix, the storage adapts a method proposed by Knuth. Two files are needed:

  1. File ".rec" contains the non-null elements. In fact, it stores a series of records composed from (value,line,column,next line,next column).
  2. File ".info" contains the size of the matrix, the positions of the first and the last elements of each line and column and other information that the developer may add. In the case of an ascending ordered sparse matrix, the file contains also the number of values associated with each line.

Of course, once the matrix storage is created, it is not possible to change its type (full, sparse or ascending ordered sparse). If done, at best, the values manipulated are wrong, but mostly a generation will be generated after a few calls.

Remarks
The information of ".info" are removed if the size of the matrix is changed and the matrix is sparse. Therefore, in this case, the information should be loaded first, and store again before the file is closed after the modification.

Constructor & Destructor Documentation

RMatrixStorage ( void  )

Construct the storage.

~RMatrixStorage ( void  )

Destructor.

Member Function Documentation

void Open ( const RString baseuri,
RGenericMatrix::tType  type 
)

Open the storage.

Parameters
baseuriBase URI.
typeType of the matrix.
void Close ( void  )

Close the storage.

size_t GetLowerPos ( size_t  i,
size_t  j 
)
private

Compute the position if a given element in the lower part of a full matrix.

Parameters
iLine.
jColumn.
Returns
Position of the element.

To compute ther size of the lower part of a full matrix $n \cdot m$, you must use:

size_t Size=(GetLowerPos(n-1,m-1)+1)*sizeof(double).
size_t GetUpperPos ( size_t  i,
size_t  j 
)
private

Compute the position if a given element in the upper part of a full matrix.

Parameters
iLine.
jColumn.
Returns
Position of the element.

To compute ther size of the upper part of a full matrix $n \cdot m$, you must use:

size_t Size=(GetUpperPos(n-1,m-1)+1)*sizeof(double).
size_t GetMaxDim ( void  ) const
private

Get the maximal dimension of the matrix.

size_t GetNbLines ( void  ) const

Get the number of lines in the matrix.

size_t GetNbCols ( void  ) const

Get the number of columns in the matrix.

size_t GetNbCols ( size_t  line) const

For full and sparse matrices, the method returns the number of column of the matrix. For an ascending ordered sparse matrix, the method returns the number of elements associated with that line (which may be smaller that the number of columns of the matrix).

Parameters
lineLine.
Returns
the number of columns in the matrix at a given line.
void Clear ( double  val = NAN)

Clear the files. In practice, when the files correspond to full matrices, a default value is assigned.

Parameters
valDefault value.
void Init ( double  val)

Set the elements to a given value. In the case of sparse matrices, this may lead to the creation of a high number of records when the value is not null.

Parameters
valValue to set.
void InitLine ( size_t  line,
double  val 
)

Set the elements corresponding to a line to a given value. In the case of sparse matrices, this may lead to the creation of a high number of records when the value is not null.

Parameters
lineLine of the elements.
valValue to set.
void InitCol ( size_t  col,
double  val 
)

Set the elements corresponding to a column to a given value. In the case of sparse matrices, this may lead to the creation of a high number of records when the value is not null.

Parameters
colColumns of the elements.
valValue to set.
void ReCreateLowerFile ( size_t  newlines,
size_t  newcols,
double  val 
)
private

Method called to re-created the lower file of a full matrix.

Parameters
newlinesNew lines.
newcolsNew cols.
valValue used eventually to fill the elements created.
void ReCreateUpperFile ( size_t  newlines,
size_t  newcols,
double  val 
)
private

Method called to re-created the upper file of a full matrix.

Parameters
newlinesNew lines.
newcolsNew cols.
valValue used eventually to fill the elements created.
void TruncLowerFile ( size_t  newlines,
size_t  newcols 
)
private

Method called to truncate or extend the upper file of a full matrix.

Parameters
newlinesNew line number.
newcolsNew column number.
void TruncUpperFile ( size_t  newlines,
size_t  newcols 
)
private

Method called to truncate or extend the upper file of a full matrix.

Parameters
newlinesNew line number.
newcolsNew column number.
void ExtendLowerFile ( size_t  newlines,
size_t  newcols,
bool  fill,
double  val 
)
private

Method called to truncate or extend the upper file of a full matrix.

Parameters
newlinesNew line number.
newcolsNew column number.
fillElements must be filled with a value.
valValue used eventually to fill the elements created.
void ExtendUpperFile ( size_t  newlines,
size_t  newcols,
bool  fill,
double  val 
)
private

Method called to truncate or extend the upper file of a full matrix.

Parameters
newlinesNew line number.
newcolsNew column number.
fillElements must be filled with a value.
valValue used eventually to fill the elements created.
void ModifyFull ( size_t  newlines,
size_t  newcols,
bool  fill,
double  val 
)
private

Modify the files of a full matrix of a given size. Depending of the cases, the files are truncated, extended or recreated.

Parameters
newlinesNew line number.
newcolsNew column number.
fillElements must be filled with a value.
valValue used eventually to fill the elements created.
void ReCreateSparse ( size_t  newlines,
size_t  newcols,
bool  keepnull 
)
private

Recreate the file of a sparse matrix of a given size.

Parameters
newlinesNew line number.
newcolsNew column number.
fillElements must be filled with a value.
valValue used eventually to fill the elements created.
keepnullKeep null elements ?
void ExtendSparse ( size_t  newlines,
size_t  newcols 
)
private

Extend the files of a sparse matrix of a given size. In practice, the method updates the indexes in the '.info' files.

Parameters
newlinesNew line number.
newcolsNew column number.
fillElements must be filled with a value.
valValue used eventually to fill the elements created.
void VerifySize ( size_t  newlines,
size_t  newcols,
bool  fill = false,
double  val = NAN 
)

Verify if the matrix has a given size, and modify the files if necessary:

  • When a full matrix is reduced, the files are either recreated or reduced.
  • When a full matrix is extended, the files are either recreated or extended.
  • When a sparse matrix is reduced, a new file is re-created and the unnecessary elements are removed.
  • When a sparse matrix is extended, no values are filled.

Since the operation of modifying the size of a matrix can be costly, this method should be use carefully. The ideal solution is to call this method before a read or write call, or at the end of a program.

Remarks
Actually, a very conservative approach is implemented that may lead to unnecessary recreation of files for full matrices.
Parameters
newlinesNew line number.
newcolsNew column number.
fillElements must be filled with a value.
valValue used eventually to fill the elements created.
void Load ( RGenericMatrix matrix)

Load a matrix.

Warning
If the matrix is a sparse one, the values read are added to the matrix.
Parameters
matrixmatrix.
void SaveFull ( const RGenericMatrix matrix)
private

Save a full matrix.

Parameters
matrixmatrix.
void SaveSparse ( const RGenericMatrix matrix)
private

Save a sparse matrix.

Template Parameters
cMatrixClass of the sparse matrix.
cVectorClass of the sparse vector.
cValueClass of a value of sparse vectors and matrices.
Parameters
matrixmatrix.
void Save ( const RGenericMatrix matrix)

Save a matrix.

Parameters
matrixmatrix.
double ReadSparse ( size_t  i,
size_t  j 
)
private

Read a value of a given element in a sparse matrix.

Parameters
iLine of the element.
jColumn of the element.
double ReadMax ( size_t  i,
size_t  j 
)
private

Read a value of a given element in a sparse matrix.

Parameters
iLine of the element.
jColumn of the element.
double Read ( size_t  i,
size_t  j 
)

Read a value of a given element.

In the case of an ascending ordered sparse matrix, $j$ represents the $jth$ greater elements of line $i$.

Parameters
iLine of the element.
jColumn of the element. For an ascending ordered sparse matrix, this parameter is the index at that line (and not the identifier).
void WriteSparse ( size_t  i,
size_t  j,
double  val 
)
private

Write a value of a given element in a sparse matrix. If an old value is already present, a null value replaces the old value in the file.

In the case of an ascending ordered sparse matrix, $j$ doesn't represent the column of the element in the matrix, but the identifier associated to a particular value of line $$i$$.

Parameters
iLine of the element.
jColumn of the element.
valValue to write.
void WriteMax ( size_t  i,
size_t  j,
double  val 
)
private

Write a value of a given element in a sparse matrix. If an old value is already present, a null value replaces the old value in the file.

Parameters
iLine of the element.
jColumn of the element.
valValue to write.
void Write ( size_t  i,
size_t  j,
double  val 
)

Write a value of a given element. If the matrix is sparse, the method first verify if the value is already stored.

If the matrix is sparse and an old value is already present, a null value replaces the old value in the file.

For an ascending ordered sparse matrix, if the number of elements for that line equals the size of the matrix, the value is only inserted if another value of that line is smaller (this latest value will then be removed).

Parameters
iLine of the element.
jColumn of the element. For an ascending ordered sparse matrix, this parameter is the identifier of element (and not its index in the line).
valValue to write.
void ReadInfo ( size_t  posinfo,
char *  buffer,
size_t  nb 
)

Read a given information.

Parameters
posinfoIdentifier of the information.
bufferBuffer that will hold the information (must be allocated).
nbNumber of bytes of the information.

Here is an example of reading information an information starting at 10 which is a double:

...
double nb; // Information to read
Storage.ReadInfo(10,static_cast<char*>(&nb),sizeof(double));
void WriteInfo ( size_t  posinfo,
const char *  buffer,
size_t  nb 
)

Write a given information.

Parameters
posinfoPosition of the information.
bufferBuffer holding the information.
nbNumber of bytes of the information.

Here is an example of writing information an information starting at 10 which is a double:

...
double nb(3.5); // Information to write
Storage.WriteInfo(10,static_cast<char*>(&nb),sizeof(double));
bool HasInfo ( void  ) const

See if there are some information contained in the ".info" file.

void PrintSparse ( S &  stream,
const char *  format = "%E" 
)

Print the content of the file representing a sparse matrix in a human-comprehensible format. In practice, the method prints :

  • The index for the lines and the columns.
  • All the records representing the value of the matrix.

It is useful for debugging purposes.

Template Parameters
SStream class that implements the << operator.
Parameters
streamStream.
formatFormat used to print the number. By default, it is "%E".

Member Data Documentation

RBinaryFile File1
private

File containing the ".lower" or the ".rec" part.

RBinaryFile File2
private

File containing the ".upper" part if necessary.

bool Upper
private

An upper part of the matrix is managed.

RBinaryFile Index
private

Index file.

RString BaseURI
private

Base URI.

size_t NbLines
private

Number of lines of the matrix.

size_t NbCols
private

Number of columns of the matrix.

size_t LastLine
private

Line of the last element accessed.

size_t LasCol
private

Column of the last element accessed.

bool LastWrite
private

Last element accessed was write (true) or read (false).

RGenericMatrix::tType Type
private

Type of the matrix stored.

bool Sparse
private

Sparse version of the storage ?

bool Max
private

Max version of the storage ?