Introduce a simplified tutorial

[mabruzzo]

Motivation

At present, we provide several extremely useful resources for teaching Grackle. But, I've long felt that there's initially something of a learning curve. While all of the examples and the "Interacting with Grackle in Your Simulation Code" section are extremely rich, detailed, and informative, I always feel like they may include a little too much information...

Every usage of Grackle, boils down to the following flow:

1. We have some data about parcels of gas & we want to know something about it (mostly how chemistry/cooling cause it to evolve)

2. We need to encode information about the gas and the physics we care about in a format that Grackle understands.¹

3. We package up the data about the gas parcels into a format that Grackle understands (the grackle_field_data struct).

4. We call the appropriate function.

Unfortunately, this flow is not very obvious from the existing resources (i.e. there's just a little too much going on). But, once you understand the flow ("the big picture"), I think our existing resources are extremely useful.

Overview

This patch tries to bridge this gap. I came up with the shortest and simplest possible example. (I probably could save a line or 2 if I used the global API, but that was a conscious choice). Then, I wrote a tutorial to try to walk the reader through the example chunk by chunk.

To help annotate the example, I wrote a really simple sphinx extension.

Future Thoughts

Honestly, this is far from perfect, but I think its a good start. Some thoughts for the future:

• It would be nice if Grackle could operate with CGS units. The tutorial could then gloss over a number of details.

  • Since we already use double-precision within Grackle, I think don't think there are any problems with doing this. But clearly, it needs to wait

  • I think it would also be nice for teaching the pygrackle bindings

• It would be better if the example were even shorter:

  • the gr_fields type proposed within Introducing gr_fields, an experimental replacement for grackle_field_data #271 will help

  • a number of my other "experimental APIs" will also help

  • in the 4.0 release, we may want to revisit the default values for the use_grackle and with_radiative_cooling parameters (the current defaults are pretty silly).

• if we merge in Auto File Management Part 1: Introducing a Datafile Management Tool #235, Auto File Management Part 2: Allow Grackle to search for automatically managed data files #237, and Auto File Management Part 3: Install data-management tool as command line program #246, then we could easily add a section describing how to try out the example without git commands (those PRs are essential for crafting a sample CMake configuration that can automatically install data-files)

Footnotes

1. Of course, Grackle is designed to let callers avoid repeating step 2 over and over again. ↩