Developer Training - Oxford 17^th of April 2024

Schedule

Overview of the project and folder structure

• Provide fast, reliable battery simulations

​

• Grow battery modelling community

​

• Facilitate development of new battery models

​

• Improve reproducibility of research�
• Increase impact and industry engagement

Python Battery Mathematical Modelling

PyBaMM's mission is to accelerate battery modelling research by providing an open-source framework

for multi-institutional, interdisciplinary collaboration.

​

PyBaMM has fostered an active community with almost

40 contributors and hundreds of users. Our most recent training workshop attracted almost 400 participants,

over 100 of which were from industry.

Python Battery Mathematical Modelling

PyBaMM's mission is to accelerate battery modelling research by providing an open-source framework

for multi-institutional, interdisciplinary collaboration.

​

PyBaMM has fostered an active community with over 40 contributors and hundreds of users. The project attracts users and developers from around the world.

The PyBaMM community has seen rapid growth over the last 3 years. Our most recent training workshop attracted almost 400 participants,

over 100 of which were from industry.

Python Battery Mathematical Modelling

An open-source framework for predicting battery behaviour, a virtual physics lab to explore new mechanisms, a quality control environment to compare models, and a testing ground to validate model predictions.

Who is PyBaMM?

A maintainers team and steering council oversee the growth and direction of the project

Valentin

Sulzer

Martin

Robinson

Robert

Timms

Tom

Tranter

Ferran�Brosa Planella

Jon

Chapman

Scott

Marquis

Saransh

Chopra

Priyanshu

Agarwal

Jacqueline

Edge

Maintainers

Team

Gregory Offer

Ferran�Brosa Planella

Valentin

Sulzer

Saransh

Chopra

Martin

Robinson

Steering Council

Eric G. Kratz

Simon O'Kane

Agriya Khetarpal

Arjun Verma

PyBaMM structure�https://github.com/pybamm-team/PyBaMM�

PyBaMM structure�https://github.com/pybamm-team/PyBaMM�

PyBaMM structure�https://github.com/pybamm-team/PyBaMM�

PyBaMM infrastructure

The infrastructure is a series of tools that allow us to maintain the package standard, and let us know when it’s not the case.

The most important ones are:

• Tests
• Docs
• Coverage
• Benchmarks
• Workflows

Tests

Check that the code does what it is meant to do.

Docs

Documentation automatically generated and hosted at https://docs.pybamm.org

Coverage

Percentage of the code covered by the unit tests (should be 100% for any new code).

Benchmarks

Check how fast the code runs (under development/improvement).

Workflows

“Bots” that perform routine tasks automatically, e.g. run tests, publish new version to PyPI…

Accessing support

PyBaMM doesn’t do something you think it should?

​

Not sure how to use existing features or implement your own model?

​

Interested in commercial or academic collaboration?

​

Please get in touch!

Further information – pybamm.org

Follow us on twitter - @pybamm_ and @battbot_

Star us on GitHub - PyBaMM

Join us on Slack

Try our online examples - colab.pybamm.org

PyBaMM Contribution Workflow:

Getting started with Git/GitHub

Workflow to contribute to PyBaMM

Step 0: fork the PyBaMM repository (see How to Sync a fork)

Colour code:

• Developer
• Maintainer

Discuss proposed changes

What is Git?

• Git is a free, open-source distributed version control system designed to handle everything from small to large projects with speed and efficiency
• Key features: Version control, Collaboration, Branching, Merging

​

https://www.diagrams.net/blog/gitflow-diagram

What is GitHub?

• GitHub is a web-based platform for version control and collaboration, built on top of Git, allowing users to manage repositories, collaborate, and contribute to open-source projects
• Key features: Repository hosting, Issue tracking, Pull requests, Code review, Project management

GitHub Issues

• Issues are a way to track bugs, enhancements, and other tasks related to a project on GitHub.
• Use cases: Bug reporting, Feature requests, Task assignment, Collaboration

Branches

• Branches are pointers to specific commits in a repository, allowing you to create a separate line of development
• Use cases: Feature development, Bug fixes, Experimentation

https://the-turing-way.netlify.app/reproducible-research/vcs/vcs-git-branches.html

PyBaMM branches

• CalVer: 4 monthly release (YY.MM, no distinction between major and minor releases)
• Main branch: latest release
• Develop branch: latest approved changes
• All PRs merge into develop
• Develop branch gets merged into main branch on every release

Forks

• A fork is a copy of a repository that allows you to freely experiment with changes without affecting the original project
• Use cases: Contributing to open-source projects, Creating your own version of a project

https://www.tomasbeuzen.com/post/git-fork-branch-pull/

Branches vs Forks vs Clone

https://flatironinstitute.github.io/sciware-git-collaborative/01-remotes/

GitHub Pull Requests

• Pull requests are a way to propose changes to a repository, allowing collaborators to review and discuss the changes before merging them into the main branch
• Use cases: Code review, Collaboration, Merging changes

How to review a PR?

• Line added
• Line removed
• Line changed

Tips to review a PR

• Check workflows (tests & coverage).

​

• Ask questions if something is not clear.

​

• Feel free to suggest changes.

​

• Be specific/reasonable with the suggested changes.

​

• Be nice to the person who opened the PR (sometimes they are new to PyBaMM/OSS).

​

• Re-review the PR once changes have been made.

Git conflicts

• Git conflicts occur when two or more developers make changes to the same lines of code in the same file, or when one developer deletes a file while another developer makes changes to it
• Causes: Simultaneous changes, Divergent branches, Deleted files
• Conflict markers: <<<<<<<, =======, >>>>>>>
• Steps to resolve conflicts:
• Identify conflicting files
• Examine and edit conflict markers
• Merge changes and save the file
• Commit the resolved conflict
• Tips: Communicate with team members, Use branches for separate tasks, Regularly pull and merge changes
• ​

Workflow to contribute to PyBaMM

Colour code:

• Developer
• Maintainer

Questions?

Model Development

Schedule

https://train.oxrse.uk/

1. Login with your github account
2. Enrol on “PyBaMM Developer Training”
1. Use key: pybamm_developer_training
3. Navigate to material via sidebar or go to https://train.oxrse.uk/material/HPCu/libraries/pybamm-developer