Package mbdyn

This package is based on the top of MBDyn, a MultiBody Dynamics software written at the university Politecnico di Milano. In MBDyn, a simulation is started by providing an input file describing reference frames, nodes and elements. This package motivation is to turn MBDyn into a multibody dynamics library for Python, so then the user communicates with objects during the whole simulation. He does not describe its problem by a MBDyn input file any more. But moreover he can interact with objects at run time.

1 MBDyn description

1.1 Thanks for this public service

1.2 Communication problematic with objects

User requirements

By using a general description with nodes and elements, almost all the quantities computed were output in text files. Just some of the objects could write optional results, like for example dynamic structural nodes, but it could not be specified for every integrated quantity. It sounds really optional. Why does the user need such feature? Because he knows its model and useless operations at run time are critical as many iterations are involved. Some of the items are used only for the model building but will not output any interesting results. A variant would be to perform different simulations for the same model, a particular behavior being investigated each time. For example, a node under constraints does not need to output all its degrees of freedom, some of them will inherently be out of interest. If the user just want to know about the position of a node, there is no need to output the rotation matrix, velocity and angular velocity. C++ is fast but why does it do many useless operations? The reason comes from the input file. The user has already to supply a value for every field. If moreover he has to specify each quantity to save, or may want a particular degree of freedom, the parameters to write are too numerous.

Forcing the user to supply every field is furthermore relevant for a beginner, but not so convenient for an end user. For example for every node, the user has to write the position, rotation matrix, velocity and angular velocity relative to a reference frame. But a node is supposed to inherit from the reference frame attributes. If those last ones already described the node, the values entered will be a null position, velocity and angular velocity, the rotation matrix will be the identity one. Most of the nodes will be like that because the user needs to set up reference frames for defining the initial conditions of a complex problem. Generally just one or two parameters are specified differently between a node and its reference frame. As a result, it could be convenient to have default value for every item (reference frame, node or element). It could also be useful to describe a custom item having default values suited for the simulation.

Developer difficulties

Conclusion

2 Providing new functionalities

2.1 Building models from Python

The first point to highlight, is that the situation is simpler than in the mbdyn.bindings module for the reason that the MBDyn service is not run. In the pre processing part, the task is finally to write a text file from Python in an object oriented way. This input file will start WraptMBDyn and once the interaction finished, the post processing is also done without a running MBDyn. This point makes the development simpler because it can always been done in Python. Thus there is not all the work of compiling a C++ shared library and SWIG extension with SCons , debugging memory allocation problems with GDB and so on. From here, how was Python used?

Python was used to describe an interface to every MBDyn object. The first advantage was the syntax (for example a class or function is defined by one keyword) and language features (list, dictionaries, everything object, third part packages). The crucial point is that Python allows references to objects. It would have been difficult, and also surely obscure, to write an interface to a C++ code in a language that does not support this feature because the MBDyn design uses it heavily. The disadvantage is for the user coming from a language that never deals with references, that is to say Matlab. In that case the language will of course be simpler (so commercial advertisements are more attractive) but also very limited. On that point Python does well because it only simplifies the pointer mechanism. For the user this is however very important to understand that once he has created an instance , he will always manipulate references to it. This is where the interface really starts to make sense. By using this package, the user first describes an object suited for his problem. Then only the MBDyn ones are going to be simulated but at each time step, in his script, he will have references to the objects current status and can use them to solve its specific problem. All the Python libraries and services are moreover available.

2.2 Pre-processing

Input file writing

Each object is responsible of writing its part of the input file. Those informations finally represent how MBDyn will instantiate the C++ objects. This process could certainly be done by Python but it will require further development. Moreover the input file is maybe an intermediate step to keep. First it allows to check how the Python package is working. The user could ignore the input file syntax but in case of a simulation crash, he can test it independently on the MBDyn executable. Moreover the C++ parser checks also for model consistency by requiring a 'control data' section. As a resume, the input file is probably a good idea for the systematic process of a solver.

Object description

   node1 = StructuralNode()
   node1.set_type("static")
   node2 = StructulalNode()

   # Description to continue

   begin: nodes;
       structural: 1, static,
       # description of node 1 goes here
       
       structural: 1, dynamic,
       # description of node 2 goes here
   
   end: nodes;

For the developers the situation becomes however really easier, because this is the user that choose the class from the library and create the instance. Thus he expresses more ideas than in a plain text file and he will directly dialog with the instance. In that case no tests are needed, if he fails in that part he will get a Python error. For scientists dealing with multibody dynamics problem, the Python bases are accessible very quickly. Similar simulations as the usual input files could be reproduced without many efforts.

But more can be done from that approach. When the user creates an instance, default settings are applied on it. They are described in the set_default method of every object, as a start the reader can see mbdyn.nodes and mbdyn.elements_base. If the user sets the node or element relative to a reference frame, the default properties will be updated in that base. There are however still some problems, warned in that place. But the design idea is to apply method on the object for handling options. For example the attributes that need to be saved on the item will be specified by the will_save, will_save_only and will_save_nothing methods applied on the Record class (base of the BasicObject and thus every item). Then the internal saving process is addressed in details in the post-processing section.

2.3 Post processing

Python interaction

Graphical exploration of results

Project for final animation

2.4 A resuming example

At that step it may be difficult to follow what represents each section and what has been concretely achieved. The following example try to illustrate it. It could be bombarded with criticisms for being actually too simple and idealistic. It is true that the package has not yet reached a mature status and some solutions are probably more complicated than what they should be. But this section aims at giving a picture of the functionalities researched.

   class HubNode(StructuralNode):
       pass

   class HubNode(StructuralNode):

       def __init__(self, name="hub node"):
           StructuralNode.__init__(self, name)
           self.set_type("dynamic")

   class HubNode(StructuralNode):

       def __init__(self, name="hub node"):
           StructuralNode.__init__(self, name)
           self.set_type("dynamic")
           self.rotational_speed = 0.
           self.will_save_only("rotational_speed")

   class HubNode(StructuralNode):

       def __init__(self, name="hub node"):
           StructuralNode.__init__(self, name)
           self.set_type("dynamic")
           self.rotational_speed = 0.
           self.will_save_only("rotational_speed")

       def save(self):
           rot_array = self.mbdyn_inst.get_rotational_speed()
           self.rotational_speed = rot_array[2][0]
           self.save_results()

   hub_node = HubNode("hub node")
   # initial conditions go here (reference frame, 
   # position, rotation_matrix...)

   # Problem description with others nodes and elements
   
   simu = Simulation()
   simu.add_node(hub_node)
   # others items are added

   simu.run()

   pyf = pyMBDynFile("rotor_simu.pymb", "w")
   pyf.add(simu)
   pyf.close()

   pyf = pyMBDynFile("rotor_simu.pymb")
   simu = pyf.simulations[0]
   strnodes = simu.nodes.structurals

   >>> hub = strnodes.get("hub node")
   >>> hub.results
   [rotational_speed]

   >>> import pylab as P
   >>> P.plot(simu.results.time, hub.results.rotational_speed)
   >>> P.show()

The rotational speed is available through the results attribute, instance of Results defined in mbdyn.quantity. With the three last lines, a figure showing the rotational speed according to the time should be plotted.

3 Conclusion

To conclude Python does not execute any integration but is just a language replacing the input file to describe a simulation. Its batteries included are however not a joke. Imitating the current way to write input files is possible but a complete programming language is now placed in the user hands. As a result he can describe its own objects that manipulate MBDyn ones, keep references of computed items, define its own and with some efforts extend the library for post-processing. This great flexibility has a price: the requirement to learn Python. But the reward is worth the hassle because the script is interactive and especially suited to his problem. Last but not least, third part packages could potentially improve the scientific usability of MBDyn: SciPy, PyDSTool, IPython, Matplotlib... to name a few. Is there still a reason to not dive into Python?