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.
| OpenSim version | Conda packages | Includes Moco |
|---|---|---|
| <4.4 | Not available | N/A |
| 4.4, 4.4.1 | 3.7, 3.8, 3.9, 3.10, 3.11 | No |
| 4.5 | 3.9, 3.10, 3.11 | No |
| 4.5.1 | 3.9, 3.10, 3.11 | Yes |
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:
- If installing from a GUI distribution with OpenSim 4.3 or later, only Python 3.8 is supported.
- While it is not necessary to use Conda to create a Python environment, you must use a 64-bit version of Python.
- 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 using Python.
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:
- Press the Windows key and search for "Edit the system environment variables". Click the top search result.
- Click "Environment Variables..." in the bottom right corner. Look for Path under "System variables".
- Highlight the Path entry and click "Edit...".
- Add a new entry with value <OPENSIM_INSTALL_DIR>/bin and move it to the top of the list.
- 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
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
- 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.
- 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%"
- 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.
Example Scripts
Scripts can are located wherever you installed the resources that come packaged OpenSim distribution (i.e., the folder you choose after opening the GUI the first time after installation). For example, on Windows the <RESOURCES_DIR> might be C:\Users\username\Documents\OpenSim\4.X.
The scripts below are located at <RESOURCES_DIR>\Code\Python. Additional scripts containing Moco examples can be found under <RESOURCES_DIR>\Code\Python\Moco.
Script Name | Description |
|---|---|
| build_simple_arm_model.py | This script generates a simple arm model, runs a simulation, and visualizes the results. |
| wiring_inputs_and_outputs_with_TableReporter.py | This script shows how to write model outputs (the position of a body) to a data file. |
| dynamic_walker_example_optimization.py | This script shows how to run an optimization with the dynamic walker model. |
| posthoc_StatesTrajectory_example.py | This script shows how to use a StatesTrajectory to analyze a simulation. |
| numpy_conversions.py | This script shows how to convert NumPy arrays to and from OpenSim's Vector and Matrix classes. |
| extend_OpenSim_Vec3_class.py | This script demonstrates how to extend the Vec3 class. |
Jupyter Notebooks
You can find a series of OpenSim scripting tutorials written using Jupyter notebooks here. These notebooks leverage Google Colab, a service for hosting interactive Jupyter notebooks in the cloud, and condacolab, a package that enables creating Conda environments in Google Colab.
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
v = opensim.Vector([6, 7, 8, 9]) rv = opensim.RowVector([1, 2, 5])
Accessing elements of VecX and Vector using brackets
v = opensim.Vec3(1, 2, 3) v[0] = 1.5 + v[1] w = opensim.Vector(5, 1.5) w[0] = 3 * w[1]
Printing the contents of a VecX or Vector
>>> v = opensim.Vec3(1, 2, 3) >>> print v ~[1,2,3]
Getting the length of a VecX or Vector
You can use the built-in python function len() on VecX (e.g., Vec3) and Vector:
w = opensim.Vector(5)
if len(w) < 5:
raise Exception()
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:
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())
Iterate over all bodies in a model (even bodies not in the model's BodySet)
model = opensim.Model("my_model.osim")
for body in model.getBodyList():
print(body.getName())