MBsysPy
=======

MBsysPy is a wrapper of MBsysC libraries. It allows the user to analyze
multibody systems without needing to buy Matlab or to learn C
programming language.

In its basic way of work it allows to get an equivalent computation
speed as Matlab. However for advanced user it can be used to wrap an
entire C project, getting the speed of C compiled libraries while
keeping the ability to use Python tools (matplotlib, scipy.optimize) and
to adapt on the fly the parameters of the model without any compilation
step or opening MBsysPad.

**WARNING: MBsysPy is only compatible with 64 bits!**

Requirements
------------

MBsysPy requires a `Python3 <http://www.python.org/>`__ (see below for
Python2) distribution with `numpy <http://www.numpy.org/>`__ for
computation and updated `pip <https://pypi.org/project/pip/>`__ for
packages installation. Other packages such as
`matplotlib <http://matplotlib.org/>`__ and
`scipy <https://www.scipy.org/>`__ are usefull as they allow better
vizualization (graphs generation) and analysis tools (optimization,
statistical tools…).

.. container:: Win64

   For windows you can install `Anaconda <https://www.anaconda.com/>`__,
   remember to take the **Python 3.X** (64 bits) version. It is a
   distribution of Python that includes by default all the required
   packages, and a lot more. Moreover it comes with
   `Spyder <https://github.com/spyder-ide/spyder/blob/master/README.md>`__
   which is a python IDE.

..

   REMARK:

   As Python2 has reached its end of life (since january 2020), we do
   not check the compatibility of MBsysPy with this version.

Upgrading pip
~~~~~~~~~~~~~

Installing MBsysPy requires an up-to-date version of pip:
``pip install -U pip``. Refer to the `official pip
documentation <https://pip.pypa.io/en/stable/installation/>`__ for
details.

Installation
------------

The package of MBsysPy is distributed using pip but are hosted on a
specific repository. The installation is pretty straightforward:
``pip install --index-url https://www.robotran.eu/dist/ MBsysPy --user``.

The option ``--index-url`` redirect pip to our repository, while the
option ``--user`` is used to install the package in the user folders
(avoiding admin access requirements). According to your system
configuration this command has to be entered by different way described
below.

Using Spyder
~~~~~~~~~~~~

Start *Spyder* (you may have to firstly run *anaconda-navigator* to get
the *Spyder* icon), then select the *console* (bottom-right panel where
a version number is printed for example ``Python 3.5.2``) by clicking
inside it. Then just write the previous command (``pip install ...``).

If you get the message ``SyntaxError: invalid syntax`` it is possible
that in your system the spyder console does not have access to pip. Try
another method.

Using Anaconda-prompt
~~~~~~~~~~~~~~~~~~~~~

Start *Anaconda-prompt*, it should open a terminal. In this terminal
write the previous command (``pip install ...``).

Using a system terminal
~~~~~~~~~~~~~~~~~~~~~~~

Open a system terminal and write the previous command
(``pip install ...``). According to your system configuration, your
terminal may not have access to *pip* command. In that case prepend the
previous command with ``python -m`` (it gives:
``python -m pip install...``).

If your system haves both ``Python 2`` and ``Python 3`` installed, you
may have to prepend with ``python3 -m`` instead of ``python -m``.

Remarks and Testing
~~~~~~~~~~~~~~~~~~~

According to your system configuration, you may not have access to the
packages installed via *anaconda* (using *anaconda-prompt* and/or
*spyder* started from *anaconda*) from python started from the system.
If you cannot access the package containing the ``MBsysPy`` module,
please check `KnownTroubleshootings <./KnownTroubleshooting.html>`__.

After installation, you can check that everything is correct by typing
``import MBsysPy`` in Python. If the ``MBsysPy`` module is not found,
please check `KnownTroubleshootings <./KnownTroubleshooting.html>`__.

Lot of our class and functions are documented (but not all, work still
in progress). You can see the related documentation, after importing
MBsysPy, in the field ``__doc__`` of the function or class:

::

   import MBsysPy
   print(MBsysPy.MbsData.__doc__)
   print(MBsysPy.MbsData.__init__.__doc__)
   print(MBsysPy.MbsData.set_qdriven.__doc__)

In spyder you can show the documentation in the *Object inspector* panel
(top right) by writing in the Object field, for example:
``MBsysPy.MbsData`` or ``MBsysPy.MbsData.set_qdriven``.

Updating MBsysPy
----------------

To update the package follow the same installation procedure than used
for installation with the command
``pip install --index-url https://www.robotran.eu/dist/ MBsysPy --user --upgrade``
instead of the previous one. The only difference is the addition of the
option ``--upgrade``.

Using development version
-------------------------

To update the package follow the same installation procedure than used
for installation but with the command
``pip install --index-url https://www.robotran.eu/dist/ MBsysPy --user --upgrade --pre``
instead of the previous one. The only difference is the addition of the
option ``--pre``.

Using PyCharm IDE
-----------------

We do not recommend using PyCharm but some users did manage to configure
PyCharm so that MBsysPy works. We do not provide any support for this
IDE.

Using Thonny IDE
----------------

We do not recommend using Thonny and do not provide any support for this
IDE. If you still want to use Thonny, please install a 64bits version of
Python. Also, you will maybe need to configure specifically this IDE so
that MBsysPy works.