Use examples
============

It is now time to use the containers built
in the :doc:`build_examples` section
to compile some Rat C++ projects.

.. hint::

    - The content of the `rat-containers/work`_ directory is ignored
      by Git so feel free to use it as a playground to experiment.

    - Use the ``--nv`` flag to mount CUDA libraries from host and
      enable GPU acceleration when running calculaitons on HPC.

Rat-Template
------------

A good exercise is to compile the Rat-Template_ repository from
Project-Rat_ group. It defines a simple program to simulate a
solenoid and calculate field values over its mesh.

This can be done with the ``rocky-cuda-project-rat.sif`` image.

- From the root of the repository, enter an interactive shell:

.. code-block:: bash

    singularity shell -B $(pwd):/io singularityCE/rocky-cuda-project-rat.sif
    
    # Optional: colored prompt and aliases
    source env.sh

- Navigate into the ``work`` subdirectory:

.. code-block:: bash

    cd work

- Clone the Rat-Template_ repository and navigate into it:

.. code-block:: bash

    git clone https://gitlab.com/project-rat/rat-template.git
    cd rat-template

- Configure the project using ``cmake``
  following Rat-Template_ instructions,
  or following the definition files:

.. code-block:: bash

    cmake -B build -S . -G Ninja

.. note::

    One might need to modify the ``CMakeLists.txt`` configuration
    file in order to match the versions of the Rat libraries
    installed inside the container (e.g. ``v2.021.1``).

- Build the project:

.. code-block:: bash

    cmake --build build

- Run the project:

.. code-block:: bash

    ./bin/solenoid --od ./mydata

pyRat_
------

The same can be done for the pyRat_ project
with the ``rocky-cuda-pyrat`` image instead
in order to build pyRat_ Python wheels.

- From the root of the repository, enter an interactive shell:

.. code-block:: bash

    singularity shell -B $(pwd):/io singularityCE/rocky-cuda-pyrat.sif
    
    # Optional: colored prompt and aliases
    source env.sh

- Navigate into the ``work`` subdirectory:

.. code-block:: bash

    cd work

- Create a UV_ virtual environment to
  have access to Python and activate it:

.. code-block:: bash

    uv venv venv --python=3.12
    source ./venv/bin/activate

.. note::

    The Python version of this environment is not important.

    The later Python build script will create another
    virtual environment depending on the Python version
    requested to build the wheel for regardless.

- Clone the pyRat_ repository and navigate into it:

.. code-block:: bash

    git clone https://gitlab.com/project-rat-extras/pyrat.git
    cd pyrat

- Run the Python build script:

.. code-block:: bash

    ./scripts/py/make_wheel.py -p 3.14 -s

.. Links
.. _Project-Rat: https://gitlab.com/project-rat
.. _pyRat: https://gitlab.com/project-rat-extras/pyrat
.. _rat-containers/env.sh: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/env.sh
.. _rat-containers/singularityCE: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/singularityCE/
.. _rat-containers/work: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/work
.. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation
.. _Rat-Template: https://gitlab.com/project-rat/rat-template
.. _SingularityCE: https://sylabs.io/singularity/
.. _UV: https://docs.astral.sh/uv/