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:

• Python wikipedia
• python.org
• Python vs Matlab
• Google Python classes
• Python style guide (PEP8)
• Structuring a Python project
• Anaconda Application
• Conda user guide

Setting up your Python scripting environment

Conda packages

The fastest way to get started with OpenSim scripting with Python is to install one of our pre-built Conda packages. We highly recommend trying this option first before a manual installation, especially if you have not used Python before.

For information about how to install Conda and create a Python environment, please consult the Conda user guide. Once you have Conda installed and activated in your terminal (or Anaconda prompt), use the following commands to create and activate a new Conda environment.  

$ conda create -n opensim_scripting python=3.11 numpy
$ conda activate opensim_scripting

Note that the environement name opensim_scripting can be changed to any environment name you choose.

Once you've created a Conda environment, use the following command to install the latest version of OpenSim that is compatiable with your environment.

$ conda install -c opensim-org opensim

The following table summarizes the available packages that can be installed.

To install a specific version, find the package name matching the version you want in the list of packages hosted on Anaconda.org. For example, to install OpenSim 4.4 into a Python 3.10 environment (which requires NumPy 1.21), you would use the following command.

$ conda install -c opensim-org opensim=4.4=py310np121

OpenSim Conda packages that include Moco are available for OpenSim 4.4, 4.4.1, and 4.5, but only for Windows. Use the following command to install these packages.

$ conda install -c opensim-org opensim-moco

If possible, we recommend using the Conda packages with the latest OpenSim version which includes Moco and all of the latest features in the OpenSim API. 

Manual installation (OpenSim 4.3 or later)

It is possible to manually install the OpenSim Python bindings, but this approach comes with a few caveats:

1.  If installing from a GUI distribution with OpenSim 4.3 or later, only Python 3.8 is supported.
2. While it is not necessary to use Conda to create a Python environment, you must use a 64-bit version of Python.
3. If you want to create a manual installation with a different version of Python, you must build the Python bindings from source.

The following instructions will refer to a directory <OPENSIM_INSTALL_DIR>, where you installed some version of OpenSim. On Windows this might look like C:\OpenSim 4.X, and on MacOS it might look like /Applications/OpenSim 4.X. The installation directory can be identified by the subfolders "bin" and "sdk". If you built from source on Mac or Linux, where the installation directory might use a Unix-like folder structure with subfolders "lib", "libexec", and "share".

To install, first navigate to the location of the OpenSim Python package within the OpenSim installation. If you are using OpenSim's GUI distribution, this location is <OPENSIM_INSTALL_DIR>/sdk/Python. If you built OpenSim from source on Mac or Linux, this location is likely <OPENSIM_INSTALL_DIR>/lib/python3.x/site-packages.

If on Windows, you may need to run the following command when using OpenSim 4.3 or later with Python 3.8. (If setup_win_python38.py does not exist in your distribution, then you can skip this step.)

$ python setup_win_python38.py

To install the OpenSim Python bindings on all platforms, run the following command. Note that if you have a Conda environment activated, this command with install OpenSim as a package into your Conda environment.

$ python -m pip install .

On Windows, you will likely need to set the Path environment variable to point to the "bin" folder in your OpenSim installation. To do this:

1. Press the Windows key and search for "Edit the system environment variables". Click the top search result.
2. Click "Environment Variables..." in the bottom right corner. Look for Path under "System variables".
3. Highlight the Path entry and click "Edit...".
4. Add a new entry with value <OPENSIM_INSTALL_DIR>/bin and move it to the top of the list.
5. Restart your terminal for the change to Path to take effect before testing your Python installation.

On Mac, you may need to update the DYLD_LIBRARY_PATH environment variable to point to the OpenSim and Simbody libraries. 

$ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:<OPENSIM_INSTALL_DIR>/sdk/lib
$ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:<OPENSIM_INSTALL_DIR>/sdk/Simbody/lib

You can place export commands in your ~/.bashrc file (or other terminal configuration file) so that they are set whenever you open up a new terminal.

Similarly on Linux, you may need to updated LD_LIBRARY_PATH.

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<OPENSIM_INSTALL_DIR>/sdk/lib
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<OPENSIM_INSTALL_DIR>/sdk/Simbody/lib

Installing older OpenSim and Python versions (OpenSim 4.2 or earlier)

While we strongly recommend upgrading to a recent version of OpenSim and using the install instructions above, for legacy purposes, you may expand the following section to install older versions of OpenSim and Python.

$ export PYTHONPATH=<OPENSIM_INSTALL_DIR>/sdk/Python:$PYTHONPATH

$ python setup.py install

$ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:<OPENSIM_INSTALL_DIR>/lib
$ sudo python setup.py install

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<OPENSIM_INSTALL_DIR>/lib
$ sudo python setup.py instal

Testing your installation 

After activating your Conda environment (or manually installed Python environment), run the following commands to test your OpenSim installation.

$ python
>>> import opensim as osim
>>> osim.GetVersionAndDate()

Troubleshooting

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 DLLs are not on your PATH. In a command window, you could achieve this with a command like "set PATH=C:\OpenSim 4.0\bin;%PATH%"
3. There are 2 possible architectures on OSX: arm64 and intel x86_64. There're conda packages for both, however the GUI distribution includes ONLY x86_64 build with Python 3.8. MacOS comes with some version of Python, 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.

v = opensim.Vector([6, 7, 8, 9])
rv = opensim.RowVector([1, 2, 5])

v = opensim.Vec3(1, 2, 3)
v[0] = 1.5 + v[1]
w = opensim.Vector(5, 1.5)
w[0] = 3 * w[1]

>>> v = opensim.Vec3(1, 2, 3)
>>> print v
~[1,2,3]

w = opensim.Vector(5)
if len(w) < 5:
    raise Exception()

model = opensim.Model("my_model.osim")
for force in model.getForceSet():
    print(force.getName())
for name, muscle in model.getMuscles():
    print(name, muscle.get_max_isometric_force())

model = opensim.Model("my_model.osim")
for body in model.getBodyList():
    print(body.getName())