Restructure examples directory

[BradyPlanden]

Feature description

The current examples directory includes a variety of unordered workflows. This should be restructured to provide a clearer entry point for users looking for specific functionality. I propose we do something like:

• Optimisation Type (Fitting, Design Optim., etc.)
  • {model}_{cost function}.py

For both examples/notebooks/ and examples/scripts/. In this restructure we can reduce the total number of examples by using multipler optimisers for each {model}_{cost function}.py. This would look something like our integration test test_parameterisation.py.

Motivation

No response

Possible implementation

No response

Additional context

No response

[arjxn-py]

Hey @BradyPlanden, I'd want to work on this one and am happy to discuss more about -

Optimisation Type (Fitting, Design Optim., etc.)

Do you want to maybe sub-group notebooks & scripts as well or just give to give them more clearer names?

For reference & a sample example, please have a look at a1eaa84

[BradyPlanden]

Hi @arjxn-py, excellent, thanks! In terms of structure, I'm thinking we probably need to do a larger structural change with more curated examples. Currently, we have quite a few example scripts that have duplicate functionality with only an optimiser change. A first step would be to update to the below structure (open to other suggestions @NicolaCourtier @martinjrobins @agriyakhetarpal), then we can start populating the examples directory. It's worth noting that this issue cross-links to #173.

• examples/notebooks

  • Getting Started

    • creating_a_model.ipynb
    • creating_a_problem.ipynb
    • creating_a_cost.ipynb
    • simple_parameterisation.ipynb
    • simple_optimisation.ipynb
    • simple_plotting.ipynb
    • import_export_parameter_sets.ipynb

  • Costs

    • simple_costs.ipynb
    • maximum_likelihood.ipynb
    • maximum_a_posteriori.ipynb

  • Optimisers

    • multi_optimiser_identification.ipynb
    • optimiser_interface.ipynb
    • optimiser_calibration.ipynb
    • gradient_non_gradient_optimisers.ipynb

  • Identification Workflows

    • pouch_cell_identification.ipynb
    • diffusion_identification.ipynb (GITT)
    • thevenin_identification.ipynb
    • single_particle.ipynb
    • single_particle_with_electrolyte.ipynb
    • doyle_fuller_newman.ipynb

  • Optimisation Workflows

    • spm_electrode_design.ipynb

  • Observers

    • unscented_kalman_filter.ipynb

  • Monte Carlo Samplers

    • simple_monte_carlo.ipynb
    • parameter_transformation.ipynb
    • *different_methods.ipynb
    • summary_diagnostics.ipynb

[NicolaCourtier]

Thanks @BradyPlanden and @arjxn-py for getting started on this issue! My suggestion would be to group the examples as follows - focusing more on workflows rather than specific costs/models/optimisers since we have designed these objects to be fairly interchangeable.

Getting Started (focused around objects that can be visualised)

• plotting_a_dataset (loading an example dataset from within PyBOP and plotting)
• importing_a_pybamm_model (importing, running and plotting the result of a PyBaMM model)
• import_export_parameter_sets (importing, exporting and viewing parameter sets)
• defining_parameters (defining one parameter, adding, removing from parameters, showing different properties, plotting prior)
• parameter_identification (a minimal example showing the set up and identification of two parameters from data, plotting cost, trace and result)
• parameter_optimisation (as above but for optimisation of two design parameters)

Comparison Examples (demonstrating the choices available and range of performance)

• comparing_error_measures (comparing different costs for parameter identification)
• comparing_optimisers (comparing different optimisers, gradient and non-gradient based)
• comparing_samplers (comparing different samplers)
• optimiser_calibration (showing how gradient descent can be tailored)

Battery Parameterisation (moving toward workflows that are appropriate for the type of data available)

• OCP_balance
• diffusion_identification/GITT_fitting
• pouch_cell_identification
• thevenin_identification
• unscented_kalman_filter

Design Optimisation

• spme_max_energy

It would be great to have the same key examples included as both scripts and notebooks. We should probably try to get a full set of Getting Started examples together first before moving to the following sections. Happy to discuss further.

[arjxn-py]

Hi, while commenting on this issue first I thought it was more about restructuring the directory instead of notebooks i.e. Renaming & segregating the notebooks. As I do not have much experience with battery modelling, I might not be the best person writing these notebooks from scratch.

Although I tried deriving one notebook i.e. plotting_a_dataset.ipynb here in this commit but it cannot import DFN (same is the case with other pre-existing notebooks, I'm not sure if it's an issue from my end or Code), on a side note I'd be happier to pick up those issues first for which I hold a bit of experience maybe. Thanks & Apologies.

[NicolaCourtier]

Thanks for having a go @arjxn-py! Looks like you were on the right track 👍

The reason for the import issue is the PyBOP version - the DFN model is not included in the current release (v24.3), but it is on the develop branch and will be in the next release. To work with the current version, try (temporarily) replacing the line %pip install pybop -q with pip install git+https://github.com/pybop-team/PyBOP.git@develop -q. For me though, it was not that easy in WSL/VSCode. I also needed to create a new kernel (of the venv variety, using the kernel picker in the top right) to ensure that the packages are installed into the relevant workspace.

To get your example working, simply change the last line from simulate to predict and add some plotting, e.g.

values = synth_model.predict(t_eval=t_eval)
dataset["Voltage [V]"] = values["Voltage [V]"].data
pybop.plot_dataset(dataset);

Some of our current examples could also just be renamed to tick off many of my suggestions above, as follows:

getting_started

• plotting_a_dataset.ipynb
• spm_AdamW -> parameter_identification.ipynb
• spm_electrode_design -> parameter_optimisation.ipynb

comparison_examples

• multi_model_identification -> comparing_models.ipynb
• multi_optimiser_identification -> comparing_optimisers.ipynb
• optimiser_calibration.ipynb
• optimiser_interface.ipynb

battery_parameterisation

• 1-single-pulse-circuit-model -> LGM_50_identification.ipynb
• equivalent_circuit_identification -> thevenin_identification.ipynb
• pouch_cell_identification.ipynb
• gitt.py -> diffusion_identification_from_gitt.py
• exp_UKF.py -> unscented_kalman_filter.py
• all other scripts can go here for now (most are repeats with only slight changes)

design_optimisation

• spm_electrode_design -> energy_maximisation.ipynb
• spme_max_energy -> energy_maximisation.py

Further examples can be added in future (some are already other open issues, such as OCP_balance).

[arjxn-py]

Thanks a tonn @NicolaCourtier, this comment of yours was really very helpful 🚀
I've made some suggested changes to the notebook & now it seems to be working.

Though i'd need to mention that as I created a fresh python==3.11 environment for this, I had to install these separately after installing pybamm & pybop -

%pip install plotly -q
%pip install kaleido -q
%pip install nbformat>=4.2.0 -q

Should I also install them in notebook too?

[NicolaCourtier]

Looks great @arjxn-py, thanks! I think these dependencies should all be included in the latest version of pybop, so there's no need to add these lines to the notebook. To check that it works with the upcoming release, please try running nox -s notebooks to test all the notebooks (a command which should be added to the documentation here).