Introduction
============

pyRat_ is set a set of bindings for Rat C++ libraries.
It uses the pybind11_ library in order to interface
the C++ functions, classes and other objects defined
in Rat to the Python_ programming language.

.. note::
    This is a very broad topic which will not be completely
    covered in this documentation but feel free to explore it.

For instance it allows to bridge Rat C++ code like this:

.. code-block:: c++
    :caption: ``solenoid.cpp``

    // Rat-Template solenoid example:
    // <https://gitlab.com/Project-Rat/rat-template/-/blob/master/solenoid.cpp?ref_type=heads>
    // (adapted for consiceness)

    // DESCRIPTION
    // Minimalist example of a solenoid model

    #include "rat/common/log.hh"
    #include "rat/models/pathcircle.hh"
    #include "rat/models/crossrectangle.hh"
    #include "rat/models/modelcoil.hh"
    #include "rat/models/calcmesh.hh"
    int main(int argc, char *argv[]){

        // Input parameters
        const rat::fltp time = 0; // output time [s]
        const rat::fltp radius = 40e-3; // coil inner radius [m]
        const rat::fltp dcoil = 10e-3; // thickness of the coil [m]
        const rat::fltp wcable = 12e-3; // width of the cable [m]
        const rat::fltp delem = 1e-3; // element size [m]
        const arma::uword num_sections = 4; // number of coil sections
        const rat::fltp operating_current = 200; // operating current in [A]
        const arma::uword num_turns = 100; // number of turns

        // Model creation
        const rat::mdl::ShPathCirclePr circle = rat::mdl::PathCircle::create(radius, num_sections, delem);
        circle->set_offset(dcoil);
        const rat::mdl::ShCrossRectanglePr rectangle = rat::mdl::CrossRectangle::create(0, dcoil, 0, wcable, delem);
        const rat::mdl::ShModelCoilPr coil = rat::mdl::ModelCoil::create(circle, rectangle);
        coil->set_number_turns(num_turns);
        coil->set_operating_current(operating_current);

        // Mesh calculation
        const rat::mdl::ShCalcMeshPr mesh_calculation = rat::mdl::CalcMesh::create(coil);
        std::string output_path_argument = "./data";
        const rat::cmn::ShLogPr lg = rat::cmn::Log::create(rat::cmn::Log::LogoType::RAT);
        mesh_calculation->calculate_write({time},output_path_argument,lg);
    }

To Python pyRat_ Python code like this:

.. code-block:: python
    :caption: ``solenoid.py``

    from pyrat import rat
    if __name__ == "__main__":

        # Input parameters
        time = 0  # output time [s]
        radius = 40e-3  # coil inner radius [m]
        dcoil = 10e-3  # thickness of the coil [m]
        wcable = 12e-3  # width of the cable [m]
        delem = 1e-3  # element size [m]
        num_sections = 4  # number of coil sections
        operating_current = 200  # operating current in [A]
        num_turns = 100  # number of turns

        # Model creation
        circle = rat.mdl.PathCircle(radius, num_sections, delem)
        rectangle = rat.mdl.CrossRectangle(0, dcoil, 0, wcable, delem)
        coil = rat.mdl.ModelCoil(path_circle, cross_rectangle)
        solenoid.number_turns = num_turns
        solenoid.operating_current = operating_current

        # Mesh calculation
        calc_mesh = rat.mdl.CalcMesh(solenoid)
        output_path_argument = "./data"
        lg = rat.cmn.Log()
        calc_mesh.calculate_write([time], output_dir, lg)

Obviously a *lot* is going on under the hood to make this work,
and it is the job of pyRat_ with the help of the pybind11_ framework.

The bridges can be summarized by the following diagram:

.. mermaid:: ../graphs/repo-pyrat/introduction_communication.mmd

.. 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
.. _Python: https://www.python.org/
.. _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/