Arithmetic operations on symmetric matrices in docs

[Marcin Copik]

I have a problem with the documentation of symmetric matrices: https://bitbucket.org/blaze-lib/blaze/wiki/Symmetric%20Matrices#!arithmetic-operations

The claim here is that you can perform usual matrix operations (addition, subtraction, multiplication) on a combination of symmetric and regular matrix and save results into a symmetric matrix, e.g.

E = A + B;
F = A * D;

where F and D are symmetric, A is not. I think it's incorrect and such operations do not preserve symmetry of a matrix. I checked if it may lead to incorrect results but it seems to be only a problem with documentation: https://github.com/mcopik/cpp_samples/blob/master/lin_alg/blaze_symmetric_mult.cpp#L55

In this particular example we can expect an exception notifying about invalid assignment to a symmetric matrix.

[Klaus Iglberger]

Hi Marcin!

Thanks a lot for pointing out this inaccuracy. The documentation is not wrong since in Blaze it is possible to assign any kind of matrix to a symmetric matrix. However, it unfortunately fails to mention that this assignment involves a runtime check, which in case the assigned matrix is not symmetric throws an exception. We will improve the examples to make it clear, which assignments involve a runtime check and which assignments only involve a compile time check.

Again, thanks a lot for your help,

Best regards,

Klaus!

[Klaus Iglberger]

Summary

The examples for arithmetic operations involving a SymmetricMatrixhave been updated. The updated class documentation and tutorial are immediately available via cloning the Blaze repository and will be officially released in Blaze 3.1. The wiki will be updated during the release of Blaze 3.1.

Arithmetic Operations

A SymmetricMatrix matrix can participate in numerical operations in any way any other dense or sparse matrix can participate. It can also be combined with any other dense or sparse vector or matrix. The following code example gives an impression of the use of SymmetricMatrix within arithmetic operations:

using blaze::SymmetricMatrix;
using blaze::DynamicMatrix;
using blaze::HybridMatrix;
using blaze::StaticMatrix;
using blaze::CompressedMatrix;
using blaze::rowMajor;
using blaze::columnMajor;

DynamicMatrix<double,rowMajor> A( 3, 3 );
CompressedMatrix<double,rowMajor> B( 3, 3 );

SymmetricMatrix< DynamicMatrix<double,rowMajor> > C( 3 );
SymmetricMatrix< CompressedMatrix<double,rowMajor> > D( 3 );

SymmetricMatrix< HybridMatrix<float,3UL,3UL,rowMajor> > E;
SymmetricMatrix< StaticMatrix<float,3UL,3UL,columnMajor> > F;

E = A + B;     // Matrix addition and assignment to a row-major symmetric matrix (includes runtime check)
F = C - D;     // Matrix subtraction and assignment to a column-major symmetric matrix (only compile time check)
F = A * D;     // Matrix multiplication between a dense and a sparse matrix (includes runtime check)

C *= 2.0;      // In-place scaling of matrix C
E  = 2.0 * B;  // Scaling of matrix B (includes runtime check)
F  = C * 2.0;  // Scaling of matrix C (only compile time check)

E += A - B;    // Addition assignment (includes runtime check)
F -= C + D;    // Subtraction assignment (only compile time check)
F *= A * D;    // Multiplication assignment (includes runtime check)

Note that it is possible to assign any kind of matrix to a symmetric matrix. In case the matrix to be assigned is not symmetric at compile time, a runtime check is performed.