Results files explanation
=========================

.. container:: c-code

   .. highlight:: c

Introduction
------------

This page explains the results files that are output by Robotran when
simulating the different modules.

For the basics use of the modules, see the `tutorial <./intro.html>`__.

.. container:: c-code

   The programming language in this tutorial is **C**.

Raw results files
-----------------

.. container:: c-code python

   All simulation results are stored in the project *resultsR* folder.
   All result files use the result name as prefix (default behavior is
   the name of the module such as ``equil_`` or ``dirdyn_``).

The values are given in the International System of Units.

The files are ``.res`` files that are basically text files. These can be
opened with any text editor such as
`NotePad++ <https://notepad-plus-plus.org/>`__.

By default, the first column is the time in seconds. If not specified,
the next columns are the indexes of joints in the multibody model as
defined in MBsysPad. The suffix of the file determines the content of
the file.

Equilibrium
-----------

For this module, the first column is always the iteration number.

-  Variables of the equilibrium process are given in \*_x.res\* file,
   each line being one iteration.
-  Joint positions at each iteration are given in \*_q.res\* file.
-  Forces of the equil process are given in \*_F.res\* file.
-  Residues of the equil process are given in \*_R.res\* file.

See also `Equilibrium Tutorial <./equil.html>`__.

Modal
-----

.. container:: c-code python

   -  Main results for the multibody system studied are given in
      \*_result.res\* file.

-  Other files provide the matrices corresponding to the studied system
   as defined in `Modal Tutorial <./modal.html>`__. See also the
   corresponding documentation for more information.

Direct dynamics
---------------

Joints kinematics
~~~~~~~~~~~~~~~~~

.. container:: c-code python

   -  Multibody system joints position, velocity and acceleration
      respectively with suffix *q*, *qd* and *qdd*, each column is a
      joint.

Those can be in *m* or *rad* (resp *m/s*, *rad/s* or
*m/s\ 2\ ,\ rad/s\ 2*) depending on the type of the joint (linear or
revolute).

Joints dynamics
~~~~~~~~~~~~~~~

-  Multibody system joints internal forces/torque with suffix *Qq*.

-  Multibody system joints internal forces/torque for fixed (driven)
   variables with suffix *Qc*.

-  Multibody system joints internal forces/torque for actuated variables
   with suffix *Qa*.

-  Multibody system Lagrange multipliers (forces/torque) corresponding
   to constraints with suffix *Lambda*.

Links
~~~~~

.. container:: c-code python

   -  Multibody system links elongation (distance) and velocity with
      suffix *linkZ* and *linkZd*.
   -  Multibody system links force with suffix *linkF*.

Each column is a link.

.. container:: c-code

   The columns correspond to the indexes as defined in
   ``user_all_id.h``.

-  Multibody system links 3D with suffix *link3D_XX*. The columns are:
   first is the time. The 6 other are the forces and torques in the 3
   dimensions.

   .. container:: c-code

      ``XX`` corresponds to the *id* of the link3D as defined
      ``user_all_id.h``

User derivatives
~~~~~~~~~~~~~~~~

-  Multibody system user variables with suffix *ux*.
-  Multibody system user derivative variables with suffix *uxd*.

Solve kinematics and inverse dynamics
-------------------------------------

-  the outputs are the same as those defined in *Direct dynamics* here
   above.

Specific outputs
----------------

User can define specific outputs (see
`set_output <../ModellingFeatures/tipsAndTrick.html#saving-a-custom-quantity>`__).
The first column is always the time. The other columns depend on what
the user defined in its outputs.

.. container:: c-code

   .. rubric:: Advanced mode
      :name: advanced-mode

   User can decide to not save every defaut results file. For instance,
   the user can decide to only save the position, velocity and
   acceleration but not the link forces. This feature can save
   non-negligible computing time and disk space. Furthermore, user can
   decide to only save specific columns in the chosen files. For now
   (Robotran v1.26.0), only the dirdyn module is compatible. See the
   `documentation of the options of the dirdyn
   module <https://robotran.git-page.immc.ucl.ac.be/mbsysc/MBsysC/struct_mbs_dirdyn_options.html>`__
   for more information.