Feat/tutorials2

[rosecers]

This is a draft PR to provide a pipeline for adding the tutorials to master. The rebase became unwieldy, so @Luthaf suggested a new branch from master with only the existing files. Currently the tutorials are as follows (all within the docs/source/tutorials folder):

• Advanced_SOAP.ipynb - For introducing lambda-SOAP, Bispectrum, DVR
• Benefits_Performance.ipynb - Comparison of LR performance and benchmarks
• benchmark_tutorial.cc - Unknown
• Converting_Quip.ipynb - Converting quippy workflow to LR (based off of https://libatoms.github.io/QUIP/Tutorials/quippy-descriptor-tutorial.html)
• Hyperparameters.ipynb - Notebook about playing around with hyperparameters
• Introduction_to_Atomic_Descriptors.ipynb - General introduction of atomic descriptors and SOAP
• Kernels.ipynb - Generating different kernels using LR
• nl-for-user - how to use the C++ interface for building neighbor lists
• Property_Prediction_Tutorial.ipynb - Use of SOAP vectors for linear regression
• TutorialEn.rst - tutorial developed by old master's student, from what I understand. Mostly deprecated.
• Tutorial_Template.ipynb - General template for tutorials

notebooks listed in bold are in progress or completed, those listed in italics are empty as of opening this PR

Envisioned tutorial flows are (as defined in index.rst): For new users:

1. Introduction_to_Atomic_Descriptors.ipynb
   

2. Hyperparameters.ipynb
   

3. Property_Prediction_Tutorial.ipynb
   

4. Kernels.ipynb
   

5. Benefits_Performance.ipynb
   

6. Advanced_SOAP.ipynb
   

For users coming from QUIP:

1. Benefits_Performance.ipynb
   

2. Converting_Quip.ipynb
   

3. Hyperparameters.ipynb
   

4. Property_Prediction_Tutorial.ipynb
   

5. Kernels.ipynb
   

6. Advanced_SOAP.ipynb
   

For developers:

1. nl-for-user

Other existing examples/tutorials, which can be worked into documentation:

• alanine_chain.cc - written by @mastricker in June 2018
• center_select_example.py - Example for selecting centres by species, written by either @felixmusil or @max-veit, I am guessing
• coulomb_example.ipynb - Example to compute the atom centered Coulomb Matrix representation
• json_structure.cc - written by @felixmusil in Aug. 2019, example for constructing atomic structures and StructureManagers from JSON
• linked_cells.ipynb
• spherical_expansion_example.cc - written by @max-veit in June 2019, Example for computing the spherical expansion
• spherical_expansion_example.ipynb
• spherical_invariants_example.cc - written by @max-veit in June 2019
• structure_manager_iterator.cc - written by @mastricker in Nov. 2018, brief highlights the building and iteration possibilities of the concept 'structure manager' and adaptors

Intended Purpose of this PR

• Agree on tutorials vs. examples and what goes where
• Agree on general tutorials format/coverage
• Include necessary notebooks in tutorials and decide where in the flow they go
• Investigate a better way to include the notebooks in the documentation other than including in docs/source/tutorials
• Solicit help on more specialized notebooks

Tasks before review:

• [ ] Add tests, examples, and complete documentation of any added functionality
  • [ ] Make sure the autogenerated documentation appears in Sphinx and is formatted correctly (ask @max-veit if you need help with this task).
  • [ ] Write additional documentation in the Sphinx (not docstrings!) to explain the feature and its usage in plain English
  • [ ] Make sure the examples run (!) and produce the expected output
  • [ ] For bugfix pull requests, list here which tests have been added or re-enabled to verify the fix and catch future regressions as well as similar bugs elsewhere in the code.
• [ ] Run make lint on the project, ensure it passes
  • [ ] Run make pretty-cpp and make pretty-python, check that the auto-formatting is sensible
  • [ ] Review variable names, make sure they're descriptive (ask a friend)
  • [ ] Review all TODOs, convert to issues wherever possible
  • [ ] Make sure draft, in-progress, and commented-out code is moved to its own branch
• [ ] If committing any code in Jupyter/IPython notebooks, install and run nbstripout
• [ ] Merge with master and resolve any conflicts
• [ ] (anything else that's still in progress)

[mastricker]

I would like to discuss this also in the meeting. I'll put it in the minutes.

Quickly here: I do like the structure, especially of the python-side notebook. There should probably be an additional "Behler-Type" introduction. Maybe something like coming from n2p2. It is what I use and what colleagues of mine and you use for the Behler Parinello Neural Networks (BPNN). We do want a legacy version of the BPNN, which allows to reuse existing trained neural networks (testing, speed comparison, etc.). But the workflows might be too different to make less of a conversion than making two tutorials:

1. How to train BPNN style potentials with librascal
2. How to reuse your existing parametrization of n2p2 trained potentials.

You list c++ examples. My gut says most of the people do not care about the backend of librascal. I.e.: they don't even want to touch the c++ side. These examples could be part of the developer tutorials maybe?

Other remarks to thinkg about: The emphasis on (former) QUIP users seems strong. In the metals/metallurgy community, I do not know many people who use QUIP. One reason of it is that it is just too slow. A lot of people in that community - good or bad - focus on neural network type models. If we want librascal to be attractive to this community, we should probably make two tracks: QUIP and NN style tutorials.

[felixmusil]

The emphasis on (former) QUIP users seems strong.

For clarity I would mention GAP users rather than QUIP users since the QUIP package does many other things.

[max-veit]

And to be fair, quite a bit of the audience we're writing these for will be GAP users who will want to switch for the speed boost (and modern SOAP features). Of course we're planning on having two tracks for SOAP/SO(3) and ClusterExpansion uses; this is mainly just starting with what we know.

[mastricker]

I am not saying you intentionally omitted it. Just trying to provide feedback from my perspective. Maybe we could make that section something like:

Transition from other libraries

For clarity I would mention GAP users rather than QUIP users since the QUIP package does many other things. I was just quoting what is stated in the opening.

Another thing to maybe keep in mind: are we in competition to DScribe and should we add transition tutorials for that? (I don't know anybody who uses it)

Just to summarize a little for the discussion tomorrow: Provide transition tutorials from?

• n2p2
• QUIP (specifically GAP-type)
• DScribe
• DeepMD