Skip to main content

Simple N-body code for Python

Project description


"They told me computers could only do arithmetic." -- Grace Hopper

Gravitational N-body simulation code written by Jeremy Bailin.

Named in honour of pioneering computer scientist Grace Hopper. Doubly appropriate because it uses a leapfrog integrator.

This is a simple Python-interface code for performing gravitational N-body simulations. It combines a simple Python interface for ease of use with a C backend for speed, and has the following features:

  • Choice of Barnes-Hut tree or direct summation algorithm.
  • Ability to include external potentials from galpy, gala, or user-supplied functions.
  • Ability to return output as pynbody snapshots.
  • Functions that generate equilibrium or near-equilibrium initial conditions (ICs) for several density profiles (Plummer, Hernquist, exponential disk), along with the ability to create ICs from galpy distribution function objects or pynbody snapshots.
  • Utility functions for plotting snapshots and making movies.

For now, it uses a constant uniform timestep and constant uniform Plummer softening.


  • Astropy
  • NumPy, SciPy, Matplotlib
  • C compiler
  • To use galpy, gala, or pynbody interface functions, they will need to be installed.
  • Saving movies requires ffmpeg.

For example, this will create a Plummer sphere with 2000 particles, run it for a few dynamical times, and plot the particle positions before and after to show that it is in equilibrium:

from gravhopper import Simulation, IC
from astropy import units as u
import matplotlib.pyplot as plt

# Create Plummer initial conditions.
Plummer_IC = IC.Plummer(N=2000, b=1*u.pc, totmass=1e6*u.Msun)

# Create a new simulation with a time step of 0.005 Myr and a softening of 0.05 pc.
sim = Simulation(dt=0.005*u.Myr, eps=0.05*u.pc)
# Add the Plummer model to the simulation
# Run for 400 time steps

# Plot the x-y positions at the beginning and end.
fig = plt.figure(figsize=(12,4))
ax1 = fig.add_subplot(121, aspect=1.0)
ax2 = fig.add_subplot(122, aspect=1.0)
sim.plot_particles(snap='IC', unit=u.pc, xlim=[-10,10], ylim=[-10,10], ax=ax1)
sim.plot_particles(snap='final', unit=u.pc, xlim=[-10,10], ylim=[-10,10], ax=ax2)

To make a movie of the whole evolution of the simulation:

# Make and save a movie of the simulation running
sim.movie_particles('Plummer_sim.mp4', unit=u.pc, xlim=[-10,10], ylim=[-10,10])


Full documentation, including installation instructions, examples, and library reference, are at Read The Docs


Option 1: Pip

If all goes well, you should be able to install GravHopper simply with:

pip install gravhopper

Option 2: Install from source

To install directly from the current source:

  1. Clone or download the git repository
git clone
  1. Go into the gravhopper directory and build the code.
cd gravhopper
python build_ext --inplace
  1. Copy the gravhopper subdirectory to wherever you want to use it.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gravhopper-1.1.0.tar.gz (24.5 kB view hashes)

Uploaded source

Built Distributions

gravhopper-1.1.0-cp311-cp311-win_amd64.whl (28.9 kB view hashes)

Uploaded cp311

gravhopper-1.1.0-cp310-cp310-win_amd64.whl (28.9 kB view hashes)

Uploaded cp310

gravhopper-1.1.0-cp39-cp39-win_amd64.whl (28.7 kB view hashes)

Uploaded cp39

gravhopper-1.1.0-cp38-cp38-win_amd64.whl (28.7 kB view hashes)

Uploaded cp38

gravhopper-1.1.0-cp37-cp37m-win_amd64.whl (28.6 kB view hashes)

Uploaded cp37

gravhopper-1.1.0-cp36-cp36m-win_amd64.whl (29.0 kB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page