MBsysPy.mbsyspy.mbs_dirdyn module

Module to handle direct dynamics simulations on Multibody systems.

Summary

Define the class MbsDirdyn based on the MbsDirdyn structure of MBsysC. This class has the functions required to manipulate the direct dynamic module. This includes setting the options, running an(or multiple) analysis and freeing the memory.

class MBsysPy.mbsyspy.mbs_dirdyn.MbsDirdyn(mbs, user_path=None, symbolic_path=None)

Bases: object

Class of the direct dynamic module.

Variables
  • dt (double) – Current integration step size.

  • mbs (MbsData) – Instance of MbsData related to the analysis.

  • results (MBsysPy.MbsResult) – Instance of MbsResult containing the results of the direct dynamics analysis.

  • symbolic_path (str) – Path to the folder containing the symbolic functions(python modules) to be loaded.

  • tsim (double) – Current simulation time.

  • user_path (str) – Path to the folder containing the user functions(python modules) to be loaded.

Examples

>>> mbs_data = MBsysPy.MbsData("../dataR/ExampleProject.mbs")
>>> mbs_dirdyn = MBsysPy.MbsDirdyn(mbs_data)
>>> mbs_dirdyn.set_options(t0 = 5, tf = 10)
>>> mbs_dirdyn.get_options("t0", "tf")
(5.0, 10.0)
>>> results = mbs_dirdyn.run()
Attributes
buffer_nb

Access to bufferNb attribute (read-only).

dt

Access to dt attribute (read-only).

tsim

Access to tsim attribute (read-only).

Methods

get_options(self, *args)

Get the specified options for Dirdyn module.

run(self, **kwargs)

Run a direct dynamics analysis.

set_options(self, **kwargs)

Set the specified options for Dirdyn module.

set_user_fct_from_file(self, function_name, …)

Load a user function from a file chosen by the user instead of the default one in the userfctR folder.

set_user_fct_from_ptr(self, function_name, …)

Load a user function chosen by the user instead of the default one in the userfctR folder.

__init__(self, mbs, user_path=None, symbolic_path=None)

Create an instance of the MbsDirdyn class for the provided MbsData instance.

Parameters
  • mbs (MbsData) – Instance of MbsData related to the analysis.

  • user_path (str or None, optional) – The path to the folder containing the user functions. If not provided (‘None’) the path is retrieved from the MbsData instance ‘mbs’.

    default is None

  • symbolic_path (str or None, optional) – The path to the folder containing the symbolic functions. If not provided(‘None’) the path is retrieved from the MbsData instance ‘mbs’. default is None

Returns

MbsDirdyn – A MbsDirdyn instance.

Return type

self

property buffer_nb

Access to bufferNb attribute (read-only).

property dt

Access to dt attribute (read-only).

get_options(self, *args)

Get the specified options for Dirdyn module.

Parameters

The different options specified in the documentation of ‘set_options()’

Returns

Return type

The value of the different options specified in the documentation of ‘set_options()’

run(self, **kwargs)

Run a direct dynamics analysis.

Options can be set with the function ‘set_options()’ before calling this function. Options can be retrieved with the function ‘get_options()’.

Results are stored in the field ‘results’ if the options ‘store_results’ is set to True.

Returns

self.results – The MbsResults containing the results of the analysis.

Return type

MbsResult

set_options(self, **kwargs)

Set the specified options for Dirdyn module.

Parameters
  • t0 (float) – Initial time of the simulation. default is 0.0

  • tf (float) – Final time of the simulation default is 5.0

  • dt0 (float) – Initial value of the integration step size. For fixed-step integrator (ie. RK4, Euler explicit…) this is the time step for the whole simulation.

    default is 0.001

  • save2file (int) –

    Determine whether results are written to files on disk(in resultsR folder):
    • 1: results are saved

    • 0: results are not saved

    default is 1

  • resfilename (str) – The keyword used for determining the name of result files. The default value is set to ‘oneshot’ (instead of ‘dirdyn’) if ‘flag_oneshot’ is True. default is ‘dirdyn’

  • respath (str) – Path in which result file are saved. This is the full path or the relative path. The folder must exist. default is the ‘resultsR/’ folder of the project

  • animpath (str) – Path in which animation file is saved. This is the full path or the relative path. The folder must exist. default is the ‘animationR/’ folder of the project

  • save_anim (int) – 1 to save the animation file, if ‘save2file’ is set to 1. Set to 0 to not save the animation file. default is 1

  • save_visu (int) – Unused options as realtime is deactivated is MBsysPy. 1 to save the visualization file(as it appears in ‘user_realtime_visu.c’), if ‘save2file’ is set to 1. Set to O to not save the visualization. default is 0

  • framerate (int) – number of frame per second for the animation file. default is 1000

  • saveperiod (int) – The number of time steps between two buffer records. default is 1(every time step are recorded)

  • max_save_user (int) – The maximal number of user variables saved. default is 12

  • buffersize (int) – The number of time step that can be recorded in the buffer. Results are written to disk when the buffer is full. Writing to disk is slow. If set to -1, it computes the buffer size for saving results only once at the end according to dt0, t0 and tf. default is -1

  • buffer_format (str) – The format for saving the data (double) to file. For example set “%.3e” to use scientific notation with 3 decimal. defaut: ‘%e’.

  • realtime (int) – Unused options as realtime is deactivated is MBsysPy. 1 to activate to real-time features, 0 to deactivate them. default = 0

  • accelred (int) – 1 to use accelred, 0 otherwise. default is 0

  • flag_oneshot (int) – Set to 1 to compute the derivative function only once (no time integration). Then default resfilename is set to ‘oneshot’. The time is the value found in the option t0 (used by user functions). default is 0

  • flag_compute_Qc (int) – If 1 it computes the forces/torques applied in each driven joints in order to follow the specified trajectory. Otherwise the forces/torques are only computed in the joints specified in the option ‘compute_Qc’. Setting the option to 0 speeds up the computation. default is 1

  • compute_all_uxd (int) – If 1 the user derivative are computed during the analysis. Otherwise If set to 0, they are not computed. default is 1

  • compute_Qc (numpy.ndarray) – If option “flag_compute_Qc’ is set to 0, the vector allows to select the(driven) joints on which the force/torque required to follow the trajectory will be computed. The shape of the array is ‘(mbs.njoint + 1)’, for example with ‘compute_Qc = numpy.array([mbs.njoint 1 0 0 1 0])’, we will compute Qc(1) and Qc(4) only, on a mbs made of 5 joints. compute_Qc[0] is always mbs.njoint default is an array full of zero(no forces computation)

  • integrator (str) – Set integrator to use, available values are:

    • “RK4”: explicit Runge–Kutta method order 4
      • fixed stepsize

    • “Dopri5”: explicit Runge–Kutta method of order(4)5
      • adaptive stepsize

    • “Rosenbrock”: implicit fourth-order Rosenbrock
      • adaptive stepsize

      • for stiff problems

    • “EulerEx”: Euler explicit method
      • fixed stepsize

    • “Eulaire”: Modified Euler explicit method
      • fixed stepsize

    • “EulerIm”: Euler implicit method
      • fixed stepsize

      • for stiff problems

    • “WMethods”: Implicit Euler extended to two stages
      • for stiff problems

    • “Bader”: Semi-implicit midpoint rule method
      • adaptive stepsize

      • for stiff problems

    • “AlphaM”: Explicit integrator simplification of alpha-method.
      • fixed stepsize

      • multistep method

    default is “RK4”

  • verbose (int) – Set to 1 to get messages related to adaptive stepsize integrator. To disable message set to 0. default is 1

  • flag_stop_stiff (int) – For adaptive stepsize integrator, set at 1 to stop integration if the systems become too stiff. Set it at 0 to continue integration. default is 0

  • flag_precise_dynamics (int) – Flag to set which values are saved in the output files. This only changes the value save to the output files not the simulation results.

    If set at 1, the direct dynamics(constraint solving, computation of the generalized acceleration) will be done at the beginning of each time step of integration. The output files will be exact, but the computation will be a little slower. If set at 0, the output file will contains the value(constraint solution and the generalized acceleration) of the last computation of the integrator. The values may be the one used for an internal step of the integrator, but the computation is a little faster.

    default is 1

  • flag_baumgarte_stabilization (int) – Flag to use the baumgarte stabilization of the independent accelerations. default is 0

  • baumgarte_alpha (float) – Alpha parameter of baumgarte stabilization (>0) in 1/s. default = 0.1

  • baumgarte_beta (float) – Beta parameter of baumgarte stabilization (>0) in 1/s. default = 0.1

  • flag_waypoint (int) – If set to 1, the integrator will be forced to give a solution at the specified time interval(‘delta_t_wp’). If set to 0, the solution will be given at every computed time-step. default is 0

  • flag_solout_wp (int) – Only used if ‘flag_waypoint’ is 1. In that case if set to 1, the integration results will only contains the value at the specified time interval(‘delta_t_wp’). Otherwise the solution will contain all the timesteps and the waypoints. default is 0

  • delta_t_wp (float) – Time interval between two waypoints [s], unused if ‘flag_waypoint’ is set to 0. default is 1.0e-3

  • nmax (int) – maximal number of steps for adaptive stepsize integrators. default is 1e9

  • toler (float) – mixed error tolerances for some adaptive stepsize integrators. default is 1.0e-3

  • rtoler (float) – relative error tolerances for some adaptive stepsize integrators. default is 1.0e-3

  • atoler (float) – absolute error tolerances for some adaptive stepsize integrators. default is 1.0e-6

  • dt_max (float) – maximal time step [s] for some adaptive stepsize integrators. default is 1.0e-3

  • n_freeze (int) – number of time step when the jacobian is freezed(computed once at the start of the n_freeze time steps) for implicit integrators. default is 0

  • show_failed_closure (int) – If set to 1, an animation of the Newton-Raphson procedure is generated if the closure fails. default is 0

  • store_results (int) – If set to 1, a copy of the results is done. default is 1

set_user_fct_from_file(self, function_name, user_path, user_file)

Load a user function from a file chosen by the user instead of the default one in the userfctR folder.

The function is then unassigned by the module at the end of the run().

Parameters
  • function_name (str) – name of the user function to replace.

  • user_path (str) – path to the new user function file.

  • user_file (str) – name of the new user function file.

set_user_fct_from_ptr(self, function_name, user_fct_ptr)

Load a user function chosen by the user instead of the default one in the userfctR folder.

The function is then unassigned by the module at the end of the run().

Parameters
  • function_name (str) – name of the user function to replace.

  • user_fct_ptr (ptr) – new user function pointer.

property tsim

Access to tsim attribute (read-only).