Updated documentation

.gitignore

@@ -31,6 +31,7 @@ others/*.tar
 doc/doxygen/xml/
 doc/_build/
 doc/c_examples.rst
+doc/c_example_*.rst
 doc/doxygen/html/
 doc/ipython
 doc/search.json

doc/conf.py

@@ -24,10 +24,9 @@
     subprocess.call('cd doxygen; doxygen', shell=True)
 
 # C Example update
-with open("c_examples.rst","w") as fd:
-    fd.write("Examples (C)\n")
-    fd.write("============\n\n")
-    for problemc in glob.glob("../examples/*/problem.c"):
+for problemc in glob.glob("../examples/*/problem.c"):
+    cname = problemc.split("/")[2]
+    with open("c_example_"+cname+".rst","w") as fd:
         will_output = 0
         with open(problemc) as pf:
             did_output=0
@@ -41,8 +40,9 @@
                     fd.write("\n\n.. code-block:: c\n");
                 if will_output>1:
                     if will_output == 2:
-                        under = "-"*(len(line.strip())-2)
-                        line = "  " +line.strip() + '\n' + under
+                        title = line.strip() + " (C)"
+                        under = "-"*(len(title)-2)
+                        line = "  " +title + '\n' + under
                     will_output = 2
                     if len(line[3:].strip())==0:
                         fd.write("\n\n"+line[3:].strip())
@@ -59,29 +59,33 @@
 
 # iPython examples:
 import shutil
-if os.path.exists("ipython"):
-    shutil.rmtree('./ipython')
-os.makedirs("./ipython")
 if 1:
-    try:
-        os.chdir("ipython")
-        for example in glob.glob("../../ipython_examples/*.ipynb"):
-            print("Trying file: ", example)
-            outp = subprocess.check_output(["cp", example, example[23:]])
-            outp = subprocess.check_output(["jupyter", "nbconvert", example[23:], "--to", "rst"])
-            print(outp)
-            print("Replacing links")
-            outp = subprocess.check_output(["perl", "-i", "-pe", "s/ipynb/html/g", example[23:][:-5]+"rst"])
-            print(outp)
-    except:
-        with open("ipython.rst","w") as fd:
-            fd.write("Examples can be found on github\n")
-            fd.write("-------------------------------\n\n")
-            fd.write("Due to a bug in the readthedocs system, the iPython notebooks are currently not included here. To view them, head over to github: \n")
-            fd.write("https://github.com/hannorein/rebound/tree/master/ipython_examples \n")
-    finally:
-        os.chdir("../")
-
+    if os.path.exists("ipython"):
+        shutil.rmtree('./ipython')
+    os.makedirs("./ipython")
+    os.chdir("ipython")
+    for example in glob.glob("../../ipython_examples/*.ipynb"):
+        print("Trying file: ", example)
+        outp = subprocess.check_output(["cp", example, example[23:]])
+        outp = subprocess.check_output(["jupyter", "nbconvert", example[23:], "--to", "rst"])
+        print(outp)
+        print("Replacing links")
+        outp = subprocess.check_output(["perl", "-i", "-pe", "s/ipynb/html/g", example[23:][:-5]+"rst"])
+        print(outp)
+    for example in glob.glob("*.rst"):
+        with open(example) as fd:
+            lines = fd.readlines()
+        with open(example,"w") as fd:
+            for i,l in enumerate(lines):
+                if i==1:
+                    fd.write(l.strip()+" (iPython)\n")
+                elif i==2:
+                    fd.write(l.strip()+"==========\n")
+                else:
+                    fd.write(l)
+
+    os.chdir("../")
+
 
 
 
@@ -189,8 +193,9 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
-html_theme = 'classic'
+html_theme = 'bizstyle'
+#html_theme = 'alabaster'
+#html_theme = 'classic'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

doc/examples.rst

@@ -0,0 +1,178 @@
+Examples
+========
+We provide a lot of examples for REBOUND. We think examples are the easiest way to learn how to use REBOUND.
+This is a list of all examples that come with REBOUND. 
+You can find all the source code for these in the `examples` and `ipython_examples` directories. 
+
+The examples are sorted by topic. 
+Note that some examples use the C version, other the python version of REBOUND. 
+Often, the syntax is very similar and you might want to look at the c examples even if you want to write python code and vice verse.
+
+Planetary systems
+-----------------
+All examples in this section are related to simulations of planetary systems. 
+
+The following examples are good if you're just starting to use REBOUND.
+
+.. toctree::
+   c_example_simplest
+   ipython/Churyumov-Gerasimenko
+   ipython/WHFast
+   c_example_solar_system
+   c_example_outer_solar_system
+   c_example_kozai
+   c_example_eccentric_orbit
+   c_example_restricted_threebody
+   ipython/Horizons
+
+If you want to capture close encounters and collisions between particles, have a look at the following examples.
+
+.. toctree::
+   c_example_closeencounter
+   c_example_closeencounter_record
+   c_example_closeencounter_hybrid
+   ipython/CloseEncounters
+   c_example_mergers
+
+The following examples demonstrate how to calculate orbital elements.
+
+.. toctree::
+   c_example_orbital_elements
+   ipython/OrbitalElements
+
+If you are interested in simulating a planetary system in which there are many small particles, have a look at the following examples. 
+All these examples use the HERMES integrator.
+
+.. toctree::
+   c_example_planetesimal_disk_migration
+   ipython/EccentricComets
+   ipython/PrimordialEarth
+
+Some more advanced topics are covered in the following examples.
+
+.. toctree::
+   ipython/AdvWHFast
+   ipython/Resonances_of_Jupiters_moons
+   ipython/TransitTimingVariations
+   ipython/HyperbolicOrbits
+
+Checkpoints and Simulation Archive
+----------------------------------
+All examples in this section demonstrate how to store, reload and restart simulations. 
+They also show how to use the Simulation Archive. 
+It is a framework that allows you to not only restart simulations, but recreate them bit-by-bit in a machine independent way. 
+With the simulation archive you can run a simulation first, then think later about how you want to analyze it.
+
+.. toctree::
+   ipython/Checkpoints
+   c_example_simulationarchive
+   c_example_restarting_simulation
+   ipython/SimulationArchive
+   ipython/SimulationArchiveRestart
+
+Variational Equations and Chaos detectors
+-----------------------------------------
+REBOUND supports first and second order variational equations. 
+Varational equations have several advantages over shadow particles when calculating chaos indicators such as Lyapunov exponents. 
+They can also be used in optimization problems. 
+For more details on variational equations and the math behind them, have a look at the paper `Rein and Tamayo 2016 <https://arxiv.org/abs/1603.03424>`_ and the following examples.
+
+.. toctree::
+   c_example_variational_equations
+   ipython/VariationalEquations
+   ipython/VariationalEquationsWithChainRule
+
+If you are interested in chaos indicators such as MEGNO, have a look at the following examples.
+
+.. toctree::
+   c_example_megno
+   ipython/Megno
+   ipython/PoincareMap
+   ipython/FourierSpectrum
+
+
+Additional forces
+-----------------
+
+REBOUND lets you add additional forces to your simulations.
+These can be used to simulate radiation drag, general relativistic corrections, planet migration or any other force that you can come up with. 
+The following list has a few simple examples. 
+You might also want to check out `REBOUNDx <https://github.com/dtamayo/reboundx>`_ which is an add-on to REBOUND that has many additional forces already implemented, so you don't have to do the work. 
+
+.. toctree::
+   c_example_J2
+   c_example_dragforce
+   c_example_prdrag
+   c_example_circumplanetarydust
+   c_example_planetary_migration
+   ipython/Forces
+
+
+Granular Dynamics
+-----------------
+The examples in this section show how to use REBOUND for simulations in which particles are colliding with each other.
+Note that this is a different type of simulation than simulations of colliding planets.
+Here, particles collide often with each other. In the planet case, they collide with each other very rarely. 
+
+.. toctree::
+   c_example_bouncing_balls
+   c_example_bouncing_balls_corners
+   c_example_bouncing_string
+   c_example_spreading_ring
+   c_example_granulardynamics
+
+
+Tree code
+---------
+REBOUND has a built in Barnes-Hut oct tree for collision detection and gravity. 
+This allows you, for example, to simulate large gravitationally interacting systems.
+
+.. toctree::
+   c_example_selfgravity_disc
+   c_example_selfgravity_disc_mpi
+
+
+Planetary rings
+---------------
+The following examples show simulations integrating particles in planetary rings. 
+They use values characteristic for Saturn's rings but can also be used for other ring systems.
+
+.. toctree::
+   c_example_shearing_sheet
+   c_example_shearing_sheet_2
+   c_example_shearing_sheet_mpi
+   c_example_overstability
+   ipython/SaturnsRings
+
+Visualization
+-------------
+REBOUND comes with several built-in visualization tools. Most of the C examples can be run with OPENGL visualization (just edit the make file in the corresponding directory). 
+If you use Jupyter notebooks, you can use a webGL widget that interactively runs in your notebook. 
+REBOUND also comes with tools that can be used to visualize orbits using the matplotlib library. 
+The following examples illustrate the visualization feature for python.
+
+.. toctree::
+   ipython/WebGLVisualization
+   ipython/OrbitPlot
+
+Removing particles
+------------------
+The following examples illustrate how to remove particles from simulations, i.e. after a collision.
+
+.. toctree::
+   c_example_removing_particles_from_simulation
+   ipython/EscapingParticles
+   ipython/RemovingParticlesFromSimulation
+
+And finally, the following examples didn't fit anywhere else.
+They for example show how to use hashes to identify particles.
+
+.. toctree::
+   c_example_selfgravity_plummer
+   c_example_uniquely_identifying_particles_with_hashes
+   c_example_openmp
+   c_example_profiling
+   c_example_star_of_david
+   ipython/Testparticles
+   ipython/UniquelyIdentifyingParticlesWithHashes
+   ipython/Units

doc/index.rst

@@ -38,7 +38,7 @@ REBOUND is an N-body integrator, i.e. a software package that can integrate the
 
 How to use REBOUND - a quick introduction
 -----------------------------------------
-You can call REBOUND from C or Python. Which programming language you want to use depends on your taste and your specific application. In short: If you simply want to integrate a few particles such as a planetary system with the high order integrator IAS15 or the new symplectic integrator WHFast then use the Python version. If you want to run large simulations with millions of particles, use an exotic integrator, use OpenGL visualizations, or make use of the distributed tree code then use the C version. 
+You can call REBOUND from C or Python. Which programming language you want to use depends on your taste and your specific application. In short: If you simply want to setup a few particles such as a planetary system, visualize it with a WebGL widget, and integrate it with the high order integrator IAS15 or the new symplectic integrator WHFast then use the Python version. If you want to run large simulations with millions of particles, use an exotic integrator, use fast OpenGL visualizations, or make use of the distributed tree code then use the C version. 
 
 All the computationally expensive parts of REBOUND are written in C. So even if you use the Python version, you'll end up with a very fast code.
 
@@ -107,15 +107,14 @@ You should have received a copy of the GNU General Public License along with REB
 Table of Contents
 -----------------
 .. toctree::
-   :numbered:
+   :maxdepth: 2
+
 
    self
+   changelog
    modules
-   c_quickstart
-   c_examples
+   quickstart
+   examples
    c_api
-   python_quickstart
    python_api
-   ipython_examples
-   changelog
 

doc/modules.rst

@@ -1,7 +1,7 @@
-Available physics modules
-=========================
+Available modules
+=================
 
-REBOUND is extremely modular. You have the choice between different gravity, collision, boundary and integrator modules. It is also possible to implement completely new modules with minimal effort. In the new version of REBOUND, modules are chosen at runtime by setting flags in the `reb_simulation` structure. 
+REBOUND is very modular. You have the choice between different gravity, collision, boundary and integrator modules. It is also possible to implement completely new modules with minimal effort. In the new version of REBOUND, modules are chosen at runtime by setting flags in the `reb_simulation` structure. 
 
 The following sections list the available modules that come with REBOUND.
 

doc/python_quickstart.rst

@@ -1,5 +1,5 @@
-Quick User Guide (Python)
-=========================
+Python Version
+==============
 
 Installation
 ------------

doc/quickstart.rst

@@ -0,0 +1,13 @@
+Quick User Quide
+================
+
+You can call REBOUND from C or Python. Which programming language you want to use depends on your taste and your specific application. In short: If you simply want to setup a few particles such as a planetary system, visualize it with a WebGL widget, and integrate it with the high order integrator IAS15 or the new symplectic integrator WHFast then use the Python version. If you want to run large simulations with millions of particles, use an exotic integrator, use fast OpenGL visualizations, or make use of the distributed tree code then use the C version. 
+
+We provide two quickstart guides, one for C and one for Python:
+
+.. toctree::
+   :titlesonly:
+
+   c_quickstart
+   python_quickstart
+

examples/eccentric_orbit/problem.c

@@ -1,5 +1,5 @@
 /**
- * Example problem: Kozai.
+ * Highly eccentric orbits
  *
  * This example uses the IAS15 integrator to simulate
  * a very eccentric planetary orbit. The integrator

ipython_examples/Churyumov-Gerasimenko.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 67P/Churyumov–Gerasimenko\n",
+    "# The comet 67P/Churyumov–Gerasimenko\n",
     "\n",
     "This tutorial teaches you how to use the IAS15 integator (Rein and Spiegel, 2015) to simulate the orbit of 67P/Churyumov–Gerasimenko. We will download the data from NASA Horizons and visualize the orbit using matplotlib.\n",
     "\n",

ipython_examples/EccentricComets.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Eccentric Comets (HERMES tutorial)\n",
+    "# Integrating eccentric Comets with HERMES\n",
     "In this example, we study highly eccentric comets which interact with a Neptune mass planet.\n",
     "\n",
     "HERMES, a hybrid integration scheme which combines the WHFAST and IAS15 algorithms, is well suited to study this problem, since the algorithm will automatically switch to IAS15 during the perihelion passage of a comet or a close encounter with the planet but otherwise will use a large timestep with the symplectic WHFast integrator."

ipython_examples/Horizons.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Horizons\n",
+    "# Adding particles using NASA JPL Horizons system\n",
     "\n",
     "REBOUND can add particles to simulations by obtaining ephemerides from NASA's powerful HORIZONS database.  HORIZONS supports many different options, and we will certainly not try to cover everything here.  This is meant to serve as an introduction to the basics, beyond what's in [Churyumov-Gerasimenko.ipynb](Churyumov-Gerasimenko.ipynb).  If you catch any errors, or would either like to expand on this documentation or improve REBOUND's HORIZONS interface (`rebound/horizons.py`), please do fork the repository and send us a pull request.\n",
     "\n",