===================
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/one../api/onemkl.html#gs.jceywx>`_ 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)

.. 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

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 (experimental). 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_COMPLEX``
     - Enable support for complex numbers.
     - ``ON``
   * - ``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``
     - Generate the test target.
     - ``ON``
   * - ``HIGHFM_SHARED``
     - Create a shared library instead of a static one.
     - ``OFF``

.. note::
    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.

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

To use the library, in the ``CMakeLists.txt`` script in your project, first add the following lines:

.. code-block:: cmake

    set(HighFM_DIR <install directory>/lib/cmake)
    find_package(HighFM)

    # ... #

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

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/detail/ode-solvers.hpp>       // Methods for solving ODEs
    #include <highfm/funm.hpp>              // Methods for evaluating matrix functions

Alternatively, you can include only the headers your project needs, e.g., ``highfm/funm/restarted-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``.