REBOUNDi Version 4.0.0

- Naming Convention
- Emscripten support
- Web server for visualization
- Minor bug fixes

.github/workflows/emscripten.yml

@@ -0,0 +1,29 @@
+name: REBOUND (emscripten)
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    name: Compiling with emscripten
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Download and install emscripten
+        run: |
+          git clone https://github.com/emscripten-core/emsdk.git
+          emsdk/emsdk install latest
+          emsdk/emsdk activate latest
+      - name: Compile web client
+        run: |
+          bash web_client/compile.bash
+      - name: Archive web client
+        uses: actions/upload-artifact@v3
+        with:
+          name: web_client
+          path: web_client/rebound.html
+      - name: Compile all C examples
+        run: |
+          bash docs/c_examples/compile_emcc.bash 0

.github/workflows/ipynb.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v3

.github/workflows/python.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
         os: [ubuntu-latest, windows-2019, macos-11]
 
     steps:

.gitignore

@@ -12,6 +12,7 @@ Info.plist
 *.pyc
 *.pdf
 *.bin
+*.dSYM
 nbody
 .DS_Store
 error.txt
@@ -33,11 +34,14 @@ venv/
 dist/
 build/
 src/rebound
+src/*.wasm
+src/*.js
+src/*.html
 .ipynb_checkpoints
 ipython_examples/*.png
 others/*.tar.gz
 others/*.tar
-docs/c_examples
+docs/c_examples/*.md
 problems/
 .vscode/
 *.pete

.readthedocs.yaml

@@ -9,6 +9,13 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.11"
+  jobs:
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/emscripten_c_examples/
+      - git clone https://github.com/emscripten-core/emsdk.git
+      - emsdk/emsdk install latest
+      - emsdk/emsdk activate latest
+      - bash docs/c_examples/compile_emcc.bash
 
 mkdocs:
   configuration: mkdocs.yml

MANIFEST.in

@@ -10,6 +10,7 @@ include src/integrator_eos.c
 include src/integrator_janus.c
 include src/integrator.c
 include src/gravity.c
+include src/server.c
 include src/collision.c
 include src/boundary.c
 include src/binarydiff.c
@@ -37,6 +38,7 @@ include src/integrator.h
 include src/collision.h
 include src/boundary.h
 include src/gravity.h
+include src/server.h
 include src/tree.h
 include src/tree.c
 include src/tools.h

README.md

@@ -1,4 +1,4 @@
-[![Version](https://img.shields.io/badge/rebound-v3.28.4-green.svg?style=flat)](https://rebound.readthedocs.org)
+[![Version](https://img.shields.io/badge/rebound-v4.0.0-green.svg?style=flat)](https://rebound.readthedocs.org)
 [![PyPI](https://badge.fury.io/py/rebound.svg)](https://badge.fury.io/py/rebound)
 [![GPL](https://img.shields.io/badge/license-GPL-green.svg?style=flat)](https://github.com/hannorein/rebound/blob/main/LICENSE)
 [![Paper](https://img.shields.io/badge/arXiv-1110.4876-green.svg?style=flat)](https://arxiv.org/abs/1110.4876)
@@ -92,7 +92,7 @@ There are several papers describing the functionality of REBOUND.
 
 5. Rein & Tamayo 2016 (Monthly Notices of the Royal Astronomical Society, Volume 459, Issue 3, p.2275-2285) develop the framework for second order variational equations. <https://ui.adsabs.harvard.edu/abs/2016MNRAS.459.2275R>
 
-6. Rein & Tamayo 2017 (Monthly Notices of the Royal Astronomical Society, Volume 467, Issue 2, p.2377-2383) describes the Simulation Archive for exact reproducibility of N-body simulations. <https://ui.adsabs.harvard.edu/abs/2017MNRAS.467.2377R>
+6. Rein & Tamayo 2017 (Monthly Notices of the Royal Astronomical Society, Volume 467, Issue 2, p.2377-2383) describes the Simulationarchive for exact reproducibility of N-body simulations. <https://ui.adsabs.harvard.edu/abs/2017MNRAS.467.2377R>
 
 7. Rein & Tamayo 2018 (Monthly Notices of the Royal Astronomical Society, Volume 473, Issue 3, p.3351–3357) describes the integer based JANUS integrator. <https://ui.adsabs.harvard.edu/abs/2018MNRAS.473.3351R>
 

docs/addingparticles.md

@@ -13,11 +13,11 @@ The following code shows an example on how to add particles this way:
 
 === "C"
     ```c
-    struct reb_simulation* r = reb_create_simulation();
+    struct reb_simulation* r = reb_simulation_create();
     struct reb_particle p = {0};
     p.m = 1.;
     p.x = 1.;
-    reb_add(r, p);
+    reb_simulation_add(r, p);
     ```
     !!! Important
         The `= {0}` syntax above ensures that the struct is initialized with zeros.
@@ -36,21 +36,21 @@ The following code shows an example on how to add particles this way:
 
 You can also use orbital parameters to initialize the particle object.
 === "C"
-    In C, this is done by calling the `reb_tools_orbit_to_particle` function. Its arguments are gravitational constant, primary object, mass, semi-major axis, eccentricity, inclination, longitude of ascending node, argument of pericenter, and true anomaly. 
+    In C, this is done by calling the `reb_particle_from_orbit` function. Its arguments are gravitational constant, primary object, mass, semi-major axis, eccentricity, inclination, longitude of ascending node, argument of pericenter, and true anomaly. 
     It returns an initialized particle object which you can then add to the simulation.
     ```c
-    struct reb_simulation* r = reb_create_simulation();
+    struct reb_simulation* r = reb_simulation_create();
     struct reb_particle primary = {0};
     primary.m = 1;
-    reb_add(r, primary);
-    struct reb_particle planet = reb_tools_orbit_to_particle(r->G, primary, 1e-3, 1., 0., 0., 0., 0., 0.);
-    reb_add(r, planet);
+    reb_simulation_add(r, primary);
+    struct reb_particle planet = reb_particle_from_orbit(r->G, primary, 1e-3, 1., 0., 0., 0., 0., 0.);
+    reb_simulation_add(r, planet);
     ```
 
     You can also the coordinates described by [Pal 2009](https://ui.adsabs.harvard.edu/abs/2009MNRAS.396.1737P/abstract) to initialize orbits using the following function:
 
     ```c
-    struct reb_particle reb_tools_pal_to_particle(double G, struct reb_particle primary, double m, double a, double lambda, double k, double h, double ix, double iy);
+    struct reb_particle reb_particle_from_pal(double G, struct reb_particle primary, double m, double a, double lambda, double k, double h, double ix, double iy);
     ``` 
     Here, `lambda` is the longitude, `h` is $e\cos(\omega)$, `k` is $e\sin(\omega)$, `ix` and `iy` are the x and y components of the inclination respectively. 
 
@@ -75,34 +75,34 @@ You can also use orbital parameters to initialize the particle object.
 ## Convenience functions
 By far the easiest way to add particles to REBOUND is to use a convenience function.
 === "C"
-    In C, the function is called `reb_add_fmt` and has the following syntax:
+    In C, the function is called `reb_simulation_add_fmt` and has the following syntax:
     ```c
-    void reb_add_fmt(struct reb_simulation* r, const char* fmt, ...);
+    void reb_simulation_add_fmt(struct reb_simulation* r, const char* fmt, ...);
     ```
     This is a [variadic function](https://en.cppreference.com/w/c/variadic) which takes a variable number of arguments similar to the `printf` function.
     The following code shows how this function is used.
     ```c
-    struct reb_simulation* r = reb_create_simulation();
-    reb_add_fmt(r, "m", 1.0);                // star at origin with mass 1
-    reb_add_fmt(r, "m a", 1e-3, 1.0);        // planet with mass 1e-3 and semi-major axis 1
-    reb_add_fmt(r, "m a e", 1e-3, 2.0, 0.1); // planet with mass 1e-3, semi-major axis 2, and eccentricity 0.1
-    reb_add_fmt(r, "m x vy", 1e-6, 1., 1.);  // planet with mass 1e-6, cartesian coordinates
+    struct reb_simulation* r = reb_simulation_create();
+    reb_simulation_add_fmt(r, "m", 1.0);                // star at origin with mass 1
+    reb_simulation_add_fmt(r, "m a", 1e-3, 1.0);        // planet with mass 1e-3 and semi-major axis 1
+    reb_simulation_add_fmt(r, "m a e", 1e-3, 2.0, 0.1); // planet with mass 1e-3, semi-major axis 2, and eccentricity 0.1
+    reb_simulation_add_fmt(r, "m x vy", 1e-6, 1., 1.);  // planet with mass 1e-6, cartesian coordinates
     ```
 
     The first argument is the simulation to which you want to add the particle.
     The second argument is a format string and it determines how many other arguments the function expects.
 
     !!! Danger
-        You need to pass exactly the right number of arguments to `reb_add_fmt` as indicated by your format string. 
+        You need to pass exactly the right number of arguments to `reb_simulation_add_fmt` as indicated by your format string. 
         Each argument also has to be the right type (mostly double floating point numbers).
         The latter is particularly important. If you call the function like this:
         ```c
-        reb_add_fmt(r, "m a", 1, 1);
+        reb_simulation_add_fmt(r, "m a", 1, 1);
         ```
         then the arguments are integers, not doubles. This can lead to unexpected behaviour that is very difficult to debug.
         The correct way to call the function is by making sure the arguments are doubles (by adding a `.`):
         ```c
-        reb_add_fmt(r, "m a", 1.0, 1.0);
+        reb_simulation_add_fmt(r, "m a", 1.0, 1.0);
         ```
 
     The following parameters are supported:

docs/api.md

@@ -1,6 +1,7 @@
 # REBOUND API
-These pages describe the REBOUND API.
-There are two structures (called *objects* in Python) which you will encounter frequently when working with REBOUND.
+These pages describe the main features of REBOUND and its API.
+
+There are two structures (*objects* in Python) which you will encounter frequently when working with REBOUND.
 The first is the [Simulation structure](simulation.md) which contains all the configuration, status and particle data of one REBOUND simulation.
 The second is the [Particle structure](particles.md) which represents one particle in a simulation.
 
@@ -9,6 +10,8 @@ You can combine different [gravity solvers](gravity.md), [collision detection al
 Not all combinations make physically sense, and not all combinations are supported.
 We describe the different modules and their configuration in this section.
 
+Also make sure to some of the other concepts documented in this section. 
+They will help you understand the [units](units.md) used in REBOUND, how REBOUND handles [orbital elements](orbitalelements.md), how to save and load simulations to [Simulationarchive](simulationarchive.md) files, how to use [chaos indicators](chaosindicators.md), how to use the [browser based 3D visualization](visualization.md), and several other topics.
 
 
 !!! Info

docs/binaryformat.md

@@ -2,8 +2,8 @@
 
 REBOUND comes with its own binary format.
 The binary format allows you to store a current simulation state to a file or to memory.
-The binary format is also used when you make a copy of a simulation or when you compare two similations with each other.
-The Simulation Archive is an extension of the binary format which allows you to store multiple snapshots of a simulation in one file.
+The binary format is also used when you make a copy of a simulation or when you compare two simulations with each other.
+The Simulationarchive is an extension of the binary format which allows you to store multiple snapshots of a simulation in one file.
 This page explains the details of the binary format.
 It is mainly intended for people who wish to extend the built-in REBOUND functionality.
 You do not need to know those details if you're only working with binary files to save and load simulations.
@@ -34,16 +34,16 @@ struct reb_simulationarchive_blob {
 You create a binary file if you save a simulation
 === "C"
     ```c
-    struct reb_simulation* r = reb_create_simulation();
+    struct reb_simulation* r = reb_simulation_create();
     // ... setup simulation ...
-    reb_output_binary(r, "snapshot.bin");
+    reb_simulation_save_to_file(r, "snapshot.bin");
     ```
 
 === "Python"
     ```python
     sim = rebound.Simulation()
     // ... setup simulation ...
-    sim.save("snapshot.bin")
+    sim.save_to_file("snapshot.bin")
     ```
 Such a binary file with one snapshot is simply a set of `reb_binaryfield`s followed by one `reb_simulationarchive_blob` at the end, for example:
 
@@ -80,8 +80,8 @@ The last binary field of type `9999` (`end`) to indicate that the snapshot ends
     Before version 3.27 data was encoded using the enum `REB_BINARY_FIELD_TYPE` instead of `reb_binary_field_descriptor_list`.
 
 
-## SimulationArchive file (multiple snapshots)
-The binary file above can also be interpeted as a SimulationArchive with one snapshot. 
+## Simulationarchive file (multiple snapshots)
+The binary file above can also be interpreted as a Simulationarchive with one snapshot. 
 You can append many (millions!) of snapshots to a binary file.
 REBOUND only stores data that has changed since the original snapshot (typically the particle data, time, etc).
 This allows for a very compact file size, while still maintaining bit-wise reproducibility. 
@@ -90,7 +90,7 @@ Each snapshot is separated by a `reb_simulationarchive_blob`.
 The blob contains the offset to the previous and next blobs. 
 This allows REBOUND to quickly jump from one blob in the archive to the next.
 Between the blobs are the same `reb_binary_field`s we already encountered for a binary file with one snapshot.
-Thus, a SimulationArchive file with multiple snapshots looks something like this:
+Thus, a Simulationarchive file with multiple snapshots looks something like this:
 
 ```
 reb_binary_field:
@@ -166,7 +166,7 @@ REBOUND also supports array like fields. For example consider the `particles` fi
     struct reb_binary_field_descriptor fd_particles = { 85, REB_POINTER, "particles", offsetof(struct reb_simulation, particles), offsetof(struct reb_simulation, N), sizeof(struct reb_particle)};
 ```
 
-The second to last entry lists the offset of the a variable in the `reb_simulation` structure that determines the number of array elements. In this case the number of partiles. The last entry is the size of a single element. In this case, the size of one `reb_particle`.
+The second to last entry lists the offset of the a variable in the `reb_simulation` structure that determines the number of array elements. In this case the number of particles. The last entry is the size of a single element. In this case, the size of one `reb_particle`.
 
 If you add an additional field to the `reb_simulation` struct and you want to write it to a binary file and read it back in, then you need to add an entry to `reb_binary_field_descriptor_list`.
 

docs/boundaryconditions.md

@@ -9,7 +9,7 @@ Because this is the default setting, you don't need to do anything if you don't
 Nevertheless, here is the syntax to set this manually:
 === "C"
     ```c
-    struct reb_simulation* r = reb_create_simulation();
+    struct reb_simulation* r = reb_simulation_create();
     r->boundary = REB_BOUNDARY_NONE;
     ```
 
@@ -26,8 +26,8 @@ The syntax is as follows:
 
 === "C"
     ```c
-    struct reb_simulation* r = reb_create_simulation();
-    reb_configure_box(r, 10., 1, 1, 1); # confine the simulation to a box of size 10
+    struct reb_simulation* r = reb_simulation_create();
+    reb_simulation_configure_box(r, 10., 1, 1, 1); # confine the simulation to a box of size 10
     r->boundary = REB_BOUNDARY_OPEN;
     ```
 
@@ -45,8 +45,8 @@ The syntax is as follows:
 
 === "C"
     ```c
-    struct reb_simulation* r = reb_create_simulation();
-    reb_configure_box(r, 10., 1, 2, 3); # confine the simulation to a box of size 10x20x30
+    struct reb_simulation* r = reb_simulation_create();
+    reb_simulation_configure_box(r, 10., 1, 2, 3); # confine the simulation to a box of size 10x20x30
     r->boundary = reb_boundary_periodic;
     ```
 
@@ -64,9 +64,9 @@ The following code sets up two rings of ghost boxes in the x and y directions.
 
 === "C"
     ```c
-    r->nghostx = 2;
-    r->nghosty = 2;
-    r->nghostz = 0;
+    r->N_ghost_x = 2;
+    r->N_ghost_y = 2;
+    r->N_ghost_z = 0;
     ```
 
 === "python"
@@ -76,9 +76,9 @@ The following code sets up two rings of ghost boxes in the x and y directions.
 
 See [Rein & Liu](https://ui.adsabs.harvard.edu/abs/2012A%26A...537A.128R/abstract) for details on the ghost box implementation.
 
-You might encounter the `reb_ghostbox` structure in various parts of the code, for example in function related to gravity calculation and collision detection. 
-It contains the relative position and velocity of a ghostbox.
-If there are no ghostboxes used, then all elements of this structure will be zero.
+You might encounter the `reb_vec6d` structure in various parts of the code, for example in function related to gravity calculation and collision detection. 
+It often contains the relative position and velocity of a ghost-box.
+If there are no ghost-boxes used, then all elements of this structure will be zero.
 
 ## Shear
 ![Shearing sheet](img/shear.png)
@@ -91,8 +91,8 @@ For more information on how to setup simulations of planetary rings in REBOUND,
 
 === "C"
     ```c
-    struct reb_simulation* r = reb_create_simulation();
-    reb_configure_box(r, 10., 1, 1, 1); 
+    struct reb_simulation* r = reb_simulation_create();
+    reb_simulation_configure_box(r, 10., 1, 1, 1); 
     r->OMEGA = 1.0;
     r->boundary = REB_BOUNDARY_SHEAR;
     ```

docs/c_examples/compile_emcc.bash

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+source emsdk/emsdk_env.sh
+READTHEDOCS_OUTPUT="${READTHEDOCS_OUTPUT:-.}"
+OPTIMI="${1:-3}"
+
+echo "Compiling C examples with emscripten."
+echo "Output dir: $READTHEDOCS_OUTPUT"
+echo ""
+
+for dir in examples/*/
+do
+    echo "Working on $dir ..."
+    mpi_enabled=$(cat $dir/Makefile | grep -c "export MPI=1")
+    openmp_enabled=$(cat $dir/Makefile | grep -c "export OPENMP=1")
+    server_used=$(cat $dir/problem.c | grep -c "reb_simulation_start_server")
+    if [ $mpi_enabled -eq 0 ] && [ $openmp_enabled -eq 0 ]; then
+        mkdir -p $READTHEDOCS_OUTPUT/html/emscripten_c_$dir/
+        echo "Compiling... "
+        if [ $server_used -eq 0 ]; then
+            emcc -O$OPTIMI -Isrc/ src/*.c $dir/problem.c -DSERVERHIDEWARNING -sSTACK_SIZE=655360 -s -sASYNCIFY --shell-file web_client/shell_console_rebound.html -o $READTHEDOCS_OUTPUT/html/emscripten_c_$dir/index.html || exit 1
+        else
+            emcc -O$OPTIMI -Isrc/ src/*.c $dir/problem.c -DSERVERHIDEWARNING -DOPENGL=1 -sSTACK_SIZE=655360 -s USE_GLFW=3 -s FULL_ES3=1 -sASYNCIFY --shell-file web_client/shell_rebound.html -o $READTHEDOCS_OUTPUT/html/emscripten_c_$dir/index.html || exit 1
+        fi
+        echo "Done. "
+    else
+        echo "Skipping."
+    fi
+    echo ""
+
+done