Blaze 3.9
Classes | Functions
MatrixSerializer.h File Reference

Serialization of dense and sparse matrices. More...

#include <blaze/math/Aliases.h>
#include <blaze/math/constraints/Matrix.h>
#include <blaze/math/dense/DynamicMatrix.h>
#include <blaze/math/Exception.h>
#include <blaze/math/expressions/DenseMatrix.h>
#include <blaze/math/expressions/SparseMatrix.h>
#include <blaze/math/expressions/Matrix.h>
#include <blaze/math/serialization/TypeValueMapping.h>
#include <blaze/math/sparse/CompressedMatrix.h>
#include <blaze/math/typetraits/IsDenseMatrix.h>
#include <blaze/math/typetraits/IsResizable.h>
#include <blaze/math/typetraits/IsRowMajorMatrix.h>
#include <blaze/util/Assert.h>
#include <blaze/util/EnableIf.h>
#include <blaze/util/Types.h>
#include <blaze/util/typetraits/IsNumeric.h>

Go to the source code of this file.

Classes

class  blaze::MatrixSerializer
 Serializer for dense and sparse matrices. More...
 

Functions

template<typename Archive , typename MT , bool SO>
void blaze::serialize (Archive &archive, const Matrix< MT, SO > &mat)
 Serializes the given matrix and writes it to the archive. More...
 
template<typename Archive , typename MT , bool SO>
void blaze::deserialize (Archive &archive, Matrix< MT, SO > &mat)
 Deserializes a matrix from the given archive. More...
 

Detailed Description

Serialization of dense and sparse matrices.

Copyright (C) 2012-2020 Klaus Iglberger - All Rights Reserved

This file is part of the Blaze library. You can redistribute it and/or modify it under the terms of the New (Revised) BSD License. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the names of the Blaze development group nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

◆ deserialize()

template<typename Archive , typename MT , bool SO>
void blaze::deserialize ( Archive archive,
Matrix< MT, SO > &  mat 
)

Deserializes a matrix from the given archive.

Parameters
archiveThe archive to be read from.
matThe matrix to be deserialized.
Returns
void
Exceptions
std::runtime_errorMatrix could not be deserialized.

The deserialize() function converts the portable, binary representation contained in the given archive into the given matrix type. For a detailed example that demonstrates the (de-)serialization process of matrices, see the serialize() function.

◆ serialize()

template<typename Archive , typename MT , bool SO>
void blaze::serialize ( Archive archive,
const Matrix< MT, SO > &  mat 
)

Serializes the given matrix and writes it to the archive.

Parameters
archiveThe archive to be written.
matThe matrix to be serialized.
Returns
void
Exceptions
std::runtime_errorMatrix could not be serialized.

The serialize() function converts the given matrix into a portable, binary representation. The following example demonstrates the (de-)serialization process of matrices:

// Serialization of both matrices
{
// ... Resizing and initialization
// Creating an archive that writes into a the file "matrices.blaze"
blaze::Archive<std::ofstream> archive( "matrices.blaze" );
// Serialization of both matrices into the same archive. Note that D lies before S!
archive << D << S;
}
// Reconstitution of both matrices
{
// ... Resizing and initialization
// Creating an archive that reads from the file "matrices.blaze"
blaze::Archive<std::ofstream> archive( "matrices.blaze" );
// Reconstituting the former D matrix into D1. Note that it is possible to reconstitute
// the matrix into a differrent kind of matrix (StaticMatrix -> DynamicMatrix), but that
// the type of elements has to be the same.
archive >> D1;
// Reconstituting the former S matrix into D2. Note that is is even possible to reconstitute
// a sparse matrix as a dense matrix (also the reverse is possible) and that a column-major
// matrix can be reconstituted as row-major matrix (and vice versa). Note however that also
// in this case the type of elements is the same!
archive >> D2
}
Binary archive for the portable serialization of data.
Definition: Archive.h:140
Efficient implementation of a compressed matrix.
Definition: CompressedMatrix.h:239
Efficient implementation of a dynamic matrix.
Definition: DynamicMatrix.h:242
Efficient implementation of a fixed-sized matrix.
Definition: StaticMatrix.h:249
constexpr bool rowMajor
Storage order flag for row-major matrices.
Definition: StorageOrder.h:71
constexpr bool columnMajor
Storage order flag for column-major matrices.
Definition: StorageOrder.h:99

As the example demonstrates, the matrix serialization offers an enormous flexibility. However, several actions result in errors:

  • matrices cannot be reconstituted as vectors (and vice versa)
  • the element type of the serialized and reconstituted matrix must match, which means that on the source and destination platform the general type (signed/unsigned integral or floating point) and the size of the type must be exactly the same
  • when reconstituting a StaticMatrix, the number of rows and columns must match those of the serialized matrix

In case an error is encountered during (de-)serialization, a std::runtime_exception is thrown.