GSoC 2012 Application Angadh Nanjangud: sympy.physics.mechanics - sympy/sympy GitHub Wiki

About Me

I’m Angadh Nanjangud, a third year PhD student in the Mechanical and Aerospace Engineering Department at the University of California, Davis. The focus of my research is on the dynamics of variable mass systems. Over the course of my stay at UC Davis, I have taken courses on advanced and multi-body dynamics, mechanical design, advanced control systems and linear systems. Email- [email protected]; [email protected] Github- angadhn

Coding platform

I have been working on learning Linux and version control (Git and Github) in preparation for the Summer of Code. I am proficient programming in Matlab and LabView. I’ve been learning Python, SymPy (in particular, sympy.physics.mechanics) over the last three months. I opened pull request #1213 to meet SymPy’s patch requirement[0] for the GSoC. The patch I submitted tests the parallel axis theorem that is used in sympy.physics.mechanics Kane class, which was as yet untested. I also have familiarity with C and Mathematica.

Overview

sympy.physics.mechanics was developed as part of two previous GSoC projects by Luke Peterson and Gilbert Gede. It is a package geared towards the derivation of equations of motion for mechanical systems in classical mechanics, from simple particle motion to complex multi-body systems. To explain how it works in a brief manner, the package requires the user to define the parameters of the system such as the geometry, the mass and inertia associated with different components of the system, and the forces and torques acting on this system. Its algorithms determine both the kinematic relationships of the system configuration, i.e. the velocities and accelerations and the kinetics, and the forces and torques, acting on the system. These quantities and relationships can then be used to derive the equations of motion with various methods, with Kane’s method currently being the only automated method. All of this information can finally be used to obtain equations of motion, linear or non-linear, which can be solved to glean information on the trajectory of the motion of a system and/or its different components. I have been using sympy.physics.mechanics for about 3 months now to study various dynamical systems. The dynamical systems I studied using sympy.physics.mechanics over the last three months are the following-

a disk rolling on an inclined plane - a 1 degree of freedom (d.o.f) system
an inverted pendulum on a cart - a 2 d.o.f system
a conical pendulum - a 2 d.o.f. system
a child on a swing - a 1 d.o.f system The last of these systems was for a class project where a fairly comprehensive parametric study was performed on the pumping a swing whilst standing on it. I’ve found sympy.physics.mechanics to be an extremely powerful tool but there is considerable scope for improvement. To this effect I have made a list of primary and secondary goals.

Primary Goals

Helper functions- Autolev (now defunct) was a commercial software package which derives equations of motion of mechanical systems symbolically, and in many ways was the inspiration for sympy.physics.mechanics. It had a plethora of helper functions in addition to its main purpose of deriving equations of motion; it is my goal to add as many of those helper functions to the sympy.physics.mechanics. These helper functions will be of particular interest to dynamicists and will also be fruitful in implementing other methods commonly used in rigid body mechanics, the latter I discuss in my next goal. I have already identified a few of the helper functions that I think would be extremely beneficial for these purposes:

The momentum function will take a list of all the particles and/or bodies and determine the total linear momentum, total angular momentum about some point, and even possibly the generalized momentum as defined in [1] or any text on classical dynamics.
A similar function will be written for energies that will determine the kinetic and potential energies of the system, or parts of the system, as a function of time. These energies can then be used to compute the Lagrangian, which I discuss in detail in the next section.
Functions to determine partial velocities and partial angular velocities[2] with respect to generalized speeds.
Gravity helper function to attach gravitational forces to particles and bodies.
Explicit inertia manipulation in the tensor framework for translation and rotation.
Other helper functions of interest like gyrostat and autoz[3].

I will continue to peruse the literature and add several more helper functions which might be of immediate use. The helper functions mentioned above (from 1 through 4) will prove to be significant for my work in the next goal.The implementation of numbers 5 and 6 will not be focused upon until the completion of subsequent tasks but I will continue to formulate ideas with respect to the gyrostat and autoz helper functions.

Methods- sympy.physics.mechanics has many of the necessary tools to derive the equations of motion by any method (Newton-Euler, Gibbs-Appel, Lagrange, etc), but the only method which has been implemented in a generic fashion is Kane’s method. Kane’s method was chosen as the first implementation because it lends itself well to be design as a computer algorithm. Unfortunately, not everyone has an understanding of how Kane’s method works as it is a relatively less popular method to deriving the equations of motion due to its very recent development. So, I feel it is in the best interest to add at least one new automated method of equation of motion derivation to sympy.physics.mechanics. This will lead to a growing user base and will put it on par with other such symbolic packages. Lagrange’s and Newton-Euler methods are generally the more prominent ones, at least among rigid body dynamicists. After discussions with the developers (and possibly GSoC 2012 mentors) of the mechanics submodule, it was inferred that it would be ideal to implement Lagrange’s technique for unconstrained systems. This is because Lagrange’s method would be more tractable to implement than the Newton-Euler technique as some parts of its implementation could possibly be similar to implementation of Kane’s method; in both Kane and Lagrange methods, the non-contributing constraint forces can be left out. The same can’t be said for the Newton-Euler approach. I have already mentioned in goal 1 that helper functions will be significant to my work in goal 2 and I would like to explain that here; Lagrange’s technique[4] hinges upon the knowledge of kinetic energy and potential energy of the system to determine the Lagrangian[5], a scalar quantity, which is defined as the difference between the kinetic and potential energies. To obtain the equations of motion with Lagrange’s technique one also needs the partial velocities. All of these quantities will be available as helper functions at this point. Finally, all of this will be tied together as described in [4] and other classical mechanics textbooks to yield Lagrange’s equations of motion for unconstrained systems. The implementation of this technique would be less straightforward for constrained systems; determination of Lagrange multipliers[6] proves to be necessary when the system has either configuration or motion constraints. The unconstrained Lagrange method will cover the majority of use cases for simple systems. More work will be needed to properly add the constraints and the time required for its implementation might not fall within the boundaries of the GSoC timeline. I will work on this if I finish up subsequent tasks and have extra time. If all goes according to plan, the user should be able to generate equations of motion of unconstrained systems, say a simple pendulum, with a command as simple as ‘lagrange(simplependulum)’ once (s)he has it all configured. If all goes according to plan, the Lagrangian function may even prove to be useful in implementing a generic function in the SymPy variation module to compute ODEs.

Code output- Generating equations of motion would be trivial if one could not further analyse what the system does. Consequently, I will next look into code output, which was an unfinished secondary goal from last year’s project. Currently, the equations of motion generated in mechanics can generally only be solved numerically. This transition from the symbolic framework provided by SymPy to a numerical one requires dependencies such as SciPy, Matlab, Octave, etc. I’d like to create a code output module for supporting generic code output to any language. This would leverage SymPy’s generic code output functionality, potentially improve it and create a custom class structure for ode integration output code. The module would have a plugin architecture so that output code types could easily be implemented and the api for the input from various equation of motion generation classes would allow for easy addition of these too, with both the Kane and Lagrange classes as the working models. I will implement code output for the most popular languages. The code output will properly account for system inputs and outputs with specified quantities being treated separately. The following is example code showing possible functionality for outputting code from a Kane object for a single degree of freedom system:

## assuming a Kane object is already formed for a general system, it can be passed to the CodeOutput class
co = CodeOutput(kane, "outfile")

## get the default numerical physical parameters for the system 
par = co.get_parameters()

## provide numerical values for all of the system’s physical parameters: geometry, mass, inertia, friction, etc
co.set_parameters([1.72, 20, 9.81, 3, 60])

## get the default initial conditions
init = co.get_initialconditions()

## set the initial conditions of the states
co.set_initialconditions([.1, .106])

## specify a time vector
co.set_time_int([0,10,1000])

## create a configuration file with all of the previously defined settings and parameters
co.write_settings_file()

## writing the ode integration routine file  in the specified environment, in this case SciPy 
co.write_rhs_file(ode_integrator='SciPy')

## import the python file you just created and run the simulation
import outfile
results = outfile.main() # contains the time histories of the states, inputs and outputs

This basically involves writing all the parameters and initial conditions of our system to another file, which in this case is called ‘outfile’, and simulating it in SciPy. This example gives an idea of how the code output workflow may be designed. There are many details not present, such as specifying time varying inputs, but this gives the basic use case. Increasing the code output for multiple platforms such as C, Fortran, MATLAB, SciLab, GNU Scientific library, OCTAVE, etc. are obvious goals for this project. Being able to easily import the equations to the desired platform would make this package more appealing towards students, academicians and technicians so that people can then easily analyse these systems on the platform they are most comfortable with and provide options for speed and various other utilities. This would also make sympy.physics.mechanics a relatively complete dynamics package as systems can be configured, their equations of motion generated and then analyzed either within the Python environment or an environment more suited to the particular application domain.

Documentation- Apart from maintaining a weekly blog post and working on the documentation for the tasks defined above, I will improve existing documentation to make it more accessible to the novice user. The current documentation on sympy.physics.mechanics assumes basic knowledge of undergraduate dynamics or that a user is in a class where he/she is learning dynamics along with sympy.physics.mechanics. Ideally the user could learn to use the package without any prior introduction to the material. This would involve the following-

Documentation will be developed for the worked examples in [2]. As [2] is available as a pdf on the internet, it will be assumed that the user has access to the requisite theory. This part of documentation will focus on implementing the relevant theory. The documentations will thus start at kinematics and end at the equation of motion derivation using [2] as a rigid guideline.
More worked examples to train the user to completely derive equations of motion for systems with various EoM derivation techniques. This would be in done in a manner where the complexity of systems increases as the user gains more experience and intuition.
Writing workbooks so that the users can learn to implement the knowledge that they gained on the package.
API and example use documentation on the new functionality created during the summer.

I also envision making use of the iPython notebooks and/or Sage so that the users can concentrate on learning the package and bypass having to deal with setup of Python on their computers. Sage has an online interface and iPython notebooks can be run from a server. This will facilitate the understanding of the intricacies of each line of code that is written by the user.

Secondary Goals

Code optimization- As has been documented in [7], two operations are extremely time consuming for complex systems: substitution and differentiation. For example, we’ve found that the solution to the bicycle example takes about 30 minutes to compute. Thus, the idea here is to investigate the .subs() and .diff() commands and make requisite changes to speed them up. The contribution of this would not benefit just users of the mechanics submodule but users of sympy in general. I will spend time learning how these algorithms are implemented, research alternatives and improvements, and finally implement the faster versions in the SymPy codebase.

Even more methods!!- In the ‘Methods’ section of my primary goals I mentioned the Newton-Euler method. Newton’s second law state[8] that the net force acting on a particle is equal to the time rate of change of its linear momentum. Similarly Euler has a second law of motion which states that [9] the net external moments acting on a body is equal to the time rate of change of angular momentum about a point. What this means is that, in theory, the implementation of these equations would be straightforward as by this time in the project, I would have already implemented the helper functions for momenta. Also, the force list is already available in sympy.physics.mechanics. But the reality is that its implementation isn’t as straightforward as one would assume; this method requires the inclusion of all forces acting within a system whether they be contributing (forces that do work) or non-contributing (forces that don’t do work) whereas the Kane and Lagrange methods consider only contributing forces. Traditionally these non-contributing forces cancel out and the ultimate equations from the Newton-Euler method are identical to those from the other two method but the hurdle for the implementation of the Newton-Euler method is that the symbolic manipulation required for said cancellation might not be performed effectively using any CAS software such as SymPy. Thus, the Newton-Euler technique implementation may not be trivial. In the event that I accomplish all the goals I have identified up to this one (both primary and secondary), I will begin to thoroughly investigate problems associated with the implementation of the Newton-Euler method and find effective ways to tackle them.

Timeline

My timeline is as follows-

pre-GSoC Familiarization period- I will be working on getting to know the SymPy community better, survey the existing documentation on SymPy and its subsidiaries to further my knowledge on Python and SymPy. I will survey the Autolev tutorial and also begin working on goal 1 described above. This is because I will be unable to devote 40 hours in the first couple of weeks as defined by the GSoC calendar as it corresponds to the last few days of school here (which are the busiest of the quarter). So, I will distribute those hours in this period and over the summer as I have no other breaks planned then. I will also begin to plan out the documentation structure more rigorously. Details of my approach to goal 1 are discussed next.
Weeks 1 and 2- I will write code for the helper functions. I will submit a pull request at completion of all the helper functions. I’m fairly confident that I will come across more helper functions than I have listed in this proposal during my survey period. I will also write tests for every function and class I implement. I will simultaneously work on documentation on usage of helper functions at this stage. Write tests for the helper functions.
Weeks 3, 4 and 5- I will work on the Lagrange technique for unconstrained systems in this phase. I will also conduct necessary tests and then a pull request will be submitted once I have the technique implemented. The test will be done by verifying that the equations of motion for a particular system using two distinct methods (i.e. Kane and Lagrange) are identical. Continue work on documentation for this stage which will involve some examples on how to use this method. At this stage it will also be time for the midterm evaluation.
Weeks 6, 7 and 8- Identify the most commonly used environments for analysis, research how to generate outputs for these environments in order of popularity and implement necessary code. Pull request will be submitted at completion of code output for each environment. I will then work on documentation on how the code output functionality can be employed for each platform.
Weeks 9 and 10- Work and finish up documentation as described in my final primary goal (i.e. workbooks, ipython notebook, etc). Polish up all my code, which will probably be needed. I will also work on the secondary goals in these weeks.
Weeks 11 and 12- Work on secondary goals in the following order; improving the .subs() and .diff() commands and iron out the kinks and follow that up with work on the Newton-Euler method. Pull request will be submitted upon completion of work on each of the commands.

As already mentioned above, I may be unable to commit 40 hours in the opening couple of weeks (May 23-June 5) after which I will be committing a full 40 hours/week at the least. As I have no other breaks planned for the summer, I’m sure I can squeeze in the hours that I miss in the first week or two. I will strictly adhere to this timeline to the best of my ability. All efforts will be made to open pull requests consistently through the summer. I feel I’m a strong candidate for this project as I have significant prior experience using sympy.physics.mechanics along with a strong foundation in rigid body dynamics. I firmly believe that with these ideas that I have laid out, sympy.physics.mechanics will be a more powerful and alluring proposition to academicians and dynamicists everywhere.

References-

[0] https://github.com/sympy/sympy/pull/1213

[1] ‘Principle of Dynamics’ by Donald T. Greenwood

[2] ‘Dynamics: Theory and Application’ by Thomas R. Kane and David Levinson

[3] ‘Autolev Tutorial’ by Paul Mitiguy and Keith Reckdahl

[4] http://en.wikipedia.org/wiki/Lagrangian_mechanics#cite_note-6

[5] http://en.wikipedia.org/wiki/Lagrangian

[6] http://en.wikipedia.org/wiki/Lagrange_multiplier

[7]http://docs.sympy.org/dev/modules/physics/mechanics/advanced.html#future-features

[8]http://en.wikipedia.org/wiki/Newton%27s_laws_of_motion#Newton.27s_second_law

[9] http://en.wikipedia.org/wiki/Euler%27s_laws_of_motion