[WIP] Improve "Creating Models" series

[brosaplanella]

Description

Refactor and improve the Creating Models series notebooks. I have significantly refactored the existing notebooks, but the underpinning philosophy should be similar. The first few notebooks follow very closely the material from the training session in Oxford (Apr 24) which worked quite well.

Fixes #3844

List of notebooks

1. Creating a simple ODE model: demonstrate the basics of PyBaMM models and illustrate with a simple ODE model. I have used the reservoir model to stick to battery models. I solved the model using the simulation class.
2. Creating a simple PDE model: extends the previous model to solving a PDE model, in this case a simplified version of SPM for a half cell to continue with the battery-flavoured models. I solved the model using the simulation class.
3. Wrapping a model into a class: takes the model from notebook 2 and wraps it into a class.

Other additions

• BasicReservoir model

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist:

• No style issues: $ pre-commit run (or $ nox -s pre-commit) (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
• All tests pass: $ python run-tests.py --all (or $ nox -s tests)
• The documentation builds: $ python run-tests.py --doctest (or $ nox -s doctests)

You can run integration tests, unit tests, and doctests together at once, using $ python run-tests.py --quick (or $ nox -s quick).

Further checks:

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.55%. Comparing base (e22d10c) to head (e870db7).
Report is 3 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #4184   +/-   ##
========================================
  Coverage    99.55%   99.55%           
========================================
  Files          288      289    +1     
  Lines        21856    21918   +62     
========================================
+ Hits         21759    21821   +62     
  Misses          97       97           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[valentinsulzer]

I think it's ok to leave out explanations of the simulation class in this series, and just stick to the models

[brosaplanella]

The PR is not yet ready, but I have hit a point where I would really benefit from some feedback before continuing. I believe that the 3 notebooks I have written introduce all the main features needed to write models except for Broadcasts. I was originally planning on introducing broadcasts in later notebooks, but they would fit well into notebook 2.

Most of the questions I have on how to proceed are related to the model refactoring area #3908. I think everything revolves around the following question: how do we envision users will write their models? Will they write everything from scratch inheriting from the pybamm.BaseModel template, or will they use the features in pybamm.lithium_ion.BaseModel class? If the latter, this could be demonstrated in additional notebooks (e.g. the one I started writing but haven't pushed yet is how to build SPM, and makes extensive use of the lithium ion parameter class). But if the former, any additional notebooks will focus solely on the battery modelling side (happy to do so if that's useful).

Another thing to include, either in notebook 3 or future notebooks, is how to get a Basic model to work with experiments.

TLDR

The three models so far document all the main features someone would need to know to write their own models. There are other features that we could show, but the usefulness of this depends on how we expect users to write models.

Additional questions

Here is a list of additional questions I have. They might open several cans of worms so please only spend time on them after you have given your thoughts on the main points above.

• If we choose to show how to use the lithium ion parameters class, how do we document them? At the moment the syntax is not documented anywhere.
• How do we want to show models in notebooks? Classes need to be defined in a single cell which gets really verbose.
• Some Basic models use slighlty different notation (e.g. some parameters are defined as pybamm.Parameter, some call the LithiumIonParameters class). Is there any reason for this or should I unify them?
• Submodels: I was planning on writing a final notebook on submodels, but I believe it is better to hold this until we have implemented the fix suggested by Valentin in [Roadmap area] Model refactoring #3908 (comment) (unless we don't see this happening any time soon).