Input/Output¶
Printing to the Terminal¶
Any object from the HighFM library can be printed to the terminal using the fmt::print()
from the {fmt} library. Likewise, they can formatted and then stored as a string
by using the fmt::format()
routine. You can customize how the entries of the container are displayed on the screen by using the format options as specified in the Format Syntax Guide.
Matrix<float> mat(3, 3);
mat(0, 0) = 11; mat(0, 1) = 12; mat(0, 2) = 13;
mat(1, 0) = 21; mat(1, 1) = 22; mat(1, 2) = 23;
mat(2, 0) = 31; mat(2, 1) = 32; mat(2, 2) = 33;
fmt::print("Matrix:\n{}\n", mat);
Vector<double> vec(4);
vec(0) = 1.2; vec(1) = 2.4; vec(2) = 3.6; vec(3) = 4.8;
fmt::print("Vector:\n{:>+9.3f}\n", vec);
Output:
Matrix:
[[ 11 12 13 ]
[ 21 22 23 ]
[ 31 32 33 ]]
Vector:
[ +1.200 +2.400 +3.600 +4.800 ]
If the object is large, not all entries will be printed into the terminal. You can control the number of rows, columns and nonzeros that will be displayed by setting the following global print options:
HighFM::format_options::nrows = 10; // Default: 5
HighFM::format_options::ncols = 20; // Default: 5
HighFM::format_options::nonzeros = 100; // Default: 5
For displaying all entries, you can set it to a negative value.
MTX Files¶
Matrix Market Format (MTX) was created by the U.S. National Institute of Standards and Technology (NIST) for facilitating the exchange of matrix data over the web. The sparse matrices are stored in the coordinate format, i.e., only nonzero entries are provided and the coordinates of each nonzero entry are given explicitly. It supports four different data types — pattern
(i.e., all nonzero entries are equal to 1
), integer
, real
or complex
— and symmetry structures — general
, symmetric
, skew-symmetric
and hermitian
. If the matrix is symmetric, the file only contains the lower triangular part of the matrix (i.e., the entries on or below the main diagonal), reducing the file size. Comments can be included between the header and the matrix parameters and must begin with the %
symbol.
In summary, the MTX file has the following format:
%%MatrixMarket matrix <matrix format> <data type> <symmetry>
% <comments>
% ...
<number of rows> <number of columns> <number of nonzeros>
<nonzero entry 1>
<nonzero entry 2>
...
If pattern
is specified, only the position of the nonzeros entries is provided (i.e., <row> <column>
). Otherwise, each nonzero entry is stored as a triplet: <row> <column> <value>
. The nonzero entries do not need to be sorted. To read and write data to MTX files, you can use the read_mtx()
and write_mtx()
, respectively.
HDF5 Files¶
The Hierarchical Data Format 5 (HDF5) is an open-source file format for storing large, heterogeneous data and the associated metadata in a tree-like structure. To improve performance and reduce file size, the HDF5 files often employ some form of compression. Note that -DHIGHFM_ENABLE_HDF5=ON
must be passed to cmake
during the installation to enable the native support for HDF5.
HighFM provides two ways for writing and reading data from/to HDF5 files. The first consists on a set of high-level routines — write_hdf5()
and read_hdf5()
— to directly read/write data to the HDF5 file from one or more HighFM objects. While the second consist on a set of C++ objects in the hdf5
namespace that represent the HDF5 files, groups and datasets to allow greater control in how the data is organized.
The following code creates an HDF5 File test.h5
, then writes a 5x5 matrix A
as mat
to the file, vector v
as a vector to group G1
and u
as u
to the “root” group. A similar procedure can be done for reading HDF5 files.
Matrix<int> A(5, 5);
Vector<double> v(200), u(100);
//...//
hdf5::File file("test.h5", "w");
write_hdf5(file, "mat", A, "G1/vec", v);
file.root().write("u", u);
API: