Merge pull request #156 from pybop-team/v23.12

Make release v23.12

Author: BradyPlanden

.all-contributorsrc

@@ -16,7 +16,8 @@
         "infra",
         "test",
         "code",
-        "example"
+        "example",
+        "review"
       ]
     },
     {
@@ -26,7 +27,9 @@
       "profile": "https://github.com/NicolaCourtier",
       "contributions": [
         "code",
-        "review"
+        "review",
+        "example",
+        "test"
       ]
     },
     {
@@ -46,7 +49,35 @@
       "profile": "http://www.rse.ox.ac.uk",
       "contributions": [
         "ideas",
-        "mentoring"
+        "mentoring",
+        "review"
+      ]
+    },
+    {
+      "login": "brosaplanella",
+      "name": "Ferran Brosa Planella",
+      "avatar_url": "https://avatars.githubusercontent.com/u/28443643?v=4",
+      "profile": "https://www.brosaplanella.xyz",
+      "contributions": [
+        "review"
+      ]
+    },
+    {
+      "login": "FaradayInstitution",
+      "name": "Faraday Institution",
+      "avatar_url": "/assets/UKRI.svg",
+      "profile": "https://faraday.ac.uk",
+      "contributions": [
+        "financial"
+      ]
+    },
+    {
+      "login": "UKRI",
+      "name": "UK Research and Innovation",
+      "avatar_url": "/assets/UKRI.svg",
+      "profile": "https://www.ukri.org/",
+      "contributions": [
+        "financial"
       ]
     }
   ],

.github/workflows/release-action.yaml

@@ -1,6 +1,9 @@
 name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
 
-on: push
+on:
+  workflow_dispatch:
+  release:
+    types: [published, prereleased]
 
 jobs:
   build:
@@ -30,7 +33,9 @@ jobs:
   publish-to-pypi:
     name: >-
       Publish Python 🐍 distribution 📦 to PyPI
-    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    if: >
+      startsWith(github.ref, 'refs/tags/') &&
+      !contains(github.ref, 'rc')
     needs:
     - build
     runs-on: ubuntu-latest

.github/workflows/scheduled_tests.yaml

@@ -12,10 +12,11 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.8", "3.9", "3.10", "3.11"]
 
     steps:
@@ -32,7 +33,7 @@ jobs:
           python -m nox -s unit
           python -m nox -s notebooks
 
-    #M-series Mac Mini
+  #M-series Mac Mini
   build-apple-mseries:
     runs-on: [self-hosted, macOS, ARM64]
     env:

.github/workflows/test_on_push.yaml

@@ -1,7 +1,6 @@
 name: test_on_push
 
 on:
-  push:
   workflow_dispatch:
   pull_request:
 
@@ -30,10 +29,11 @@ jobs:
 
 
   build:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.8", "3.9", "3.10", "3.11"]
 
     steps:

.gitignore

@@ -175,6 +175,9 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/examples/generated/
+docs/api/
+warnings.txt
 
 # PyBuilder
 .pybuilder/
@@ -304,3 +307,6 @@ $RECYCLE.BIN/
 
 # Visual Studio Code settings
 .vscode/*
+
+# Output JSON files
+**/fit_ecm_parameters.json

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ ci:
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.5"
+    rev: "v0.1.7"
     hooks:
       - id: ruff
         args: [--fix, --show-fixes]

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+formats:
+   - htmlzip
+   - pdf
+   - epub
+
+python:
+  install:
+    - method: pip
+      path: .[docs]

CHANGELOG.md

@@ -0,0 +1,28 @@
+# [Unreleased](https://github.com/pybop-team/PyBOP)
+
+## Features
+
+## Bug Fixes
+
+# [v23.12](https://github.com/pybop-team/PyBOP/tree/v23.12) - 2023-12-19
+## Features
+
+- [#141](https://github.com/pybop-team/PyBOP/pull/141) - Adds documentation with Sphinx and PyData Sphinx Theme. Updates docstrings across package, relocates `costs` and `dataset` to top-level of package. Adds noxfile session and deployment workflow for docs.
+- [#131](https://github.com/pybop-team/PyBOP/issues/131) - Adds `SciPyDifferentialEvolution` optimiser, adds functionality for user-selectable maximum iteration limit to `SciPyMinimize`, `NLoptOptimize`, and `BaseOptimiser` classes.
+- [#107](https://github.com/pybop-team/PyBOP/issues/107) - Adds Equivalent Circuit Model (ECM) with examples, Import/Export parameter methods `ParameterSet.import_parameter` and `ParameterSet.export_parameters`, updates default FittingProblem.signal definition to `"Voltage [V]"`, and testing infrastructure
+- [#127](https://github.com/pybop-team/PyBOP/issues/127) - Adds Windows and macOS runners to the `test_on_push` action
+- [#114](https://github.com/pybop-team/PyBOP/issues/114) - Adds standard plotting class `pybop.StandardPlot()` via plotly backend
+- [#114](https://github.com/pybop-team/PyBOP/issues/114) - Adds `quick_plot()`, `plot_convergence()`, and `plot_cost2d()` methods
+- [#114](https://github.com/pybop-team/PyBOP/issues/114) - Adds a SciPy minimize example and logging for non-Pints optimisers
+- [#116](https://github.com/pybop-team/PyBOP/issues/116) - Adds PSO, SNES, XNES, ADAM, and IPropMin optimisers to PintsOptimisers() class
+- [#38](https://github.com/pybop-team/PyBOP/issues/38) - Restructures the Problem classes ahead of adding a design optimisation example
+- [#120](https://github.com/pybop-team/PyBOP/issues/120) - Updates the parameterisation test settings including the number of iterations
+- [#145](https://github.com/pybop-team/PyBOP/issues/145) - Reformats Dataset to contain a dictionary and signal into a list of strings
+
+## Bug Fixes
+
+# [v23.11](https://github.com/pybop-team/PyBOP/releases/tag/v23.11)
+- Initial release
+- Adds Pints, NLOpt, and SciPy optimisers
+- Adds SumofSquareError and RootMeanSquareError cost functions
+- Adds Parameter and Dataset classes

CITATION.cff

@@ -11,4 +11,5 @@ authors:
     family-names: Courtier
   - given-names: David
     family-names: Howey
+version: "23.12" # Update this when you release a new version
 repository-code: 'https://www.github.com/pybop-team/pybop'

CONTRIBUTING.md

@@ -1,10 +1,23 @@
-# Contributing to PyBOP
+# Contributing
 
-If you'd like to contribute to PyBOP, please have a look at the [pre-commit](#pre-commit-checks) and the [workflow](#workflow) guidelines below.
+If you'd like to contribute to PyBOP, please have a look at the guidelines below.
 
+## Developer-Installation
+
+To install PyBOP for development purposes, which includes the testing and plotting dependencies, use the `[all]` flag as demonstrated below:
+
+For `zsh`:
+
+```sh
+pip install -e '.[all]'
+```
+For `bash`:
+```sh
+pip install -e .[all]
+```
 ## Pre-commit checks
 
-Before you commit any code, please perform the following checks:
+Before you commit any code, please perform the following checks using [Nox](https://nox.thea.codes/en/stable/index.html):
 
 - [All tests pass](#testing): `$ nox -s unit`
 
@@ -17,7 +30,7 @@ pip install pre-commit
 pre-commit install
 ```
 
-This would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using -
+This would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using,
 
 ```bash
 pre-commit run --all-files
@@ -34,7 +47,7 @@ We use [GIT](https://en.wikipedia.org/wiki/Git) and [GitHub](https://en.wikipedi
 1. Create an [issue](https://guides.github.com/features/issues/) where new proposals can be discussed before any coding is done.
 2. Create a [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) of this repo (ideally on your own [fork](https://help.github.com/articles/fork-a-repo/)), where all changes will be made
 3. Download the source code onto your local system, by [cloning](https://help.github.com/articles/cloning-a-repository/) the repository (or your fork of the repository).
-4. [Install](Developer-Install) PyBOP with the developer options.
+4. [Install](#developer-installation) PyBOP with the developer options.
 5. [Test](#testing) if your installation worked: `$ pytest --unit -v`.
 
 You now have everything you need to start making changes!
@@ -69,7 +82,7 @@ python -m pip install pre-commit
 pre-commit run ruff
 ```
 
-ruff is configured inside the file `pre-commit-config.yaml`, allowing us to ignore some errors. If you think this should be added or removed, please submit an [issue](#issues)
+ruff is configured inside the file `pre-commit-config.yaml`, allowing us to ignore some errors. If you think this should be added or removed, please submit an [issue](https://guides.github.com/features/issues/).
 
 When you commit your changes they will be checked against ruff automatically (see [Pre-commit checks](#pre-commit-checks)).
 
@@ -113,6 +126,16 @@ def plot_great_things(self, x, y, z):
 
 This allows people to (1) use PyBOP without ever importing Matplotlib and (2) configure Matplotlib's back-end in their scripts, which _must_ be done before e.g. `pyplot` is first imported.
 
+### Building documentation
+
+We use [Sphinx](http://www.sphinx-doc.org/en/stable/) to build our documentation. A [Nox](https://nox.thea.codes/en/stable/index.html) session has been created to reduce the overhead when building the documentation locally. To run this session, type
+
+```bash
+nox -s docs
+```
+
+This will build the docs using sphinx-autobuild and render them in your browser.
+
 ## Testing
 
 All code requires testing. We use the [pytest](https://docs.pytest.org/en/) package for our tests. (These tests typically just check that the code runs without error, and so, are more _debugging_ than _testing_ in a strict sense. Nevertheless, they are very useful to have!)
@@ -123,7 +146,7 @@ If you have nox installed, to run unit tests, type
 nox -s unit
 ```
 
-else, type
+Alternatively, to run tests standalone with pytest, run,
 
 ```bash
 pytest --unit -v
@@ -270,7 +293,7 @@ Configuration files:
 setup.py
 ```
 
-Note that this file must be kept in sync with the version number in [pybop/**init**.py](pybop/__init__.py).
+Note that this file must be kept in sync with the version number in [pybop/**init**.py](https://github.com/pybop-team/PyBOP/blob/develop/pybop/__init__.py).
 
 ### Continuous Integration using GitHub actions
 
@@ -293,11 +316,10 @@ Code coverage (how much of our code is seen by the (Linux) unit tests) is tested
 
 GitHub does some magic with particular filenames. In particular:
 
-- The first page people see when they go to [our GitHub page](https://github.com/pybop-team/PyBOP) displays the contents of [README.md](README.md), which is written in the [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Some guidelines can be found [here](https://help.github.com/articles/about-readmes/).
-- The license for using PyBOP is stored in [LICENSE](LICENSE.txt), and [automatically](https://help.github.com/articles/adding-a-license-to-a-repository/) linked to by GitHub.
-- This file, [CONTRIBUTING.md](CONTRIBUTING.md) is recognised as the contribution guidelines and a link is [automatically](https://github.com/blog/1184-contributing-guidelines) displayed when new issues or pull requests are created.
+- The first page people see when they go to [our GitHub page](https://github.com/pybop-team/PyBOP) displays the contents of [README.md](https://github.com/pybop-team/PyBOP/blob/develop/README.md), which is written in the [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Some guidelines can be found [here](https://help.github.com/articles/about-readmes/).
+- The license for using PyBOP is stored in [LICENSE](https://github.com/pybop-team/PyBOP/blob/develop/LICENSE), and [automatically](https://help.github.com/articles/adding-a-license-to-a-repository/) linked to by GitHub.
+- This file, [CONTRIBUTING.md](https://github.com/pybop-team/PyBOP/blob/develop/CONTRIBUTING.md) is recognised as the contribution guidelines and a link is [automatically](https://github.com/blog/1184-contributing-guidelines) displayed when new issues or pull requests are created.
 
 ## Acknowledgements
 
-This CONTRIBUTING.md file, along with large sections of the code infrastructure,
-was copied from the excellent [Pints repo](https://github.com/pints-team/pints), and [PyBaMM repo](https://github.com/pybamm-team/PyBaMM)
+This CONTRIBUTING.md file, along with large sections of the code infrastructure, was copied from the excellent [Pints repo](https://github.com/pints-team/pints), and [PyBaMM repo](https://github.com/pybamm-team/PyBaMM)