===================
Getting started
===================

Dependencies
-------------------

To build the HighFM library, you must have the following packages installed:

- A C++20 compiler with support to OpenMP (e.g., ``clang``, ``gcc``, etc.)
- `CMake <https://cmake.org/>`_
- The `{fmt} formatting library <https://github.com/fmtlib/fmt>`_
- A BLAS/LAPACK library, for instance, `Intel MKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_ or `AMD AOCL <https://www.amd.com/en/developer/aocl.html>`_
- `HDF5 <https://www.hdfgroup.org/solutions/hdf5/>`_ (optional)
- `NVIDIA CUDA Toolkit <https://developer.nvidia.com/cuda-toolkit>`_ (optional)
- FORTRAN compiler and the GNU FORTRAN standard library (optional)

.. note::
    Intel(R) MKL, AMD AOCL and NVIDIA CUDA are proprietary software and it is the responsibility of users to buy or register for community (free) licenses for their products.

Installation
-------------------
First, clone the source code from the GitLab repository::

    git clone https://gitlab.com/highfm/highfm

Then, build and install the library using the following commands::

    cd highfm
    cmake -B build -DCMAKE_INSTALL_PREFIX=<install directory>
    make -C build/ -j
    make -C build/ install -j

Additionally, you can customize your installation by adding ``-D<option>=<value>`` when calling ``cmake``.

.. list-table:: CMake Options
   :widths: 25 50 25
   :header-rows: 1

   * - Variable
     - Description
     - Default Value
   * - ``HIGHFM_BLAS``
     - Specify the BLAS backend used by HighFM. Options: ``MKL``, ``AOCL``
     - ``MKL``
   * - ``HIGHFM_ENABLE_CUDA``
     - Enable support for NVIDIA CUDA. See :ref:`guide_cuda` for more details.
     - ``OFF``
   * - ``HIGHFM_ENABLE_HDF5``
     - Enable native support for writing/reading HDF5 files. See :ref:`api_hdf5` for more details.
     - ``ON``
   * - ``HIGHFM_ENABLE_ARPACK``
     - Enable the ARPACK package for solving large eigenvalue problems. It requires a FORTRAN compiler and the GNU FORTRAN standard library (``gfortran``). See :ref:`arpack` for more details.
     - ``ON``
   * - ``HIGHFM_ENABLE_COMPLEX``
     - Enable support for complex numbers.
     - ``ON``
   * - ``HIGHFM_ENABLE_PSTL``
     - Enable support for the Parallel STL. It requires the Intel TBB.
     - ``OFF``
   * - ``HIGHFM_USE_32_INDEX``
     - Use 32-bit indexing instead of 64-bit.
     - ``OFF``
   * - ``HIGHFM_DOCS``
     - Generate the documentation.
     - ``OFF``
   * - ``HIGHFM_INSTALL``
     - Install the library.
     - ``OFF``
   * - ``HIGHFM_TEST``
     - Build the test suite.
     - ``ON``
   * - ``HIGHFM_SHARED``
     - Create a shared library instead of a static one.
     - ``OFF``

Usage
-------------------

First, import the HighFM package and link the library against your executable in the ``CMakeLists.txt`` script in your project,

.. code-block:: cmake

    set(HighFM_DIR <install directory>/lib/cmake)
    # set(HIGHFM_ENABLE_CUDA ON)    # Enable the CUDA backend (optional)
    # set(HIGHFM_ENABLE_ARPACK ON)  # Enable ARPACK (optional)
    find_package(HighFM)

    # ... #

    # <target> is the name of your executable
    target_link_libraries(<target> PRIVATE HighFM::HighFM)

    # Optionally, link against the additional modules: HighFM::CUDA and/or HighFM::ARPACK
    # target_link_libraries(<target> PRIVATE <additional modules>)

Then, in your code, include the ``highfm/core.hpp`` header and optionally, any of the following::

    #include <highfm/lapack.hpp>            // LAPACK routines (matrix factorization, least-square, etc.)
    #include <highfm/random.hpp>            // Random number generation and associated routines
    #include <highfm/ode-solvers.hpp>       // Methods for solving ODEs
    #include <highfm/funm.hpp>              // Methods for evaluating matrix functions
    #include <highfm/linsys/*.hpp>          // Methods for solving linear systems
    #include <highfm/extras/*.hpp>          // Other routines (IO with HDF5/MTX, ARPACK, etc.)

Alternatively, you can include only the headers your project needs, e.g., ``highfm/funm/krylov.hpp`` for the Restarted Krylov solver.

**IMPORTANT:**
In your ``main`` function, add the following lines to initialize and clean the environment used by the library (e.g., internal allocations, hardware context, etc.)::

    int main(int argc, char* argv[])
    {
        HighFM::initialize();
        // ... //
        HighFM::terminate();
        return EXIT_SUCCESS;
    }


Documentation
--------------------

To build the documentation, you need the following packages:

- `Doxygen <https://www.doxygen.nl/>`_
- `Sphinx <https://www.sphinx-doc.org/en/master/index.html>`_
- `Breathe plugin <https://www.breathe-doc.org/>`_
- `Sphinx-copybutton plugin <https://sphinx-copybutton.readthedocs.io/en/latest/>`_
- `Sphinx furo theme <https://github.com/pradyunsg/furo.git>`_

And, when building the library, pass ``-DHIGHFM_DOCS=ON`` to ``cmake``. The ``html`` documentation will be generated and copied to ``<install directory>/docs``.

Testing Suite
--------------------

HighFM uses the `Doctest <https://github.com/doctest/doctest>`_ framework for testing. All the necessary files are already included in the repository and do not need to be installed separately.

To built the test suite, pass ``-DHIGHFM_TEST=ON`` to ``cmake``. Then, call ``./build/tests/validate_highfm`` to run the test suite. You can control which tests are executed using the command line options specified `here <https://github.com/doctest/doctest/blob/master/doc/markdown/commandline.md>`_. Likewise, The test module for CUDA can be run with ``./build/tests/validate_highfm_cuda``.