Add regression model, and API page

[MilesCranmer]

Added Jan 5, 2021: This adds a version of the Bayesian regression model in our upcoming paper. Accessible with: from spock import DeepRegressor. Requirements given in the setup.py file. e.g.,

model = DeepRegressor()
sim = rebound.Simulation()
sim.add(m=1.)
sim.add(m=1.e-5, P=1.)
sim.add(m=1.e-5, P=2.)
sim.add(m=1.e-5, P=3.)
time = model.predict(sim)

This returns log-instability time.

Samples of the posterior can be obtained like so:

time = model.sample(sim, samples=1000)

predict gives the median of these samples. All values given above 9 are drawn from a simple prior - these can be resampled by the user.

Initial PR: This also creates a readthedocs page for spock. It has a manually-written quick-start page, configured at docs/start.md, as well as API documentation that is auto-generated from the current python code docstrings. The front-page of the read the docs will be a hugo-rendered version of the README.md (translated it from rst so that hugo can render it).

Project page: https://readthedocs.org/projects/spock-instability/.

After pulling, it will be built at every commit, and then rendered at: https://spock-instability.readthedocs.io/en/latest/ (spock was taken).

[MilesCranmer]

Also, I think jupyter nbconvert could be used to turn the Jupyter notebook examples into tutorial pages without extra work.

[MilesCranmer]

A local documentation server can be created and started by going to the spock directory and running:

pydoc-markdown --bootstrap hugo && pydoc-markdown --server --open

[dtamayo]

Wow, thanks! I would need to learn more about this to figure out to clean up what gets included in the documentation--I think there are actually very few classes/functions we want to expose to the user. I justified to myself that they were few enough that just writing the examples was sufficient documentation, but I think you're right that especially once we add the regression model, we should have a documentation page to guide people. All the documentation I've written for other packages has been with sphinx, so I need to catch up a bit.

How would you feel about waiting to clean this up and merging it when we add in the regression model?

[MilesCranmer]

Np! Fine with either. Btw, it is quite easy to include only specific functions, I just changed it to only document FeatureClassifier - I will tag you at the line of code in question. Also I think Hugo and Sphinx have the same syntax, the difference is mostly aesthetic.

[MilesCranmer]

Updated this PR with the regression model:

This adds a version of the Bayesian regression model in our upcoming paper. Accessible with: from spock import DeepRegressor. Requirements given in the setup.py file. e.g.,

model = DeepRegressor()
sim = rebound.Simulation()
sim.add(m=1.)
sim.add(m=1.e-5, P=1.)
sim.add(m=1.e-5, P=2.)
sim.add(m=1.e-5, P=3.)
time = model.predict(sim)

This returns log instability time (base 10).

Samples of the posterior can be obtained like so:

time = model.sample(sim, samples=1000)

predict gives the median of these samples. All values given above 9 are drawn from a simple prior - these can be resampled by the user.

[MilesCranmer]

Here is the unit test used, which monitors that decreasing mass => increasing stability:

times = []
for mass in [1e-4, 5e-5, 3e-5, 1e-5]:
    sim = rebound.Simulation()
    sim.add(m=1.)
    sim.add(m=mass, P=1)
    sim.add(m=mass, P=1.3)
    sim.add(m=mass, P=1.6)
    predicted_time = self.model.predict(sim)
    times.append(predicted_time)

times = np.array(times)
self.assertTrue(np.all(times[1:] > times[:-1]))

[MilesCranmer]

Temporarily closing to avoid spamming this PR, as I make changes to the API and add more documentation.