diff --git a/.gitignore b/.gitignore index de8fcaf899..6937100b9b 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ *.DS_Store *.mat *.csv +*.hidden # don't ignore important .txt and .csv files !requirements* diff --git a/docs/conf.py b/docs/conf.py index 49989b3307..f2972869a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,6 +49,7 @@ "sphinx.ext.napoleon", "sphinx_design", "sphinx_copybutton", + "myst_parser", ] @@ -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": { diff --git a/docs/index.rst b/docs/index.rst index 3ff5c4d6d4..8a448394b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ PyBaMM documentation :maxdepth: 1 :hidden: - source/user_guide/index + User Guide source/api/index **Version**: |version| diff --git a/docs/source/user_guide/fundamentals/index.rst b/docs/source/user_guide/fundamentals/index.md similarity index 52% rename from docs/source/user_guide/fundamentals/index.rst rename to docs/source/user_guide/fundamentals/index.md index e9fabdf34c..28bba54424 100644 --- a/docs/source/user_guide/fundamentals/index.rst +++ b/docs/source/user_guide/fundamentals/index.md @@ -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 `_ example gives an introduction to the computer algebra system, and the `Getting Started `_ 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 `_. +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. \ No newline at end of file diff --git a/docs/source/user_guide/getting_started.md b/docs/source/user_guide/getting_started.md new file mode 100644 index 0000000000..dc0cb41f4b --- /dev/null +++ b/docs/source/user_guide/getting_started.md @@ -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/). \ No newline at end of file diff --git a/docs/source/user_guide/getting_started.rst b/docs/source/user_guide/getting_started.rst deleted file mode 100644 index 4753ce9a34..0000000000 --- a/docs/source/user_guide/getting_started.rst +++ /dev/null @@ -1,41 +0,0 @@ -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: - -.. code-block:: 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: - -.. code-block:: 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 `_ or `notebook `_). - -For new users we recommend the `Getting Started `_ 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 `_. - -Further details can be found in a number of `detailed examples `_, hosted on -GitHub. In addition, full details of classes and methods can be found in the :ref:`api_docs`. -Additional supporting material can be found -`here `_. \ No newline at end of file diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md new file mode 100644 index 0000000000..42bff84d39 --- /dev/null +++ b/docs/source/user_guide/index.md @@ -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 +``` diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst deleted file mode 100644 index ebf661e9ae..0000000000 --- a/docs/source/user_guide/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _user: - -################# -PyBaMM user guide -################# - -This guide is an overview and explains the important features; -details are found in :ref:`api_docs`. - -.. toctree:: - :caption: Getting started - :maxdepth: 1 - - installation/index - getting_started - -.. toctree:: - :caption: Fundamentals and usage - :maxdepth: 2 - - fundamentals/index diff --git a/docs/source/user_guide/todo.md b/docs/source/user_guide/todo.md deleted file mode 100644 index dc16b3d010..0000000000 --- a/docs/source/user_guide/todo.md +++ /dev/null @@ -1,14 +0,0 @@ -Fundamentals - -- More details on each section including code examples - -Creating a project using PyBaMM - -- Setup -- Basic use -- Creating your own model - - Your own model - - Making it compatible with experiments - - Extending the existing models (adding submodels) -- Adding your own parameter sets -- Contributing