Merge pull request #17 from BattMoTeam/nb01_update

Notebooks clean up
BattMoTeam · Oct 2, 2024 · 33330e1 · 33330e1
2 parents 680d865 + 36dde39
commit 33330e1
Show file tree

Hide file tree

Showing 41 changed files with 2,389 additions and 1,835 deletions.
diff --git a/Documentation/README.org b/Documentation/README.org
@@ -1,36 +1,42 @@
 #+TITLE: Documentation generation for BattMo
 * Requirements
-** sphinx
-   installation instruction described [[https://www.sphinx-doc.org/en/master/usage/installation.html][here]]
-   #+begin_src
-     pip install sphinx
+** Installation
+   Run from the Documentation directory where the ~requirements.txt~ file is
+   #+begin_src 
+     pip install -r requirements.txt
    #+end_src
-** install sphinx rtd theme
-   https://pypi.org/project/sphinx-rtd-theme/
-   #+begin_src
-     pip install sphinx-rtd-theme
-   #+end_src
-** bibtex extension
-   https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
-   #+begin_src
-     pip install sphinxcontrib-bibtex
-   #+end_src
-** globabsubs extension
-   #+begin_src
-     pip install sphinxcontrib-globalsubs
-   #+end_src
-** youtube
-   #+begin_src shell
-     pip install sphinxcontrib-youtube
-   #+end_src
-** collapse
-   #+begin_src shell
-     python -m pip install sphinx_collapse
-   #+end_src   
-** autosectionlabel
-   - part of default distribution
-   - We use ~autosectionlabel_prefix_document = True~ which means that the internal link must be prefixed by the file
-     name and a semi-column, see [[https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html][here]].
+** Overview of the package used in sphinx
+*** sphinx
+    installation instruction described [[https://www.sphinx-doc.org/en/master/usage/installation.html][here]]
+    #+begin_src
+      pip install sphinx
+    #+end_src
+*** install sphinx rtd theme
+    https://pypi.org/project/sphinx-rtd-theme/
+    #+begin_src
+      pip install sphinx-rtd-theme
+    #+end_src
+*** bibtex extension
+    https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
+    #+begin_src
+      pip install sphinxcontrib-bibtex
+    #+end_src
+*** globabsubs extension
+    #+begin_src
+      pip install sphinxcontrib-globalsubs
+    #+end_src
+*** youtube
+    #+begin_src shell
+      pip install sphinxcontrib-youtube
+    #+end_src
+*** collapse
+    #+begin_src shell
+      python -m pip install sphinx_collapse
+    #+end_src   
+*** autosectionlabel
+    - part of default distribution
+    - We use ~autosectionlabel_prefix_document = True~ which means that the internal link must be prefixed by the file
+      name and a semi-column, see [[https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html][here]].
 
 * Workflow for editing
 
@@ -41,15 +47,14 @@
 
   The command generates all the files for a static website and writes them in ~Documentation/_build/html~
 
-  All the files in this directory must then be copied to the ~BattMo-doc~ [[https://github.com/BattMoTeam/BattMo-doc][repo]]. From there, make a *force* push. We do
-  not keep track of the history of the ouput files (html), but we of course keep track of the documentation source, directly in the
-  main repo ~BattMo~.
+  When the changes are pushed, the documentation is also automatically compiled on github using github actions
+
 
-  The deployment of the webpage can be followed from the [[https://github.com/BattMoTeam/BattMo-doc/actions][github pages section]]
+  The deployment of the webpage can be followed from the [[https://github.com/BattMoTeam/BattMo/actions][github page section]]
 
   The result can be view at
 
-  https://battmoteam.github.io/BattMo-doc/
+  https://battmoteam.github.io/BattMo/
 
 * Special workflow for example scripts
 ** Compilation

diff --git a/Documentation/_static/notebooks/tutorial_1_a_simple_p2d_model_live.html b/Documentation/_static/notebooks/tutorial_1_a_simple_p2d_model_live.html
diff --git a/Documentation/_static/notebooks/tutorial_2_changing_control_protocol_live.html b/Documentation/_static/notebooks/tutorial_2_changing_control_protocol_live.html
diff --git a/Documentation/_static/notebooks/tutorial_3_modify_structural_parameters_live.html b/Documentation/_static/notebooks/tutorial_3_modify_structural_parameters_live.html
diff --git a/Documentation/_static/notebooks/tutorial_4_modify_material_parameters_live.html b/Documentation/_static/notebooks/tutorial_4_modify_material_parameters_live.html
diff --git a/Documentation/_static/notebooks/tutorial_5_simulate_CCCV_cycling_live.html b/Documentation/_static/notebooks/tutorial_5_simulate_CCCV_cycling_live.html
diff --git a/Documentation/_static/notebooks/tutorial_6_simulate_thermal_performance_live.html b/Documentation/_static/notebooks/tutorial_6_simulate_thermal_performance_live.html
diff --git a/Documentation/_static/notebooks/tutorial_7_a_simple_p4d_model_live.html b/Documentation/_static/notebooks/tutorial_7_a_simple_p4d_model_live.html
diff --git a/Documentation/_static/notebooks/tutorial_8_simulate_a_multilayer_pouch_cell_live.html b/Documentation/_static/notebooks/tutorial_8_simulate_a_multilayer_pouch_cell_live.html
diff --git a/Documentation/_static/notebooks/tutorial_9_simulate_a_cylindrical_cell_live.html b/Documentation/_static/notebooks/tutorial_9_simulate_a_cylindrical_cell_live.html
diff --git a/Documentation/conf.py b/Documentation/conf.py
@@ -40,6 +40,7 @@
               'sphinxcontrib.bibtex',
               'sphinx.ext.intersphinx',
               'sphinx.ext.autosectionlabel',
+              'sphinx.ext.mathjax',
               'sphinxcontrib.youtube',
               'sphinx_collapse',
               'sphinx_design']

diff --git a/Documentation/gui.rst b/Documentation/gui.rst
@@ -1,8 +1,20 @@
-:orphan:
-
 ==========
-BattMo GUI
+BattMo App
 ==========
 
-:todo:`fill in page`
+A web-based graphical user-interface of BattMo is under development. At the moment, this application 
+utilizes the Julia version of BattMo and has the possibility to do simulations using the P2D model.
+The application is very easy to use, intuitive and can be easily accessed at `http://app.batterymodel.com/ <http://app.batterymodel.com/>`_.
 
+.. note::
+  This section is still under development.
+
+This section provides a description on some of its features.
+It gives details on some of the calculation that are done within the application, like for example the calculation of the cell mass and specific capacities.
+Furthermore, it provides some troubleshooting for when simulations aren't successful or when the results contain unexpected artifacts.
+
+.. toctree::
+
+    gui_features
+    gui_calculations
+    gui_troubleshooting
diff --git a/Documentation/gui_calculations.rst b/Documentation/gui_calculations.rst
@@ -0,0 +1,56 @@
+================
+Calculations
+================
+Multiple quick calculations are done within the app to calculate certain parameters.
+In this section you can find the formulas that belong to these calculations. 
+
+**Effective density**
+   The effective density of an electrode coating:
+
+   .. math::
+
+      \rho = \sum_i \omega_{i} \rho_i
+
+   Here is :math:`\omega_{i}` the mass fraction of an electrode coating material and :math:`\rho_{i}` the density of the same coating material.
+
+**Mass loading**
+   The mass loading of an electrode:
+
+   .. math::
+
+      \rho A = d \rho(1-\varepsilon)
+
+   Here is :math:`d` the thickness of the electrode coating, :math:`\rho` is the effective density, and :math:`\varepsilon` is the porosity.
+
+**Specific capacity**
+   The specific capacity of an active material:
+
+   .. math::
+
+      Q_s = c_{max} |x_{max} - x_{min}| \frac{nF}{\rho}
+
+   Here is :math:`c_{max}` the maximum concentration, :math:`x_{max}` and :math:`x_{min}` are the maximum and minimum stoichiometry,
+   :math:`F` is the Faraday constant, :math:`\rho` the density of the active material, and :math:`n` is the number of electrons transfered.
+
+
+**Capacity**
+   The capacity of an electrode:
+
+   .. math::
+
+      Q =  \omega Q_s \rho V (1-\varepsilon)
+
+   Here is :math:`\omega` the mass fraction, :math:`Q_s` is the specific capacity, :math:`\rho` the effective density, :math:`V` is the volume of the electrode, and :math:`\varepsilon` is the porosity.  
+
+   The capacity of the cell is the limiting capacity out of the thwo electrode capacities.
+
+**Cell mass**
+   The cell mass:
+
+   .. math::
+
+      m = \sum_i m_{i}
+
+   :math:`m_i` represents here the mass of the several battery components: negative and positive electrode, separator, electrolyte, current collector, and the packing mass.
+
+
diff --git a/Documentation/gui_features.rst b/Documentation/gui_features.rst
@@ -0,0 +1,36 @@
+=============
+Features
+=============
+
+This section explains some convenient features that the application includes.
+
+
+Use default materials
+=====================
+The application has some default materials that you can use in your input parameter setup.
+These materials are datasets formed from literature. An overview of which materials are available
+can be found on the page `Materials and models <http://app.batterymodel.com/Materials_and_models>`_ together with the reference and dataset details.
+
+Define your own materials
+=========================
+Did you characterize your own material in the lab, found one in literature, or just simply would like to see how changing material characteristics change the
+simulation results? Then you can do this by defining your own material. You can do this on the `Simulation <http://app.batterymodel.com/Simulation>`_ page by selecting 'User defined' in the 
+a material selectbox. When 'User defined' is selected, an expander will appear where you can fill in your own parameter values. You can still use parameter values from the default materials by copying
+the values from the `Materials and models <http://app.batterymodel.com/Materials_and_models>`_ page.
+
+Visualize your geometry
+=======================
+We've included a feature on the `Simulation <http://app.batterymodel.com/Simulation>`_ page that visualizes the battery cell geometry depending on the component 
+thicknesses and porosities, the length, and the width that are defined in the parameter inputs. 
+
+Download your input data
+========================
+After defining your parameters on the `Simulation <http://app.batterymodel.com/Simulation>`_ page, you can download them in two different formats.
+The first format is the JSON Linked Data format in which the data is structured, together with its metadata, according to the `FAIR data principles <https://www.go-fair.org/fair-principles/>`_ and 
+the `5 star open data guidelines <https://5stardata.info/en/>`_ in order to improve interoperability.
+In the second format, the input data is structured according to the |battmo| format.
+
+Visualize and download your results
+===================================
+After a simulation has finished, the results can immediatly be Visualized on the `Results <http://app.batterymodel.com/Results>`_ page.
+You can choose from several results parameters and visualize them in line or color plots. You can also download you results as an HDF5 file.
diff --git a/Documentation/gui_troubleshooting.rst b/Documentation/gui_troubleshooting.rst
@@ -0,0 +1,18 @@
+===================
+Troubleshooting
+===================
+
+This sections gives some troubleshooting ideas.
+
+Unnatural artifacts in your results
+====================================
+
+
+.. image:: img/discretization_issue_battmo_app.png
+
+A spike like this in your results indicates a discritization issue. In order to fix the issue you can increase the number of cells used in the simulation.
+As in the example, the artifact is visible in the results of the negative electrode, the number of electrode cells of the negative electrode should be increased until the issue is resolved.
+The 'number of cells' parameters can be found among the 'advanced' input parameters.
+
+.. Unsuccesful simulation
+.. ======================
diff --git a/Documentation/img/discretization_issue_battmo_app.png b/Documentation/img/discretization_issue_battmo_app.png
diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -15,6 +15,7 @@
    advancedtopics
    juliabridge
    Electrolyser simulation <publishedExamples/runElectrolyser>
+   gui
    seealso
    References <bibliography>
 

diff --git a/Documentation/publishedExamples/battMoTutorial.png b/Documentation/publishedExamples/battMoTutorial.png