===============
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 <https://github.com/fmtlib/fmt>`_. 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 <https://fmt.dev/latest/syntax.html>`_.

.. code:: cpp

    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:

.. code::

    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:

.. code:: cpp

    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) <https://math.nist.gov/MatrixMarket/formats.html>`_ 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 <https://www.hdfgroup.org/solutions/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.

.. code::

    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:**

.. toctree::
    :maxdepth: 2

    ../api/hdf5