Skip to main content

Python tool kit for multi-body dynamics.

Project description

Latest Released Version anaconda Documentation Status github-build

PyDy, short for Python Dynamics, is a tool kit written in the Python programming language that utilizes an array of scientific programs to enable the study of multibody dynamics. The goal is to have a modular framework that can provide the user with their desired workflow, including:

  • Model specification

  • Equation of motion generation

  • Simulation

  • Visualization

  • Benchmarking

  • Publication

We started by building the SymPy mechanics package which provides an API for building models and generating the symbolic equations of motion for complex multibody systems. More recently we developed two packages, pydy.codegen and pydy.viz, for simulation and visualization of the models, respectively. This Python package contains these two packages and other tools for working with mathematical models generated from SymPy mechanics. The remaining tools currently used in the PyDy workflow are popular scientific Python packages such as NumPy, SciPy, IPython, Jupyter, ipywidgets, pythreejs, and matplotlib which provide additional code for numerical analyses, simulation, and visualization.


We recommend the conda package manager and the Anaconda or Miniconda distributions for easy cross platform installation.

Once Anaconda (or Miniconda) is installed type:

$ conda install -c conda-forge pydy

Also, a simple way to install all of the optional dependencies is to install the pydy-optional metapackage using conda:

$ conda install -c conda-forge pydy-optional

Note that pydy-optional currently enforces the use of Jupyter 4.0, so you may not want to install into your root environment. Create a new environment for working with PyDy examples that use the embedded Jupyter visualizations:

$ conda create -n pydy -c conda-forge pydy-optional
$ conda activate pydy
(pydy)$ python -c "import pydy; print(pydy.__version__)"

Other installation options

If you have the pip package manager installed you can type:

$ pip install pydy

Installing from source is also supported. The latest stable version of the package can be downloaded from PyPi[1]:

$ wget

and extracted and installed[2]:

$ tar -zxvf pydy-X.X.X.tar.gz
$ cd pydy-X.X.X
$ python install


PyDy has hard dependencies on the following software[3]:

  • Python >= 3.7

  • setuptools >= 44.0.0

  • NumPy >= 1.16.5

  • SciPy >= 1.3.3

  • SymPy >= 1.5.1

  • PyWin32 >= 219 (Windows Only)

PyDy has optional dependencies for extended code generation on:

and animated visualizations with Scene.display_jupyter() on:

or interactive animated visualizations with Scene.display_ipython() on:

The examples may require these dependencies:


This is an example of a simple one degree of freedom system: a mass under the influence of a spring, damper, gravity and an external force:

/ / / / / / / / /
  |    |     |   | g
  \   | |    |   V
k /   --- c  |
  |    |     | x, v
 --------    V
 |  m   | -----
    | F

Derive the system:

from sympy import symbols
import sympy.physics.mechanics as me

mass, stiffness, damping, gravity = symbols('m, k, c, g')

position, speed = me.dynamicsymbols('x v')
positiond = me.dynamicsymbols('x', 1)
force = me.dynamicsymbols('F')

ceiling = me.ReferenceFrame('N')

origin = me.Point('origin')
origin.set_vel(ceiling, 0)

center = origin.locatenew('center', position * ceiling.x)
center.set_vel(ceiling, speed * ceiling.x)

block = me.Particle('block', center, mass)

kinematic_equations = [speed - positiond]

force_magnitude = mass * gravity - stiffness * position - damping * speed + force
forces = [(center, force_magnitude * ceiling.x)]

particles = [block]

kane = me.KanesMethod(ceiling, q_ind=[position], u_ind=[speed],
kane.kanes_equations(particles, loads=forces)

Create a system to manage integration and specify numerical values for the constants and specified quantities. Here, we specify sinusoidal forcing:

from numpy import array, linspace, sin
from pydy.system import System

sys = System(kane,
             constants={mass: 1.0, stiffness: 10.0,
                        damping: 0.4, gravity: 9.8},
             specifieds={force: lambda x, t: sin(t)},
             initial_conditions={position: 0.1, speed: -1.0},
             times=linspace(0.0, 10.0, 1000))

Integrate the equations of motion to get the state trajectories:

y = sys.integrate()

Plot the results:

import matplotlib.pyplot as plt

plt.plot(sys.times, y)
plt.legend((str(position), str(speed)))
plt.xlabel('Time [s]')


The documentation for this package is hosted at but you can also build them from source using the following instructions.

To build the documentation you must install the dependencies:

To build the HTML docs, run Make from within the docs directory:

$ cd docs
$ make html

You can then view the documentation from your preferred web browser, for example:

$ firefox _build/html/index.html

Modules and Packages

Code Generation (codegen)

This package provides code generation facilities. It generates functions that can numerically evaluate the right hand side of the ordinary differential equations generated with sympy.physics.mechanics with three different backends: SymPy’s lambdify, Theano, and Cython.

Models (

The models module provides some canned models of classic systems.

Systems (

The System module provides a System class to manage simulation of a single system.

Visualization (viz)

This package provides tools to create 3D animated visualizations of the systems. The visualizations utilize WebGL and run in a web browser. They can also be embedded into an IPython notebook for added interactivity.

Development Environment

The source code is managed with the Git version control system. To get the latest development version and access to the full repository, clone the repository from Github with:

$ git clone

You should then install the dependencies for running the tests:

Isolated Environments

It is typically advantageous to setup a virtual environment to isolate the development code from other versions on your system. There are two popular environment managers that work well with Python packages: virtualenv and conda.

The following installation assumes you have virtualenvwrapper in addition to virtualenv and all the dependencies needed to build the various packages:

$ mkvirtualenv pydy-dev
(pydy-dev)$ pip install numpy scipy cython nose theano sympy ipython "notebook<5.0" "ipywidgets<5.0" version_information
(pydy-dev)$ pip install matplotlib # make sure to do this after numpy
(pydy-dev)$ git clone
(pydy-dev)$ cd pydy
(pydy-dev)$ python develop

Or with conda:

$ conda create -c pydy -n pydy-dev setuptools numpy scipy ipython "notebook<5.0" "ipywidgets<5.0" cython nose theano sympy matplotlib version_information
$ source activate pydy-dev
(pydy-dev)$ git clone
(pydy-dev)$ cd pydy
(pydy-dev)$ conda develop .

The full Python test suite can be run with:

(pydy-dev)$ nosetests

For the JavaScript tests the Jasmine and blanket.js libraries are used. Both of these libraries are included in pydy.viz with the source. To run the JavaScript tests:

cd pydy/viz/static/js/tests && phantomjs run-jasmine.js SpecRunner.html && cd ../../../../../


Run the benchmark to test the n-link pendulum problem with the various backends:

$ python bin/ <max # of links> <# of time steps>


If you make use of PyDy in your work or research, please cite us in your publications or on the web. This citation can be used:

Gilbert Gede, Dale L Peterson, Angadh S Nanjangud, Jason K Moore, and Mont Hubbard, “Constrained Multibody Dynamics With Python: From Symbolic Equation Generation to Publication”, ASME 2013 International Design Engineering Technical Conferences and Computers and Information in Engineering Conference, 2013, 10.1115/DETC2013-13470.

Questions, Bugs, Feature Requests

If you have any question about installation, usage, etc, feel free send a message to our public mailing list.

If you think there’s a bug or you would like to request a feature, please open an issue on Github.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydy-0.7.1.tar.gz (6.6 MB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page