diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d7d57a21c..910616de35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,10 @@ ## Features -- Steps in `Experiment` can now be tagged and cycle numbers be searched based on those tags ([#2593](https://github.com/pybamm-team/PyBaMM/pull/2593)). +- Changed linting from `flake8` to `ruff` ([#2630](https://github.com/pybamm-team/PyBaMM/pull/2630)). +- Changed docs theme to pydata theme and start to improve docs in general ([#2618](https://github.com/pybamm-team/PyBaMM/pull/2618)). - New `contact resistance` option, new parameter `Contact resistance [Ohm]` and new variable `Contact overpotential [V]` ([#2598](https://github.com/pybamm-team/PyBaMM/pull/2598)). +- Steps in `Experiment` can now be tagged and cycle numbers be searched based on those tags ([#2593](https://github.com/pybamm-team/PyBaMM/pull/2593)). ## Bug fixes diff --git a/README.md b/README.md index 222dd9c72e..00d42d5058 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ sim.solve([0, 3600]) # solve for 1 hour sim.plot() ``` -or simulate an experiment such as CCCV: +or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge: ```python3 import pybamm diff --git a/docs/conf.py b/docs/conf.py index 5566c50cc0..a642eced15 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,7 +15,6 @@ import os import sys import pybamm -import guzzle_sphinx_theme sys.path.insert(0, os.path.abspath("../")) @@ -48,6 +47,8 @@ "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.napoleon", + "sphinx_design", + "sphinx_copybutton", ] @@ -88,44 +89,63 @@ # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -# html_theme = "sphinxdoc" +html_theme = "pydata_sphinx_theme" -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} +html_static_path = ["source/_static"] -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +# Theme -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} +# pydata theme options (see +# 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" -# Guzzle theme +html_theme_options = { + "logo": { + "image_light": "pybamm_logo.png", + "image_dark": "pybamm_logo.png", + }, + "github_url": "https://github.com/pybamm-team/pybamm", + "twitter_url": "https://twitter.com/pybamm_", + "collapse_navigation": True, + "external_links": [ + { + "name": "Examples", + "url": "https://github.com/pybamm-team/PyBaMM/tree/develop/examples", + }, + { + "name": "Contributing", + "url": "https://github.com/pybamm-team/PyBaMM/tree/develop/CONTRIBUTING.md", + }, + ], + # Add light/dark mode and documentation version switcher: + # "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"], + # "switcher": { + # "version_match": switcher_version, + # "json_url": "https://numpy.org/doc/_static/versions.json", + # }, + "use_edit_page_button": True, +} -html_theme_path = guzzle_sphinx_theme.html_theme_path() -html_theme = "guzzle_sphinx_theme" +html_title = "%s v%s Manual" % (project, version) +html_last_updated_fmt = "%b %d, %Y" +html_css_files = ["pybamm.css"] +html_context = {"default_mode": "light"} +html_use_modindex = True +html_copy_source = False +html_domain_indices = False +html_file_suffix = ".html" -# Register the theme as an extension to generate a sitemap.xml -extensions.append("guzzle_sphinx_theme") +htmlhelp_basename = "pybamm" -# Guzzle theme options (see theme.conf for more information) -html_theme_options = { - # Set the name of the project to appear in the sidebar - "project_nav_name": project +html_sidebars = {"**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"]} + +# For edit button +html_context = { + "github_user": "pybamm-team", + "github_repo": "pybamm", + "github_version": "develop", + "doc_path": "docs/", } @@ -210,7 +230,7 @@ "python": ("https://docs.python.org/3/", None), "sphinx": ("https://www.sphinx-doc.org/en/master/", None), "numpy": ("https://numpy.org/doc/stable", None), - # "scipy": ("http://docs.scipy.org/doc/scipy/reference", None), + "scipy": ("https://docs.scipy.org/doc/scipy", None), "matplotlib": ("https://matplotlib.org", None), } @@ -235,6 +255,8 @@ def setup(app): # Context for Jinja Templates -html_context = { - "parameter_sets": pybamm.parameter_sets, -} +html_context.update( + { + "parameter_sets": pybamm.parameter_sets, + } +) diff --git a/docs/index.rst b/docs/index.rst index 8859b8e5c5..3ff5c4d6d4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,101 +1,117 @@ .. Root of all pybamm docs -.. _GitHub: https://github.com/pybamm-team/PyBaMM +.. Remove the right side-bar for the home page -Welcome to PyBaMM's documentation! -================================== +:html_theme.sidebar_secondary.remove: -Python Battery Mathematical Modelling (**PyBAMM**) solves continuum models for -batteries, using both numerical methods and asymptotic analysis. +#################### +PyBaMM documentation +#################### -PyBaMM is hosted on GitHub_. This page provides the *API*, or *developer -documentation* for ``pybamm``. +.. This TOC defines what goes in the top navbar +.. toctree:: + :maxdepth: 1 + :hidden: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + source/user_guide/index + source/api/index -Quickstart -========================= -PyBaMM is available on GNU/Linux, MacOS and Windows. +**Version**: |version| -Using pip ----------- +.. **Download documentation**: +.. `PDF Version `_ | +.. `Historical versions of documentation `_ + +**Useful links**: +`Project Home Page `_ | +`Installation `_ | +`Source Repository `_ | +`Issue Tracker `_ | +`Discussions `_ -GNU/Linux and Windows -~~~~~~~~~~~~~~~~~~~~~~ +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 -.. code:: bash +#. 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. - pip install pybamm +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. -macOS -~~~~~~~~~~~~~~~~~~~~~~ +.. grid:: 2 -.. code:: bash + .. grid-item-card:: + :img-top: source/_static/index-images/getting_started.svg - brew install sundials && pip install pybamm + User Guide + ^^^^^^^^^^ -Using conda -------------- -PyBaMM is available as a conda package through the conda-forge channel. + The user guide is the best place to start learning PyBaMM. It contains an installation + guide, an introduction to the main concepts and links to additional tutorials. -.. code:: bash + +++ - conda install -c conda-forge pybamm + .. button-ref:: source/user_guide/index + :expand: + :color: secondary + :click-parent: -Optional solvers ------------------ -Following GNU/Linux and macOS solvers are optionally available: + To the user guide + + .. grid-item-card:: + :img-top: source/_static/index-images/examples.svg -* `scikits.odes `_ -based solver, see `Optional - scikits.odes solver `_. -* `jax `_ -based solver, see `Optional - JaxSolver `_. + Examples + ^^^^^^^^ -Installation -============ + Examples and tutorials can be viewed on the GitHub examples page, + which also provides a link to run them online through Google Colab. -.. toctree:: - :maxdepth: 1 + +++ - install/GNU-linux - install/windows - install/windows-wsl - install/install-from-source + .. button-link:: https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks + :expand: + :color: secondary + :click-parent: -API documentation -==================== + To the examples -.. module:: pybamm + .. grid-item-card:: + :img-top: source/_static/index-images/api.svg -.. toctree:: - :maxdepth: 2 - - source/expression_tree/index - source/models/index - source/parameters/index - source/geometry/index - source/meshes/index - source/spatial_methods/index - source/solvers/index - source/experiments/index - source/simulation - source/plotting/index - source/util - source/callbacks - source/citations - source/batch_study - -Examples -======== - -Detailed examples can be viewed on the -`GitHub examples page `_, -and run locally using ``jupyter notebook``, or online through -`Google Colab `_. - -Contributing -============ - -Contributions to PyBaMM and its development are welcome! If you have ideas for features, bug fixes, models, spatial methods, or solvers, we would love to hear from you. - -Before contributing, please read the `Contribution Guidelines `_. + API Documentation + ^^^^^^^^^^^^^^^^^ + + The reference guide contains a detailed description of the functions, + modules, and objects included in PyBaMM. The reference describes how the + methods work and which parameters can be used. + + +++ + + .. button-ref:: source/api/index + :expand: + :color: secondary + :click-parent: + + To the API documentation + + .. grid-item-card:: + :img-top: source/_static/index-images/contributor.svg + + Contributor's Guide + ^^^^^^^^^^^^^^^^^^^ + + Contributions to PyBaMM and its development are welcome! If you have ideas for + features, bug fixes, models, spatial methods, or solvers, we would love to hear from you. + + +++ + + .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md + :expand: + :color: secondary + :click-parent: + + To the contributor's guide diff --git a/docs/requirements.txt b/docs/requirements.txt index 0e38481d28..e015c3deac 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -16,5 +16,7 @@ sympy >= 1.8 # Should not be imported matplotlib >= 2.0 # -guzzle-sphinx-theme sphinx>4.0 +pydata-sphinx-theme +sphinx_design +sphinx-copybutton diff --git a/docs/source/_static/index-images/api.svg b/docs/source/_static/index-images/api.svg new file mode 100644 index 0000000000..e637525cc0 --- /dev/null +++ b/docs/source/_static/index-images/api.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/index-images/contributor.svg b/docs/source/_static/index-images/contributor.svg new file mode 100644 index 0000000000..3a689e0e4c --- /dev/null +++ b/docs/source/_static/index-images/contributor.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/_static/index-images/examples.svg b/docs/source/_static/index-images/examples.svg new file mode 100644 index 0000000000..d61b0937da --- /dev/null +++ b/docs/source/_static/index-images/examples.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/_static/index-images/getting_started.svg b/docs/source/_static/index-images/getting_started.svg new file mode 100644 index 0000000000..04db7e6156 --- /dev/null +++ b/docs/source/_static/index-images/getting_started.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/pybamm.css b/docs/source/_static/pybamm.css new file mode 100644 index 0000000000..39f202a6f6 --- /dev/null +++ b/docs/source/_static/pybamm.css @@ -0,0 +1,147 @@ +@import url("https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap"); + +.navbar-brand img { + height: 50px; +} + +.navbar-brand { + height: 50px; +} + +body { + font-family: "Open Sans", sans-serif; +} + +pre, +code { + font-size: 100%; + line-height: 155%; +} + +h1 { + font-family: "Lato", sans-serif; + color: #013243; + /* warm black */ +} + +h2 { + color: #4d77cf; + /* han blue */ + letter-spacing: -0.03em; +} + +h3 { + color: #013243; + /* warm black */ + letter-spacing: -0.03em; +} + +/* Style the active version button. + +- dev: orange +- stable: green +- old, PR: red + +Colors from: + +Wong, B. Points of view: Color blindness. +Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618 +*/ + +/* If the active version has the name "dev", style it orange */ +#version_switcher_button[data-active-version-name*="dev"] { + background-color: #e69f00; + border-color: #e69f00; + color: #000000; +} + +/* green for `stable` */ +#version_switcher_button[data-active-version-name*="stable"] { + background-color: #009e73; + border-color: #009e73; +} + +/* red for `old` */ +#version_switcher_button:not( + [data-active-version-name*="stable"], + [data-active-version-name*="dev"], + [data-active-version-name=""] + ) { + background-color: #980f0f; + border-color: #980f0f; +} + +/* Main page overview cards */ + +.sd-card { + background: #fff; + border-radius: 0; + padding: 30px 10px 20px 10px; + margin: 10px 0px; +} + +.sd-card .sd-card-header { + text-align: center; +} + +.sd-card .sd-card-header .sd-card-text { + margin: 0px; +} + +.sd-card .sd-card-img-top { + height: 52px; + width: 52px; + margin-left: auto; + margin-right: auto; +} + +.sd-card .sd-card-header { + border: none; + background-color: white; + color: #150458 !important; + font-size: var(--pst-font-size-h5); + font-weight: bold; + padding: 2.5rem 0rem 0.5rem 0rem; +} + +.sd-card .sd-card-footer { + border: none; + background-color: white; +} + +.sd-card .sd-card-footer .sd-card-text { + max-width: 220px; + margin-left: auto; + margin-right: auto; +} + +/* Dark theme tweaking */ +html[data-theme="dark"] .sd-card img[src*=".svg"] { + filter: invert(0.82) brightness(0.8) contrast(1.2); +} + +/* Main index page overview cards */ +html[data-theme="dark"] .sd-card { + background-color: var(--pst-color-background); +} + +html[data-theme="dark"] .sd-shadow-sm { + box-shadow: 0 0.1rem 1rem rgba(250, 250, 250, 0.6) !important; +} + +html[data-theme="dark"] .sd-card .sd-card-header { + background-color: var(--pst-color-background); + color: #150458 !important; +} + +html[data-theme="dark"] .sd-card .sd-card-footer { + background-color: var(--pst-color-background); +} + +html[data-theme="dark"] h1 { + color: var(--pst-color-primary); +} + +html[data-theme="dark"] h3 { + color: #0a6774; +} diff --git a/docs/source/_static/pybamm_logo.png b/docs/source/_static/pybamm_logo.png new file mode 100644 index 0000000000..54a931c29e Binary files /dev/null and b/docs/source/_static/pybamm_logo.png differ diff --git a/docs/source/_static/pybamm_logo.svg b/docs/source/_static/pybamm_logo.svg new file mode 100644 index 0000000000..401e6b59b5 --- /dev/null +++ b/docs/source/_static/pybamm_logo.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/source/batch_study.rst b/docs/source/api/batch_study.rst similarity index 100% rename from docs/source/batch_study.rst rename to docs/source/api/batch_study.rst diff --git a/docs/source/callbacks.rst b/docs/source/api/callbacks.rst similarity index 100% rename from docs/source/callbacks.rst rename to docs/source/api/callbacks.rst diff --git a/docs/source/citations.rst b/docs/source/api/citations.rst similarity index 100% rename from docs/source/citations.rst rename to docs/source/api/citations.rst diff --git a/docs/source/experiments/experiment.rst b/docs/source/api/experiments/experiment.rst similarity index 100% rename from docs/source/experiments/experiment.rst rename to docs/source/api/experiments/experiment.rst diff --git a/docs/source/experiments/index.rst b/docs/source/api/experiments/index.rst similarity index 100% rename from docs/source/experiments/index.rst rename to docs/source/api/experiments/index.rst diff --git a/docs/source/expression_tree/array.rst b/docs/source/api/expression_tree/array.rst similarity index 100% rename from docs/source/expression_tree/array.rst rename to docs/source/api/expression_tree/array.rst diff --git a/docs/source/expression_tree/binary_operator.rst b/docs/source/api/expression_tree/binary_operator.rst similarity index 100% rename from docs/source/expression_tree/binary_operator.rst rename to docs/source/api/expression_tree/binary_operator.rst diff --git a/docs/source/expression_tree/broadcasts.rst b/docs/source/api/expression_tree/broadcasts.rst similarity index 100% rename from docs/source/expression_tree/broadcasts.rst rename to docs/source/api/expression_tree/broadcasts.rst diff --git a/docs/source/expression_tree/concatenations.rst b/docs/source/api/expression_tree/concatenations.rst similarity index 100% rename from docs/source/expression_tree/concatenations.rst rename to docs/source/api/expression_tree/concatenations.rst diff --git a/docs/source/expression_tree/functions.rst b/docs/source/api/expression_tree/functions.rst similarity index 100% rename from docs/source/expression_tree/functions.rst rename to docs/source/api/expression_tree/functions.rst diff --git a/docs/source/expression_tree/independent_variable.rst b/docs/source/api/expression_tree/independent_variable.rst similarity index 100% rename from docs/source/expression_tree/independent_variable.rst rename to docs/source/api/expression_tree/independent_variable.rst diff --git a/docs/source/expression_tree/index.rst b/docs/source/api/expression_tree/index.rst similarity index 100% rename from docs/source/expression_tree/index.rst rename to docs/source/api/expression_tree/index.rst diff --git a/docs/source/expression_tree/input_parameter.rst b/docs/source/api/expression_tree/input_parameter.rst similarity index 100% rename from docs/source/expression_tree/input_parameter.rst rename to docs/source/api/expression_tree/input_parameter.rst diff --git a/docs/source/expression_tree/interpolant.rst b/docs/source/api/expression_tree/interpolant.rst similarity index 100% rename from docs/source/expression_tree/interpolant.rst rename to docs/source/api/expression_tree/interpolant.rst diff --git a/docs/source/expression_tree/matrix.rst b/docs/source/api/expression_tree/matrix.rst similarity index 100% rename from docs/source/expression_tree/matrix.rst rename to docs/source/api/expression_tree/matrix.rst diff --git a/docs/source/expression_tree/operations/convert_to_casadi.rst b/docs/source/api/expression_tree/operations/convert_to_casadi.rst similarity index 100% rename from docs/source/expression_tree/operations/convert_to_casadi.rst rename to docs/source/api/expression_tree/operations/convert_to_casadi.rst diff --git a/docs/source/expression_tree/operations/evaluate.rst b/docs/source/api/expression_tree/operations/evaluate.rst similarity index 100% rename from docs/source/expression_tree/operations/evaluate.rst rename to docs/source/api/expression_tree/operations/evaluate.rst diff --git a/docs/source/expression_tree/operations/index.rst b/docs/source/api/expression_tree/operations/index.rst similarity index 100% rename from docs/source/expression_tree/operations/index.rst rename to docs/source/api/expression_tree/operations/index.rst diff --git a/docs/source/expression_tree/operations/jacobian.rst b/docs/source/api/expression_tree/operations/jacobian.rst similarity index 100% rename from docs/source/expression_tree/operations/jacobian.rst rename to docs/source/api/expression_tree/operations/jacobian.rst diff --git a/docs/source/expression_tree/operations/unpack_symbol.rst b/docs/source/api/expression_tree/operations/unpack_symbol.rst similarity index 100% rename from docs/source/expression_tree/operations/unpack_symbol.rst rename to docs/source/api/expression_tree/operations/unpack_symbol.rst diff --git a/docs/source/expression_tree/parameter.rst b/docs/source/api/expression_tree/parameter.rst similarity index 100% rename from docs/source/expression_tree/parameter.rst rename to docs/source/api/expression_tree/parameter.rst diff --git a/docs/source/expression_tree/scalar.rst b/docs/source/api/expression_tree/scalar.rst similarity index 100% rename from docs/source/expression_tree/scalar.rst rename to docs/source/api/expression_tree/scalar.rst diff --git a/docs/source/expression_tree/state_vector.rst b/docs/source/api/expression_tree/state_vector.rst similarity index 100% rename from docs/source/expression_tree/state_vector.rst rename to docs/source/api/expression_tree/state_vector.rst diff --git a/docs/source/expression_tree/symbol.rst b/docs/source/api/expression_tree/symbol.rst similarity index 100% rename from docs/source/expression_tree/symbol.rst rename to docs/source/api/expression_tree/symbol.rst diff --git a/docs/source/expression_tree/unary_operator.rst b/docs/source/api/expression_tree/unary_operator.rst similarity index 100% rename from docs/source/expression_tree/unary_operator.rst rename to docs/source/api/expression_tree/unary_operator.rst diff --git a/docs/source/expression_tree/variable.rst b/docs/source/api/expression_tree/variable.rst similarity index 100% rename from docs/source/expression_tree/variable.rst rename to docs/source/api/expression_tree/variable.rst diff --git a/docs/source/expression_tree/vector.rst b/docs/source/api/expression_tree/vector.rst similarity index 100% rename from docs/source/expression_tree/vector.rst rename to docs/source/api/expression_tree/vector.rst diff --git a/docs/source/geometry/battery_geometry.rst b/docs/source/api/geometry/battery_geometry.rst similarity index 100% rename from docs/source/geometry/battery_geometry.rst rename to docs/source/api/geometry/battery_geometry.rst diff --git a/docs/source/geometry/geometry.rst b/docs/source/api/geometry/geometry.rst similarity index 100% rename from docs/source/geometry/geometry.rst rename to docs/source/api/geometry/geometry.rst diff --git a/docs/source/geometry/index.rst b/docs/source/api/geometry/index.rst similarity index 100% rename from docs/source/geometry/index.rst rename to docs/source/api/geometry/index.rst diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 0000000000..91563fb338 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,32 @@ +.. module:: pybamm + +.. _api_docs: + +################# +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. +For a high-level introduction to PyBaMM, see the :ref:`user guide `. + +.. toctree:: + :maxdepth: 2 + + expression_tree/index + models/index + parameters/index + geometry/index + meshes/index + spatial_methods/index + solvers/index + experiments/index + simulation + plotting/index + util + callbacks + citations + batch_study \ No newline at end of file diff --git a/docs/source/meshes/index.rst b/docs/source/api/meshes/index.rst similarity index 100% rename from docs/source/meshes/index.rst rename to docs/source/api/meshes/index.rst diff --git a/docs/source/meshes/meshes.rst b/docs/source/api/meshes/meshes.rst similarity index 100% rename from docs/source/meshes/meshes.rst rename to docs/source/api/meshes/meshes.rst diff --git a/docs/source/meshes/one_dimensional_submeshes.rst b/docs/source/api/meshes/one_dimensional_submeshes.rst similarity index 100% rename from docs/source/meshes/one_dimensional_submeshes.rst rename to docs/source/api/meshes/one_dimensional_submeshes.rst diff --git a/docs/source/meshes/two_dimensional_submeshes.rst b/docs/source/api/meshes/two_dimensional_submeshes.rst similarity index 100% rename from docs/source/meshes/two_dimensional_submeshes.rst rename to docs/source/api/meshes/two_dimensional_submeshes.rst diff --git a/docs/source/meshes/zero_dimensional_submeshes.rst b/docs/source/api/meshes/zero_dimensional_submeshes.rst similarity index 100% rename from docs/source/meshes/zero_dimensional_submeshes.rst rename to docs/source/api/meshes/zero_dimensional_submeshes.rst diff --git a/docs/source/models/base_models/base_battery_model.rst b/docs/source/api/models/base_models/base_battery_model.rst similarity index 85% rename from docs/source/models/base_models/base_battery_model.rst rename to docs/source/api/models/base_models/base_battery_model.rst index 45f0eb6a3e..64715ae5d4 100644 --- a/docs/source/models/base_models/base_battery_model.rst +++ b/docs/source/api/models/base_models/base_battery_model.rst @@ -1,3 +1,5 @@ +.. _base_battery_model: + Base Battery Model ================== diff --git a/docs/source/models/base_models/base_model.rst b/docs/source/api/models/base_models/base_model.rst similarity index 100% rename from docs/source/models/base_models/base_model.rst rename to docs/source/api/models/base_models/base_model.rst diff --git a/docs/source/models/base_models/event.rst b/docs/source/api/models/base_models/event.rst similarity index 100% rename from docs/source/models/base_models/event.rst rename to docs/source/api/models/base_models/event.rst diff --git a/docs/source/models/base_models/index.rst b/docs/source/api/models/base_models/index.rst similarity index 100% rename from docs/source/models/base_models/index.rst rename to docs/source/api/models/base_models/index.rst diff --git a/docs/source/models/equivalent_circuit/index.rst b/docs/source/api/models/equivalent_circuit/index.rst similarity index 100% rename from docs/source/models/equivalent_circuit/index.rst rename to docs/source/api/models/equivalent_circuit/index.rst diff --git a/docs/source/models/equivalent_circuit/thevenin.rst b/docs/source/api/models/equivalent_circuit/thevenin.rst similarity index 100% rename from docs/source/models/equivalent_circuit/thevenin.rst rename to docs/source/api/models/equivalent_circuit/thevenin.rst diff --git a/docs/source/models/index.rst b/docs/source/api/models/index.rst similarity index 100% rename from docs/source/models/index.rst rename to docs/source/api/models/index.rst diff --git a/docs/source/models/lead_acid/base_lead_acid_model.rst b/docs/source/api/models/lead_acid/base_lead_acid_model.rst similarity index 100% rename from docs/source/models/lead_acid/base_lead_acid_model.rst rename to docs/source/api/models/lead_acid/base_lead_acid_model.rst diff --git a/docs/source/models/lead_acid/full.rst b/docs/source/api/models/lead_acid/full.rst similarity index 100% rename from docs/source/models/lead_acid/full.rst rename to docs/source/api/models/lead_acid/full.rst diff --git a/docs/source/models/lead_acid/index.rst b/docs/source/api/models/lead_acid/index.rst similarity index 100% rename from docs/source/models/lead_acid/index.rst rename to docs/source/api/models/lead_acid/index.rst diff --git a/docs/source/models/lead_acid/loqs.rst b/docs/source/api/models/lead_acid/loqs.rst similarity index 100% rename from docs/source/models/lead_acid/loqs.rst rename to docs/source/api/models/lead_acid/loqs.rst diff --git a/docs/source/models/lithium_ion/base_lithium_ion_model.rst b/docs/source/api/models/lithium_ion/base_lithium_ion_model.rst similarity index 100% rename from docs/source/models/lithium_ion/base_lithium_ion_model.rst rename to docs/source/api/models/lithium_ion/base_lithium_ion_model.rst diff --git a/docs/source/models/lithium_ion/dfn.rst b/docs/source/api/models/lithium_ion/dfn.rst similarity index 100% rename from docs/source/models/lithium_ion/dfn.rst rename to docs/source/api/models/lithium_ion/dfn.rst diff --git a/docs/source/models/lithium_ion/electrode_soh.rst b/docs/source/api/models/lithium_ion/electrode_soh.rst similarity index 100% rename from docs/source/models/lithium_ion/electrode_soh.rst rename to docs/source/api/models/lithium_ion/electrode_soh.rst diff --git a/docs/source/models/lithium_ion/index.rst b/docs/source/api/models/lithium_ion/index.rst similarity index 100% rename from docs/source/models/lithium_ion/index.rst rename to docs/source/api/models/lithium_ion/index.rst diff --git a/docs/source/models/lithium_ion/mpm.rst b/docs/source/api/models/lithium_ion/mpm.rst similarity index 100% rename from docs/source/models/lithium_ion/mpm.rst rename to docs/source/api/models/lithium_ion/mpm.rst diff --git a/docs/source/models/lithium_ion/newman_tobias.rst b/docs/source/api/models/lithium_ion/newman_tobias.rst similarity index 100% rename from docs/source/models/lithium_ion/newman_tobias.rst rename to docs/source/api/models/lithium_ion/newman_tobias.rst diff --git a/docs/source/models/lithium_ion/spm.rst b/docs/source/api/models/lithium_ion/spm.rst similarity index 100% rename from docs/source/models/lithium_ion/spm.rst rename to docs/source/api/models/lithium_ion/spm.rst diff --git a/docs/source/models/lithium_ion/spme.rst b/docs/source/api/models/lithium_ion/spme.rst similarity index 100% rename from docs/source/models/lithium_ion/spme.rst rename to docs/source/api/models/lithium_ion/spme.rst diff --git a/docs/source/models/lithium_ion/yang2017.rst b/docs/source/api/models/lithium_ion/yang2017.rst similarity index 100% rename from docs/source/models/lithium_ion/yang2017.rst rename to docs/source/api/models/lithium_ion/yang2017.rst diff --git a/docs/source/models/submodels/active_material/base_active_material.rst b/docs/source/api/models/submodels/active_material/base_active_material.rst similarity index 100% rename from docs/source/models/submodels/active_material/base_active_material.rst rename to docs/source/api/models/submodels/active_material/base_active_material.rst diff --git a/docs/source/models/submodels/active_material/constant_active_material.rst b/docs/source/api/models/submodels/active_material/constant_active_material.rst similarity index 100% rename from docs/source/models/submodels/active_material/constant_active_material.rst rename to docs/source/api/models/submodels/active_material/constant_active_material.rst diff --git a/docs/source/models/submodels/active_material/index.rst b/docs/source/api/models/submodels/active_material/index.rst similarity index 100% rename from docs/source/models/submodels/active_material/index.rst rename to docs/source/api/models/submodels/active_material/index.rst diff --git a/docs/source/models/submodels/active_material/loss_active_material.rst b/docs/source/api/models/submodels/active_material/loss_active_material.rst similarity index 100% rename from docs/source/models/submodels/active_material/loss_active_material.rst rename to docs/source/api/models/submodels/active_material/loss_active_material.rst diff --git a/docs/source/models/submodels/base_submodel.rst b/docs/source/api/models/submodels/base_submodel.rst similarity index 100% rename from docs/source/models/submodels/base_submodel.rst rename to docs/source/api/models/submodels/base_submodel.rst diff --git a/docs/source/models/submodels/convection/base_convection.rst b/docs/source/api/models/submodels/convection/base_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/base_convection.rst rename to docs/source/api/models/submodels/convection/base_convection.rst diff --git a/docs/source/models/submodels/convection/index.rst b/docs/source/api/models/submodels/convection/index.rst similarity index 100% rename from docs/source/models/submodels/convection/index.rst rename to docs/source/api/models/submodels/convection/index.rst diff --git a/docs/source/models/submodels/convection/through_cell/base_through_cell_convection.rst b/docs/source/api/models/submodels/convection/through_cell/base_through_cell_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/through_cell/base_through_cell_convection.rst rename to docs/source/api/models/submodels/convection/through_cell/base_through_cell_convection.rst diff --git a/docs/source/models/submodels/convection/through_cell/explicit_convection.rst b/docs/source/api/models/submodels/convection/through_cell/explicit_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/through_cell/explicit_convection.rst rename to docs/source/api/models/submodels/convection/through_cell/explicit_convection.rst diff --git a/docs/source/models/submodels/convection/through_cell/full_convection.rst b/docs/source/api/models/submodels/convection/through_cell/full_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/through_cell/full_convection.rst rename to docs/source/api/models/submodels/convection/through_cell/full_convection.rst diff --git a/docs/source/models/submodels/convection/through_cell/index.rst b/docs/source/api/models/submodels/convection/through_cell/index.rst similarity index 100% rename from docs/source/models/submodels/convection/through_cell/index.rst rename to docs/source/api/models/submodels/convection/through_cell/index.rst diff --git a/docs/source/models/submodels/convection/through_cell/no_convection.rst b/docs/source/api/models/submodels/convection/through_cell/no_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/through_cell/no_convection.rst rename to docs/source/api/models/submodels/convection/through_cell/no_convection.rst diff --git a/docs/source/models/submodels/convection/transverse/base_transverse_convection.rst b/docs/source/api/models/submodels/convection/transverse/base_transverse_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/transverse/base_transverse_convection.rst rename to docs/source/api/models/submodels/convection/transverse/base_transverse_convection.rst diff --git a/docs/source/models/submodels/convection/transverse/full_convection.rst b/docs/source/api/models/submodels/convection/transverse/full_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/transverse/full_convection.rst rename to docs/source/api/models/submodels/convection/transverse/full_convection.rst diff --git a/docs/source/models/submodels/convection/transverse/index.rst b/docs/source/api/models/submodels/convection/transverse/index.rst similarity index 100% rename from docs/source/models/submodels/convection/transverse/index.rst rename to docs/source/api/models/submodels/convection/transverse/index.rst diff --git a/docs/source/models/submodels/convection/transverse/no_convection.rst b/docs/source/api/models/submodels/convection/transverse/no_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/transverse/no_convection.rst rename to docs/source/api/models/submodels/convection/transverse/no_convection.rst diff --git a/docs/source/models/submodels/convection/transverse/uniform_convection.rst b/docs/source/api/models/submodels/convection/transverse/uniform_convection.rst similarity index 100% rename from docs/source/models/submodels/convection/transverse/uniform_convection.rst rename to docs/source/api/models/submodels/convection/transverse/uniform_convection.rst diff --git a/docs/source/models/submodels/current_collector/base_current_collector.rst b/docs/source/api/models/submodels/current_collector/base_current_collector.rst similarity index 100% rename from docs/source/models/submodels/current_collector/base_current_collector.rst rename to docs/source/api/models/submodels/current_collector/base_current_collector.rst diff --git a/docs/source/models/submodels/current_collector/effective_resistance_current_collector.rst b/docs/source/api/models/submodels/current_collector/effective_resistance_current_collector.rst similarity index 100% rename from docs/source/models/submodels/current_collector/effective_resistance_current_collector.rst rename to docs/source/api/models/submodels/current_collector/effective_resistance_current_collector.rst diff --git a/docs/source/models/submodels/current_collector/homogeneous_current_collector.rst b/docs/source/api/models/submodels/current_collector/homogeneous_current_collector.rst similarity index 100% rename from docs/source/models/submodels/current_collector/homogeneous_current_collector.rst rename to docs/source/api/models/submodels/current_collector/homogeneous_current_collector.rst diff --git a/docs/source/models/submodels/current_collector/index.rst b/docs/source/api/models/submodels/current_collector/index.rst similarity index 100% rename from docs/source/models/submodels/current_collector/index.rst rename to docs/source/api/models/submodels/current_collector/index.rst diff --git a/docs/source/models/submodels/current_collector/potential_pair.rst b/docs/source/api/models/submodels/current_collector/potential_pair.rst similarity index 100% rename from docs/source/models/submodels/current_collector/potential_pair.rst rename to docs/source/api/models/submodels/current_collector/potential_pair.rst diff --git a/docs/source/models/submodels/electrode/base_electrode.rst b/docs/source/api/models/submodels/electrode/base_electrode.rst similarity index 100% rename from docs/source/models/submodels/electrode/base_electrode.rst rename to docs/source/api/models/submodels/electrode/base_electrode.rst diff --git a/docs/source/models/submodels/electrode/index.rst b/docs/source/api/models/submodels/electrode/index.rst similarity index 100% rename from docs/source/models/submodels/electrode/index.rst rename to docs/source/api/models/submodels/electrode/index.rst diff --git a/docs/source/models/submodels/electrode/ohm/base_ohm.rst b/docs/source/api/models/submodels/electrode/ohm/base_ohm.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/base_ohm.rst rename to docs/source/api/models/submodels/electrode/ohm/base_ohm.rst diff --git a/docs/source/models/submodels/electrode/ohm/composite_ohm.rst b/docs/source/api/models/submodels/electrode/ohm/composite_ohm.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/composite_ohm.rst rename to docs/source/api/models/submodels/electrode/ohm/composite_ohm.rst diff --git a/docs/source/models/submodels/electrode/ohm/full_ohm.rst b/docs/source/api/models/submodels/electrode/ohm/full_ohm.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/full_ohm.rst rename to docs/source/api/models/submodels/electrode/ohm/full_ohm.rst diff --git a/docs/source/models/submodels/electrode/ohm/index.rst b/docs/source/api/models/submodels/electrode/ohm/index.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/index.rst rename to docs/source/api/models/submodels/electrode/ohm/index.rst diff --git a/docs/source/models/submodels/electrode/ohm/leading_ohm.rst b/docs/source/api/models/submodels/electrode/ohm/leading_ohm.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/leading_ohm.rst rename to docs/source/api/models/submodels/electrode/ohm/leading_ohm.rst diff --git a/docs/source/models/submodels/electrode/ohm/li_metal_explicit.rst b/docs/source/api/models/submodels/electrode/ohm/li_metal_explicit.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/li_metal_explicit.rst rename to docs/source/api/models/submodels/electrode/ohm/li_metal_explicit.rst diff --git a/docs/source/models/submodels/electrode/ohm/surface_form_ohm.rst b/docs/source/api/models/submodels/electrode/ohm/surface_form_ohm.rst similarity index 100% rename from docs/source/models/submodels/electrode/ohm/surface_form_ohm.rst rename to docs/source/api/models/submodels/electrode/ohm/surface_form_ohm.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/base_electrolyte_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/base_electrolyte_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/base_electrolyte_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/base_electrolyte_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/composite_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/composite_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/composite_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/composite_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/full_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/full_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/full_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/full_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/index.rst b/docs/source/api/models/submodels/electrolyte_conductivity/index.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/index.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/index.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/integrated_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/integrated_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/integrated_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/integrated_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/leading_order_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/leading_order_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/leading_order_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/leading_order_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/surface_form/explicit_surface_form_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/surface_form/explicit_surface_form_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/surface_form/explicit_surface_form_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/surface_form/explicit_surface_form_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/surface_form/full_surface_form_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/surface_form/full_surface_form_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/surface_form/full_surface_form_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/surface_form/full_surface_form_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/surface_form/index.rst b/docs/source/api/models/submodels/electrolyte_conductivity/surface_form/index.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/surface_form/index.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/surface_form/index.rst diff --git a/docs/source/models/submodels/electrolyte_conductivity/surface_form/leading_surface_form_conductivity.rst b/docs/source/api/models/submodels/electrolyte_conductivity/surface_form/leading_surface_form_conductivity.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_conductivity/surface_form/leading_surface_form_conductivity.rst rename to docs/source/api/models/submodels/electrolyte_conductivity/surface_form/leading_surface_form_conductivity.rst diff --git a/docs/source/models/submodels/electrolyte_diffusion/base_electrolyte_diffusion.rst b/docs/source/api/models/submodels/electrolyte_diffusion/base_electrolyte_diffusion.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_diffusion/base_electrolyte_diffusion.rst rename to docs/source/api/models/submodels/electrolyte_diffusion/base_electrolyte_diffusion.rst diff --git a/docs/source/models/submodels/electrolyte_diffusion/constant_concentration.rst b/docs/source/api/models/submodels/electrolyte_diffusion/constant_concentration.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_diffusion/constant_concentration.rst rename to docs/source/api/models/submodels/electrolyte_diffusion/constant_concentration.rst diff --git a/docs/source/models/submodels/electrolyte_diffusion/full_diffusion.rst b/docs/source/api/models/submodels/electrolyte_diffusion/full_diffusion.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_diffusion/full_diffusion.rst rename to docs/source/api/models/submodels/electrolyte_diffusion/full_diffusion.rst diff --git a/docs/source/models/submodels/electrolyte_diffusion/index.rst b/docs/source/api/models/submodels/electrolyte_diffusion/index.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_diffusion/index.rst rename to docs/source/api/models/submodels/electrolyte_diffusion/index.rst diff --git a/docs/source/models/submodels/electrolyte_diffusion/leading_order_diffusion.rst b/docs/source/api/models/submodels/electrolyte_diffusion/leading_order_diffusion.rst similarity index 100% rename from docs/source/models/submodels/electrolyte_diffusion/leading_order_diffusion.rst rename to docs/source/api/models/submodels/electrolyte_diffusion/leading_order_diffusion.rst diff --git a/docs/source/models/submodels/equivalent_circuit_elements/index.rst b/docs/source/api/models/submodels/equivalent_circuit_elements/index.rst similarity index 100% rename from docs/source/models/submodels/equivalent_circuit_elements/index.rst rename to docs/source/api/models/submodels/equivalent_circuit_elements/index.rst diff --git a/docs/source/models/submodels/equivalent_circuit_elements/ocv_element.rst b/docs/source/api/models/submodels/equivalent_circuit_elements/ocv_element.rst similarity index 100% rename from docs/source/models/submodels/equivalent_circuit_elements/ocv_element.rst rename to docs/source/api/models/submodels/equivalent_circuit_elements/ocv_element.rst diff --git a/docs/source/models/submodels/equivalent_circuit_elements/rc_element.rst b/docs/source/api/models/submodels/equivalent_circuit_elements/rc_element.rst similarity index 100% rename from docs/source/models/submodels/equivalent_circuit_elements/rc_element.rst rename to docs/source/api/models/submodels/equivalent_circuit_elements/rc_element.rst diff --git a/docs/source/models/submodels/equivalent_circuit_elements/resistor_element.rst b/docs/source/api/models/submodels/equivalent_circuit_elements/resistor_element.rst similarity index 100% rename from docs/source/models/submodels/equivalent_circuit_elements/resistor_element.rst rename to docs/source/api/models/submodels/equivalent_circuit_elements/resistor_element.rst diff --git a/docs/source/models/submodels/equivalent_circuit_elements/thermal.rst b/docs/source/api/models/submodels/equivalent_circuit_elements/thermal.rst similarity index 100% rename from docs/source/models/submodels/equivalent_circuit_elements/thermal.rst rename to docs/source/api/models/submodels/equivalent_circuit_elements/thermal.rst diff --git a/docs/source/models/submodels/equivalent_circuit_elements/voltage_model.rst b/docs/source/api/models/submodels/equivalent_circuit_elements/voltage_model.rst similarity index 100% rename from docs/source/models/submodels/equivalent_circuit_elements/voltage_model.rst rename to docs/source/api/models/submodels/equivalent_circuit_elements/voltage_model.rst diff --git a/docs/source/models/submodels/external_circuit/explicit_control_external_circuit.rst b/docs/source/api/models/submodels/external_circuit/explicit_control_external_circuit.rst similarity index 100% rename from docs/source/models/submodels/external_circuit/explicit_control_external_circuit.rst rename to docs/source/api/models/submodels/external_circuit/explicit_control_external_circuit.rst diff --git a/docs/source/models/submodels/external_circuit/function_control_external_circuit.rst b/docs/source/api/models/submodels/external_circuit/function_control_external_circuit.rst similarity index 100% rename from docs/source/models/submodels/external_circuit/function_control_external_circuit.rst rename to docs/source/api/models/submodels/external_circuit/function_control_external_circuit.rst diff --git a/docs/source/models/submodels/external_circuit/index.rst b/docs/source/api/models/submodels/external_circuit/index.rst similarity index 100% rename from docs/source/models/submodels/external_circuit/index.rst rename to docs/source/api/models/submodels/external_circuit/index.rst diff --git a/docs/source/models/submodels/index.rst b/docs/source/api/models/submodels/index.rst similarity index 100% rename from docs/source/models/submodels/index.rst rename to docs/source/api/models/submodels/index.rst diff --git a/docs/source/models/submodels/interface/base_interface.rst b/docs/source/api/models/submodels/interface/base_interface.rst similarity index 100% rename from docs/source/models/submodels/interface/base_interface.rst rename to docs/source/api/models/submodels/interface/base_interface.rst diff --git a/docs/source/models/submodels/interface/diffusion_limited.rst b/docs/source/api/models/submodels/interface/diffusion_limited.rst similarity index 100% rename from docs/source/models/submodels/interface/diffusion_limited.rst rename to docs/source/api/models/submodels/interface/diffusion_limited.rst diff --git a/docs/source/models/submodels/interface/index.rst b/docs/source/api/models/submodels/interface/index.rst similarity index 100% rename from docs/source/models/submodels/interface/index.rst rename to docs/source/api/models/submodels/interface/index.rst diff --git a/docs/source/models/submodels/interface/inverse_butler_volmer.rst b/docs/source/api/models/submodels/interface/inverse_butler_volmer.rst similarity index 100% rename from docs/source/models/submodels/interface/inverse_butler_volmer.rst rename to docs/source/api/models/submodels/interface/inverse_butler_volmer.rst diff --git a/docs/source/models/submodels/interface/kinetics.rst b/docs/source/api/models/submodels/interface/kinetics.rst similarity index 100% rename from docs/source/models/submodels/interface/kinetics.rst rename to docs/source/api/models/submodels/interface/kinetics.rst diff --git a/docs/source/models/submodels/interface/open_circuit_potential.rst b/docs/source/api/models/submodels/interface/open_circuit_potential.rst similarity index 100% rename from docs/source/models/submodels/interface/open_circuit_potential.rst rename to docs/source/api/models/submodels/interface/open_circuit_potential.rst diff --git a/docs/source/models/submodels/interface/sei.rst b/docs/source/api/models/submodels/interface/sei.rst similarity index 100% rename from docs/source/models/submodels/interface/sei.rst rename to docs/source/api/models/submodels/interface/sei.rst diff --git a/docs/source/models/submodels/oxygen_diffusion/base_oxygen_diffusion.rst b/docs/source/api/models/submodels/oxygen_diffusion/base_oxygen_diffusion.rst similarity index 100% rename from docs/source/models/submodels/oxygen_diffusion/base_oxygen_diffusion.rst rename to docs/source/api/models/submodels/oxygen_diffusion/base_oxygen_diffusion.rst diff --git a/docs/source/models/submodels/oxygen_diffusion/full_oxygen_diffusion.rst b/docs/source/api/models/submodels/oxygen_diffusion/full_oxygen_diffusion.rst similarity index 100% rename from docs/source/models/submodels/oxygen_diffusion/full_oxygen_diffusion.rst rename to docs/source/api/models/submodels/oxygen_diffusion/full_oxygen_diffusion.rst diff --git a/docs/source/models/submodels/oxygen_diffusion/index.rst b/docs/source/api/models/submodels/oxygen_diffusion/index.rst similarity index 100% rename from docs/source/models/submodels/oxygen_diffusion/index.rst rename to docs/source/api/models/submodels/oxygen_diffusion/index.rst diff --git a/docs/source/models/submodels/oxygen_diffusion/leading_oxygen_diffusion.rst b/docs/source/api/models/submodels/oxygen_diffusion/leading_oxygen_diffusion.rst similarity index 100% rename from docs/source/models/submodels/oxygen_diffusion/leading_oxygen_diffusion.rst rename to docs/source/api/models/submodels/oxygen_diffusion/leading_oxygen_diffusion.rst diff --git a/docs/source/models/submodels/oxygen_diffusion/no_oxygen.rst b/docs/source/api/models/submodels/oxygen_diffusion/no_oxygen.rst similarity index 100% rename from docs/source/models/submodels/oxygen_diffusion/no_oxygen.rst rename to docs/source/api/models/submodels/oxygen_diffusion/no_oxygen.rst diff --git a/docs/source/models/submodels/particle/base_particle.rst b/docs/source/api/models/submodels/particle/base_particle.rst similarity index 100% rename from docs/source/models/submodels/particle/base_particle.rst rename to docs/source/api/models/submodels/particle/base_particle.rst diff --git a/docs/source/models/submodels/particle/fickian_diffusion.rst b/docs/source/api/models/submodels/particle/fickian_diffusion.rst similarity index 100% rename from docs/source/models/submodels/particle/fickian_diffusion.rst rename to docs/source/api/models/submodels/particle/fickian_diffusion.rst diff --git a/docs/source/models/submodels/particle/index.rst b/docs/source/api/models/submodels/particle/index.rst similarity index 100% rename from docs/source/models/submodels/particle/index.rst rename to docs/source/api/models/submodels/particle/index.rst diff --git a/docs/source/models/submodels/particle/polynomial_profile.rst b/docs/source/api/models/submodels/particle/polynomial_profile.rst similarity index 100% rename from docs/source/models/submodels/particle/polynomial_profile.rst rename to docs/source/api/models/submodels/particle/polynomial_profile.rst diff --git a/docs/source/models/submodels/particle/x_averaged_polynomial_profile.rst b/docs/source/api/models/submodels/particle/x_averaged_polynomial_profile.rst similarity index 100% rename from docs/source/models/submodels/particle/x_averaged_polynomial_profile.rst rename to docs/source/api/models/submodels/particle/x_averaged_polynomial_profile.rst diff --git a/docs/source/models/submodels/particle_mechanics/base_mechanics.rst b/docs/source/api/models/submodels/particle_mechanics/base_mechanics.rst similarity index 100% rename from docs/source/models/submodels/particle_mechanics/base_mechanics.rst rename to docs/source/api/models/submodels/particle_mechanics/base_mechanics.rst diff --git a/docs/source/models/submodels/particle_mechanics/crack_propagation.rst b/docs/source/api/models/submodels/particle_mechanics/crack_propagation.rst similarity index 100% rename from docs/source/models/submodels/particle_mechanics/crack_propagation.rst rename to docs/source/api/models/submodels/particle_mechanics/crack_propagation.rst diff --git a/docs/source/models/submodels/particle_mechanics/index.rst b/docs/source/api/models/submodels/particle_mechanics/index.rst similarity index 100% rename from docs/source/models/submodels/particle_mechanics/index.rst rename to docs/source/api/models/submodels/particle_mechanics/index.rst diff --git a/docs/source/models/submodels/particle_mechanics/swelling_only.rst b/docs/source/api/models/submodels/particle_mechanics/swelling_only.rst similarity index 100% rename from docs/source/models/submodels/particle_mechanics/swelling_only.rst rename to docs/source/api/models/submodels/particle_mechanics/swelling_only.rst diff --git a/docs/source/models/submodels/porosity/base_porosity.rst b/docs/source/api/models/submodels/porosity/base_porosity.rst similarity index 100% rename from docs/source/models/submodels/porosity/base_porosity.rst rename to docs/source/api/models/submodels/porosity/base_porosity.rst diff --git a/docs/source/models/submodels/porosity/constant_porosity.rst b/docs/source/api/models/submodels/porosity/constant_porosity.rst similarity index 100% rename from docs/source/models/submodels/porosity/constant_porosity.rst rename to docs/source/api/models/submodels/porosity/constant_porosity.rst diff --git a/docs/source/models/submodels/porosity/index.rst b/docs/source/api/models/submodels/porosity/index.rst similarity index 100% rename from docs/source/models/submodels/porosity/index.rst rename to docs/source/api/models/submodels/porosity/index.rst diff --git a/docs/source/models/submodels/porosity/reaction_driven_porosity.rst b/docs/source/api/models/submodels/porosity/reaction_driven_porosity.rst similarity index 100% rename from docs/source/models/submodels/porosity/reaction_driven_porosity.rst rename to docs/source/api/models/submodels/porosity/reaction_driven_porosity.rst diff --git a/docs/source/models/submodels/porosity/reaction_driven_porosity_ode.rst b/docs/source/api/models/submodels/porosity/reaction_driven_porosity_ode.rst similarity index 100% rename from docs/source/models/submodels/porosity/reaction_driven_porosity_ode.rst rename to docs/source/api/models/submodels/porosity/reaction_driven_porosity_ode.rst diff --git a/docs/source/models/submodels/thermal/base_thermal.rst b/docs/source/api/models/submodels/thermal/base_thermal.rst similarity index 100% rename from docs/source/models/submodels/thermal/base_thermal.rst rename to docs/source/api/models/submodels/thermal/base_thermal.rst diff --git a/docs/source/models/submodels/thermal/index.rst b/docs/source/api/models/submodels/thermal/index.rst similarity index 100% rename from docs/source/models/submodels/thermal/index.rst rename to docs/source/api/models/submodels/thermal/index.rst diff --git a/docs/source/models/submodels/thermal/isothermal.rst b/docs/source/api/models/submodels/thermal/isothermal.rst similarity index 100% rename from docs/source/models/submodels/thermal/isothermal.rst rename to docs/source/api/models/submodels/thermal/isothermal.rst diff --git a/docs/source/models/submodels/thermal/lumped.rst b/docs/source/api/models/submodels/thermal/lumped.rst similarity index 100% rename from docs/source/models/submodels/thermal/lumped.rst rename to docs/source/api/models/submodels/thermal/lumped.rst diff --git a/docs/source/models/submodels/thermal/pouch_cell/index.rst b/docs/source/api/models/submodels/thermal/pouch_cell/index.rst similarity index 100% rename from docs/source/models/submodels/thermal/pouch_cell/index.rst rename to docs/source/api/models/submodels/thermal/pouch_cell/index.rst diff --git a/docs/source/models/submodels/thermal/pouch_cell/pouch_cell_1D_current_collectors.rst b/docs/source/api/models/submodels/thermal/pouch_cell/pouch_cell_1D_current_collectors.rst similarity index 100% rename from docs/source/models/submodels/thermal/pouch_cell/pouch_cell_1D_current_collectors.rst rename to docs/source/api/models/submodels/thermal/pouch_cell/pouch_cell_1D_current_collectors.rst diff --git a/docs/source/models/submodels/thermal/pouch_cell/pouch_cell_2D_current_collectors.rst b/docs/source/api/models/submodels/thermal/pouch_cell/pouch_cell_2D_current_collectors.rst similarity index 100% rename from docs/source/models/submodels/thermal/pouch_cell/pouch_cell_2D_current_collectors.rst rename to docs/source/api/models/submodels/thermal/pouch_cell/pouch_cell_2D_current_collectors.rst diff --git a/docs/source/models/submodels/thermal/x_full.rst b/docs/source/api/models/submodels/thermal/x_full.rst similarity index 100% rename from docs/source/models/submodels/thermal/x_full.rst rename to docs/source/api/models/submodels/thermal/x_full.rst diff --git a/docs/source/models/submodels/transport_efficiency/base_transport_efficiency.rst b/docs/source/api/models/submodels/transport_efficiency/base_transport_efficiency.rst similarity index 100% rename from docs/source/models/submodels/transport_efficiency/base_transport_efficiency.rst rename to docs/source/api/models/submodels/transport_efficiency/base_transport_efficiency.rst diff --git a/docs/source/models/submodels/transport_efficiency/bruggeman_transport_efficiency.rst b/docs/source/api/models/submodels/transport_efficiency/bruggeman_transport_efficiency.rst similarity index 100% rename from docs/source/models/submodels/transport_efficiency/bruggeman_transport_efficiency.rst rename to docs/source/api/models/submodels/transport_efficiency/bruggeman_transport_efficiency.rst diff --git a/docs/source/models/submodels/transport_efficiency/index.rst b/docs/source/api/models/submodels/transport_efficiency/index.rst similarity index 100% rename from docs/source/models/submodels/transport_efficiency/index.rst rename to docs/source/api/models/submodels/transport_efficiency/index.rst diff --git a/docs/source/parameters/electrical_parameters.rst b/docs/source/api/parameters/electrical_parameters.rst similarity index 100% rename from docs/source/parameters/electrical_parameters.rst rename to docs/source/api/parameters/electrical_parameters.rst diff --git a/docs/source/parameters/geometric_parameters.rst b/docs/source/api/parameters/geometric_parameters.rst similarity index 100% rename from docs/source/parameters/geometric_parameters.rst rename to docs/source/api/parameters/geometric_parameters.rst diff --git a/docs/source/parameters/index.rst b/docs/source/api/parameters/index.rst similarity index 100% rename from docs/source/parameters/index.rst rename to docs/source/api/parameters/index.rst diff --git a/docs/source/parameters/lead_acid_parameters.rst b/docs/source/api/parameters/lead_acid_parameters.rst similarity index 100% rename from docs/source/parameters/lead_acid_parameters.rst rename to docs/source/api/parameters/lead_acid_parameters.rst diff --git a/docs/source/parameters/lithium_ion_parameters.rst b/docs/source/api/parameters/lithium_ion_parameters.rst similarity index 100% rename from docs/source/parameters/lithium_ion_parameters.rst rename to docs/source/api/parameters/lithium_ion_parameters.rst diff --git a/docs/source/parameters/parameter_sets.rst b/docs/source/api/parameters/parameter_sets.rst similarity index 98% rename from docs/source/parameters/parameter_sets.rst rename to docs/source/api/parameters/parameter_sets.rst index f3de4eac3a..97da4d272e 100644 --- a/docs/source/parameters/parameter_sets.rst +++ b/docs/source/api/parameters/parameter_sets.rst @@ -1,5 +1,7 @@ :tocdepth: 3 +.. _parameter_sets: + =============== Parameters Sets =============== @@ -84,7 +86,7 @@ listed below. See :ref:`adding-parameter-sets` for information on registering ne parameter sets with PyBaMM. Lead-acid Parameter Sets -========================== +======================== {% for k,v in parameter_sets.items() if v.chemistry == "lead_acid" %} {{k}} @@ -99,4 +101,3 @@ Lithium-ion Parameter Sets ---------------------------- {{ parameter_sets.get_docstring(k) }} {% endfor %} - diff --git a/docs/source/parameters/parameter_values.rst b/docs/source/api/parameters/parameter_values.rst similarity index 100% rename from docs/source/parameters/parameter_values.rst rename to docs/source/api/parameters/parameter_values.rst diff --git a/docs/source/parameters/process_parameter_data.rst b/docs/source/api/parameters/process_parameter_data.rst similarity index 100% rename from docs/source/parameters/process_parameter_data.rst rename to docs/source/api/parameters/process_parameter_data.rst diff --git a/docs/source/parameters/thermal_parameters.rst b/docs/source/api/parameters/thermal_parameters.rst similarity index 100% rename from docs/source/parameters/thermal_parameters.rst rename to docs/source/api/parameters/thermal_parameters.rst diff --git a/docs/source/plotting/index.rst b/docs/source/api/plotting/index.rst similarity index 88% rename from docs/source/plotting/index.rst rename to docs/source/api/plotting/index.rst index 52852d02f6..088823c64c 100644 --- a/docs/source/plotting/index.rst +++ b/docs/source/api/plotting/index.rst @@ -4,7 +4,6 @@ Plotting .. toctree:: quick_plot - dynamic_plot plot plot_2D plot_voltage_components diff --git a/docs/source/plotting/plot.rst b/docs/source/api/plotting/plot.rst similarity index 100% rename from docs/source/plotting/plot.rst rename to docs/source/api/plotting/plot.rst diff --git a/docs/source/plotting/plot_2D.rst b/docs/source/api/plotting/plot_2D.rst similarity index 100% rename from docs/source/plotting/plot_2D.rst rename to docs/source/api/plotting/plot_2D.rst diff --git a/docs/source/plotting/plot_summary_variables.rst b/docs/source/api/plotting/plot_summary_variables.rst similarity index 100% rename from docs/source/plotting/plot_summary_variables.rst rename to docs/source/api/plotting/plot_summary_variables.rst diff --git a/docs/source/plotting/plot_voltage_components.rst b/docs/source/api/plotting/plot_voltage_components.rst similarity index 76% rename from docs/source/plotting/plot_voltage_components.rst rename to docs/source/api/plotting/plot_voltage_components.rst index 5ba712630d..04d95e62cc 100644 --- a/docs/source/plotting/plot_voltage_components.rst +++ b/docs/source/api/plotting/plot_voltage_components.rst @@ -1,3 +1,5 @@ +.. _plot_voltage_components: + Plot Voltage Components ======================= diff --git a/docs/source/plotting/quick_plot.rst b/docs/source/api/plotting/quick_plot.rst similarity index 54% rename from docs/source/plotting/quick_plot.rst rename to docs/source/api/plotting/quick_plot.rst index b26903ba14..ef81719056 100644 --- a/docs/source/plotting/quick_plot.rst +++ b/docs/source/api/plotting/quick_plot.rst @@ -1,5 +1,9 @@ +.. _quick_plot: + Quick Plot ========== .. autoclass:: pybamm.QuickPlot :members: + +.. autofunction:: pybamm.dynamic_plot \ No newline at end of file diff --git a/docs/source/simulation.rst b/docs/source/api/simulation.rst similarity index 100% rename from docs/source/simulation.rst rename to docs/source/api/simulation.rst diff --git a/docs/source/solvers/algebraic_solvers.rst b/docs/source/api/solvers/algebraic_solvers.rst similarity index 100% rename from docs/source/solvers/algebraic_solvers.rst rename to docs/source/api/solvers/algebraic_solvers.rst diff --git a/docs/source/solvers/base_solver.rst b/docs/source/api/solvers/base_solver.rst similarity index 100% rename from docs/source/solvers/base_solver.rst rename to docs/source/api/solvers/base_solver.rst diff --git a/docs/source/solvers/casadi_solver.rst b/docs/source/api/solvers/casadi_solver.rst similarity index 100% rename from docs/source/solvers/casadi_solver.rst rename to docs/source/api/solvers/casadi_solver.rst diff --git a/docs/source/solvers/dummy_solver.rst b/docs/source/api/solvers/dummy_solver.rst similarity index 100% rename from docs/source/solvers/dummy_solver.rst rename to docs/source/api/solvers/dummy_solver.rst diff --git a/docs/source/solvers/idaklu_solver.rst b/docs/source/api/solvers/idaklu_solver.rst similarity index 100% rename from docs/source/solvers/idaklu_solver.rst rename to docs/source/api/solvers/idaklu_solver.rst diff --git a/docs/source/solvers/index.rst b/docs/source/api/solvers/index.rst similarity index 100% rename from docs/source/solvers/index.rst rename to docs/source/api/solvers/index.rst diff --git a/docs/source/solvers/jax_solver.rst b/docs/source/api/solvers/jax_solver.rst similarity index 100% rename from docs/source/solvers/jax_solver.rst rename to docs/source/api/solvers/jax_solver.rst diff --git a/docs/source/solvers/processed_variable.rst b/docs/source/api/solvers/processed_variable.rst similarity index 100% rename from docs/source/solvers/processed_variable.rst rename to docs/source/api/solvers/processed_variable.rst diff --git a/docs/source/solvers/scikits_solvers.rst b/docs/source/api/solvers/scikits_solvers.rst similarity index 100% rename from docs/source/solvers/scikits_solvers.rst rename to docs/source/api/solvers/scikits_solvers.rst diff --git a/docs/source/solvers/scipy_solver.rst b/docs/source/api/solvers/scipy_solver.rst similarity index 100% rename from docs/source/solvers/scipy_solver.rst rename to docs/source/api/solvers/scipy_solver.rst diff --git a/docs/source/solvers/solution.rst b/docs/source/api/solvers/solution.rst similarity index 100% rename from docs/source/solvers/solution.rst rename to docs/source/api/solvers/solution.rst diff --git a/docs/source/spatial_methods/discretisation.rst b/docs/source/api/spatial_methods/discretisation.rst similarity index 100% rename from docs/source/spatial_methods/discretisation.rst rename to docs/source/api/spatial_methods/discretisation.rst diff --git a/docs/source/spatial_methods/finite_volume.rst b/docs/source/api/spatial_methods/finite_volume.rst similarity index 100% rename from docs/source/spatial_methods/finite_volume.rst rename to docs/source/api/spatial_methods/finite_volume.rst diff --git a/docs/source/spatial_methods/index.rst b/docs/source/api/spatial_methods/index.rst similarity index 100% rename from docs/source/spatial_methods/index.rst rename to docs/source/api/spatial_methods/index.rst diff --git a/docs/source/spatial_methods/scikit_finite_element.rst b/docs/source/api/spatial_methods/scikit_finite_element.rst similarity index 100% rename from docs/source/spatial_methods/scikit_finite_element.rst rename to docs/source/api/spatial_methods/scikit_finite_element.rst diff --git a/docs/source/spatial_methods/spatial_method.rst b/docs/source/api/spatial_methods/spatial_method.rst similarity index 100% rename from docs/source/spatial_methods/spatial_method.rst rename to docs/source/api/spatial_methods/spatial_method.rst diff --git a/docs/source/spatial_methods/spectral_volume.rst b/docs/source/api/spatial_methods/spectral_volume.rst similarity index 100% rename from docs/source/spatial_methods/spectral_volume.rst rename to docs/source/api/spatial_methods/spectral_volume.rst diff --git a/docs/source/spatial_methods/zero_dimensional_method.rst b/docs/source/api/spatial_methods/zero_dimensional_method.rst similarity index 100% rename from docs/source/spatial_methods/zero_dimensional_method.rst rename to docs/source/api/spatial_methods/zero_dimensional_method.rst diff --git a/docs/source/util.rst b/docs/source/api/util.rst similarity index 100% rename from docs/source/util.rst rename to docs/source/api/util.rst diff --git a/docs/source/plotting/dynamic_plot.rst b/docs/source/plotting/dynamic_plot.rst deleted file mode 100644 index b363ab2222..0000000000 --- a/docs/source/plotting/dynamic_plot.rst +++ /dev/null @@ -1,4 +0,0 @@ -Dynamic Plot -============ - -.. autofunction:: pybamm.dynamic_plot diff --git a/docs/source/user_guide/fundamentals/index.rst b/docs/source/user_guide/fundamentals/index.rst new file mode 100644 index 0000000000..e9fabdf34c --- /dev/null +++ b/docs/source/user_guide/fundamentals/index.rst @@ -0,0 +1,85 @@ +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. + +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:: + + This user-guide is a work-in-progress, we hope that this brief but incomplete overview will be useful to you. + +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 +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 `_. + +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). +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. + +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`). + +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 + +.. code-block:: 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 + + 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() + +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 + +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 + +and using the plotting library of their choice. \ No newline at end of file diff --git a/docs/source/user_guide/getting_started.rst b/docs/source/user_guide/getting_started.rst new file mode 100644 index 0000000000..4753ce9a34 --- /dev/null +++ b/docs/source/user_guide/getting_started.rst @@ -0,0 +1,41 @@ +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.rst b/docs/source/user_guide/index.rst new file mode 100644 index 0000000000..ebf661e9ae --- /dev/null +++ b/docs/source/user_guide/index.rst @@ -0,0 +1,21 @@ +.. _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/install/GNU-linux.rst b/docs/source/user_guide/installation/GNU-linux.rst similarity index 100% rename from docs/install/GNU-linux.rst rename to docs/source/user_guide/installation/GNU-linux.rst diff --git a/docs/source/user_guide/installation/index.rst b/docs/source/user_guide/installation/index.rst new file mode 100644 index 0000000000..3c03521cca --- /dev/null +++ b/docs/source/user_guide/installation/index.rst @@ -0,0 +1,54 @@ +Installation +============ + +PyBaMM is available on GNU/Linux, MacOS and Windows. +It can be installed using pip or conda, or from source. + +Using pip +---------- + +PyBaMM can be installed via pip from `PyPI `__ + +GNU/Linux and Windows +~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + pip install pybamm + +macOS +~~~~~ + +.. code:: bash + + brew install sundials && pip install pybamm + +Using conda +----------- + +PyBaMM is part of the `Anaconda `_ distribution and is available as a conda package through the conda-forge channel + +.. code:: bash + + conda install -c conda-forge pybamm + +Optional solvers +---------------- + +Following GNU/Linux and macOS solvers are optionally available: + +* `scikits.odes `_ -based solver, see `Optional - scikits.odes solver `_. +* `jax `_ -based solver, see `Optional - JaxSolver `_. + +Full installation guide +----------------------- + +Installing a specific version? Installing from source? Check the advanced installation pages below + +.. toctree:: + :maxdepth: 1 + + GNU-linux + windows + windows-wsl + install-from-source \ No newline at end of file diff --git a/docs/install/install-from-source.rst b/docs/source/user_guide/installation/install-from-source.rst similarity index 100% rename from docs/install/install-from-source.rst rename to docs/source/user_guide/installation/install-from-source.rst diff --git a/docs/install/windows-wsl.rst b/docs/source/user_guide/installation/windows-wsl.rst similarity index 100% rename from docs/install/windows-wsl.rst rename to docs/source/user_guide/installation/windows-wsl.rst diff --git a/docs/install/windows.rst b/docs/source/user_guide/installation/windows.rst similarity index 100% rename from docs/install/windows.rst rename to docs/source/user_guide/installation/windows.rst diff --git a/docs/source/user_guide/todo.md b/docs/source/user_guide/todo.md new file mode 100644 index 0000000000..dc16b3d010 --- /dev/null +++ b/docs/source/user_guide/todo.md @@ -0,0 +1,14 @@ +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 diff --git a/examples/notebooks/README.md b/examples/notebooks/README.md index 7cc0e5ffd2..8b52c47c74 100644 --- a/examples/notebooks/README.md +++ b/examples/notebooks/README.md @@ -65,7 +65,6 @@ Once you are comfortable with the expression tree structure, a good starting poi - [Full porous-electrode](https://pybamm.readthedocs.io/en/latest/source/models/lead_acid/full.html) - [Leading-Order Quasi-Static](https://pybamm.readthedocs.io/en/latest/source/models/lead_acid/loqs.html) -- [Higher-Order](https://pybamm.readthedocs.io/en/latest/source/models/lead_acid/higher_order.html) ### Spatial Methods diff --git a/pybamm/models/submodels/electrode/ohm/li_metal.py b/pybamm/models/submodels/electrode/ohm/li_metal.py index 9f6b7501ef..f97b37fea0 100644 --- a/pybamm/models/submodels/electrode/ohm/li_metal.py +++ b/pybamm/models/submodels/electrode/ohm/li_metal.py @@ -122,7 +122,7 @@ class LithiumMetalExplicit(LithiumMetalBaseModel): Parameters ---------- - param : parameteslackr class + param : parameter class The parameters to use for this submodel options : dict, optional A dictionary of options to be passed to the model. diff --git a/setup.py b/setup.py index f8257e478d..df64abe44b 100644 --- a/setup.py +++ b/setup.py @@ -208,7 +208,12 @@ def compile_KLU(): "matplotlib>=2.0", ], extras_require={ - "docs": ["sphinx>=1.5", "guzzle-sphinx-theme"], # For doc generation + "docs": [ + "sphinx>=1.5", + "pydata-sphinx-theme", + "sphinx_design", + "sphinx-copybutton", + ], # For doc generation "dev": [ "flake8>=3", # For code style checking "black", # For code style auto-formatting diff --git a/tox.ini b/tox.ini index 1baebeb389..c741a7854a 100644 --- a/tox.ini +++ b/tox.ini @@ -13,7 +13,9 @@ deps = dev-!windows-!mac: cmake dev: black dev,doctests: sphinx>=1.5 - dev,doctests: guzzle-sphinx-theme + dev,doctests: pydata-sphinx-theme + dev,doctests: sphinx_design + dev,doctests: sphinx-copybutton !windows-!mac: scikits.odes commands = @@ -57,7 +59,7 @@ usedevelop = false skip_install = false deps = sphinx>=1.5 - guzzle-sphinx-theme + pydata-sphinx-theme sphinx-autobuild changedir = docs commands = sphinx-autobuild --open-browser -qT . {envtmpdir}/html