Updt. landing page grid and header names, docstring typos, contributi…

…ng render method
pybop-team · Dec 14, 2023 · af10b31 · af10b31
1 parent 6ac1880
commit af10b31
Show file tree

Hide file tree

Showing 15 changed files with 65 additions and 81 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to PyBOP
+# Contributing
 
 If you'd like to contribute to PyBOP, please have a look at the guidelines below.
 
@@ -82,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)).
 
@@ -293,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
 
@@ -316,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)
diff --git a/docs/Contributing.md b/docs/Contributing.md
@@ -0,0 +1,8 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      Contributing docs..
+---
+
+```{include} ../CONTRIBUTING.md
diff --git a/docs/contributing.md b/docs/contributing.md
diff --git a/docs/index.md b/docs/index.md
@@ -13,24 +13,25 @@ Welcome to PyBOP, a Python package dedicated to the optimization and parameteriz
 ```{gallery-grid}
 :grid-columns: 1 2 2 2
 
-- header: "{fab}`bootstrap;pst-color-primary` API Documentation"
-  content: "Get detailed information on functions, classes, and modules that allow you to fully leverage the power of PyBOP in your own projects."
-  link: "api/index.html"
 - header: "{fas}`bolt;pst-color-primary` Installation"
   content: "Setting up PyBOP is straightforward. Follow our step-by-step guide to install PyBOP on your system."
-  link: "user_guide/installation.html"
-- header: "{fas}`circle-half-stroke;pst-color-primary` Usage"
-  content: "Discover how to use PyBOP effectively with our usage examples. From basic tasks to advanced features, learn how to solve real-world problems with PyBOP."
-  link: "user_guide/index.html"
+  link: "installation.html"
+- header: "{fas}`circle-half-stroke;pst-color-primary` Quick Start"
+  content: "Discover how to use PyBOP effectively. From basic tasks to advanced features, learn how to solve real-world problems with PyBOP."
+  link: "quick_start.html"
 - header: "{fab}`python;pst-color-primary` Contributing"
   content: "Contribute to the PyBOP project and become a part of our growing community."
-  link: "contributing.html"
+  link: "Contributing.html"
+- header: "{fab}`bootstrap;pst-color-primary` API Reference"
+  content: "Get detailed information on functions, classes, and modules that allow you to fully leverage the power of PyBOP in your own projects."
+  link: "api/index.html"
 ```
 
 ```{toctree}
 :maxdepth: 2
 :hidden:
 
-user_guide/index
-contributing
+installation
+quick_start
+Contributing <Contributing>
 ```
diff --git a/docs/user_guide/installation.rst → docs/installation.rst b/docs/user_guide/installation.rst → docs/installation.rst
@@ -1,6 +1,6 @@
 .. _installation:
 
-Installation Guide for PyBOP
+Installation
 *****************************
 
 PyBOP is a versatile Python package designed for optimization and parameterization of battery models. Follow the instructions below to install PyBOP and set up your environment to begin utilizing its capabilities.
@@ -52,7 +52,7 @@ For Developers
 
 If you are installing PyBOP for development purposes, such as contributing to the project, please ensure that you follow the guidelines outlined in the contributing guide. It includes additional steps that might be necessary for setting up a development environment, including the installation of dependencies and setup of pre-commit hooks.
 
-`Contributing Guide <../contributing.html>`_
+`Contributing Guide <../Contributing.html>`_
 
 Further Assistance
 ------------------
@@ -64,5 +64,5 @@ Next Steps
 
 After installing PyBOP, you might want to:
 
-* Explore the `Quick Start Guide <usage.html>`_ to begin using PyBOP.
+* Explore the `Quick Start Guide <quick_start.html>`_ to begin using PyBOP.
 * Check out the `API Reference <../api/index.html>`_ for detailed information on PyBOP's programming interface.
diff --git a/docs/user_guide/usage.rst → docs/quick_start.rst b/docs/user_guide/usage.rst → docs/quick_start.rst
@@ -1,4 +1,4 @@
-Quick Start Guide for PyBOP
+Quick Start
 ****************************
 
 Welcome to the Quick Start Guide for PyBOP. This guide will help you get up and running with PyBOP. If you're new to PyBOP, we recommend you start here to learn the basics and get a feel for the package.
@@ -53,4 +53,6 @@ Support and Contributions
 
 If you encounter any issues or have questions as you start using PyBOP, don't hesitate to reach out to our community:
 
-- **Contributions**: Interested in contributing to PyBOP? Check out our [contributing-guide](contributing-guide) for guidelines on how to contribute.
+- **GitHub Issues**: Report bugs or request new features by opening an `Issue <https://github.com/pybop-team/PyBOP/issues>`_
+- **GitHub Discussions**: Post your questions or feedback on our `GitHub Discussions <https://github.com/pybop-team/PyBOP/discussions>`_
+- **Contributions**: Interested in contributing to PyBOP? Check out our `Contributing Guide <../Contributing.html>`_ for guidelines.
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
diff --git a/examples/costs/standalone.py b/examples/costs/standalone.py
@@ -6,7 +6,7 @@ class StandaloneCost(pybop.BaseCost):
     """
     A standalone cost function example that inherits from pybop.BaseCost.
 
-    This class represents a simple cost function without a problem obkect, used for demonstration purposes.
+    This class represents a simple cost function without a problem object, used for demonstration purposes.
     It is a quadratic function of one variable with a constant term, defined by
     the formula: cost(x) = x^2 + 42.
 

diff --git a/noxfile.py b/noxfile.py
@@ -1,7 +1,7 @@
 import nox
 
 # nox options
-nox.options.reuse_existing_virtualenvs = True
+nox.options.reuse_existing_virtualenvs = False
 
 
 @nox.session

diff --git a/pybop/_optimisation.py b/pybop/_optimisation.py
@@ -5,16 +5,16 @@
 
 class Optimisation:
     """
-    A class for conducting optimization using PyBOP or PINTS optimizers.
+    A class for conducting optimization using PyBOP or PINTS optimisers.
 
     Parameters
     ----------
-    cost : pints.ErrorMeasure or pints.LogPDF
-        An objective function to be optimized, which can be either a PINTS error measure or log PDF.
-    optimiser : pints.Optimiser or subclass of pybop.BaseOptimizer, optional
-        An optimizer from either the PINTS or PyBOP framework to perform the optimization (default: None).
+    cost : pybop.BaseCost or pints.ErrorMeasure
+        An objective function to be optimized, which can be either a pybop.Cost or PINTS error measure
+    optimiser : pybop.Optimiser or subclass of pybop.BaseOptimiser, optional
+        An optimiser from either the PINTS or PyBOP framework to perform the optimization (default: None).
     sigma0 : float or sequence, optional
-        Initial step size or standard deviation for the optimizer (default: None).
+        Initial step size or standard deviation for the optimiser (default: None).
     verbose : bool, optional
         If True, the optimization progress is printed (default: False).
 
@@ -27,7 +27,7 @@ class Optimisation:
     n_parameters : int
         Number of parameters in the optimization problem.
     sigma0 : float or sequence
-        Initial step size or standard deviation for the optimizer.
+        Initial step size or standard deviation for the optimiser.
     log : list
         Log of the optimization process.
     """
@@ -146,7 +146,7 @@ def run(self):
 
     def _run_pybop(self):
         """
-        Internal method to run the optimization using a PyBOP optimizer.
+        Internal method to run the optimization using a PyBOP optimiser.
 
         Returns
         -------
@@ -167,7 +167,7 @@ def _run_pybop(self):
 
     def _run_pints(self):
         """
-        Internal method to run the optimization using a PINTS optimizer.
+        Internal method to run the optimization using a PINTS optimiser.
 
         Returns
         -------
@@ -362,7 +362,7 @@ def f_guessed_tracking(self):
 
     def set_f_guessed_tracking(self, use_f_guessed=False):
         """
-        Set the method used to track the optimizer progress.
+        Set the method used to track the optimiser progress.
         Credit: PINTS
 
         Parameters

diff --git a/pybop/optimisers/nlopt_optimize.py b/pybop/optimisers/nlopt_optimize.py
@@ -83,7 +83,7 @@ def cost_wrapper(x, grad):
 
     def needs_sensitivities(self):
         """
-        Indicates if the optimizer requires gradient information for the cost function.
+        Indicates if the optimiser requires gradient information for the cost function.
 
         Returns
         -------
@@ -94,7 +94,7 @@ def needs_sensitivities(self):
 
     def name(self):
         """
-        Returns the name of this optimizer instance.
+        Returns the name of this optimiser instance.
 
         Returns
         -------

diff --git a/pybop/optimisers/pints_optimisers.py b/pybop/optimisers/pints_optimisers.py
@@ -5,8 +5,8 @@ class GradientDescent(pints.GradientDescent):
     """
     Implements a simple gradient descent optimization algorithm.
 
-    This class extends the gradient descent optimizer from the PINTS library, designed
-    to minimize a scalar function of one or more variables. Note that this optimizer
+    This class extends the gradient descent optimiser from the PINTS library, designed
+    to minimize a scalar function of one or more variables. Note that this optimiser
     does not support boundary constraints.
 
     Parameters
@@ -16,7 +16,7 @@ class GradientDescent(pints.GradientDescent):
     sigma0 : float, optional
         Initial step size (default is 0.1).
     bounds : sequence or ``Bounds``, optional
-        Ignored by this optimizer, provided for API consistency.
+        Ignored by this optimiser, provided for API consistency.
 
     See Also
     --------
@@ -35,9 +35,9 @@ class Adam(pints.Adam):
     """
     Implements the Adam optimization algorithm.
 
-    This class extends the Adam optimizer from the PINTS library, which combines
+    This class extends the Adam optimiser from the PINTS library, which combines
     ideas from RMSProp and Stochastic Gradient Descent with momentum. Note that
-    this optimizer does not support boundary constraints.
+    this optimiser does not support boundary constraints.
 
     Parameters
     ----------
@@ -46,7 +46,7 @@ class Adam(pints.Adam):
     sigma0 : float, optional
         Initial step size (default is 0.1).
     bounds : sequence or ``Bounds``, optional
-        Ignored by this optimizer, provided for API consistency.
+        Ignored by this optimiser, provided for API consistency.
 
     See Also
     --------
@@ -65,7 +65,7 @@ class IRPropMin(pints.IRPropMin):
     """
     Implements the iRpropMin optimization algorithm.
 
-    This class inherits from the PINTS IRPropMin class, which is an optimizer that
+    This class inherits from the PINTS IRPropMin class, which is an optimiser that
     uses resilient backpropagation with weight-backtracking. It is designed to handle
     problems with large plateaus, noisy gradients, and local minima.
 
@@ -97,7 +97,7 @@ class PSO(pints.PSO):
     """
     Implements a particle swarm optimization (PSO) algorithm.
 
-    This class extends the PSO optimizer from the PINTS library. PSO is a
+    This class extends the PSO optimiser from the PINTS library. PSO is a
     metaheuristic optimization method inspired by the social behavior of birds
     flocking or fish schooling, suitable for global optimization problems.
 
@@ -129,7 +129,7 @@ class SNES(pints.SNES):
     """
     Implements the stochastic natural evolution strategy (SNES) optimization algorithm.
 
-    Inheriting from the PINTS SNES class, this optimizer is an evolutionary algorithm
+    Inheriting from the PINTS SNES class, this optimiser is an evolutionary algorithm
     that evolves a probability distribution on the parameter space, guiding the search
     for the optimum based on the natural gradient of expected fitness.
 
@@ -159,7 +159,7 @@ def __init__(self, x0, sigma0=0.1, bounds=None):
 
 class XNES(pints.XNES):
     """
-    Implements the Exponential Natural Evolution Strategy (XNES) optimizer from PINTS.
+    Implements the Exponential Natural Evolution Strategy (XNES) optimiser from PINTS.
 
     XNES is an evolutionary algorithm that samples from a multivariate normal distribution, which is updated iteratively to fit the distribution of successful solutions.
 
@@ -189,7 +189,7 @@ def __init__(self, x0, sigma0=0.1, bounds=None):
 
 class CMAES(pints.CMAES):
     """
-    Adapter for the Covariance Matrix Adaptation Evolution Strategy (CMA-ES) optimizer in PINTS.
+    Adapter for the Covariance Matrix Adaptation Evolution Strategy (CMA-ES) optimiser in PINTS.
 
     CMA-ES is an evolutionary algorithm for difficult non-linear non-convex optimization problems.
     It adapts the covariance matrix of a multivariate normal distribution to capture the shape of the cost landscape.

diff --git a/pybop/parameters/priors.py b/pybop/parameters/priors.py
@@ -70,7 +70,7 @@ def rvs(self, size):
         Raises
         ------
         ValueError
-            If the size parameter is not positive.
+            If the size parameter is negative.
         """
         if size < 0:
             raise ValueError("size must be positive")
@@ -153,7 +153,7 @@ def rvs(self, size):
         Raises
         ------
         ValueError
-            If the size parameter is not positive.
+            If the size parameter is negative.
         """
         if size < 0:
             raise ValueError("size must be positive")
@@ -235,7 +235,7 @@ def rvs(self, size):
         Raises
         ------
         ValueError
-            If the size parameter is not positive.
+            If the size parameter is negative.
         """
         if size < 0:
             raise ValueError("size must be positive")

diff --git a/pybop/plotting/plot_convergence.py b/pybop/plotting/plot_convergence.py
@@ -7,7 +7,7 @@ def plot_convergence(
     """
     Plot the convergence of the optimisation algorithm.
 
-    Parameters:
+    Parameters
     -----------
     optim : optimisation object
         Optimisation object containing the cost function and optimiser.
@@ -18,7 +18,7 @@ def plot_convergence(
     title : str, optional
         Title of the plot (default is "Convergence").
 
-    Returns:
+    Returns
     ---------
     fig : plotly.graph_objs.Figure
         The Plotly figure object for the convergence plot.

diff --git a/pybop/plotting/plot_cost2d.py b/pybop/plotting/plot_cost2d.py
@@ -15,7 +15,7 @@ def plot_cost2d(cost, bounds=None, optim=None, steps=10):
     bounds : numpy.ndarray, optional
         A 2x2 array specifying the [min, max] bounds for each parameter. If None, uses `get_param_bounds`.
     optim : object, optional
-        An optimizer instance which, if provided, overlays its specific trace on the plot.
+        An optimiser instance which, if provided, overlays its specific trace on the plot.
     steps : int, optional
         The number of intervals to divide the parameter space into along each dimension (default is 10).
 
@@ -94,7 +94,7 @@ def create_figure(x, y, z, bounds, params, optim):
     params : iterable
         An iterable of parameter objects with 'name' attributes for axis labeling.
     optim : object
-        An optimizer instance with 'log' and 'x0' attributes for plotting traces.
+        An optimiser instance with 'log' and 'x0' attributes for plotting traces.
 
     Returns
     -------