Improve documentation for CompressedMatrix and use of finalize()

[Jan-Michael Tressler]

It looks like the finalize() function needs to be called for all rows in a matrix regardless of if that row has data. There's no note of this in the current documentation. If finalize() is not called (see below) for a particular row, subsequent index() calls return the same value.

Can the documentation be updated to note this?

Thanks, Jan-Michael

blaze::CompressedMatrix<int> M1( 3UL, 5UL );
M1.reserve( 3 );       // Reserving enough space for 3 non-zero elements
M1.append( 0, 1, 1 );  // Appending the value 1 in row 0 with column index 1
M1.finalize( 0 );      // Finalizing row 0
M1.finalize( 1 );      // Finalizing row 1
M1.append( 2, 0, 3 );  // Appending the value 3 in row 2 with column index 0
M1.finalize( 2 );      // Finalizing row 2

[Klaus Iglberger]

Hi!

Thanks for the valuable feedback! Since append() and finalize() representative the most efficient low level interface to fill a sparse matrix the documentation should be absolutely clear. We will improve the documentation for finalize() as soon as possible.

Best regards,

Klaus!

[Klaus Iglberger]

Summary

The documentation of the finalize() function has been improved as required. The improved documentation is immediately available via cloning the Blaze repository and will be officially released in Blaze 3.1.

The finalize() Function

The most efficient way to fill a sparse matrix with elements is a combination of reserve(), append(), and the finalize() function:

// Setup of the compressed row-major matrix
//
//       ( 0 1 0 2 0 )
//   A = ( 0 0 0 0 0 )
//       ( 3 0 0 0 0 )
//
blaze::CompressedMatrix<int> M1( 3UL, 5UL );
M1.reserve( 3 );       // Reserving enough space for 3 non-zero elements
M1.append( 0, 1, 1 );  // Appending the value 1 in row 0 with column index 1
M1.append( 0, 3, 2 );  // Appending the value 2 in row 0 with column index 3
M1.finalize( 0 );      // Finalizing row 0
M1.finalize( 1 );      // Finalizing the empty row 1 to prepare row 2
M1.append( 2, 0, 3 );  // Appending the value 3 in row 2 with column index 0
M1.finalize( 2 );      // Finalizing row 2

Note: The finalize() function has to be explicitly called for each row or column, even for empty ones!

Note: Although append() does not allocate new memory, it still invalidates all iterators returned by the end() functions!