Metadata-Version: 2.5
Name: PyBaMM-GEM
Version: 0.2.2
Summary: Spatially resolved (2D and 3D) battery models for PyBaMM
Author: Mohammed Asheruddin N
License-Expression: BSD-3-Clause
License-File: LICENSE.txt
License-File: LICENSES-bundled.txt
Keywords: battery,electrochemistry,lithium-ion,modelling,pybamm,simulation
Requires-Python: >=3.10
Requires-Dist: pybamm[cite]>=26.9
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pybamm-model-zoo; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# PyBaMM-GEM

An open-source extension package for PyBaMM providing advanced battery models, degradation
models, and simulation tools.

## Models

```python
import pybamm_gem as gem

print(gem.list_models())
# ['dfn_2d', 'dfn_3d', 'spm_2d', 'spm_3d']
```

| Model | Class | What it is |
|---|---|---|
| `dfn_2d` | `DFN2D` | Doyle-Fuller-Newman model resolved in x and z |
| `dfn_3d` | `DFN3D` | The same, resolved in x, y and z |
| `spm_2d` | `BasicSPM2D` | Single Particle Model with a pair of particles at every height z |
| `spm_3d` | `BasicSPM3D` | The same, over a y-z grid of points |

## Installation

```
pip install pybamm-gem
```

PyBaMM 26.9 or newer is needed. To get the newest code from GitHub instead:
`pip install git+https://github.com/ImperialCollegeLondon/PyBaMM-GEM`

## Usage

```python
import pybamm
import pybamm_gem as gem

print(gem.list_models())
model = gem.load("spm_2d")()
simulation = pybamm.Simulation(model)
solution = simulation.solve([0, 3000])
print(solution["Voltage [V]"](1500))
```

The classes are also available directly, for example `gem.lithium_ion.BasicSPM2D` or
`gem.lithium_ion.DFN2D`.

The commands are the same as in the PyBaMM model zoo (`pybamm_model_zoo`): `list_models()`,
`info()`, `load()`, `require()` and `register_citation()`. `info()`, `load()`, `require()` and
`register_citation()` take either the slug (`"spm_2d"`) or the class name (`"BasicSPM2D"`);
`list_models()` returns the slugs. With `pybamm-model-zoo` installed, the GEM models are also
listed by `pybamm_model_zoo.list_models()`.

The notebook `examples/higher_dimensional_models.ipynb` runs all four models, compares them with
the stock PyBaMM models and shows a temperature that changes with height.

## About PyBaMM-GEM

PyBaMM-GEM is an open, collaborative home for battery models that extend
[PyBaMM](https://pybamm.org). Many new models are experimental, specialised or still under active
research, which makes them unsuitable for the core PyBaMM project in their early stages. GEM is
where they can be developed, validated, compared and shared, while staying close to PyBaMM. Some
GEM models may later move into PyBaMM; others stay in GEM because they answer specialised
questions. Both outcomes count as success.

**Stay close to PyBaMM. Explore beyond it.** GEM models follow PyBaMM's design, options and user
experience, so PyBaMM users feel at home. Where a GEM model differs scientifically from a PyBaMM
model, it is a separate, explicitly named model. Every release states the PyBaMM versions it
supports.

GEM stands for **General Enough Model** and **Good Enough Model**: the fewest physical processes
needed to explain the behaviour of interest. The name also honours Professor John B. Goodenough.

The models are laid out like the PyBaMM model zoo: one folder per model, each with a `model.toml`
manifest, a `CITATION.bib`, a README, tests and an example.

## Automatic checks

- **Every push and pull request, and every Monday:** ruff, GEM's tests and the PyBaMM model zoo's
  contract checks, against the newest PyBaMM and `pybamm-model-zoo`. If the Monday run fails, an
  issue "Weekly check failed" is opened; it is closed when the check passes again.
- **1st of every month:** a health report of the released package (installed from PyPI) with the
  newest PyBaMM and model zoo, posted on the pinned issue "Monthly health report". It can also be
  run by hand with `python scripts/health_report.py`.

## Releasing a new version

1. In a pull request, raise `version` in `pyproject.toml` (for example `0.2.2`) and add a
   `CHANGELOG.md` entry. Merge it.
2. On GitHub, go to Releases, then "Draft a new release". Create the tag `v0.2.2` (a "v" and
   the version), add a title and notes, and publish.
3. The Release workflow builds and tests the package, uploads it to TestPyPI and tests it again.
   It then waits for a maintainer to approve the upload to PyPI (GitHub sends an email).

## Licence

BSD 3-Clause, see `LICENSE.txt`. Copyright (c) 2026, Imperial College London.
Some of the model code is adapted from PyBaMM; see `LICENSES-bundled.txt`.
