Example nbinteract integration for Acoustics

[cleb11]

Related issues: #123, SamLau95/nbinteract#45

Our original goal was to reproduce your html book using nbinteract to enable widgets. However, we were only successful in converting Acoustics.html. link
These were our steps:

• Running nbinteract on command-line by itself. This produced html but the html didn't have widgets because the binder image wasn't set up properly. In this PR, we have made a change to your dockerfile to make binder work.
• Next we realized that you had your own built system to convert IPython notebooks to html. So we integrated our nbinteract template into your original html template. This means you won't have to run nbinteract on command-line; you can run your old python script: make_html_on_master.py
• So after those steps, the acoustics.html page works: https://calebs97.github.io/riemann_book/build_html/Acoustics.html#Interactive-solution-in-the-phase-plane
• However, the widgets appear alongside static images that you guys generate. We didn't investigate how to turn off static image generation.
• You will notice in that example the Tabs widget doesn't work. We don't know why but we are looking into it.

Moving forward:

• We noticed that other notebooks, such as the Nonconvex_scalar notebook, do not correctly generate the "Show Widgets" button. We're not exactly sure why this happens because usually running a notebook running IPywidgets will generate the static widget output that nbinteract needs to hook into. We think it might be an issue with your customized build system and we're happy to discuss this further since you know more about this build system than we do.
• We also ran into difficulties running notebooks that use your clawpack library. You might have better luck since you have the package installed properly.

We think a good way to work together is for you to tell us what you think are particularly useful pages for interaction and we can work with you to get those pages up and running. Hopefully in the process, we'll fix the rest of the bugs that will allow the rest of your book to be converted using nbinteract.

cc @SamLau95

[rjleveque]

@CalebS97, @SamLau95 : Thanks for working on this! We've just gotten back to this project after a hiatus, and are in the process of updating various things. @ketch is currently taking a pass on all notebooks, mostly with regard to content and some pdf issues, but soon we'll get back to thinking about the html rendering, and then it will be good to see if we can make it all work with nbinteract.

[ketch]

@CalebS97 @SamLau95 I tried it out with your modified version of html.tpl, and I'm getting the same results you posted (but not the results you described). What I see (in the Acoustic notebook as well as all others) is that where we explicitly call display(widget.out), nbinteract works. However, for the majority of widgets we simply use interact(some_function), and in this case nbinteract doesn't seem to work (I only see a static plot).

I've also been looking at the output for the Traffic_flow notebook. Again, all the simple interact(fun) widgets don't work, but the one at the end seems to (when we call display(widget.out)). However, the first time I clicked 'Show widget', the wheel spun for several minutes (I think I waited about 10 minutes) and no widget appeared. I tried reloading the page, but then I got a traceback with the error message:

NameError: global name 'traffic_LWR' is not defined

suggesting that the Python kernel had not run the other cells in the notebook.

Also, wherever the 'Show widgets' button shows up, I see two of them.

I'd like to work with you on fixing these issues; let me know how I can help.

[SamLau95]

Thanks for taking a closer look @ketch ! I've made three new nbinteract issues (linked above) based on what you've reported and we're working on them this week. We'll focus our efforts on getting the Traffic_flow notebook converting properly, and I don't think there's anything else we need from you right now for us to move forward.

Since trying (and failing) to get nbinteract to work on this book has been really helpful in surfacing current issues, @CalebS97 and I are making it a priority to go as far as we can in creating an interactive HTML version of the Riemann book. In the short term, we'll take on each issue as it arises; all of the issues reported so far will likely arise for other people as well, so this isn't just a one-off effort for us. We'll report back on this thread as we fix bugs.

In the longer term, we're looking into ways of extending nbinteract's plotting methods to allow us to recreate your interactive plots without the flickering that occurs because of matplotlib-based plotting. Our hope is that the resulting API will be both easier to use than manually hooking up widgets and produce smoother interactions for viewers.

Let me know if you have any comments / questions!

[ketch]

@SamLau95 This is great! We're happy to be providing good test cases for you. We think that notebooks + widgets is a promising new paradigm for education and hoping that our book will help move it forward, and I think nbinteract can make the whole framework dramatically better.

[SamLau95]

Hey @ketch , we made some fixes to nbinteract and some changes to your script (827cb02). We were then able to convert all notebooks without error except these: Traffic_variable_speed.ipynb, Shallow_tracer.ipynb, and Introduction.ipynb.

For those notebooks, I run into errors importing clawpack modules. In particular, from clawpack.riemann import shallow_roe_tracer_1D breaks and I'm having some trouble figuring out how to fix it since I have clawpack v5.4.0 and the source code for the riemann module doesn't seem to have a shallow_roe_tracer_1D file. Do you know more about this particular case? I also get import errors for riemann.traffic_vc_fwave_1D.

I've pushed all the resulting successfully converted notebooks onto this branch. You can view them at https://calebs97.github.io/riemann_book/build_html/Index.html

We've fixed the issue with widgets not generating when using interact calls, as you can see in the Traffic_flow notebook:

Here are the remaining issues off the top of my head:

• Figure out why some modules don't import properly
• Fix duplicate Show Widget button output
• Avoid generating static images when the cell has widgets (right now a cell with widgets will have two copies of each plot, one for the widget and one static image).
• See if we can do less computation on interaction so that the plots regenerate faster. This is something that you guys will know more about. One suggestion is to precompute as many values as possible and then use interact to select from cached results instead of computing on the fly.

[ketch]

@SamLau95 It's looking good. I can answer your first question: as explained at https://github.com/clawpack/riemann_book/wiki/Installation, you need the "bleeding edge" development version of clawpack.riemann. That page also has instructions on how to get it. We'll make a new Clawpack release when the book is ready, but for now those additional steps are necessary.

I agree that the interacts are not as snappy as they ought to be. The amount of actual "computation" being done is very small though -- at least, for most of them. Most of the delay is time spent in matplotlib plotting calls. I'm not sure how to speed that up. Perhaps we could cache the images themselves, but we'd need to do that in a vectorized format (rasterizing them makes the line plots too difficult to read, in my opinion).

For interacts with a single parameter, the JSAnimation library does exactly this -- cache all the results. So it might be nice to stick with that for such interacts, and use the nbinteract approach only for interacts with more than one parameter.

[SamLau95]

@ketch Thanks for the tip; with your advice I was able to build all the notebooks and push them to https://calebs97.github.io/riemann_book/build_html/Index.html .

It looks like there are still a few remaining TODO items on our end. In order of priority:

• Fix the Tab widget (switching tabs doesn't change anything)
• Put back JSAnimation widgets for widgets with only one parameter
• Avoid generating static images when the cell has widgets (right now a cell with widgets will have two copies of each plot, one for the widget and one static image).
• Fix duplicate Show Widget button output

As a heads up, I've been pretty busy putting together my MS thesis and will be prioritizing that for the near month or so. Development on nbinteract will likely be my main focus starting at the end of May. Do you have a rough idea of when you'd ideally have an interactive HTML version of the book by?