Module ``pyrat``
================

The pyRat_ Python_ module ``pyrat``
is split into several submodules.

Python and C++
--------------

The ``pyrat.rat`` submodule is the only submodule using C++.
All other submodules are written in pure Python_
code within the `pyrat/src/pyrat`_ directory and are
mostly helpers and tools for comfort using ``pyrat.rat``.

CLI : ``pyrat.cli``
-------------------

The ``pyrat.cli`` command line interface
submodule is used as a simple entry point
for generating pyRat_ examples defined in
the `pyrat/src/pyrat/examples`_ directory.

.. code-block::

    pyrat -e              # list all available examples
    pyrat -e moon         # generate rat/dm/moon.py example
    pyrat -e dmsh*        # generate rat/mdl/dmesher/{dmshcoil.py, dmshyoke1.py, dmshyoke2.py} examples
    pyrat -e mdl/**       # generate all Rat-Models examples
    pyrat -e rat-template # generate rat/rat-template/rat-template.py example
    pyrat -e **           # generate all examples

Examples will be stored under a generated
``./examples`` directory like so:

.. code-block:: text

    examples/
    ├── rat/
        ├── dm/
        ├── fmm/
        ├── mat/
        ├── mdl/
        |   ├── asbuild/
        |   ├── dmesher/
        |   ├── nlsolver/
        |   ├── other/
        |   ├── simple/
        ├── rat-template/

Color : ``pyrat.col``
---------------------

The ``pyrat.col`` color submodule can be
used for simple message formatting, mimicing
terminal color definitions from the
`rat-common/include/typedefs.hh`_ header
file with some additional escape sequences.

.. code-block:: python

    from pyrat.col import *
    print(f"{KYEL}WARNING:{KNRM} Colors are nice.")

Log : ``pyrat.log``
-------------------

The ``pyrat.log`` logging submodule defines a simple base config
for users to easily setup a logger with console and file handlers.

.. code-block:: python

    # Import pyRat logging module
    import pyrat.log
    # Get logger instance with basic configuration (console + file handlers)
    plg = pyrat.log.config(__file__)
    # Get logger instance with basic configuration (console handler only)
    plg = pyrat.log.config(__file__, file_h=0)
    # Get logger instance with basic configuration (file handler only)
    plg = pyrat.log.config(__file__, console_h=0)

Python_ offers a nice standard ``logging`` module that is
very flexible, although easy to make complex rather quickly.

Meta : ``pyrat.meta``
---------------------

The ``pyrat.meta`` metadata submodule gathers
information about the ``pyrat`` Python_ module
such as versions of Rat or CUDA, ASCII logos and more.

Rat : ``pyrat.rat``
-------------------

The ``pyrat.rat`` core module contains the
binding to Rat C++ libraries made with pybind11_.
It is of course the heart of the magnetic simulations
and bridges Python_ code to the original C++ Code.

.. Links
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _Project-Rat: https://gitlab.com/project-rat
.. _pybind11: https://github.com/pybind/pybind11
.. _pyRat: https://gitlab.com/project-rat-extras/pyrat
.. _pyrat/src/pyrat: https://gitlab.com/project-rat-extras/pyrat/-/tree/main/src/pyrat?ref_type=heads
.. _pyrat/src/pyrat/examples: https://gitlab.com/project-rat-extras/pyrat/-/tree/main/src/pyrat/examples?ref_type=heads
.. _Python: https://www.python.org/
.. _rat-common/include/typedefs.hh: https://gitlab.com/Project-Rat/rat-common/-/blob/master/include/typedefs.hh
.. _Rat-Containers: https://gitlab.com/project-rat-extras/rat-containers
.. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _rat-vcpkg/ports: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/ports?ref_type=heads
.. _vcpkg: https://vcpkg.io/en/