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:
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.
On Mac systems with Arm64 processors (e.g., M1, M2, M3, etc.), you may need to first run the following command to install the latest version of libcxx
to install the latest version of OpenSim.
conda install conda-forge::libcxx |
Once you've created a Conda environment, use the following command to install the latest version of OpenSim that is compatible 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 | Arm64 Mac support |
---|---|---|---|
<4.4 | Not available | N/A | No |
4.4, 4.4.1 | 3.7, 3.8, 3.9, 3.10, 3.11 | No | No |
4.5 | 3.9, 3.10, 3.11 | No | No |
4.5.1 | 3.9, 3.10, 3.11 | Yes | 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.
It is possible to manually install the OpenSim Python bindings, but this approach comes with a few caveats:
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:
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 |
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.
As of December 2023, Python 3.7 is past end of life. Therefore, installation instructions for versions prior to OpenSim 4.3 are different. For OpenSim 4.2 or earlier, you may need to set the PYTHONPATH environment variable. To do this on Windows:
On Mac or Linux, you can set PYTHONPATH via the terminal, or in your
First, navigate to <OPENSIM_INSTALL_DIR>/sdk/Python. To install on Windows, run the following command. Note that your terminal might need to be in Administrator mode.
To install on Mac, run the following commands.
To install on Linux, instead navigate to <OPENSIM_INSTALL_DIR>/lib/python3.x/site-packages, since we assume you built and installed from source. Run the following commands.
|
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() |
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. |
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.
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()) |
Next: Developer's Guide Previous: Scripting with Matlab |