Skip to content

Commit

Permalink
switch some doc files to markdown, add favicon
Browse files Browse the repository at this point in the history
  • Loading branch information
valentinsulzer committed Feb 2, 2023
1 parent 0c120de commit 695175e
Show file tree
Hide file tree
Showing 9 changed files with 109 additions and 122 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
*.DS_Store
*.mat
*.csv
*.hidden

# don't ignore important .txt and .csv files
!requirements*
Expand Down
2 changes: 2 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@
"sphinx.ext.napoleon",
"sphinx_design",
"sphinx_copybutton",
"myst_parser",
]


Expand Down Expand Up @@ -99,6 +100,7 @@
# https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html# for more information)
# mostly copied from numpy, scipy, pandas
html_logo = "source/_static/pybamm_logo.png"
html_favicon = "source/_static/favicon/favicon.png"

html_theme_options = {
"logo": {
Expand Down
2 changes: 1 addition & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ PyBaMM documentation
:maxdepth: 1
:hidden:

source/user_guide/index
User Guide <source/user_guide/index>
source/api/index

**Version**: |version|
Expand Down
Original file line number Diff line number Diff line change
@@ -1,85 +1,82 @@
Fundamentals
============
# Fundamentals

PyBaMM (Python Battery Mathematical Modelling) is an open-source battery simulation package
written in Python. Our mission is to accelerate battery modelling research by
providing open-source tools for multi-institutional, interdisciplinary collaboration.
Broadly, PyBaMM consists of

#. a framework for writing and solving systems of differential equations,
#. a library of battery models and parameters, and
#. specialized tools for simulating battery-specific experiments and visualizing the results.
1. a framework for writing and solving systems of differential equations,
2. a library of battery models and parameters, and
3. specialized tools for simulating battery-specific experiments and visualizing the results.

Together, these enable flexible model definitions and fast battery simulations, allowing users to
explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.

.. note::
>**NOTE**: This user-guide is a work-in-progress, we hope that this brief but incomplete overview will be useful to you.
This user-guide is a work-in-progress, we hope that this brief but incomplete overview will be useful to you.
## Core framework

Core framework
~~~~~~~~~~~~~~
The core of the framework is a custom computer algebra system to define mathematical equations,
and a domain specific modeling language to combine these equations into systems of differential equations
(usually partial differential equations for variables depending on space and time).
The `expression tree <https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/expression_tree/expression-tree.ipynb>`_ example gives an introduction to the computer algebra system, and the `Getting Started <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started>`_ tutorials
The [expression tree](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/expression_tree/expression-tree.ipynb) example gives an introduction to the computer algebra system, and the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started) tutorials
walk through creating models of increasing complexity.

Once a model has been defined symbolically, PyBaMM solves it using the Method of Lines. First, the equations are discretised in the spatial dimension, using the finite volume method. Then, the resulting system is solved using third-party numerical solvers. Depending on the form of the model, the system can be ordinary differential equations (ODEs) (if only `model.rhs` is defined), or algebraic equations (if only `model.algebraic` is defined), or differential-algebraic equations (DAEs) (if both `model.rhs` and `model.algebraic` are defined). Jupyter notebooks explaining the solvers can be found `here <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/solvers>`_.
Once a model has been defined symbolically, PyBaMM solves it using the Method of Lines. First, the equations are discretised in the spatial dimension, using the finite volume method. Then, the resulting system is solved using third-party numerical solvers. Depending on the form of the model, the system can be ordinary differential equations (ODEs) (if only `model.rhs` is defined), or algebraic equations (if only `model.algebraic` is defined), or differential-algebraic equations (DAEs) (if both `model.rhs` and `model.algebraic` are defined). Jupyter notebooks explaining the solvers can be found [here](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/solvers).

## Model and Parameter Library

Model and Parameter Library
~~~~~~~~~~~~~~~~~~~~~~~~~~~
PyBaMM contains an extensive library of battery models and parameters.
The bulk of the library consists of models for lithium-ion, but there are also some other chemistries (lead-acid, lithium metal).
Models are first divided broadly into common named models of varying complexity, such as the single particle model` (SPM) or Doyle-Fuller-Newman model (DFN).
Models are first divided broadly into common named models of varying complexity, such as the single particle model (SPM) or Doyle-Fuller-Newman model (DFN).
Most options can be applied to any model, but some are model-specific (an error will be raised if you attempt to set an option is not compatible with a model).
See :ref:`base_battery_model` for a list of options.
See [](base_battery_model) for a list of options.

The parameter library is simply a collection of python files each defining a complete set of parameters
for a particular battery chemistry, covering all major lithium-ion chemistries (NMC, LFP, NCA, ...).
External parameter sets can be linked using entry points (see :ref:`parameter_sets`).
External parameter sets can be linked using entry points (see [](parameter_sets)).

Battery-specific tools
~~~~~~~~~~~~~~~~~~~~~~
One of PyBaMM's unique features is the ``Experiment`` class, which allows users to define synthetic experiments using simple instructions in English
## Battery-specific tools

.. code-block:: python
One of PyBaMM's unique features is the `Experiment` class, which allows users to define synthetic experiments using simple instructions in English

pybamm.Experiment(
[
("Discharge at C/10 for 10 hours or until 3.3 V",
"Rest for 1 hour",
"Charge at 1 A until 4.1 V",
"Hold at 4.1 V until 50 mA",
"Rest for 1 hour")
]
* 3,
)
``` python
pybamm.Experiment(
[
("Discharge at C/10 for 10 hours or until 3.3 V",
"Rest for 1 hour",
"Charge at 1 A until 4.1 V",
"Hold at 4.1 V until 50 mA",
"Rest for 1 hour")
]
* 3,
)
```

The above instruction will conduct a standard discharge / rest / charge / rest cycle three times, with a 10 hour discharge and 1 hour rest at the end of each cycle.

The ``Simulation`` class handles simulating an ``Experiment``, as well as calculating additional outputs such as capacity as a function of cycle number. For example, the following code will simulate the experiment above and plot the standard output variables:

.. code-block:: python
The `Simulation` class handles simulating an `Experiment`, as well as calculating additional outputs such as capacity as a function of cycle number. For example, the following code will simulate the experiment above and plot the standard output variables:

import pybamm
import matplotlib.pyplot as plt
``` python
import pybamm
import matplotlib.pyplot as plt

# load model and parameter values
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment)
solution = sim.solve()
solution.plot()
# load model and parameter values
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment)
solution = sim.solve()
solution.plot()
```

Finally, PyBaMM provides cusotm visualization tools:

* :ref:`quick_plot`: for easily plotting simulation outputs in a grid, including comparing multiple simulations
* :ref:`plot_voltage_components`: for plotting the component overpotentials that make up a voltage curve
- [](quick_plot): for easily plotting simulation outputs in a grid, including comparing multiple simulations
- [](plot_voltage_components): for plotting the component overpotentials that make up a voltage curve

Users are not limited to these tools and can plot the output of a simulation solution by accessing the underlying numpy array for the solution variables as

.. code-block:: python
solution["variable name"].data
``` python
solution["variable name"].data
```

and using the plotting library of their choice.
40 changes: 40 additions & 0 deletions docs/source/user_guide/getting_started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Getting Started

The easiest way to use PyBaMM is to run a 1C constant-current discharge with a model of your choice with all the default settings:

```python
import pybamm
model = pybamm.lithium_ion.DFN() # Doyle-Fuller-Newman model
sim = pybamm.Simulation(model)
sim.solve([0, 3600]) # solve for 1 hour
sim.plot()
```

or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge:

```python
import pybamm
experiment = pybamm.Experiment(
[
("Discharge at C/10 for 10 hours or until 3.3 V",
"Rest for 1 hour",
"Charge at 1 A until 4.1 V",
"Hold at 4.1 V until 50 mA",
"Rest for 1 hour")
]
* 3,
)
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment, solver=pybamm.CasadiSolver())
sim.solve()
sim.plot()
```

However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type, number of submesh points, methods for spatial discretisation and solver for integration (see DFN [script](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/scripts/DFN.py) or [notebook](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/models/DFN.ipynb)).

For new users we recommend the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started) guides. These are intended to be very simple step-by-step guides to show the basic functionality of PyBaMM, and can either be downloaded and used locally, or used online through [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop).

Further details can be found in a number of [detailed examples](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/README.md), hosted on
GitHub. In addition, full details of classes and methods can be found in the [](api_docs).
Additional supporting material can be found
[here](https://github.com/pybamm-team/pybamm-supporting-material/).
41 changes: 0 additions & 41 deletions docs/source/user_guide/getting_started.rst

This file was deleted.

23 changes: 23 additions & 0 deletions docs/source/user_guide/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
(user)=
# PyBaMM user guide

This guide is an overview and explains the important features;
details are found in [](api_docs).

```{toctree}
---
caption: Getting started
maxdepth: 1
---
installation/index
getting_started
```

```{toctree}
---
caption: Fundamentals and usage
maxdepth: 2
---
fundamentals/index
```
21 changes: 0 additions & 21 deletions docs/source/user_guide/index.rst

This file was deleted.

14 changes: 0 additions & 14 deletions docs/source/user_guide/todo.md

This file was deleted.

0 comments on commit 695175e

Please sign in to comment.