PyBaMM-GEM 0.1.0__tar.gz → 0.2.1__tar.gz

pybamm_gem-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+# Runs the tests on every push and pull request, and every Monday, against the latest
+# PyBaMM release. A failing scheduled run opens ONE issue (or adds a comment to the open
+# one). It never changes any code.
+name: CI
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "17 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  release:
+    name: PyBaMM release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest
+
+  report:
+    name: Report a failure
+    needs: [release]
+    if: ${{ always() && github.event_name == 'schedule' && needs.release.result == 'failure' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Open an issue, or comment on the open one
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          TITLE="Weekly check failed"
+          NUMBER=$(gh issue list --repo "$REPO" --state open --search "$TITLE in:title" --json number --jq '.[0].number')
+          if [ -z "$NUMBER" ]; then
+            gh issue create --repo "$REPO" --title "$TITLE" --body "The weekly check failed. See $RUN_URL"
+          else
+            gh issue comment "$NUMBER" --repo "$REPO" --body "Failed again. See $RUN_URL"
+          fi

pybamm_gem-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,103 @@
+# Publishes PyBaMM-GEM when a GitHub release is published (tag "v" + the version in pyproject.toml).
+#   1. Build the package and run its tests.
+#   2. Upload to TestPyPI, install it from there and run the tests again.
+#   3. Upload to PyPI. This step waits until a maintainer approves it (GitHub environment "pypi").
+# No tokens are stored anywhere: PyPI and TestPyPI trust this workflow ("trusted publishing").
+# Running it by hand (Actions -> Release -> Run workflow) only does steps 1 and 2, as a test.
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check that the release tag matches the version
+        if: github.event_name == 'release'
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$VERSION" != "$GITHUB_REF_NAME" ]; then
+            echo "The tag is $GITHUB_REF_NAME but pyproject.toml says version $VERSION"
+            exit 1
+          fi
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+      - name: Test the built package
+        run: |
+          pip install dist/*.whl pytest
+          cd /tmp
+          pytest --import-mode=importlib --pyargs pybamm_gem
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    name: Upload to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  check-testpypi:
+    name: Install from TestPyPI and test
+    needs: testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install and test
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          pip install "pybamm[cite]>=26.9" pytest
+          # A new upload can take a few minutes to appear on TestPyPI
+          for attempt in 1 2 3 4 5 6 7 8 9 10; do
+            if pip install --no-deps --index-url https://test.pypi.org/simple/ "pybamm-gem==$VERSION"; then
+              break
+            fi
+            sleep 30
+          done
+          cd /tmp
+          python -c "import pybamm_gem; print(pybamm_gem.__version__, pybamm_gem.list_models())"
+          pytest --import-mode=importlib --pyargs pybamm_gem
+
+  pypi:
+    name: Upload to PyPI (needs approval)
+    needs: check-testpypi
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pybamm_gem-0.2.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv*/
+.pytest_cache/
+.ruff_cache/
+.ipynb_checkpoints/

pybamm_gem-0.2.1/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.1
+
+- `pybamm_gem` now has the same commands as the PyBaMM model zoo: `require()` is new, and
+  `info()`, `load()`, `require()` and `register_citation()` accept the class name (for example
+  `"BasicSPM2D"`) as well as the slug (`"spm_2d"`).
+- `info()` fields can be read as `info.title` as well as `info["title"]`.
+
+## 0.2.0
+
+- Rebuilt in the PyBaMM model-zoo layout: one folder per model, each with a `model.toml`
+  manifest, `CITATION.bib`, `README.md`, tests and an example.
+- Models: `spm_2d` (`BasicSPM2D`), `spm_3d` (`BasicSPM3D`), `dfn_2d` (`DFN2D`) and `dfn_3d` (`DFN3D`).
+- Registry: `pybamm_gem.list_models()`, `pybamm_gem.info()` and `pybamm_gem.load()`.
+- Example notebook: `examples/higher_dimensional_models.ipynb`.
+- Needs PyBaMM 26.9 or newer.
+- The previous code is kept on the branch `legacy-2026-11`.

pybamm_gem-0.1.0/LICENSE → pybamm_gem-0.2.1/LICENSE.txt

@@ -1,28 +1,29 @@
-BSD 3-Clause License
-
-Copyright (c) 2026, Mohammed Asheruddin (Asher)
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+BSD 3-Clause License
+
+Copyright (c) 2026, Imperial College London
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pybamm_gem-0.2.1/LICENSES-bundled.txt

@@ -0,0 +1,37 @@
+PyBaMM-GEM contains code adapted from PyBaMM (https://github.com/pybamm-team/PyBaMM):
+
+- src/pybamm_gem/spm_2d/model.py, adapted from pybamm/models/full_battery_models/lithium_ion/basic_spm.py
+- src/pybamm_gem/dfn_2d/model.py, the electrolyte and electrode submodel methods, adapted from
+  pybamm/models/submodels/electrolyte_conductivity/full_conductivity.py,
+  pybamm/models/submodels/electrolyte_diffusion/full_diffusion.py and
+  pybamm/models/submodels/electrode/ohm/full_ohm.py
+
+PyBaMM is distributed under the following licence:
+
+Copyright (c) 2018, the PyBaMM team.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pybamm_gem-0.2.1/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: PyBaMM-GEM
+Version: 0.2.1
+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: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyBaMM-GEM
+
+Spatially resolved (2D and 3D) battery models built on [PyBaMM](https://pybamm.org), 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.
+
+## Models
+
+| Slug | Class | What it is |
+|---|---|---|
+| `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 |
+| `dfn_2d` | `DFN2D` | Doyle-Fuller-Newman model resolved in x and z |
+| `dfn_3d` | `DFN3D` | The same, resolved in x, y and z |
+
+## Installation
+
+```
+pip install git+https://github.com/ImperialCollegeLondon/PyBaMM-GEM
+```
+
+PyBaMM 26.9 or newer is needed.
+
+## 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.
+
+## 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`.
+
+## Releasing a new version
+
+1. In a pull request, raise `version` in `pyproject.toml` (for example `0.2.1`) and add a
+   `CHANGELOG.md` entry. Merge it.
+2. On GitHub, go to Releases, then "Draft a new release". Create the tag `v0.2.1` (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).

pybamm_gem-0.2.1/README.md

@@ -0,0 +1,61 @@
+# PyBaMM-GEM
+
+Spatially resolved (2D and 3D) battery models built on [PyBaMM](https://pybamm.org), 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.
+
+## Models
+
+| Slug | Class | What it is |
+|---|---|---|
+| `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 |
+| `dfn_2d` | `DFN2D` | Doyle-Fuller-Newman model resolved in x and z |
+| `dfn_3d` | `DFN3D` | The same, resolved in x, y and z |
+
+## Installation
+
+```
+pip install git+https://github.com/ImperialCollegeLondon/PyBaMM-GEM
+```
+
+PyBaMM 26.9 or newer is needed.
+
+## 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.
+
+## 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`.
+
+## Releasing a new version
+
+1. In a pull request, raise `version` in `pyproject.toml` (for example `0.2.1`) and add a
+   `CHANGELOG.md` entry. Merge it.
+2. On GitHub, go to Releases, then "Draft a new release". Create the tag `v0.2.1` (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).