Commit a621f03f authored by Nicolas Docquier's avatar Nicolas Docquier
Browse files

Merge branch 'documentation' into 'dev'

Documentation

Code is globally commented, still need to "copy-paste" the module introduction from Matlab documentation.

See merge request !83
parents 125b4f98 203d3015
......@@ -276,7 +276,12 @@ module ExternalMBS
end subroutine
!> Add the given node reaction contribution to the reaction of the global mbs in 3D simulation
!! @param i_mbs the index of the mbs for which the reaction must be applied
!! @param i_node the index of the node on which the reaction is applied
!! @param reac reaction to add with the forces expressed in global frame and torque in body frame
!! @param storage flag to communicate the state of the computation
!! @param LFTT rotation matrix to pass from global frame to body frame
subroutine add_reac_3D(i_mbs, i_node, reac, storage, LFTT)
implicit none
......@@ -284,12 +289,12 @@ module ExternalMBS
integer(kind=4), intent(in) :: i_node
integer(kind=4), intent(in) :: storage
real(kind=8) , dimension(6) :: reac
!> Reaction with Forces expressed in global frame and torque in body frame
! Reaction with Forces expressed in global frame and torque in body frame
real(kind=8) , dimension(6) :: reac_glob
!> reac vector with torques expressed in global frame.
!> reac is not modified because it's intent(in) in mod_mbs.f90
! reac vector with torques expressed in global frame.
! reac is not modified because it's intent(in) in mod_mbs.f90
real(kind=8) , dimension(3,3):: LFTT
!> Matrix to pass from global frame to body frame
! Matrix to pass from global frame to body frame
!123456789012345678901
character(len=20) :: IAM='ext_mbs::add_reac_3D'
......@@ -316,16 +321,21 @@ module ExternalMBS
end subroutine
subroutine add_reac_2D(i_mbs, i_node, reac, storage)
!> Add the given node reaction contribution to the reaction of the global mbs in 2D simulation
!! @param i_mbs the index of the mbs for which the reaction must be applied
!! @param i_node the index of the node on which the reaction is applied
!! @param reac reaction to add with the forces and torque expressed in global frame
!! @param storage flag to communicate the state of the computation
subroutine add_reac_2D(i_mbs, i_node, reac, storage)
implicit none
integer(kind=4), intent(in) :: i_mbs
integer(kind=4), intent(in) :: i_node
integer(kind=4), intent(in) :: storage
real(kind=8) , dimension(3) :: reac
!> Reaction with Forces along X and Y an torque around Z expressed in global frame
! Reaction with Forces along X and Y an torque around Z expressed in global frame
real(kind=8) , dimension(6) :: reac_glob
!> Same vector as reac but completed in 3D : [Fx, Fy, 0, 0, 0, Tz]
! Same vector as reac but completed in 3D : [Fx, Fy, 0, 0, 0, Tz]
!123456789012345678901
character(len=20) :: IAM='ext_mbs::add_reac_2D'
......
......@@ -10,13 +10,18 @@
extern "C" {
#endif
/**
* Load the data from the given *.mbs file (data in the xml
* format). The memory of a new MbsData is allocated.
* \brief Load the data from the given *.mbs file (data in the xml
format). The memory of a new MbsData is allocated.
*
* \param mbs_filename path to the file to load including filename and extension.
* \param build_name path to the build folder of MBsysC libraries
*/
MBSYSC_LOADXML_EXPORT MbsData* mbs_load(const char* mbs_filename, const char* build_name);
/**
* Free the memory used by the given MbsData structure.
* \brief Free the memory used by the given MbsData structure.
*
* \param s the structure to be freed.
*/
MBSYSC_LOADXML_EXPORT void mbs_delete_data(MbsData *s);
......@@ -27,12 +32,15 @@ void mbs_delete_data(MbsData *s);
#endif
/**
* Load the user model data
* \brief Load the user model data
*/
PROJECT_USERFCT_EXPORT void mbs_load_user_model_xml(MDS_gen_strct* gen, UserModel* ums);
/**
* Retrieve a MbsData structure from the given MDS_gen_strct
* \brief Retrieve a MbsData structure from the given MDS_gen_strct
*
* \param[in] mds_gen_strct the MDS gen structure already filled to be used to fill the MbsData structure.
* \param[in,out] s the MbsData structure that will be completed according to the MDS gen structure.
*/
MbsData* MDS_create_MBSdataStruct(MDS_gen_strct* mds_gen_strct, MbsData* s);
......
......@@ -11,64 +11,75 @@
typedef struct MDS_d_data_strct
{
int d_type; // other = 0; simplified = 1, forced = 2, optimized = 3, resulting = 4, related = 5,
double d_0; // initial value for optimization
double d_min; // bounds values for optimization
double d_max;
double d_opti; // result value of optimization
int d_type; ///< other = 0; simplified = 1, forced = 2, optimized = 3, resulting = 4, related = 5,
double d_0; ///< initial value for optimization
double d_min; ///< bounds values for optimization
double d_max; ///< bounds values for optimization
double d_opti; ///< result value of optimization
// the following variables are "comptute" in "MDS_opti_structurer"
int is_related; // unrelated = 0, master = 1, equal salve = 2, opposite slave = 3
int is_related; ///< unrelated = 0, master = 1, equal salve = 2, opposite slave = 3
struct MDS_d_data_strct *master_d_ptr;
double *d_ptr;
// link in the creation of mbs_data
double *MBSdata_d_ptr;
double *MBSdata_d_ptr; ///< link in the creation of mbs_data
} MDS_d_data_strct;
/**
* Structure defining the parent point of a body
*/
typedef struct MDS_ref_point_strct
{
char *bodyname;
char *pointname;
char *bodyname; ///< Name of the body that bear the reference point (origin of the joint chain until first body encounter).
char *pointname;///< Name of the reference point on the previous body.
} MDS_ref_point_strct;
/**
* This structure contains all information about a sensor defined on the MBS structure
*/
typedef struct MDS_sensor_strct
{
char *name;
char *name; ///< Name of the sensor
int Pos;
int Rot;
int Vit;
int Om;
int Acc;
int Omp;
int Jac;
int Pos; ///< 1 if the computation of the sensor position has been asked, 0 otherwise.
int Rot; ///< 1 if the computation of the sensor rotation matrix has been asked, 0 otherwise.
int Vit; ///< 1 if the computation of the sensor linear velocity has been asked, 0 otherwise.
int Om; ///< 1 if the computation of the sensor angular velocity has been asked, 0 otherwise.
int Acc; ///< 1 if the computation of the sensor linear acceleration has been asked, 0 otherwise.
int Omp; ///< 1 if the computation of the sensor angular acceleration has been asked, 0 otherwise.
int Jac; ///< 1 if the computation of the sensor Jacobian (\f$ \frac{dV_{sens}}{d\dot{q}} \f$) has been asked, 0 otherwise.
} MDS_sensor_strct;
/**
* This structure contains all information about an external force sensor defined on the MBS structure
*/
typedef struct MDS_extforce_strct
{
char *name;
int Pos;
int Rot;
int Vit;
int Om;
int Acc;
int Omp;
int Pos; ///< 1 if the computation of the sensor position has been asked, 0 otherwise.
int Rot; ///< 1 if the computation of the sensor rotation matrix has been asked, 0 otherwise.
int Vit; ///< 1 if the computation of the sensor linear velocity has been asked, 0 otherwise.
int Om; ///< 1 if the computation of the sensor angular velocity has been asked, 0 otherwise.
int Acc; ///< 1 if the computation of the sensor linear acceleration has been asked, 0 otherwise.
int Omp; ///< 1 if the computation of the sensor angular acceleration has been asked, 0 otherwise.
} MDS_extforce_strct;
/**
* This structure handle everything that a point on a MBS structure can handle (sensor, ...)
*/
typedef struct MDS_point_strct
{
char *name;
double *pt; // x y z
char *name; ///< Name of the point
double *pt; ///< Array with the coordinates (x, y, z) of the point relative to the origin of the body expressed in the body frame.
MDS_sensor_strct *sensor;
MDS_extforce_strct *extforce;
MDS_sensor_strct *sensor; ///< Pointer to a sensor structure if a sensor is defined on the point.
MDS_extforce_strct *extforce; ///< Pointer to an external force sensor structure if it is defined on the point.
MDS_d_data_strct **d_pt; // x y z
int is_symmmetric; // asymmetric = 0, symmetric master = 1, symmetric salve = 2
......@@ -76,48 +87,57 @@ typedef struct MDS_point_strct
} MDS_point_strct;
/**
* Structure handling the informations defined on the base of the MBS
*/
typedef struct MDS_base_strct
{
double *gravity; //x y z
int n_base_point;
MDS_point_strct **base_point_list;
double *gravity; ///< Array with the component (x, y, z) of the gravity vector expressed in the inertial frame.
int n_base_point; ///< Number of point of interest (extremities of joint bearing a sensor plus anchor point) defined on the MBS.
MDS_point_strct **base_point_list; ///< Array of pointers to the MDS_point_strct describing each point of the MBS.
} MDS_base_strct;
/**
* This structure contains all informations about a joint
*/
typedef struct MDS_joint_strct
{
char *name;
int type; // T1=1, T2=2, T3=3, R1=4, R2=5, R3=6
int nature; // independant=1, dependent=2, driven=3
char *name; ///< Name of the joint
int type; ///< Joint type: T1=1, T2=2, T3=3, R1=4, R2=5, R3=6
int nature; ///< Nature of the joint: independent=1, dependent=2, driven=3
double q0;
double qd0;
double qdd0;
double q0; ///< Initial position of the joint
double qd0; ///< Initial velocity of the joint
double qdd0;///< Initial acceleration of the joint
int actuated;
int actuated;///< For inverse dynamic only: 1 if actuated, 0 otherwise
MDS_d_data_strct *d_qf; // d_data for the forced q
int is_symmmetric; // asymmetric = 0, symmetric master = 1, symmetric salve = 2
char *symmetric_joint_name; // the name of the symmetric joint (filed if master, NULL if slave or non symetric)
MDS_d_data_strct *d_qf; ///< d_data for the forced q
int is_symmmetric; ///< asymmetric = 0, symmetric master = 1, symmetric salve = 2
char *symmetric_joint_name; ///< the name of the symmetric joint (filed if master, NULL if slave or non symetric)
} MDS_joint_strct;
/**
* This structure contains all informations about a body
*/
typedef struct MDS_body_strct
{
char *name;
char *name; ///< Name of the body.
MDS_ref_point_strct* parent;
MDS_ref_point_strct* parent; ///< Description of the parent point of the current body.
int n_joint;
MDS_joint_strct **joint_list;
int n_joint; ///< Number of joints leaving the body.
MDS_joint_strct **joint_list;///< Array of pointers to the MDS_joint_strct describing each joint leaving the body.
double mass;
double *com; //x y z
double *inertia; // Ixx Ixy Ixz Iyy Iyz Izz
double mass; ///< Mass of the body
double *com; ///< Array with the coordinate (x, y, z) of the center of mass of the body relative to the origin of the body expressed in the body frame.
double *inertia; ///< Array with the inertia tensor (Ixx, Ixy, Ixz, Iyy, Iyz, Izz) of the body relative to the center of mass expressed in the body frame.
int n_point;
MDS_point_strct **point_list;
int n_point; ///< Number of point defined on the body.
MDS_point_strct **point_list; ///< Array of pointers to the MDS_point_strct describing each point of current body.
} MDS_body_strct;
......
......@@ -45,15 +45,53 @@ int invdynared(MbsAux *mbs_aux, MbsData *s);
* \p s the MbsData of the system
*/
int mbs_calc_Fruc(double Fruc[], MbsAux *aux, MbsData *s);
/*! \brief compute a position of the multibody system which solves the constraints
*
* The algorithm is a Newton/Raphson procedure which solves the equation: \f$ v^{k+1} = v^{k}-\left(J_{v}\right)^{-1} h\f$.\n
* Robotran Basics Eq(17), chapter 3.2.1, pp. 12
*
* \param[in,out] s the MbsData structure.
* \param[in,out] mbs_aux the MbsAux structure related to the MbsData structure.
*
* \return the number of iterations needed to close the system
*/
int mbs_close_geo(MbsData *s, MbsAux *mbs_aux);
/*! \brief compute the dependent velocities that solves the constraints.
*
* The function solves the linear equation: \f$ \dot{v} = \textbf{B}_{vu} \dot{u} \f$.\n
* Robotran Basics Eq(18), chapter 3.2.1, pp. 12
*
* \param[in,out] s the MbsData structure.
* \param[in,out] mbs_aux the MbsAux structure related to the MbsData structure.
*/
void mbs_close_kin(MbsData *s, MbsAux *mbs_aux);
/*! \brief compute the current value of the constraints (\f$h(q)\f$) and the constraint Jacobian matrix (\f$\textbf{J}=\frac{\partial h(q)}{\partial q^t}\f$).
*
* \param[in,out] s the MbsData structure.
* \param[in,out] mbs_aux the MbsAux structure related to the MbsData structure.
*/
void mbs_calc_hJ(MbsData *s, MbsAux *mbs_aux);
/*! \brief compute the quadratic term of the constraints at acceleration level: \f$ \dot{\textbf{J}}\dot{q}(q,\dot{q}) \f$
*
* \param[in,out] s the MbsData structure.
* \param[in,out] mbs_aux the MbsAux structure related to the MbsData structure.
*/
void mbs_calc_jdqd(MbsData *s, MbsAux *mbs_aux);
/*! \brief compute the force and torques applied on the multibody system.
*
* Set the matrices MbsData::frc and MbsData::trq at zero, then compute the contribution of:
* - Links forces
* - Links 3D forces
* - External forces
* - Joints forces
*
* \param[in,out] s the MbsData structure.
*/
void mbs_calc_force(MbsData *s);
/*--------------------*/
......
......@@ -51,9 +51,8 @@ MbsDirdyn* mbs_new_dirdyn_aux(MbsData* mbs_data, MbsAux* mbs_aux);
*
* The MbsData structure associated to dirdyn is modified
*
* @param dirdyn the MbsDirdyn to be run
* @return the MbsDirdyn ...
*
* @param[in,out] dirdyn the MbsDirdyn to be run
* @param[in,out] mbs_data the MbsData structure of the model for which the direct dynamic is computed
*/
MBSYSC_MODULE_EXPORT void mbs_run_dirdyn(MbsDirdyn* dirdyn, MbsData* mbs_data);
......
......@@ -9,7 +9,10 @@
/**
* Allocate the memory for the Equilibrium Options (but not for all the Equilibrium structure)
* Initialize the options structure with default options
* Initialize the options structure with default options
*
* @param mbs_data the MbsData structure of the model for which the equilibrium will be computed
* @return An allocated MbsEquil structure.
*/
MbsEquil* mbs_new_equil(MbsData* mbs_data);
MbsEquil* mbs_new_equil_aux(MbsData* mbs_data, MbsAux* mbs_aux);
......@@ -18,7 +21,9 @@ MbsEquil* mbs_new_equil_aux(MbsData* mbs_data, MbsAux* mbs_aux);
* Free the Equilibrium structure (pointers table, Equibrium options, ...)
*
* The options (MbsEquilOptions) and MbsAux structures are also freed
*
*
* @param eq the MbsEquil to be freed
* @param mbs_data the MbsData structure of the model for which the equilibrium is deleted
*/
void mbs_delete_equil(MbsEquil* eq, MbsData* mbs_data);
......@@ -30,7 +35,8 @@ void mbs_delete_equil(MbsEquil* eq, MbsData* mbs_data);
*
* The MbsData structure associated is modified (equilibrium configuration, q,qd,Qq and possibly other parameters m,I,dpt, ... )
*
* @param eq the MbsEquil to be run
* @param mbs_equil the MbsEquil to be run
* @param mbs_data the MbsData structure of the model for which the equilibrium is computed
* @return the MbsEquil ...
*
*/
......
......@@ -46,8 +46,8 @@ MbsModal* mbs_new_modal_aux(MbsData* mbs_data,MbsAux* mbs_aux);
*
* The MbsData structure associated should not be modified ??QD
*
* @param mo the MbsModal to be run
* @return the MbsModal ...
* @param[in,out] mo the MbsModal to be run
* @param[in] s the MbsData structure of the model for which the modal analysis is computed
*
*/
void mbs_run_modal(MbsModal *mo,MbsData *s);
......
......@@ -16,11 +16,11 @@
*/
typedef struct MbsPartOptions
{
int rowperm; // no = 0, yes = 1, defaut = 0
int rowperm; ///< 1 to allow line permutation; 0 otherwise, defaut = 0
int visualise; // no = 0, yes = 1, defaut = 0
double treshold; // defaut = 1e-9
double treshold; ///< Maximal error on constraint allowed in Newton-Raphson algorithm, defaut = 1e-9
int drivers; // no = 0, yes = 1, defaut = 0
int verbose; // no = 0, yes = 1, defaut = 1
int verbose; ///< 1 to get print indications related partitioning module; 0 otherwise, defaut = 1
int clearmbsglobal; // inout = 1, out = 2, none = 3, all = 4, defaut = 1
} MbsPartOptions;
......@@ -35,26 +35,31 @@ typedef struct MbsPartOptions
typedef struct MbsPart
{
MbsPartOptions *options;
MbsPartOptions *options; ///< Structure containing the options for coordinate partitioning module
int n_qu;
int *ind_qu;
int n_qu; ///< Number of independent variable needed
int *ind_qu; ///< Array with the indices of best choice for independent variables
int n_qv;
int *ind_qv;
int n_qv; ///< Number of dependent variable needed
int *ind_qv; ///< Array with the indices of best choice and order for dependent variables
int n_hu;
int *ind_hu;
int n_hu; ///< Number of independent constraint
int *ind_hu; ///< Array with the indices of best choice for independent constraints
int n_hv;
int *ind_hv;
int n_hv; ///< Number of redundant constraint
int *ind_hv; ///< Array with the indices of best choice for redundant constraints
double *q_closed;
double *q_closed; ///< Array with the generalized coordinate in closed configuration (constraints solved)
} MbsPart;
#ifdef __cplusplus
extern "C" {
#endif
/**
* Main function of the coordinate partitioning module.
* \brief Main function of the coordinate partitioning module.
* It compute the coordinate partitioning for the given
* MbsData structure.
*
......@@ -63,35 +68,37 @@ typedef struct MbsPart
* part. must be performed
*
*/
#ifdef __cplusplus
extern "C" {
#endif
MBSYSC_MODULE_EXPORT int mbs_run_part(MbsPart* mbs_part, MbsData* mbs_data);
/**
* Allocate a new MbsPart structure.
* \brief Allocate a new MbsPart structure for the given MbsData structure.
* A new MbsPartOptions is also allocated and a pointer
* to this structure is kept from the new MbsPart.
* to this structure is kept from the new MbsPart.
*
* \param mbs_data the structure of the mbs for which the coordinate part. will be performed.
*/
MBSYSC_MODULE_EXPORT MbsPart* mbs_new_part(MbsData* mbs_data);
/**
* Free the memory of the given MbsPart structure.
* Th memory of the associated options (mbs_part->options)
* is also freed.
* \brief Free the memory of the given MbsPart structure.
* The memory of the associated options (mbs_part->options)
* is also freed.
*
* \param mbs_part the structure to be freed.
*/
MBSYSC_MODULE_EXPORT void mbs_delete_part(MbsPart* mbs_part);
/**
* Allocate a new MbsPartOptions structure and intialize
* options with default values.
* \brief Allocate a new MbsPartOptions structure and intialize
options with default values.
*/
MbsPartOptions* mbs_new_part_options(void);
/**
* Free the memory of the given MbsPartOptions structure.
* \brief Free the memory of the given MbsPartOptions structure.
* This function will be called by mbs_delete_part() and should never be called by the user.
*
* \param part_option_strct the structure to be freed.
*/
void mbs_delete_part_options(MbsPartOptions* part_option_strct);
......
......@@ -234,7 +234,7 @@ struct MbsData
int Nux; ///< Number of user variable.
// OTHER FIELDS //
double *udd; // axelle red
double *udd; ///< For axelle red: array with the values of the acceleration of independent coordinate
int DonePart; ///< Flag that indicates if the coordinate partitioning module has been executed (default: 0=not done; 1=done).
int DoneEquil; ///< Flag that indicates if the equilibrium module has been executed (default: 0=not done; 1=done).
......
......@@ -46,12 +46,12 @@ MbsLut2D* mbs_lut_2D_alloc();
/*! \brief Release memory used by 1D LUT structure
*
* \param[in,out] 1D LUT structure to release memory
* \param[in,out] lut 1D LUT structure to release memory
*/
void mbs_lut_1D_free(MbsLut1D *lut);
/*! \brief Release memory used by 2D LUT structure
*
* \param[in,out] 2D LUT structure to release memory
* \param[in,out] lut 2D LUT structure to release memory
*/
void mbs_lut_2D_free(MbsLut2D *lut);
......
/**
/** \file mbs_buffer.c
*
* Implements function defined in mbs_buffer.h
*
......
/**
/** \file mbs_buffer.h
*
* Define structures and function for storing results during simulation
* and writing them to disk.
......@@ -14,8 +12,9 @@
#define MBS_BUFFER_h
#include "mbsysc_utilities_export.h"
// IDs for the buffers
/**
* IDs for the buffers
*/
enum{BUFFER_Q, BUFFER_QD, BUFFER_QDD, BUFFER_QQ, BUFFER_UX, BUFFER_UXD,
BUFFER_LINK_Z, BUFFER_LINK_ZD, BUFFER_LINK_F, BUFFER_VISU, BUFFER_QC, BUFFER_OTHER};
......@@ -106,9 +105,14 @@ typedef struct MbsGrowingBuffer{
* Allocate and initialize a MbsBuffer structure.
* The associated text file defined by filename is (re-)initialized
*
* @param filename the name of the file associated to this buffer
* @param nx the size of the array to be tracked by this buffer
* @param size the size of the buffer
* @param[in] filename the name of the file associated to this buffer
* @param[in] anim_name the name of the file associated to the animation file (only used for ::BUFFER_Q)
* @param[in] nx the size of the array to be tracked by this buffer
* @param[in] size the size of the buffer
* @param[in] id the buffer ID, see ::BUFFER_Q, ::BUFFER_QD ...
* @param[in] save_anim 1 to save the anim file, 0 otherwise
* @param[in] save_visu 1 to save the visualization file (as it appears in 'user_realtime_visu.c'), 0 otherwise (for real-time simulation)
* @param[in] anim_period time interval between two recorded values in the animation file
*/
MBSYSC_UTILITIES_EXPORT MbsBuffer* mbs_new_buffer(char* filename, char* anim_name, int nx, int size, int id, int save_anim, int save_visu, double anim_period);
......@@ -116,6 +120,7 @@ MBSYSC_UTILITIES_EXPORT MbsBuffer* mbs_new_buffer(char* filename, char* anim_nam
*
* \param[in] max_nx maximum number of user inputs to save
* \param[in] size size of the buffer
* \param[in] respath path to the file for the results
* \return new growing buffer initialized
*/
MBSYSC_UTILITIES_EXPORT MbsGrowingBuffer* mbs_new_growing_buffer(int max_nx, int size, const char *respath);
......
......@@ -10,30 +10,112 @@
#ifndef mbs_matrix_h
#define mbs_matrix_h
/*--------------------*/
/*! \brief Compute the transpose of a matrix with first index is 1.
*
* The input and output matrices have unused index 0. See get_dmat_1() to such matrices creation.
*
* \param[in] M[4][4] matrix with first line and row unused.
* \param[in,out] Mt[4][4] the transpose of M, index starting at 1.
*/
void transpose(double M[4][4], double Mt[4][4]);
/*! \brief Compute the Euclidean norm of a double vector with first index is 1.
*
* The vector has unused index 0. See get_dvec_1() to such vector creation.
*
* \param[in] v[4] vector of size 4 with first element unused.
*
* \return The norm of the vector v.
*/
double norm(double v[4]);
/*! \brief Compute the normalize vector with first index is 1.