Metadata-Version: 2.4
Name: PyBaMM-GEM
Version: 0.1.0
Summary: A PyBaMM-compatible extension package for advanced battery models, research models, and simulation tools.
Project-URL: Homepage, https://github.com/mohammedasher/PyBaMM-GEM
Project-URL: Bug Tracker, https://github.com/mohammedasher/PyBaMM-GEM/issues
Project-URL: Discussions, https://github.com/mohammedasher/PyBaMM-GEM/discussions
Project-URL: Changelog, https://github.com/mohammedasher/PyBaMM-GEM/releases
Author-email: Mohammed Asheruddin N <mnazeeru@ic.ac.uk>
License-File: LICENSE
License-File: LICENSES-bundled.txt
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: pybamm
Provides-Extra: dev
Requires-Dist: nox[uv]; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov>=3; extra == 'dev'
Requires-Dist: pytest>=6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: ipython; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx-gallery; extra == 'docs'
Requires-Dist: sphinx-inline-tabs; extra == 'docs'
Requires-Dist: sphinx-last-updated-by-git; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex; extra == 'docs'
Description-Content-Type: text/markdown

# PyBaMM-GEM

PyBaMM-GEM is an open, collaborative ecosystem for developing, validating, sharing, and maintaining advanced battery models, submodels, and parameter sets that extend the PyBaMM framework.

PyBaMM has transformed battery modelling by providing a powerful, modular, and open-source framework for electrochemical simulation. As battery research continues to advance, new models are constantly being developed to address emerging scientific questions, explore new physical phenomena, and support industrial innovation. Many of these developments are experimental, highly specialised, or under active research, making them unsuitable for inclusion in the core PyBaMM project during their early stages.

**PyBaMM-GEM provides a home for these developments.**

Rather than maintaining a separate modelling framework or encouraging fragmented forks of PyBaMM, GEM extends the PyBaMM ecosystem by providing a common platform where researchers can develop, compare, validate, publish, and maintain cutting-edge battery models while remaining closely aligned with the design philosophy and user experience of PyBaMM.

Some GEM models may eventually become part of the core PyBaMM project. Others may remain within GEM because they address specialised scientific questions or niche applications. Both outcomes are considered successful.

Our long-term vision is to establish PyBaMM-GEM as a collaborative ecosystem where the next generation of battery models is developed, evaluated, and shared with the wider community.

---

# Why GEM?

Scientific software advances by balancing two complementary objectives: stability and innovation.

PyBaMM rightly prioritises stability, maintainability, and broad community applicability.

Research, however, moves much faster.

Every year, researchers develop new electrochemical models, degradation mechanisms, parameterisations, constitutive laws, numerical approaches, and modelling assumptions. These developments often require years of validation before they are mature enough for inclusion in a widely used scientific software package. Some may never belong in the core library because they address specialised scientific or industrial problems.

PyBaMM-GEM provides an environment where these ideas can be developed openly while remaining fully compatible with PyBaMM.

The goal is not to replace PyBaMM.

The goal is to accelerate battery modelling research around PyBaMM.

---

# What belongs in GEM?

PyBaMM-GEM focuses exclusively on extending the modelling capabilities of PyBaMM.

The project includes:

* Battery models
* Battery submodels
* Parameter sets
* Modified variants of existing PyBaMM models and submodels
* Documentation, scripts, and notebooks accompanying each contribution

Every scientific contribution should include runnable examples demonstrating:

* the scientific motivation,
* implementation,
* validation (where available),
* and how it differs from the corresponding implementation in PyBaMM.

PyBaMM-GEM is **not** intended to become a general battery software platform. Workflow management, optimisation, digital twins, data analysis, and unrelated utilities are intentionally outside the scope of this project.

---

# Design Philosophy

The philosophy of GEM is simple.

**Stay close to PyBaMM. Explore beyond it.**

GEM follows the architecture, programming style, and user experience of PyBaMM wherever practical. Existing PyBaMM users should feel immediately familiar with GEM, allowing new scientific developments to be adopted with minimal learning.

Scientific transparency is a fundamental principle. GEM never silently changes the behaviour of an existing PyBaMM implementation. Whenever a GEM implementation differs scientifically from PyBaMM, it is exposed through an explicit GEM-specific model or option so that published research remains reproducible and unambiguous.

Every release of GEM is developed against a defined range of PyBaMM versions and documents its compatibility.

---

# Why "GEM"?

Originally, **GEM** stood for **General Enough Model**—a long-standing research vision of developing battery models with the minimum complexity required to explain the physical behaviour of interest.

As the project evolved, this philosophy naturally broadened. GEM also represents the idea of a **Good Enough Model**: selecting the minimum set of physical processes and governing equations required to accurately describe a given scientific problem without unnecessary complexity.

The name is also inspired by **Professor John B. Goodenough**, whose pioneering contributions fundamentally shaped modern lithium-ion battery science and continue to inspire battery modelling research today.

While these meanings reflect the origins and philosophy of the project, **GEM has grown beyond an acronym**. Today, PyBaMM-GEM represents an ecosystem dedicated to advancing battery modelling research through open, collaborative scientific software.

---

# Installation

```bash
pip install pybamm-gem
```

```python
import pybamm_gem
```

---

# Relationship with PyBaMM

PyBaMM-GEM depends on the official PyBaMM project.

It does not replace PyBaMM, fork PyBaMM, or maintain an independent battery modelling framework.

Instead, GEM extends the PyBaMM ecosystem.

Where appropriate, mature GEM models may eventually be adopted into PyBaMM. Conversely, specialised research models may continue to be developed and maintained within GEM indefinitely.

---

# Contributing

Researchers from academia, industry, and national laboratories are encouraged to contribute new models, submodels, parameter sets, documentation, validation studies, and example notebooks.

Every contribution should improve the scientific capability of the PyBaMM ecosystem while preserving the principles of transparency, reproducibility, and compatibility that underpin both PyBaMM and GEM.

---

# Citation

If you use PyBaMM-GEM in academic work, please cite both:

* PyBaMM
* the relevant GEM model or publication

---

# License

PyBaMM-GEM is distributed under the BSD 3-Clause License.
