Checks
======

During its development Rat-vcpkg_ needed to check for some features
when defining ports for Project-Rat_ C++ libraries thus the
appearance of the `rat-vcpkg/checks`_ subdirectory.

It is mainly for repository development purposes.

.. caution::

    The `rat-vcpkg/checks`_ subdirectory is rather unmaintained and
    only serves for ponctual testing to see if anything broke after
    updating ports or packages.

    It is not a real ``tests`` directory so to speak.

Checks for Armadillo
--------------------

The Armadillo_ library implements LAPACK systems for LU
decomposition and some checks are here to ensure their use.

.. note::

    This repository could be enhanced in times to come to make use of
    SuperLU_ repository for more efficient LU decomposition within
    Armadillo.
    
    A ``superlu`` port used to be provided
    but has been abandonned for now.

Checks for CUDA_
----------------

The NVIDIA CUDA_ toolkit can get finicky at times.
Some checks are here to ensure the compiled CUDA_/C++ code can
interact with the NVIDIA drivers installed on the systems.
If not, Rat (in its MLFMM part) will not be able to use CUDA_,
so no GPU acceleration, which would be a shame.

The scripts checks for calls to the ``getDeviceCount`` CUDA_
method, required by Rat-MLFMM to start CUDA_ interaction.
If this fails, an error code should be returned.

With some research, the user should be able to pinpoint the error
message corresponding to the error code and thus take action to fix
the problem. It usually boils down to updating the NVIDIA drivers
on the system.

Checks for OpenBLAS single-threaded
-----------------------------------

Rat using POSIX threads, it needs OpenBLAS_ to be used with one
single thread. This should be ensured with the vcpkg port defined
by this repository. Nonetheless a check is available to ensure the
OpenBLAS instance used only uses one single thread.

Some environment variable such as ``OPENBLAS_NUM_THREADS``
can also dictate the number of threads used depending
on the compilation process.

.. note::

    The base installation sequence for compiling Rat on Windows in
    Rat-Docs_ seems to use the vcpkg_ default OpenBLAS_ port, but I
    did not have such success when trying it on my part, so
    Rat-vcpkg_ ships its own port.

.. Links
.. _Armadillo: https://arma.sourceforge.net/
.. _CUDA: https://developer.nvidia.com/cuda-downloads
.. _OpenBLAS: https://github.com/OpenMathLib/OpenBLAS
.. _Project-Rat: https://gitlab.com/project-rat
.. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _rat-vcpkg/checks: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/checks?ref_type=heads
.. _SuperLU: https://github.com/xiaoyeli/superlu
.. _vcpkg: https://vcpkg.io/en/