mbs_data.py

# -*- coding: utf-8 -*-
"""
Main class for Multibody systems.

Summary
-------
Define the class MbsData based on the MbsData structure of MBsysC.
This class has the functions required to manipulate the Data (set the number of
user constraints, set the independant or dependant variables...).
"""
# MBsysC version : 1.13.0
# Author : Robotran Team
# (c) Universite catholique de Louvain, 2019

import os
import importlib
import ctypes

import numpy as np

# importing MbsysPy functions
from ..mbs_utilities import mbs_msg
from ..mbs_utilities import mbs_warning
from ..mbs_utilities import mbs_error
from ..mbs_utilities import bytes_to_str
from ..mbs_utilities import str_to_bytes
from ..mbs_utilities import convert_numpy_type_to_int
from ..mbs_utilities import convert_numpy_type_to_float

# importing MbsysPy classes
from .mbs_sensor import MbsSensor
from .mbs_part import MbsPart
from .mbs_equil import MbsEquil
from .mbs_dirdyn import MbsDirdyn
from .mbs_modal import MbsModal
from .mbs_solvekin import MbsSolvekin
from .mbs_invdyn import MbsInvdyn

# importing libraries
from .._mbsysc_loader.loadlibs import libutilities
from .._mbsysc_loader.loadlibs import libloadXML

# importing utilities function
from ..mbs_utilities import callback_undefined

# importing wrapping function
from .._mbsysc_loader.callback import user_cons_hJ_wrap
from .._mbsysc_loader.callback import user_cons_jdqd_wrap
from .._mbsysc_loader.callback import user_Derivative_wrap
from .._mbsysc_loader.callback import user_DrivenJoints_wrap
from .._mbsysc_loader.callback import user_ExtForces_wrap
from .._mbsysc_loader.callback import user_JointForces_wrap
from .._mbsysc_loader.callback import user_LinkForces_wrap
from .._mbsysc_loader.callback import user_Link3DForces_wrap
from .._mbsysc_loader.callback import user_dirdyn_init_wrap
from .._mbsysc_loader.callback import user_dirdyn_loop_wrap
from .._mbsysc_loader.callback import user_dirdyn_finish_wrap
from .._mbsysc_loader.callback import user_equil_init_wrap
from .._mbsysc_loader.callback import user_equil_loop_wrap
from .._mbsysc_loader.callback import user_equil_finish_wrap
from .._mbsysc_loader.callback import user_equil_fxe_wrap

from .._mbsysc_loader.callback import mbs_accelred_wrap
from .._mbsysc_loader.callback import mbs_extforces_wrap
from .._mbsysc_loader.callback import mbs_gensensor_wrap
from .._mbsysc_loader.callback import mbs_link_wrap
from .._mbsysc_loader.callback import mbs_link3D_wrap
from .._mbsysc_loader.callback import mbs_sensor_wrap
from .._mbsysc_loader.callback import mbs_cons_hJ_wrap
from .._mbsysc_loader.callback import mbs_cons_jdqd_wrap
from .._mbsysc_loader.callback import mbs_invdyna_wrap
from .._mbsysc_loader.callback import mbs_dirdyna_wrap

# =============================================================================
# Global parameter of the current module
# =============================================================================
__DEBUG__ = False
__MODULE_DIR__ = os.path.dirname(os.path.abspath(__file__))


# =============================================================================
# Defining Python MbsData class
# =============================================================================

class MbsData(object):
    """
    Class containing geometrical and dynamical information of robotran Mbs.

    Attributes
    ----------
    body_id : dict
        Dictionary containing the names of the bodies as keys and their ids as
        values.
    DonePart : int
        Flag that indicates if the coordinate partitioning module has been
        executed (default: 0=not done; 1=done).
    dpt : numpy.ndarray
        Numpy array containing the coordinates of all anchor points in body
        fixed frame: [X_i,Y_i,Z_i] = dpt[1:4,i]
    extforce_id : dict
        Dictionary containing the names of the extforces as keys and their ids
        as values.
    Fl : numpy.ndarray
        Numpy array containing the current values of the forces on each link.
    frc: numpy.ndarray
        Numpy array containing the components of the resultant external forces
        (in the body fixed frame) applied to the center of mass of each body.
    g : numpy.ndarray
        The 3 gravity components in the inertial frame: g[1:4]=[g_x, g_y, g_z]
    In : numpy.ndarray
        Numpy array containing the inertia tensor component of each body (in
        the body fixed frame, relative to the center of mass). For body k:
        In[1:10, k]=[I_11,I_12,I_13,I_21,I_22,I_23,I_31,I_32,I_33]
    joint_id : dict
        Dictionary containing the names of the joints as keys and their ids as
        values.
    l : numpy.ndarray
        Numpy array containing the center of mass coordinates in the body fixed
        frame. For body k: l[1:4, k]=[gc_x, gc_y, gc_z]
    lambda_ : numpy.ndarray
        Numpy array containing the values of the Lagrange Multipliers related
        to the constraints. The sequence is the same sequence as the constraint
        definition.
    link_id : dict
        Dictionary containing the names of the links as keys and their ids as
        values.
    lrod : numpy.ndarray
        Numpy array containing the length of each rod.
    m : numpy.ndarray
        Numpy array containing the mass of each body.
    mbs_filename : str
        Path to mbs file including the file with the extension (.mbs).
    mbs_name : str
        Filename of the mbs file (excluding path and ".mbs" extension).
    nbody : int
        Number of bodies in the system. The fictious bodies are not taken into
        account.
    Ncons : int
        Number of algebraic constraints.
    nhu : int
        Number of independent constraints.
    njoint : int
        Number of joints in the system.
    Nlink : int
        Number of forces acting between two points of the system.
    Nloopc : int
        Number of loop constraints.
    npt : int
        Number of anchor points.
    nqa : int
        Number of actuated articulations.
    nqc : int
        Number of driven articulations, it includes qlocked and qdriven..
    nqdriven : int
        Number of driven articulations.
    nqlocked : int
        Number of locked articulations.
    nqu : int
        Number of independent articulations.
    nqv : int
        Number of dependent articulations.
    NRerr : float
        Maximal error on constraint allowed in Newton-Raphson algorithm,
        default 1.0e-9.
    nrod : int
        Number of rod constraints defined on the system.
    Nsensor : int
        Number of kinematic sensors.
    Nuserc : int
        Number of user constraints.
    Nux : int
        Number of user variable.
    Nxfrc : int
        Number of points where an external force is applied into a body.
    points_id : dict
        Dictionary containing the ids of the anchor points of each bodies. The
        first key is the body name and the second key is the anchor point name.
        The retrieve value is the id of the requested anchor point.
        Example: my_id = mbs_data.points_id["body_1"]["point_0"]
    process : int
        Flag that indicate which module is currently running:
        1=partitioning; 2=equilibrium; 3=direct dynamic; 4=modal
    project_path : str
        Path to the mbs project folder.
    q : numpy.ndarray
        Numpy array containing the current values of the generalized
        coordinates.
    q0 : numpy.ndarray
        Numpy array containing the initial values of the generalized
        coordinates.
    qa : numpy.ndarray of int
        Numpy array of integers containing the indices of actuated
        articulations (only for inverse dynamic). Those articulations are
        controlled by an actuator.
    Qa : numpy.ndarray
        Numpy array containing the value of actuation forces.
    qc : numpy.ndarray of int
        Numpy array of integers containing the indices of driven (locked and
        driven) articulations.
    Qc : numpy.ndarray
        Numpy array containing the value of joint force introduced in driven
        joints to respect the user function. The driven forces/torques are
        saved in the entries given by index vector 'qc'.
    qd : numpy.ndarray
        Numpy array containing the current values of the generalized
        velocities.
    qd0 : numpy.ndarray
        Numpy array containing the initial values of the generalized
        velocities.
    qdd : numpy.ndarray
        Numpy array containing the current values of the generalized
        accelerations.
    qdd0 : numpy.ndarray
        Numpy array containing the initial values of the generalized
        accelerations.
    qdriven : numpy.ndarray of int
        Numpy array of integers containing the indices of driven articulations.
        Those articulations are controlled by a user function:
        q[qdriven]=f(tsim)
    qlocked : numpy.ndarray of int
        Numpy array of integers containing the indices of locked articulations.
        Those articulations have a constant position defined by the user:
        q[qlocked]=cte
    Qq : numpy.ndarray
        Numpy array containing the values of the joint forces.
    qu : numpy.ndarray of int
        Numpy array of integers containing the indices of the independent
        articulations.
    qv : numpy.ndarray of int
        Numpy array of integers containing the indices of the dependent
        articulations.
    sensor_id : dict
        Dictionary containing the names of the sensors as keys and their ids as
        values.
    sensors : list of MbsSensor
        List containing one instance of MbsSensor (without defined id). User
        can append as many as needed sensor in the list. Sensors defined in
        this list can be used by the user for various computation.
    SWr : numpy.ndarray
        Numpy array containing the Swr vector for each external forces.
        for force k, Swr[k,1:10] = [Fx, Fy, Fz, Mx, My, Mz, dxF] with
          - Force components (expressed in the inertial frame) : Fx,Fy,Fz
          - Pure torque components (expressed in the inertial frame) : Mx,My,Mz
          - Application point local coordinates vector (expressed in the body
            fixed frame): dxF[1:4]
    t0 : scalar
        Initial time of the simulation [s]. For dirdyn and invdyn only. This
        parameter is set from dirdyn/invyn option at start of time simulation.
    tf : scalar
        Final time of the simulation [s]. For dirdyn and invdyn only. This
        parameter is set from dirdyn/invyn option at start of time simulation.
    trq : numpy.ndarray
        Numpy array containing the components of the resultant external torques
        (pure torque and couple produced by forces displacement in the body
        fixed frame) applied to each body.
    tsim : scalar
        The time value.
    user_model : dict
        Dictionary containing the names of the user models as keys and a second
        dictionary with their parameters as values. The second dictionary
        contains the names of the parameters as keys and their values as values
    ux : numpy.ndarray
        Numpy array containing the values of the user variables.
    ux0 : numpy.ndarray
        Numpy array containing the initial values of the user variables.
    uxd : numpy.ndarray
        Numpy array containing the values of the time derivative of the user
        variables.
    xfidpt : numpy.ndarray of int
        Numpy array of integers containing the indices of the points defined as
        force application points.
    Z : numpy.ndarray
        Numpy array containing the current values of the distances between of
        the points of a link.
    Zd : numpy.ndarray
        Numpy array containing the current values of the speed (spreading)
        between of the points of a link.


    Example
    -------

    >>> mbs_data = MBsysPy.MbsData("../dataR/ExampleProject.mbs")
    >>> mbs_data.user_model["MyUserModel"]["MyScalar"] = 3.0
    >>> mbs_msg(mbs_data.user_model["MyUserModel"]["MyScalar"])
        3.0
    >>> #get a copy of the scalar
    >>> a = mbs_data.user_model["MyUserModel"]["MyScalar"]
    >>> a = 2
    >>> mbs_msg(mbs_data.user_model["MyUserModel"]["MyScalar"])
        3.0
    >>> print(mbs_data.user_model["MyUserModel"]["MyVector"])
        array([1.0, 3.0])
    >>> mbs_data.user_model["MyUserModel"]["MyVector"] = [1.0, 2.0]
    >>> print(mbs_data.user_model["MyUserModel"]["MyVector"])
        array([1.0, 2.0])
    >>> b = mbs_data.user_model["MyUserModel"]["MyVector"]
    >>> b[1] = 10.0
    >>> print(mbs_data.user_model["MyUserModel"]["MyVector"])
        array([1.0, 10.0])
    >>> b = np.array([2.0, 4.0])
    >>> print(mbs_data.user_model["MyUserModel"]["MyVector"])
        array([1.0, 10.0])

    """

    def __init__(self, name, user_path=None, symbolic_path=None,
                 prj_functions_c=None, prj_lib_path=None):
        """
        Load a specific *.mbs file into a MbsData class instance.

        Parameters
        ----------
        name : str
            The path to the .mbs file to load, including the file extension.
        user_path : str, optionnal
            The path to the folder containing the user functions if the default
            project structure are not used.
        symbolic_path : str, optionnal
            The path to the folder containing the symbolic functions if the
            default project structure are not used.
        prj_functions_c : None or str, optionnal
            Option to load some of the project functions from the project C
            library. Accepted values are:
             - None : All project function are defined in python
             - "symbolic_only" or "S" : Symbolic function comes from C library
             - "symbolic_and_user" or "SU" : Symbolic and user functions come from C library
            default is None
        prj_lib_path : None or str, optionnal
            Required if 'prj_functions_c' is not None
            - In Linux, it gives the location of the folder containing the
              "symbolicR/" and, or "userfctR/" folders. Each one of the subfolder
              have to contain the corresponding library (ie: libProject_symbolic.so).
            - In Windows, it gives the location of the folder containing the project
              libraries (Project_symbolic.dll and/or Project_userfct.dll).
            - In MacOs the expected behavior is the same as Linux. It must be tested.
            default is None

        Returns
        -------
        out : MBsysPy.MbsData
            A loaded mbs file in a MbsData instance.
        """
        # Retrieve prj_functions_c value
        if prj_functions_c is None:
            self.opt_load_c = 0
            if not (prj_lib_path is None):
                mbs_msg("Argument 'prj_lib_path' is ignored as option 'prj_functions_c' is 'None'.")
                prj_lib_path = None
        elif (type(prj_functions_c) is str) or (type(prj_functions_c) is bytes):
            if (type(prj_functions_c) is bytes):
                prj_functions_c = bytes_to_str(prj_functions_c)
            if prj_functions_c == "symbolic_only" or prj_functions_c == "S":
                self.opt_load_c = 1
            elif prj_functions_c == "symbolic_and_user" or prj_functions_c == "SU":
                self.opt_load_c = 2
            else:
                raise ValueError("prj_functions_c is not valid:'"
                                 + prj_functions_c + "'.")

            if (prj_lib_path is None):
                raise ValueError("prj_lib_path must be given if 'prj_functions_c' is set.")
            if not (type(prj_lib_path) is str):
                raise TypeError("prj_lib_path type must be str but it is '"
                                + str(type(prj_lib_path)) + "'.")
            else:
                prj_lib_path = str_to_bytes(os.path.abspath(prj_lib_path))
        else:
            raise TypeError("prj_functions_c type is not valid:'"
                            + str(type(prj_functions_c)) + "'.")

        # Create a byte object from the string
        name_c = str_to_bytes(name)
        # Load the MbsInfos and keep a copy
        if __DEBUG__:
            mbs_msg("DEBUG>>  Loading: '" + bytes_to_str(name)
                             + "' from:'" + os.getcwd() + "'.")

        self.mbs_infos_ptr = libloadXML.mbs_info_reader(name_c)
        if __DEBUG__:
            mbs_msg("DEBUG>>  mbs_infos structure loaded")

        # Preparing loader and its options for loading
        loader = libloadXML.mbs_new_loader()
        if __DEBUG__:
            mbs_msg("DEBUG>>  Loader structure created")

        loader.contents.opts.contents.no_project_fct = self.opt_load_c
        if __DEBUG__:
            mbs_msg("DEBUG>>  flag ignoring project function set")

        loader.contents.mbs_infos = self.mbs_infos_ptr
        if __DEBUG__:
            mbs_msg("DEBUG>>  mbs_infos assigned to loader")

        # Load and retrieve MbsData structure
        self.mbs_data_ptr = libloadXML.mbs_load_with_loader(name_c, prj_lib_path, loader)
        if __DEBUG__:
            mbs_msg("DEBUG>>  MbsData loaded")

        # Project with link3D are not (yet) compatible
        if self.mbs_data_ptr.contents.Nlink3D:
            print("The system contains 3Dlinks which are an advanced feature not"
                  " yet supported in MBsysPy.\nUncheck the 'Link 3D' box in "
                  "MBsysPAD, or migrate to MBsysC/MBsysLab.")
            raise RuntimeError("ERROR: 3Dlinks are not yet supported in MBsysPy, modify the multibody sytem.")

        libloadXML.mbs_delete_loader(loader)
        # symbolic and user function folder
        self.user_path = None
        self.symbolic_path = None

        # pointers dict to avoid garbage collecting
        self.ptrs_to_user_fcts = dict()
        self.ptrs_to_symb_fcts = dict()

        # Creating field for all project function.
        user_fun_list = ['cons_hJ', 'cons_jdqd', 'derivative', 'DrivenJoints',
                         'ExtForces', 'JointForces', 'LinkForces', 'Link3DForces',
                         'dirdyn_init', 'dirdyn_loop', 'dirdyn_finish',
                         'equil_init', 'equil_loop', 'equil_finish', 'equil_fxe'
                         ]
        symb_fun_list = ['accelred', 'cons_hJ', 'cons_jdqd', 'invdyna', 'dirdyna',
                         'extforces', 'gensensor', 'link', 'link3D', 'sensor'
                         ]

        self.__assign_user_fct_to_none__(user_fun_list)
        if self.opt_load_c < 2:
            self.__assign_user_to_undefined__(user_fun_list)
        self.__assign_symb_fct_to_none__(symb_fun_list)
        if self.opt_load_c < 1:
            self.__assign_symb_to_undefined__(symb_fun_list)

        # Exposing some memory
        if __DEBUG__:
            mbs_msg("DEBUG>>  Exposing MbsData fields")

        # Geometric and dynamic datas
        self.__dpt = None
        if(self.npt):
            self.__dpt = np.ctypeslib.as_array(self.mbs_data_ptr.contents.dpt[0],
                                               (3 + 1, self.npt + 1))
        self.__l = np.ctypeslib.as_array(self.mbs_data_ptr.contents.l[0], (3 + 1, self.njoint + 1))
        self.__m = np.ctypeslib.as_array(self.mbs_data_ptr.contents.m, (self.njoint + 1, ))
        self.__In = np.ctypeslib.as_array(self.mbs_data_ptr.contents.In[0], (9 + 1, self.njoint + 1))
        self.__g = np.ctypeslib.as_array(self.mbs_data_ptr.contents.g, (4, ))

        # Partitioning informations
        self.__qu = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qu, (self.njoint + 1, ))
        self.__qu.flags["WRITEABLE"] = False
        self.__qc = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qc, (self.njoint + 1, ))
        self.__qc.flags["WRITEABLE"] = False
        self.__qlocked = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qlocked, (self.njoint + 1, ))
        self.__qlocked.flags["WRITEABLE"] = False
        self.__qdriven = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qdriven, (self.njoint + 1, ))
        self.__qdriven.flags["WRITEABLE"] = False
        self.__qa = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qa, (self.njoint + 1, ))
        self.__qa.flags["WRITEABLE"] = False
        self.__qv = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qv, (self.njoint + 1, ))
        self.__qv.flags["WRITEABLE"] = False

        # Generalized coordinates velocities and acceleration
        self.__q = np.ctypeslib.as_array(self.mbs_data_ptr.contents.q, (self.njoint + 1, ))
        self.__qd = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qd, (self.njoint + 1, ))
        self.__qdd = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qdd, (self.njoint + 1, ))

        self.__q0 = np.ctypeslib.as_array(self.mbs_data_ptr.contents.q0, (self.njoint + 1, ))
        self.__qd0 = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qd0, (self.njoint + 1, ))
        self.__qdd0 = np.ctypeslib.as_array(self.mbs_data_ptr.contents.qdd0, (self.njoint + 1, ))

        # Forces array
        self.__frc = np.ctypeslib.as_array(self.mbs_data_ptr.contents.frc[0], (3 + 1, self.njoint + 1))
        self.__trq = np.ctypeslib.as_array(self.mbs_data_ptr.contents.trq[0], (3 + 1, self.njoint + 1))
        self.__Qq = np.ctypeslib.as_array(self.mbs_data_ptr.contents.Qq, (self.njoint + 1, ))
        self.__Qa = np.ctypeslib.as_array(self.mbs_data_ptr.contents.Qa, (self.njoint + 1, ))

        # Constraints datas
        self.nrod = 0
        self.__lrod = None
        if (self.mbs_data_ptr.contents.lrod):
            self.nrod = int(round(self.mbs_data_ptr.contents.lrod[0]))
            self.__lrod = np.ctypeslib.as_array(self.mbs_data_ptr.contents.lrod, (self.nrod + 1, ))

        self.__lambda_ = np.ctypeslib.as_array(self.mbs_data_ptr.contents.lambda_, (self.njoint + 1, ))
        self.__Qc = np.ctypeslib.as_array(self.mbs_data_ptr.contents.Qc, (self.njoint + 1, ))

        # LinksForces
        self.__Z = self.__Zd = self.__Fl = None
        if self.Nlink:
            self.__Z = np.ctypeslib.as_array(self.mbs_data_ptr.contents.Z, (self.Nlink + 1, ))
            self.__Zd = np.ctypeslib.as_array(self.mbs_data_ptr.contents.Zd, (self.Nlink + 1, ))
            self.__Fl = np.ctypeslib.as_array(self.mbs_data_ptr.contents.Fl, (self.Nlink + 1, ))

        # ExtForces
        self.__xfidpt = self.__SWr = None
        if self.Nxfrc:
            self.__xfidpt = np.ctypeslib.as_array(self.mbs_data_ptr.contents.xfidpt, (self.Nxfrc + 1, ))
            self.__xfidpt.flags["WRITEABLE"] = False
            self.__SWr = np.ctypeslib.as_array(self.mbs_data_ptr.contents.SWr[0], (self.Nxfrc + 1, 9 + 1))

        # User State
        self.__ux = self.__ux0 = self.__uxd = None
        if self.Nux:
            self.__ux = np.ctypeslib.as_array(self.mbs_data_ptr.contents.ux, (self.Nux + 1, ))
            self.__ux0 = np.ctypeslib.as_array(self.mbs_data_ptr.contents.ux0, (self.Nux + 1, ))
            self.__uxd = np.ctypeslib.as_array(self.mbs_data_ptr.contents.uxd, (self.Nux + 1, ))

        # Adding internal sensor
        self.sensors = [MbsSensor(self, None)]

        # ID
        self.body_id = {}
        self.joint_id = {}
        self.link_id = {}
        self.extforce_id = {}
        self.sensor_id = {}
        self.points_id = {}
        self.__generate_id__()

        # UserModel
        self.user_model = _UserModelDict()
        self.__load_user_model__()

        # Loading user function
        if self.opt_load_c < 2:
            if __DEBUG__:
                mbs_msg("DEBUG>>  Loading user functions")

            project_path = self.project_path

            # Creating user path
            if user_path is None:
                user_path = os.path.join(project_path, "userfctR")
            else:
                user_path = os.path.join(project_path, user_path)
            # Error handeling
            if not os.path.isdir(user_path):
                mbs_msg('The user function directory does not exist: "' + user_path + '"')
                mbs_msg('The current root folder is: "' + os.getcwd() + '"')
            self.user_path = user_path

        # Loading symbolic function
        if self.opt_load_c < 1:
            if __DEBUG__:
                mbs_msg("DEBUG>>  Loading symbolic functions")

            project_path = self.project_path
            # Creating user path
            if symbolic_path is None:
                symbolic_path = os.path.join(project_path, "symbolicR")
            else:
                symbolic_path = os.path.join(project_path, symbolic_path)
            # Error handeling
            if not os.path.isdir(symbolic_path):
                mbs_msg('The symbolic function directory does not exist: "' + symbolic_path + '"')
                mbs_msg('The current root folder is: "' + os.getcwd() + '"')
            self.symbolic_path = symbolic_path

    def __str__(self):
        """Return str(self)."""
        if __DEBUG__:
            mbs_msg("DEBUG>>  start of __str")

        libutilities.mbs_print_data(self.mbs_data_ptr)
        if __DEBUG__:
            mbs_msg("DEBUG>>  MbsData printed")

        return ''

    def __assign_user_fct_to_none__(self, functions):
        """Create fields for user functions fields and set them to None.

        Parameters
        ----------
        functions : List
            List of strings containing the names of the user functions
            to assign.

        Notes
        -----
        Only the following user functions names can be passed as parameter:
            - 'cons_hJ'
            - 'cons_jdqd'
            - 'derivative'
            - 'DrivenJoints'
            - 'ExtForces'
            - 'JointForces'
            - 'LinkForces'
            - 'Link3DForces'
            - 'dirdyn_init'
            - 'dirdyn_loop'
            - 'dirdyn_finish'
            - 'equil_init'
            - 'equil_loop'
            - 'equil_finish'
            - 'equil_fxe'

        Returns
        -------
        None.
        """
        if isinstance(functions, list):
            for fun in functions:
                if fun == "cons_hJ":
                    self.user_cons_hJ = None
                elif fun == "cons_jdqd":
                    self.user_cons_jdqd = None
                elif fun == "derivative":
                    self.user_derivative = None
                elif fun == "DrivenJoints":
                    self.user_DrivenJoints = None
                elif fun == "ExtForces":
                    self.user_ExtForces = None
                elif fun == "JointForces":
                    self.user_JointForces = None
                elif fun == "LinkForces":
                    self.user_LinkForces = None
                elif fun == "Link3DForces":
                    self.user_Link3DForces = None
                elif fun == "dirdyn_init":
                    self.user_dirdyn_init = None
                elif fun == "dirdyn_loop":
                    self.user_dirdyn_loop = None
                elif fun == "dirdyn_finish":
                    self.user_dirdyn_finish = None
                elif fun == "equil_init":
                    self.user_equil_init = None
                elif fun == "equil_loop":
                    self.user_equil_loop = None
                elif fun == "equil_finish":
                    self.user_equil_finish = None
                elif fun == "equil_fxe":
                    self.user_equil_fxe = None
                else:
                    raise TypeError(fun + " is not an existing user function")
        else:
            raise TypeError('The "functions" parameter must be a list, got a {:}.'.format(type(functions)))

    def __assign_symb_fct_to_none__(self, functions):
        """Create fields for symbolic functions fields and set them to None.

        Parameters
        ----------
        functions : list
            List of strings containing the names of the symbolic functions
            to assign

        Notes
        -----
        Only the following symbolic functions names can be passed as parameter:
            - 'accelred'
            - 'cons_hJ'
            - 'cons_jdqd'
            - 'invdyna'
            - 'dirdyna'
            - 'extforces'
            - 'gensensor'
            - 'link'
            - 'link3D'
            - 'sensor'

        Returns
        -------
        None.

        """
        if isinstance(functions, list):
            for fun in functions:
                if fun == "accelred":
                    self.mbs_accelred = None
                elif fun == "cons_hJ":
                    self.mbs_cons_hJ = None
                elif fun == "cons_jdqd":
                    self.mbs_cons_jdqd = None
                elif fun == "dirdyna":
                    self.mbs_dirdyna = None
                elif fun == "extforces":
                    self.mbs_extforces = None
                elif fun == "gensensor":
                    self.mbs_gensensor = None
                elif fun == "invdyna":
                    self.mbs_invdyna = None
                elif fun == "link":
                    self.mbs_link = None
                elif fun == "link3D":
                    self.mbs_link3D = None
                elif fun == "sensor":
                    self.mbs_sensor = None
                else:
                    raise TypeError(fun + " is not an existing symbolic function")
        else:
            raise TypeError('The "functions" parameter must be a list, got a {:}.'.format(type(functions)))

    def __load_user_fct__(self, module_dir, functions, user_path):
        """Load specified user functions in MbsData instance.

        Load only if not yet loaded by the user.
        The functions will be assigned to the MbsData instance when the 'run'
        functions is called and unassigned at the end.

        Parameters
        ----------
        module_dir : str
            The path to the module directory
        functions : List
            List of strings containing the names of the user functions
            to assign
        user_path: str
            The path to the folder containing the user functions.

        Notes
        -----
        Only the following user functions names can be passed as parameter:
            - 'cons_hJ'
            - 'cons_jdqd'
            - 'derivative'
            - 'DrivenJoints'
            - 'ExtForces'
            - 'JointForces'
            - 'LinkForces'
            - 'Link3DForces'
            - 'dirdyn_init'
            - 'dirdyn_loop'
            - 'dirdyn_finish'
            - 'equil_init'
            - 'equil_loop'
            - 'equil_finish'
            - 'equil_fxe'

        """
        template_path = os.path.join(module_dir, '../templates/user')

        if isinstance(functions, list):
            for fun in functions:
                if fun == "cons_hJ":
                    if self.user_cons_hJ is None:
                        # cons_hJ
                        user_file = "user_cons_hJ.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_cons_hJ = module.user_cons_hJ

                elif fun == "cons_jdqd":
                    if self.user_cons_jdqd is None:
                        # cons_jdqd
                        user_file = "user_cons_jdqd.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_cons_jdqd = module.user_cons_jdqd

                elif fun == "derivative":
                    if self.user_derivative is None:
                        # derivative
                        user_file = "user_Derivative.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_derivative = module.user_derivatives

                elif fun == "DrivenJoints":
                    if self.user_DrivenJoints is None:
                        # drivenJoints
                        user_file = "user_DrivenJoints.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_DrivenJoints = module.user_DrivenJoints

                elif fun == "ExtForces":
                    if self.user_ExtForces is None:
                        # ext_forces
                        user_file = "user_ExtForces.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_ExtForces = module.user_ExtForces

                elif fun == "JointForces":
                    if self.user_JointForces is None:
                        # joint_forces
                        user_file = "user_JointForces.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_JointForces = module.user_JointForces

                elif fun == "LinkForces":
                    if self.user_LinkForces is None:
                        # link_forces
                        user_file = "user_LinkForces.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_LinkForces = module.user_LinkForces

                elif fun == "Link3DForces":
                    if self.user_Link3DForces is None:
                        # link3D_forces
                        user_file = "user_Link3DForces.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  file '" + user_file + "' not found in folder '" + os.path.dirname(path))

                            path = os.path.abspath(os.path.join(template_path, user_file))
                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_Link3DForces = module.user_Link3DForces

                elif fun == 'dirdyn_init':
                    if self.user_dirdyn_init is None:
                        # user_dirdyn
                        user_file = "user_dirdyn.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            mbs_msg("file '" + user_file + "' not found in folder '" + os.path.dirname(path))
                            path = os.path.abspath(os.path.join(template_path, user_file))
                        else:
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  loading file '" + user_file + "' in folder '" + os.path.dirname(path))

                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_dirdyn_init = module.user_dirdyn_init

                elif fun == 'dirdyn_loop':
                    if self.user_dirdyn_loop is None:
                        # user_dirdyn
                        user_file = "user_dirdyn.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            mbs_msg("file '" + user_file + "' not found in folder '" + os.path.dirname(path))
                            path = os.path.abspath(os.path.join(template_path, user_file))
                        else:
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  loading file '" + user_file + "' in folder '" + os.path.dirname(path))

                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_dirdyn_loop = module.user_dirdyn_loop

                elif fun == 'dirdyn_finish':
                    if self.user_dirdyn_finish is None:
                        # user_dirdyn
                        user_file = "user_dirdyn.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            mbs_msg("file '" + user_file + "' not found in folder '" + os.path.dirname(path))
                            path = os.path.abspath(os.path.join(template_path, user_file))
                        else:
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  loading file '" + user_file + "' in folder '" + os.path.dirname(path))

                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_dirdyn_finish = module.user_dirdyn_finish

                elif fun == 'equil_init':
                    if self.user_equil_init is None:
                        user_file = "user_equil.py"
                        path = os.path.abspath(os.path.join(user_path, user_file))
                        if not os.path.isfile(path):
                            mbs_msg("file '" + user_file + "' not found in folder '" + os.path.dirname(path))
                            path = os.path.abspath(os.path.join(template_path, user_file))
                        else:
                            if __DEBUG__:
                                mbs_msg("DEBUG>>  loading file '" + user_file + "' in folder '" + os.path.dirname(path))

                        spec = importlib.util.spec_from_file_location(user_file[:-3], path)
                        module = importlib.util.module_from_spec(spec)
                        spec.loader.exec_module(module)
                        self.user_equil_init = module.user_equil_init