Introduce identity matrices into Blaze

[Klaus Iglberger]

Description

Currently Blaze is missing an adaptor for the representation of identity matrices. In the style of the existing adaptors an IdentityMatrix adaptor should be introduced to facilitate the setup and use of identity matrices. Via according test cases the compatibility to the existing Blaze functionality must be ensured.

Tasks

• introduce the IdentityMatrix adaptor for dense and sparse matrices
• restrict the interface such that all class invariants are preserved
• provide a full class documentation
• ensure compatibility to all existing matrix types
• guarantee maximum performance for all operations
  • the multiplication of an identity matrix and another matrix should be a no-op
• add test cases for the entire IdentityMatrix functionality

[rayohauno]

Also, an adaptor for matrices composed of all ones could be useful as well.

[Klaus Iglberger]

Thanks for the proposal!

[Mikhail Katliar]

Life is really hard without IdentityMatrix.

[Klaus Iglberger]

Summary

The feature has been implemented, tested, optimized (including parallelization) and documented as required. It is immediately available via cloning the Blaze repository and will be officially released in Blaze 3.2.

IdentityMatrix

The blaze::IdentityMatrix class template is the representation of an immutable, arbitrary sized identity matrix with NxN elements of arbitrary type. It can be included via the header file

#include <blaze/math/IdentityMatrix.h>

The type of the elements and the storage order of the matrix can be specified via the two template parameters:

template< typename Type, bool SO >
class IdentityMatrix;

• Type: specifies the type of the matrix elements. IdentityMatrix can be used with any non-cv-qualified, non-reference, non-pointer element type.
• SO : specifies the storage order (blaze::rowMajor, blaze::columnMajor) of the matrix. The default value is blaze::rowMajor.

The blaze::IdentityMatrix is the perfect choice to represent an identity matrix:

// Definition of a 3x3 integral row-major identity matrix
blaze::IdentityMatrix<int> A( 3UL );

// Definition of a 6x6 single precision row-major identity matrix
blaze::IdentityMatrix<float,blaze::rowMajor> B( 6UL );

// Definition of a double precision column-major identity matrix with 0 rows and columns
blaze::IdentityMatrix<double,blaze::columnMajor> C;

declid()

The declid()? operation can be used to explicitly declare any matrix or matrix expression as identity matrix:

blaze::DynamicMatrix<double> A, B;
// ... Resizing and initialization

B = declid( A );

Any matrix or matrix expression that has been declared as identity matrix via declid() will gain all the benefits of an identity matrix, which range from reduced runtime checking to a considerable speed-up in computations:

using blaze::DynamicMatrix;
using blaze::DiagonalMatrix;

DynamicMatrix<double> A, B, C;
DiagonalMatrix< DynamicMatrix<double> > D;
// ... Resizing and initialization

isIdentity( declid( A ) );  // Will always return true without runtime effort

D = declid( A );  // Omit any runtime check for A being a diagonal matrix

C = declid( A ) * B;  // Declare the left operand of the matrix multiplication as an
                      // identity matrix, i.e. perform an optimized matrix multiplication

Warning: The declid()? operation has the semantics of a cast: The caller is completely responsible and the system trusts the given information. Declaring a non-identity matrix or matrix expression as identity matrix via the declid()? operation leads to undefined behavior (which can be violated invariants or wrong computation results)!

[Mikhail Katliar]

Hello Klaus, thanks a lot for implementing this useful class!

Does IdentityMatrix store any elements (I guess not)? If not, what is the purpose of having the SO parameter -- does it affect anything?

[Klaus Iglberger]

Hi Mikhail!

You are correct, IdentityMatrix does not store any elements is therefore very cheap to create. Therefore the SO parameter does not affect anything. We decided to add it to provide a uniform template interface across all matrix classes. I hope this helps,

Best regards,

Klaus!