We are in the process of updating this documentation for OpenSim 4.0. Are you looking for OpenSim 3.3 documentation?



Python scripting is available from OpenSim 3.2, onward. The system architecture of Python & OpenSim must match (install 64-bit Python and 64-bit OpenSim) Python setup and configuration instructions are below.


Introduction to Python

Python is a widely used general purpose programming language. Python is free and open source, with a large user community that encourages sharing and user contributions. The Python language is very flexible, supporting object-oriented and procedural styles of computing. The Python design philosophy also emphasizes code readability which makes sharing and using code easier than with some other languages. 

Those from scientific and engineering backgrounds who are new to Python should check out the following resources to help get started with the language:

What's available?

  • Access to the OpenSim API to create and simulate models 
  • Users can instantiate and run tools from setup files or programmatically 
  • Repeated/batch runs of tools
  • Users can write "main" programs similar to those written by C++ developers, while taking advantage of the many open-source Python packages for data processing, statistics, machine learning, etc. 
  • A visualizer for API users that can be invoked through Python

Limitations

  • In this mode, there’s no access to the OpenSim plotter or the graphics window (use the model/API visualizer instead).
  • Some internal Simtk classes (that belong to the SimTK namespace and simbody internals) are not available for construction, but the most commonly used classes are available as of version 3.1 (SimTK::Vec3, Vector, Mat33, State, Inertia).
  • The Python package that comes with the OpenSim GUI distribution will only work with Python 2.7.x. For Python 3, you must build the OpenSim API (opensim-core) from scratch and set the CMake variable OPENSIM_PYTHON_VERSION to 3.

Setting up your Python scripting environment

Windows 

 

 Click here to expand...
There are a couple different options for setting up Python on your Windows machine. You will need the main Python package, as well as NumPy and SciPy. Alternatively, there are applications that bundle all the required packages and include an interface for scripting.  

This setup guide was written for Enthought Canopy, but Anaconda is currently much more popular. Both include NumPy, and SciPy.  You can also just set-up Python and the associated packages manually. We have tested all three methods, but currently advise you to use Anaconda. Make sure that you get 64-bit python if you are using 64-bit OpenSim libraries (and 32-bit python if using 32-bit OpenSim).

 

Package NameDownloadsCosts/licensing
Enthought Canopy

Canopy Application

Academic licenses can be granted with a '.edu' email address. Basic package costs $199 per/year.
Continuum Anaconda Anaconda ApplicationBasic package is free to download and use, contains Python 2.7 and other dependent packages. Cleanly installs into a single directory on your machine.
Python 2.7 Python.org

Numpy

SciPy

Free to use and download.

 

Installing Canopy and the "opensim" Python package

 

 Click here to expand...

Download and Install Canopy

Visit the Canopy website, apply for an academic licence, download, and install.

 

Insert OpenSim into the System Path

Navigate to the system settings panel. Choose Advanced System Settings' then Environment Variables'. Check that OPENSIM_INSTALL_DIRECTORY\bin is in system variables Path, where OPENSIM_INSTALL_DIRECTORY is the directory where you installed the current version of OpenSim (e.g. C:/OpenSim 3.2). Delete any multiple OpenSim Path entries.

Configure Canopy to be your Default Python Environment

Make Canopy your default Python environment as multiple distributions of Python can exist on your system. Checking that Canopy is the default Python environment is achieved in the Canopy editor. Open the Editor and navigate to Edit > Preferences.

Detailed instructions can be found at here.

Run the Setup File from Command Line

Open a command prompt (type cmd into the Windows run dialog box). Navigate to the OpenSim Installation folder and find the subfolder sdk which contains the script setup.py.

Run the python script by typing:

This will copy the required files and folders to a local directory associated with python libraries.

 

Test Installation

Test OpenSim in Canopy by typing;

 

If there is no error, then the installation worked.

 

Having trouble?

If you are having trouble with getting python wrapping to work on Windows, the issue is almost certainly one of the following:
  1. You are trying to use 32-bit python with 64-bit OpenSim libraries. If you are using 64-bit OpenSim libraries, make sure to use 64-bit python.
  2. OpenSim's dll's are not on your PATH. In a command window, you could achieve this with a command like "set PATH=C:\OpenSim 3.2\bin;%PATH%"

Mac

 Click here to expand...

macOS comes with Python 2.7, but you may also want to obtain Python through Homebrew or the Anaconda Python distribution. Note that the Python package that comes with the OpenSim GUI distribution was built to use the Python that comes with macOS, and it will not work with Homebrew's Python or with Anaconda Python; in the latter cases, you must compile OpenSim from the source code.

Navigate to the location of the opensim python package within the OpenSim installation. If you are using OpenSim's GUI distribution, this location is likely /Applications/OpenSim 4.x/sdk/Python. If you built OpenSim from source, this location is likely <OPENSIM_INSTALL_DIR>/lib/python2.7/site-packages. Perform the following (modifying the path below if necessary):

The OpenSim libraries must be on your DYLD_LIBRARY_PATH:

You can place the above `export` commands in your `~/.bash_profile` file so that they are set whenever you open up a new terminal.

You should be ready to use the Python wrapping now. Try the following from any directory:

 

Ubuntu

 Click here to expand...

We assume that you will use Python through the terminal. Open a new terminal window.

Navigate to the sdk/python folder in your OpenSim installation. Assuming that OpenSim is installed into directory OPENSIM_INSTALL_DIR, perform the following:

The above assumes that you've defined an environment variable OPENSIM_HOME via a command like:

The OpenSim libraries must be on your LD_LIBRARY_PATH:

You can place the above `export` commands in your `~/.bashrc` file so that they are set whenever you open up a new terminal.

You should be ready to use the Python wrapping now. Try the following from any directory:

Available Example Scripts

Scripts can are located in the OpenSim distribution in the sdk/Scripts/Python folder. 

Script Name

Description
build_simple_arm_model.pyThis script generates a simple arm model, runs a simulation, and visualizes the results.
wiring_inputs_and_outputs_with_TableReporter.pyThis script shows how to write model outputs (the position of a body) to a data file.

Pythonic extensions of the OpenSim API

We have add some pythonic aspects to our Python interface. All examples assume that you have already imported the opensim package ("import opensim").

Initializing a Vector from a Python list
Accessing elements of VecX and Vector using brackets
Printing the contents of a VecX or Vector
Getting the length of a VecX or Vector

You can use the built-in python function len() on VecX (e.g., Vec3) and Vector:

Iterate over elements of any Set

There are two iterators: one that treats the Set like a python list, and another that treats the Set like a python dict: