Merge branch 'develop' into telemetry

Author: valentinsulzer

.pre-commit-config.yaml

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

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Features
 
+- Adds support to `pybamm.Experiment` for the `output_variables` option in the `IDAKLUSolver`. ([#4534](https://github.com/pybamm-team/PyBaMM/pull/4534))
 - Adds an option "voltage as a state" that can be "false" (default) or "true". If "true" adds an explicit algebraic equation for the voltage. ([#4507](https://github.com/pybamm-team/PyBaMM/pull/4507))
 - Improved `QuickPlot` accuracy for simulations with Hermite interpolation. ([#4483](https://github.com/pybamm-team/PyBaMM/pull/4483))
 - Added Hermite interpolation to the (`IDAKLUSolver`) that improves the accuracy and performance of post-processing variables. ([#4464](https://github.com/pybamm-team/PyBaMM/pull/4464))
@@ -20,7 +21,7 @@
 - Removed the `start_step_offset` setting and disabled minimum `dt` warnings for drive cycles with the (`IDAKLUSolver`). ([#4416](https://github.com/pybamm-team/PyBaMM/pull/4416))
 
 ## Bug Fixes
-
+- Fixed bug in post-processing solutions with infeasible experiments using the (`IDAKLUSolver`). ([#4541](https://github.com/pybamm-team/PyBaMM/pull/4541))
 - Disabled IREE on MacOS due to compatibility issues and added the CasADI
   path to the environment to resolve issues on MacOS and Linux. Windows
   users may still experience issues with interpolation. ([#4528](https://github.com/pybamm-team/PyBaMM/pull/4528))

docs/source/api/index.rst

@@ -9,10 +9,10 @@ API documentation
 :Release: |version|
 :Date: |today|
 
-This reference manual details functions, modules, and objects
-included in PyBaMM, describing what they are and what they do.
+This reference manual details the classes, functions, modules, and objects included in PyBaMM, describing what they are and what they do.
 For a high-level introduction to PyBaMM, see the :ref:`user guide <user_guide>` and the :ref:`examples <pybamm_examples>`.
 
+
 .. toctree::
    :maxdepth: 2
 

docs/source/api/util.rst

@@ -19,3 +19,5 @@ Utility functions
 .. autofunction:: pybamm.has_jax
 
 .. autofunction:: pybamm.is_jax_compatible
+
+.. autofunction:: pybamm.set_logging_level

docs/source/examples/notebooks/getting_started/tutorial-4-setting-parameter-values.ipynb

@@ -0,0 +1,74 @@
+----------
+Public API
+----------
+
+.. module:: pybamm
+    :noindex:
+
+PyBaMM is a Python package for mathematical modelling and simulation of battery systems. The main classes and functions that are intended to be used by the user are described in this document.
+For a more detailed description of the classes and methods, see the :doc:`API reference </source/api/index>`.
+
+Available PyBaMM models
+-----------------------
+
+PyBaMM includes a number of pre-implemented models, which can be used as they are or modified to suit your needs. The main models are:
+
+- :class:`lithium_ion.SPM`: Single Particle Model
+- :class:`lithium_ion.SPMe`: Single Particle Model with Electrolyte
+- :class:`lithium_ion.DFN`: Doyle-Fuller-Newman
+
+The behaviour of the models can be modified by passing in an :class:`BatteryModelOptions` object when creating the model.
+
+Simulations
+-----------
+
+:class:`Simulation` is a class that automates the process of setting up a model and solving it, and acts as the highest-level API to PyBaMM.
+Pass at least a :class:`BaseModel` object, and optionally the experiment, solver, parameter values, and geometry objects described below to the :class:`Simulation` object.
+Any of these optional arguments not provided will be supplied by the defaults specified in the model.
+
+Parameters
+----------
+
+PyBaMM models are parameterised by a set of parameters, which are stored in a :class:`ParameterValues` object. This object acts like a Python dictionary with a few extra PyBaMM specific features and methods.
+Parameters in a model are represented as either :class:`Parameter` objects or :class:`FunctionParameter` objects, and the values in the :class:`ParameterValues` object replace these objects in the model before it is solved.
+The values in the :class:`ParameterValues` object can be scalars, Python functions or expressions of type :class:`Symbol`.
+
+Experiments
+-----------
+
+An :class:`Experiment` object represents an experimental protocol that can be used to simulate the behaviour of a battery. The particular protocol can be provided as a Python string, or as a sequences of
+:class:`step.BaseStep` objects.
+
+Solvers
+-------
+
+The two main solvers in PyBaMM are the :class:`CasadiSolver` and the :class:`IDAKLUSolver`. Both are wrappers around the Sundials suite of solvers, but the :class:`CasadiSolver` uses the CasADi library
+whereas the :class:`IDAKLUSolver` is PyBaMM specific. Both solvers have many options that can be set to control the solver behaviour, see the documentation for each solver for more details.
+
+When a model is solved, the solution is returned as a :class:`Solution` object.
+
+Plotting
+--------
+
+A solution object can be plotted using the :meth:`Solution.plot` or :meth:`Simulation.plot` methods, which returns a :class:`QuickPlot` object.
+Note that the arguments to the plotting methods of both classes are the same as :class:`QuickPlot`.
+
+Other plotting functions are the :func:`plot_voltage_components` and :func:`plot_summary_variables` functions, which correspond to the similarly named methods of the :class:`Solution` and :class:`Simulation` classes.
+
+Writing PyBaMM models
+---------------------
+
+Each PyBaMM model, and the custom models written by users, are written as a set of expressions that describe the model. Each of the expressions is a subclass of the :class:`Symbol` class, which represents a mathematical expression.
+
+If you wish to create a custom model, you can use the :class:`BaseModel` class as a starting point.
+
+
+Discretisation
+--------------
+
+Each PyBaMM model contains continuous operators that must be discretised before they can be solved. This is done using a :class:`Discretisation` object, which takes a :class:`Mesh` object and a dictionary of :class:`SpatialMethod` objects.
+
+Logging
+-------
+
+PyBaMM uses the Python logging module to log messages at different levels of severity. Use the :func:`pybamm.set_logging_level` function to set the logging level for PyBaMM.

docs/source/examples/notebooks/parameterization/parameter-values.ipynb

@@ -22,6 +22,7 @@ maxdepth: 2
 ---
 fundamentals/index
 fundamentals/battery_models
+fundamentals/public_api
 ```
 
 ```{toctree}

docs/source/user_guide/fundamentals/public_api.rst

@@ -24,6 +24,17 @@ def func(self, message, *args, **kws):
 
 
 def set_logging_level(level):
+    """
+    Set the logging level for PyBaMM
+
+    Parameters
+    ----------
+
+    level: str
+        The logging level to set. Should be one of 'DEBUG', 'INFO', 'WARNING',
+        'ERROR', 'CRITICAL'
+
+    """
     logger.setLevel(level)
 
 

docs/source/user_guide/index.md

@@ -1452,6 +1452,7 @@ def get_termination_reason(solution, events):
                 solution.t_event,
                 solution.y_event,
                 solution.termination,
+                variables_returned=solution.variables_returned,
             )
             event_sol.solve_time = 0
             event_sol.integration_time = 0