Use
===

The previous :doc:`../build/index` section showed
how to build a pyRat_ ``pyrat-....whl`` `Python wheel`_.

This section describes how to use such wheels in order to
install it into a Python_ virtual environment for better
isolation, getting started with pyRat_ and how to define
magnetic simulations with it.

.. code-block:: bash

    python -m venv venv
    source ./venv/bin/activate
    python -m pip install ./pyrat-....whl

Once installed into a Python_ environment,
one can import pyRat_ Python_ module to
have access to all submodules defined
in the previous :doc:`../module` section.

The general use case import statement is the following:

.. code-block:: python

    # Rat namespaces and objects (e.g. rat.cmn.Gauss, rat.mdl.Model, ...)
    from pyrat import rat

    # Colors into global namespace (e.g. KRED, KYEL, KNRM, ...)
    from pyrat.col import *

Rat can now be invoked from Python_ code through
the ``rat`` submodule to run magnetic simulations,
and the ``col`` submodule exposes ANSI escapes
sequences for colors to the global namespace
for easy message formatting when logging results.

Inspiration can be drawn from the several pyRat_
examples or directly from the original Project-Rat_
repositories and their examples subdirectories.

.. caution::

    pyRat_ is still under active development and might lack some
    functionalities from original Rat C++ libraries for now.

.. pyRat: Use table of contents
.. toctree::
   :maxdepth: 2
   :caption: PYRAT USE CONTENTS

   install
   examples
   rat

.. Links
.. _Project-Rat: https://gitlab.com/project-rat
.. _pybind11: https://github.com/pybind/pybind11
.. _pyRat: https://gitlab.com/project-rat-extras/pyrat
.. _Python: https://www.python.org/
.. _Python wheels: https://pythonwheels.com/
.. _Python wheel: https://pythonwheels.com/
.. _Rat-Containers: https://gitlab.com/project-rat-extras/rat-containers
.. _Rat-GUI: https://rat-gui.com/
.. _Rat-Models: https://gitlab.com/project-rat/rat-models
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _UV: https://github.com/astral-sh/uv