From 164f71e94f3fba7dbb3ebe59738906cbb0cd4f81 Mon Sep 17 00:00:00 2001 From: Martin Robinson Date: Tue, 22 Oct 2024 16:39:46 +0100 Subject: [PATCH] docs: describe public api in front-page of API docs (#4536) * docs: describe public api in front-page of API docs * docs: add set_logging_level to docs * docs: move public api description to userguide * fix doctest warnings * fix reference * edit parameters for clarity --------- Co-authored-by: Eric G. Kratz --- docs/source/api/index.rst | 4 +- docs/source/api/util.rst | 2 + .../user_guide/fundamentals/public_api.rst | 74 +++++++++++++++++++ docs/source/user_guide/index.md | 1 + src/pybamm/logger.py | 11 +++ 5 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 docs/source/user_guide/fundamentals/public_api.rst diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 33be0235a7..4667752157 100644 --- a/docs/source/api/index.rst +++ b/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 ` and the :ref:`examples `. + .. toctree:: :maxdepth: 2 diff --git a/docs/source/api/util.rst b/docs/source/api/util.rst index 824ec6126d..9cf8d09470 100644 --- a/docs/source/api/util.rst +++ b/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 diff --git a/docs/source/user_guide/fundamentals/public_api.rst b/docs/source/user_guide/fundamentals/public_api.rst new file mode 100644 index 0000000000..6d73ecaec1 --- /dev/null +++ b/docs/source/user_guide/fundamentals/public_api.rst @@ -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 `. + +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. diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md index 58ce04101a..79e61936b2 100644 --- a/docs/source/user_guide/index.md +++ b/docs/source/user_guide/index.md @@ -22,6 +22,7 @@ maxdepth: 2 --- fundamentals/index fundamentals/battery_models +fundamentals/public_api ``` ```{toctree} diff --git a/src/pybamm/logger.py b/src/pybamm/logger.py index 7dcacb5237..460e264416 100644 --- a/src/pybamm/logger.py +++ b/src/pybamm/logger.py @@ -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)