𝖧𝖫𝖨𝖡𝗉𝗋𝗈 supports several file formats for reading/writing coordinates, vectors, matrices and files, e.g. Matlab, Harwell/Boeing, MatrixMarket, SAMG, PLY, Gmsh, SurfaceMesh. However, not all features of each file format is fully implemented in 𝖧𝖫𝖨𝖡𝗉𝗋𝗈, e.g. only a single object may be written to Matlab files and only triangular grids are supported in corresponding file formats.

Remarks: All I/O classes will automatically add a corresponding filename suffix, e.g. ".hm" in case of HLIBpro file format, if no suffix is present.

Coordinate I/O

Format	Class	Remarks
HLIBpro	THLibCoordIO	only format with full support
Matlab	TMatlabCoordIO	only dense matrix supported, no bounding box data
MatrixMarket	TMMCoordIO	only array format supported, no bounding box data
SAMG	TSAMGCoordIO	no bounding box data
PLTMG	TPLTMGCoordIO	no bounding box data

In case of the matrix based storage formats (Matlab and MatrixMarket), a matrix is expected where the number of columns corresponds to the dimension of the coordinates and the number of rows to the number of coordinates, respectively.

Only the HLIBpro format stores additional bounding box data for the coordinate set.

Matrix I/O

The following file formats are supported for reading and writing matrices:

Format	Class	Remarks
𝖧𝖫𝖨𝖡𝗉𝗋𝗈 format	THLibMatrixIO	H-, sparse and dense matrices (only format for H-matrices!).
Matlab v5	TMatlabMatrixIO	sparse and dense matrices in single and double precision when writing files, only a single object may be stored limited support for reading from structures support for compression via zlib
Harwell/Boeing Harwell/Rutherford	THBMatrixIO	sparse matrix format no read support for elemental matrices
MatrixMarket	TMMMatrixIO	sparse matrix format only reading supported only unsymmetric matrices supported no support for array format
SAMG	TSAMGMatrixIO	sparse matrix format
HDF5	THDF5MatrixIO	output of dense and low-rank matrices input not yet implemented

All storage classes implement the same basic interface defined by the functions:

virtual void write ( const TMatrix * A, const String & name ) const;

virtual TMatrix * read ( const String & name ) const;

Furthermore, a class for reading/writing matrices with file format autodetection is available (TAutoMatrixIO). In case of reading from a file, the auto detection works by actually looking at the stored data and hence, is very robust in choosing the correct file format. On the other hand, if data output is used, only the file name is used to decide the format. The following rules apply based on the file name extension:

Extension	File Format
hm	HLIBpro format
mat, m	Matlab format
hb, rb, rua, rsa, psa	Harwell/Boeing format
mtx	MatrixMarket format
amg	SAMG format
hdf, h5	HDF5 format

The I/O functions from TAutoMatrixIO are also available in direct from via the functions:

template < typename value_t >
std::unique_ptr< TMatrix< value_t > >
read_matrix   ( const std::string &         filename );
 
template < typename value_t >
void
write_matrix  ( const TMatrix< value_t > *  A,
                const std::string &         filename );

If the file format supports named storage, e.g. Matlab, the corresponding matrix name may be provided by an additional argument:

template < typename value_t >
std::unique_ptr< TMatrix< value_t > >
read_matrix   ( const std::string &  filename,
                const std::string &  matname );
 
template < typename value_t >
std::unique_ptr< TMatrix< value_t > >
void
write_matrix  ( const TMatrix *      A,
                const std::string &  filename,
                const std::string &  matname );

For all other file formats, this parameter will be ignored.

Please note, that for reading files, the value type of the matrix has to be defined when calling the read or read_matrix function as this can not be deduced from the function arguments. With this, the value type of the stored data is also adjusted when reading the matrix, e.g., to single precision of stored in double precision or to complex valued formats of stored as real valued data. Requesting a real valued matrix from a complex valued datafile will generate an error.

auto  A1 = read_matrix< double >( "double_matrix.mat" ); 
auto  A2 = read_matrix< float >( "double_matrix.mat" );                  // read as single prec.
auto  A3 = read_matrix< std::complex< float > >( "double_matrix.mat" );  // read as single prec. complex valued
auto  A4 = read_matrix< double >( "complex_matrix.mat" );                // ERROR

Vector I/O

Grid I/O

Format	Class	Remarks
HLIBpro	THLibGridIO	same format as in HLIB
PLY	TPlyGridIO	only ascii format and triangles supported; vertices may have normal directions
surfacemesh	TSurfMeshGridIO	only 3d with triangles supported
Gmsh v2	TGMSHGridIO
auto detection	TAutoGridIO

All grid IO classes support the interface

std::unique_ptr< TGrid >  read   ( const std::string &  filename ) const;
void                      write  ( const TGrid *        grid,
                                   const std::string &  filename ) const;

for reading and writing grid data.

Furthermore, the functional versions

std::unique_ptr< TGrid >  read_grid   ( const char *   filename );
void                      write_grid  ( const TGrid *  grid,
                                        const char *   filename );

are implemented which rely on TAutoGridIO.

Table of Contents

Coordinate I/O

Matrix I/O

Vector I/O

Grid I/O