Improving PyBaMM's documentation infrastructure – a Google Summer of Code (GSoC) 2023 project

Agriya Khetarpal

20312915002

University of Delhi

About PyBaMM 🔋

• Open-source battery modelling package for conducting experiments and simulations
• Written in Python, interfaces a C++ solver for ODEs and DAEs
• Permissive BSD-3 Clause license
• Prevalent across battery science research, especially for the study of the effects of lithium-ion batteries
• Several common battery models implemented

The what, the why, and the where? 📑

• Lack of a consolidated location for hosting project-specific information for PyBaMM
• Outdated website which is (was) difficult to navigate
• Project wiki, governance, example notebooks were scattered

What I did 🧑‍💻

• New static website for PyBaMM based on a unified theme developed for larger, general-purpose Python packages: NumPy and SciPy
• Contains everything from the previous website + a newsroom + teams page + user guides + community pages: everything under one roof
• Improved documentation infrastructure on https://docs.pybamm.org: multiple widgets and quality-of-life improvements (explained further!)

Documentation infrastructure improvements ⛩️

• Goal: more maintainable documentation
  • Make it easier to write new documentation while also keeping in mind the needs of the users
  • Adding features by liasing with other popular projects in the Scientific Python ecosystem
• Benefits
  • Easier-to-follow API documentation
  • Integrated example notebooks
  • Less breakage, more stability

Before...

...after

Automated references

Thumbnail galleries for example notebooks

Download and run notebooks at ease

Floating-window tooltips for x-references

Autogenerated inheritance diagrams

Integrating Algolia DocSearch: search-as-you-type

Improving the general infrastructure for the package 🚧

• Improved continuous integration and continuous delivery pipelines
  • In most cases, ≥50% faster!
  • Faster documentation builds
  • Some parts of this area overlapped with my GSoC co-student Arjun
  • Docker images for simplified installation
  • PDFs of the documentation on every release

What's next? 🔮

• New template project: pybamm-cookiecutter
  • Provide a standard, opinionated template for battery modelling projects
  • Make using custom parameter sets easier
  • Still a work in progress
• Nightly releases:
  • Create a registry or a server where we upload binary distributions of PyBaMM every night with the latest changes
  • Status: waiting on triage

Post GSoC 🛣️

• We migrated PyBaMM to pyproject.toml 
  • New build format with more reliable installation
  • Modern + up-to-date with the latest Scientific Python guidelines
• Enhanced notebook testing infrastructure
  • Laid down basis for migration to pytest
  • Parallel execution of notebooks – up to 5x faster based on empirical Amdahl's Law calculations, 2x faster on GitHub Actions CI runners

Post GSoC 🧑‍🎓

• Recently appointed as a maintainer trainee (October 2023) with a progressive path to maintainer status
  • I am now giving back to the community by helping triage issues and pull requests, performing code reviews, guiding new contributors, and more
  • I plan to stay involved for a long time

Thank you!

To read more, please read my work product submission using the QR code below