D2.14: Demonstrators: Interactive textbooks: Problems in Physics with Sage and Computational Mathematics for Engineering

[minrk]

• WP2: Community Building, Training, Dissemination, Exploitation, and Outreach
• Lead Institution: University of Silesia
• Due: 2019-07-31 (month 47)
• Nature: Demonstrator
• Task: T2.9 (#32) Demonstrators:interactive text books
• Proposal: p. 38
• Final report (sources)

Interactive tools have always been an attractive tool in education, engaging the student to learn both by theory and by practice, to immediately test their understanding, and to explore around the material, all at their own pace.

In Task T2.9, we explored different approaches to authoring and distributing interactive textbooks using the Jupyter toolkit. In D2.9 (#49) we reported on the writing of two interactive books. There, the books were authored as structured text files in the ReST document format, and exported as interactive html pages or pdf, using the Sphinx documentation system and the sage-cell interactive html page technology.

For this deliverable, we proceeded with two additional interactive textbooks:

• Problems in Physics
  https://github.com/marcinofulus/Mechanics_with_SageMath
  https://github.com/marcinofulus/Dynamical_Systems
  https://github.com/marcinofulus/Transport_Processes
• Introduction to Python Computational Science and Engineering
  https://github.com/fangohr/introduction-to-python-for-computational-science-and-engineering

There we explored an alternative approach: the books were authored as collections of Jupyter notebooks, and exported as notebooks, html or pdf.

In this report, we set the stage by describing the benefits of (Jupyter-based) interactive textbooks from the learners and authors perspective, and review our two new interactive text books; we then discuss the workflows we explored, their relative merits, and some best practices to enhance quality and maintenability. We present a template abstracted away from our books that enables new authors to kick-start the writing of their own book. We conclude by highlighting the ease of distribution of interactive textbooks thanks to the Binder Virtual Environment. The table of contents of the two books is provided in the appendix.

Altogether, this demonstrates that the OpenDreamKit efforts, notably T4.1 (#69), T4.3 (#71), T4.6 (#74), and T4.8 (#76) contributed to lower barriers for including computations in science education while significantly improving the maintainability of such interactive materials by proper use of automated validation.

[IzabelaFaguet]

Hello everyone!
We are organising an ODK report writing sprint From August 24th to August 31st,
a good opportunity to finish the final reports in a pleasant and friendly environment.
Would someone like to participate?

The link to the poll: https://framadate.org/tfuHjZgcSU8pHI45

[nthiery]

I have read through the current file, made some minor editions and added some TODO's. Thanks much @fangohr and @marijanbeg for your more than timely contribution!

[nthiery]

Hi @marcinofulus,
We urgently need your contribution: description of your textbook and elements of discussion based on your experience, so that the report can then be made into a single coherent whole.
What's your time line?
Thanks in advance,

[nthiery]

Salut @ocayrol,
When this report will be roughly complete, it would be very useful if you could review it, and contribute to the discussion about tools, approaches, and best practices for authoring notebooks.
Would you have some time during the upcoming week? If yes, when?
Of course you are more than welcome to join here in Cernay :-)
Amitiés,

[marcinofulus]

Hi, I will be working on the report today. Out textbooks are being finished, first 2 are on my github, the 3rd will appear in few days. There is mostly work on text going on, while key ideas and code are already there. BTW, I have "stolen" the bookbook idea from Hans, which is nicely simple (originally I wanted to make rst/sphincs/ipynb combo). mk

…

On Sun, Aug 25, 2019 at 11:34 PM Nicolas M. Thiéry ***@***.***> wrote: Hi @marcinofulus <https://github.com/marcinofulus>, We urgently need your contribution: description of your textbook and elements of discussion based on your experience, so that the report can then be made into a single coherent whole. What's your time line? Thanks in advance, — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#39?email_source=notifications&email_token=AAJDC5UPUXSQV3TW6QFCV53QGL3HDA5CNFSM4BPHFDVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5C4IDA#issuecomment-524665868>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAJDC5T265KODMJ2COSOYV3QGL3HDANCNFSM4BPHFDVA> .

-- Head of Department of Computational Physics and Electronics Institute of Physics University of Silesia ul. 75 Pułku Piechoty 1A 41-500 Chorzów, Poland tel. +48 32 3497 612 http://icse.us.edu.pl --------------------------- Linux: because rebooting is for adding new hardware.

[nthiery]

I will be working on the report today.

Great, thanks!

Out textbooks are being finished, first 2 are on my github, the 3rd will appear in few days. There is mostly work on text going on, while key ideas and code are already there.

Cool; please add links from the abstract.

BTW, I have "stolen" the bookbook idea from Hans, which is nicely simple (originally I wanted to make rst/sphincs/ipynb combo).

Ok! Definitely something that should be discussed in the section of the report about authoring tools and their pros and cons.

[nthiery]

Bringing here a piece of conversation from D2.9 #49:

We should have add "interactive books" to our online use cases section, with references to all the interactive textbooks that we authored (and possibly others too). This would be a natural place to disseminate the discussions from this report: merits of interactive textbooks, available tools, best practices, etc.

There are two options to achieve this:

• link from the use case page to the report;
• move the discussions from the report to the use case page, and link to them from the report (or include a copy as appendix).

It feels like the latter will make the information easier to discover for potential authors, and have some more chance to keep evolving later on (e.g. addition of more references? of an authoring tutorial? of a cookie-cutter?.

What do you think?

[marcinofulus]

I am preparing a cookie-cutter with all problems and solution in book-book workflow

[nthiery]

Good morning @marcinofulus
I am reviewing the current version (@fangohr did some review earlier today).
In the mean time, could you write an abstract in the issue description above?
Thanks!

[nthiery]

The abstract from D2.9 #49 is presumably a good starting point.

[marcinofulus]

I worked on cookie cutter now, and I will also write a short subsection on it.

[nthiery]

> about live cells in the HTML export I did not try. It could be possible in principle, if all cells per page are linked. But I like the idea that the whole notebook is available in e.g. binder for running and in pdf for reading. Set of notebooks is easier to maintain and extent - and it is the main advantage of this solution.

Yes, for serious reading, live notebook (e.g. in binder) or pdf is best. Having -- in addition -- a live HTML export is nice for the casual reader that stumbles on one page and just wants to briefly try out something. (I am not sure what you mean by "all cells per page are linked". You mean can be run with the same kernel?)

[marcinofulus]

yes - usually in sagecells I tries to aviod dependences, notebooks on the contrary are considered generally to be a one program (by me I mean)

[marcinofulus]

Did you review 3rd perspective ?

[marcinofulus]

@nthiery I am handling todos now...

[nthiery]

@nthiery I am handling todos now...

Great. Let me know when done, and I'll review all at once. I now see what you mean about linked cells. Yeah, this may influence the style of writing indeed.

[marcinofulus]

@nthiery was sagemath/sagemath:latest docker image done by ODK?

[nthiery]

@nthiery was sagemath/sagemath:latest docker image done by ODK?

Confirmed: it's all work by Erik and Julian, including the automated build system behind it. +1 to putting such cross-reference in your report(s). You can cite D3.1 (#58).

[marcinofulus]

I have updated https://github.com/OpenDreamKit/authoring_cookie_cutter, mentioned in - it implements workflow without notebook output cells in git (also no nbval).

[nthiery]

I have just reviewed the document, extracting an abstract in the github issue above. Altogether, it's very close to be ready.

[nthiery]

@ocayrol: please see if you could contribute some of your insight on the Sphinx vs Notebook authoring workflows:

OpenDreamKit/WP2/D2.14/report.tex

Line 374 in 7fa8f33

\subsubsection{Workflows and comparison of their relative merits}

[nthiery]

@marcinofulus: there are still a few questions from the original task that are not addressed in our report; see the github issue description above. Can you see what can be done?

[nthiery]

@IzabelaFaguet: please proofreading the whole text.

[marcinofulus]

@marcinofulus: there are still a few questions from the original task that are not addressed in our report; see the github issue description above. Can you see what can be done?

I think that they are answered indirectly, but of course I will try to make it more direc.

[marcinofulus]

I added some direct answers to monograph questiom I think also that there is already answer on collaboration (github vs email to github operator;).

[marcinofulus]

@nthiery , I think that now questions are addressed.

[embray]

I made a few minor proofreading edits.

[marcinofulus]

@embray thanks!,

[nthiery]

Thanks @marcinofulus for the last touches.
@embray: really appreciate all the continuous proofreading you have done; it's super precious and got this deliverable on time!

[nthiery]

Well, almost; for some reason, it was due M47. Good enough :-)

[nthiery]

Good that I checked a last time my e-mail in my tent before going to sleep :-)

@marcinofulus, @fangohr: thanks for the report which will be a useful read for future authors too.

Four textbooks that is, while exploring and demonstrating ODK technologies; pretty cool! Thanks a lot for all the work; @marcinofulus: you'll congratulate all contributors in Silesia on my behalf. With a thought for Jan.

I am looking forward a use case section on interactive text books!

[nthiery]

The use case section should mention jupyter-book as well (book authored in notebooks + markdown; export as static web site with Jekyll, with download links, in the work ThebeLab support, etc.). Originates from the Data 8 course.