What is OpenSim

Perhaps you have used OpenSim for muskuloskeletal modeling. Now you have found yourself here wondering how to build the project from source and what a python wheel is. To begin, building the project from source is no small feat and usually takes many hours of configuration and troubleshooting. If you succeed in this quest, you will emerge victoriously with a working python environment with the exact dependencies that you need. A Python wheel is simply a binary package which includes all the dynamic libraries a package needs to function on your platform so you don’t have to build everything from source. For more information on Python wheels check out this article. The point of this article though is to learn how to build the wheel, so we will of course be building everything from source.

Setting up Python for wheel building

  1. Install uv to manage python environments. Here is a great article on why you should use uv and not pyenv, poetry, pipx, or anaconda.
  2. Setup your python environment
uv init --python 3.11
uv venv
uv pip install swig
source .venv/bin/activate

Note: you will need to rerun source .venv/bin/activate from that directory every time you return and want to reinitialize the python environment.

  1. Install the specific version of numpy in the virtual environment that you will need in your project
uv pip install install numpy==1.24.4

The python environment and numpy version will be used during the opensim build.

Building OpenSim

There are many build scripts and instructions floating around online of how to build OpenSim. This topic has sparked heated debate online. I have maintained my own set of build scripts which I use mostly for building on Linux based systems. The essence of this process is that you should install platform dependencies, and then build the project.

I recently contributed a PR which allows you to use the current version of SWIG to build the Python bindings. This means you no longer have to resort to shimming the exact version for whatever platform you’re on.

Arch Linux

sudo pacman -S base-devel cmake autoconf pkg-config automake blas lapack freeglut libxi libxmu doxygen python3 python-numpy git openssl pcre pcre2 libtool gcc-fortran ninja patchelf byacc bison glu jdk8-openjdk

Ubuntu

sudo apt-get install --yes build-essential cmake autotools-dev autoconf pkg-config automake libopenblas-dev liblapack-dev freeglut3-dev libxi-dev libxmu-dev doxygen python3 python3-dev python3-numpy python3-setuptools git libssl-dev libpcre3 libpcre3-dev libpcre2-dev libtool gfortran ninja-build patchelf

On Ubuntu, you may also need to run sudo apt install python3.11-dev to get the wheel working. I also had to do this to fix the GLIBCXX error that pops up with Simbody. I will repost it here for convenience:

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install --only-upgrade libstdc++6

You can see this thread for more on using the wheels on various platforms.

Running the build

  1. git clone https://github.com/gateway240/opensim-build.git
  2. Clone the source repository:
 git -C ~/opensim-workspace/opensim-core-source pull ||
 git clone https://github.com/opensim-org/opensim-core.git ~/opensim-workspace/opensim-core-source
  1. ~/opensim-build/build-core.sh -n

The -n flag runs the build with ninja. The build will default to use the number of cores available on your system. It will take 20-60 minutes depending on how strong your machine is.

You should now have a succesful OpenSim build which is installed to ~/opensim-core! Following this from the same venv you were in before:

uv pip install build
(cd ~/opensim-core/sdk/Python && python -m build --wheel)

Now you should have built wheel which you can install with:

uv pip install ~/opensim-core/sdk/Python/dist/opensim-{version}(-{build})?-{python}-{abi}-{platform}.whl

For example:

uv pip install ~/opensim-core/sdk/Python/dist/opensim-4.5.2-cp311-cp311-linux_x86_64.whl