From 231d1a249b3bb0cedc1cd36568a7345c122f1fb3 Mon Sep 17 00:00:00 2001 From: Lorena Hendrix Date: Wed, 18 Dec 2024 17:19:22 +0100 Subject: [PATCH] Improvement of BattMoApp documentation --- Documentation/app.rst | 41 ++++++++++++++ ..._calculations.rst => app_calculations.rst} | 0 Documentation/app_features.rst | 56 +++++++++++++++++++ Documentation/app_troubleshooting.rst | 18 ++++++ ...ooting.rst => app_unnatural_artifacts.rst} | 16 ++---- Documentation/app_unsuccessful_simulation.rst | 10 ++++ Documentation/gui.rst | 20 ------- Documentation/gui_features.rst | 36 ------------ Documentation/index.rst | 2 +- 9 files changed, 131 insertions(+), 68 deletions(-) create mode 100644 Documentation/app.rst rename Documentation/{gui_calculations.rst => app_calculations.rst} (100%) create mode 100644 Documentation/app_features.rst create mode 100644 Documentation/app_troubleshooting.rst rename Documentation/{gui_troubleshooting.rst => app_unnatural_artifacts.rst} (69%) create mode 100644 Documentation/app_unsuccessful_simulation.rst delete mode 100644 Documentation/gui.rst delete mode 100644 Documentation/gui_features.rst diff --git a/Documentation/app.rst b/Documentation/app.rst new file mode 100644 index 00000000..812ed06d --- /dev/null +++ b/Documentation/app.rst @@ -0,0 +1,41 @@ + +BattMoApp +########### + +.. toctree:: + :maxdepth: 2 + :hidden: + +BattMoApp is a user-friendly web application that leverages the powerful BattMo.jl simulation software to model battery cells with precision and speed. It offers a suite +of features designed to make battery simulations easy, intuitive, and accessible. For now it only utilizes BattMo's P2D model, but +as BattMo.jl expands its models, BattMoApp will follow along with that development. + + + +Getting started +================ + +Accessing BattMoApp is as simple as navigating to app.batterymodel.com. Once there, you'll find an intuitive interface guiding you through the simulation setup process. + +It is also possible to install BattMoApp locally with Docker. On the `github `_ page you can find detailed instructions on how to install the app using Docker. + + +.. grid:: 1 + + .. grid-item-card:: + :padding: 2 + + `Install using Docker `_ + + .. grid-item-card:: + :padding: 2 + + :ref:`Features ` + + .. grid-item-card:: + :padding: 2 + + :ref:`Troubleshooting ` + + + diff --git a/Documentation/gui_calculations.rst b/Documentation/app_calculations.rst similarity index 100% rename from Documentation/gui_calculations.rst rename to Documentation/app_calculations.rst diff --git a/Documentation/app_features.rst b/Documentation/app_features.rst new file mode 100644 index 00000000..4960f89f --- /dev/null +++ b/Documentation/app_features.rst @@ -0,0 +1,56 @@ +Features +######### + +BattMoApp offers a multiple features designed to streamline and enhance the process of battery cell simulation. +Below is a detailed overview of the core features provided by BattMoApp. + + +Utilize Default Materials +-------------------------- +Kickstart your simulations using our curated library of default materials, +compiled from literature sources. +Explore the available materials on the `Materials and models `_ page, +complete with references and dataset details. + +Customize with Your Own Materials +---------------------------------- +Do you have specific material data from your research or literature? +BattMoApp allows you to input custom material parameters. +On the `Simulation `_ page, select 'User defined' from the material dropdown, +and input your parameters in the expanded section. +You can also reference default material values from the `Materials and models `_ page. + + +Visualize Your Battery Geometry +----------------------------------- +Curious about how your battery cell looks based on your input parameters? +Our geometry visualization tool on the `Simulation `_ page graphically represents your battery cell, +reflecting component thicknesses, porosities, length, and width. + + +Download Input Data +-------------------------- +After configuring your simulation parameters, download them in two formats: + +- JSON Linked Data Format: Structured data with metadata, adhering to `FAIR data principles `_ and the `5 star open data guidelines `_ . + +- BattMo JSON Input Format: Compatible with BattMo's input requirements. + +This feature ensures better data management and reproducibility. + + +Upload Input Data +-------------------------- +You can upload you previously downloaded input data on the `Simulation `_ page. +When you do this, the parameter values on the page will automatically be adapted to your input file. +This make it very easy to review and alter previous simulations. + +Visualize and Download Results +------------------------------------ +Once your simulation is complete, delve into the results with our visualization tools. +Analyze performance metrics, observe trends, and download the data for further examination or reporting. + +Upload your previous results +------------------------------------ +You can upload previously downloaded results and visualize them on the `Results `_ page. +This makes it very easy to review previous results and compare them with new results. \ No newline at end of file diff --git a/Documentation/app_troubleshooting.rst b/Documentation/app_troubleshooting.rst new file mode 100644 index 00000000..961bd299 --- /dev/null +++ b/Documentation/app_troubleshooting.rst @@ -0,0 +1,18 @@ +Troubleshooting +################ + +This sections gives some troubleshooting ideas. + + + +.. grid:: 2 + + .. grid-item-card:: + :padding: 2 + + :ref:`Unnatural artifacts in your results ` + + .. grid-item-card:: + :padding: 2 + + :ref:`Unsuccessful simulation ` \ No newline at end of file diff --git a/Documentation/gui_troubleshooting.rst b/Documentation/app_unnatural_artifacts.rst similarity index 69% rename from Documentation/gui_troubleshooting.rst rename to Documentation/app_unnatural_artifacts.rst index fedf0cb3..2c07539a 100644 --- a/Documentation/gui_troubleshooting.rst +++ b/Documentation/app_unnatural_artifacts.rst @@ -1,18 +1,12 @@ -=================== -Troubleshooting -=================== - -This sections gives some troubleshooting ideas. - Unnatural artifacts in your results -==================================== +#################################### +Discritization issues +------------------------ + .. 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 -.. ====================== \ No newline at end of file +The 'number of cells' parameters can be found among the 'advanced' input parameters. \ No newline at end of file diff --git a/Documentation/app_unsuccessful_simulation.rst b/Documentation/app_unsuccessful_simulation.rst new file mode 100644 index 00000000..0209f239 --- /dev/null +++ b/Documentation/app_unsuccessful_simulation.rst @@ -0,0 +1,10 @@ +Unsuccessful simulation +#################################### +Did your parameter values result in an unsuccessful simulation? See if one of the described cases below is similar to your case. +It might help solving your problem. + +Using LiFePO4 datasets +------------------------ +Do you obtain an unsuccessful simulation when using one of the default LiFePO4 datasets? +Make sure that you set the upper cutoff voltage (under Protocol) to a value that is realistic for a battery cell containing an LFP cathode. Try setting it +to 3.6 and see if it results in a successful simulation this time. diff --git a/Documentation/gui.rst b/Documentation/gui.rst deleted file mode 100644 index bac9908e..00000000 --- a/Documentation/gui.rst +++ /dev/null @@ -1,20 +0,0 @@ -========== -BattMo App -========== - -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/ `_. - -.. 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 \ No newline at end of file diff --git a/Documentation/gui_features.rst b/Documentation/gui_features.rst deleted file mode 100644 index 99552d65..00000000 --- a/Documentation/gui_features.rst +++ /dev/null @@ -1,36 +0,0 @@ -============= -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 `_ 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 `_ 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 `_ page. - -Visualize your geometry -======================= -We've included a feature on the `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 `_ 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 `_ and -the `5 star open data guidelines `_ 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 `_ 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. \ No newline at end of file diff --git a/Documentation/index.rst b/Documentation/index.rst index ea9bccf3..e5d99c58 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -17,7 +17,7 @@ Electrolyser simulation Protonic Membrane Gas Supply - gui + app Computational Graph seealso References