REBOUND N-body Integrator Wrappers

Provides functionality for calling REBOUND integrators from MATLAB

Overview

The functions rebound_mex and rebound_python provide MATLAB wrappers for the REBOUND N-body integrator suite (https://rebound.readthedocs.io/) by Hanno Rein and David S. Spiegel. If you use this code for results presented in a scientific publication, please acknowledge REBOUND as requested here: https://rebound.readthedocs.io/en/latest/#acknowledgments (doi: 10.1093/mnras/stu2164).

These wrappers are not affiliated with, nor endorsed by, the REBOUND project team. Any errors/issues should be reported to [e-mail] rather than the upstream REBOUND project.

The two functions differ in approach: rebound_mex provides a compiled MEX (https://www.mathworks.com/help/matlab/ref/mex.html) interface to the C-compiled REBOUND shared library. It is only available for Linux/macOS native MATLAB installations (and any other systems that support both MATLAB and REBOUND). REBOUND cannot be built natively on Windows - only in Windows Subsystem for Linux (WSL). rebound_python, on the other hand, uses MATLAB's ability to call Python code (https://www.mathworks.com/help/matlab/python-language.html) to call a Python installation of REBOUND. This approach can be used in Windows, but only in WSL, meaning that you will need a WSL matlab installation. This might be more trouble than its worth for casual users, but if you really want to call REBOUND from matlab on Windows, this will work.

INSTALLATION

macOS/Linux

These instructions assume that you have a working install of MATLAB and Python/pip.

For rebound_python install REBOUND via pip as described here: https://rebound.readthedocs.io/en/latest/quickstart_installation/. You may wish to ensure that the installation is working in Python by running through the example provided here: https://rebound.readthedocs.io/en/latest/quickstart_firstexample/. In MATLAB, ensure that the Python environment you are using is the same one that you installed REBOUND under. Run the command 'pyenv' to see which environment you are using. If the executable path shown does not match what you expect, then you can update the environment by executing:

pyenv('Version', "/full/path/to/python")

For example, if your Python/pip executables live in /opt/local/bin, you would run (from MATLAB):

pyenv('Version', "/opt/local/bin/python")

For rebound_mex, you will need to compile both the REBOUND shared library and the MEX file. This requires a working compiler and make installation. On macOS these can be provided by Xcode or a gcc installation via macports or Brew or other package systems. On Linux you should install gcc and make from your OS's preferred package manager.

1. Follow the compilation instructions here: https://rebound.readthedocs.io/en/latest/quickstart_installation/#compiling-the-c-version-of-rebound (essentially just grab the REBOUND git repository and run 'make' from the top level). If the compilation is successful, you should get a librebound.so object in rebound/src and a symbolic link to it in the top-level rebound directory.
2. Create a copy of (or symbolic link to) the librebound.so share library file from rebound/src to the directory where you have rebound_mex.c.
3. In MATLAB, navigate to the directory containing rebound_mex.c and run:

mex -v -IreboundPath/src -LreboundPath/src -lrebound rebound_mex.c

where reboundPath is the full path to the directory where you cloned the REBOUND git repository. So, for example, if you cloned the repo to /Users/username/Documents, then the command would look like:

mex -v -I/Users/username/Documents/rebound/src -L/Users/username/Documents/rebound/src -lrebound rebound_mex.c

Assuming the mex compilation was successful, you are now good to go. You can try executing the test script rebound_test.m to check on functionality and performance (note that this script assumes both rebound_mex and rebound_python have been set up.

Windows

Ok, are you ready for some fun? In order to get this working, we will need to set up WSL2 and install both Python and MATLAB under it. This is only supported by Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11.

1. Install WSL2 and Ubuntu 20.04 as per the instructions here: https://learn.microsoft.com/en-us/windows/wsl/install
2. Launch wsl by running wsl (or Ubuntu) from the search bar or via the Start Menu and then execute the following commands:
3. cd ~
4. sudo apt-get update
5. sudo apt-get upgrade
6. sudo apt-get install gcc g++ make unzip libxt6 default-jdk python3 python3-pip
7. pip install rebound numpy

At this point, you should have everything you need, except for a MATLAB that can run in WSL. Let's fix that. Still in wsl/ubuntu, run the following commands (note that you will be prompted for your wsl root password for any sudo commands):

1. wget https://www.mathworks.com/mpm/glnxa64/mpm
2. chmod u+x mpm
3. sudo ./mpm install --release=R2023a --destination=/usr/local/MATLAB/R2023a MATLAB
4. sudo ln -s /usr/local/MATLAB/R2023a/bin/matlab /usr/local/bin/
5. sudo mkdir /usr/local/MATLAB/R2023a/licenses

Follow the instructions for 'Manually creating a License File' found here: https://www.mathworks.com/matlabcentral/answers/235126-how-do-i-generate-a-matlab-license-file

You will need to copy the downloaded license.lic file to the licenses directory you just created. You can access your Windows file system from WSL via the /mnt directory. For example, if you place the license file on your desktop, the command would look something like:

sudo cp /mnt/c/Users/yourusername/Desktop/license.lic /usr/local/MATLAB/R2023a/licenses/

At this point, matlab in WSL should be working. The following assumes that you'll be running in headless mode, but it should be possible to get the GUI working as well. See here for details: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

Navigate to the directory where you downloaded rebound_python.m (or copy it to your Linux filesystem) and launch matlab in WSL by running:

matlab -nodisplay -nojvm

Execute the command 'pyenv'.

You should see something like:

  PythonEnvironment with properties:
          Version: "3.10"
       Executable: "/usr/bin/python3"
          Library: "libpython3.10.so.1.0"
             Home: "/usr"
           Status: NotLoaded
    ExecutionMode: InProcess

If you instead see all empty strings, then Python was not properly installed - go back and make sure the apt-get install step worked properly. You should now be able to run the rebound_python portion of rebound_test.m (rebound_mex is not supported, and figures won't work in headless mode). You can save results and re-open them back in your windows-native MATLAB installation for visualization purposes.

Execution Times

On all systems tested, the mex wrapper call in rebound_test.m executed by an order of magnitude faster than the python call. However, the majority of time is spent on I/O, meaning that execution time for shorter integrations is largely driven by the output time array. Running the same integration, but with only the initial and final times in the output array, led to nearly identical execution times. rebound_python was only benchmarked on a Windows installation within a virtual machine, meaning there were two levels of virtualization in play, so absolute time results are fairly meaningless, but execution times were similar to those when running the same integrations within Python in WSL.