Merge branch 'main' into cyl_and_sph_avg_quantities

festim-dev · Jan 10, 2025 · 1c22343 · 1c22343
2 parents e747d52 + 8d6857b
commit 1c22343
Show file tree

Hide file tree

Showing 113 changed files with 1,477 additions and 539 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,10 +10,9 @@ jobs:
       uses: actions/checkout@v2
 
     - name: Set up Conda
-      uses: conda-incubator/setup-miniconda@v2
+      uses: conda-incubator/setup-miniconda@v3
       with:
         activate-environment: myenv
-        # mamba-version: "*"
         channels: conda-forge, defaults
 
     - name: Create Conda environment

diff --git a/.gitignore b/.gitignore
@@ -64,7 +64,9 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/*/_build/
+docs/*/_static/
+docs/*/_templates/
 
 # PyBuilder
 target/

diff --git a/docs/environment.yml b/docs/environment.yml
@@ -6,14 +6,13 @@ dependencies:
   - fenics
   - matplotlib==3.7.1
   - pip>=20.1
-  - sphinx==7
+  - sphinx==7.4.3
   - folium
   - numpy==1.24
-  - pip:
-    - sympy
-    - sphinx_book_theme==1.1.2
-    - sphinx-design==0.5.0
-    - sphinxcontrib-bibtex
-    - sphinx-copybutton
-    - pillow
-    - sphinxcontrib-images
+  - sympy
+  - sphinx-book-theme
+  - sphinx-design
+  - sphinxcontrib-bibtex
+  - sphinx-copybutton
+  - pillow
+  - sphinxcontrib-images
diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css
@@ -0,0 +1,78 @@
+@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');
+
+body {
+    font-family: 'Open Sans', sans-serif;
+}
+
+h1 {
+    font-family: "Lato", sans-serif;
+}
+
+pre,
+code {
+    font-size: 100%;
+    line-height: 155%;
+}
+
+/* Main page overview cards */
+
+.sd-card {
+    border-radius: 0;
+    padding: 30px 10px 20px 10px;
+    margin: 10px 0px;
+}
+
+.sd-card .sd-card-header {
+    text-align: center;
+}
+
+.sd-card .sd-card-title {
+    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;
+    font-size: var(--pst-font-size-h5);
+    font-weight: bold;
+    padding: 2.5rem 0rem 0.5rem 0rem;
+}
+
+
+/* 
+SPHINX-BOOK-THEME HOTFIX (top-right icons): 
+https://github.com/executablebooks/sphinx-book-theme/issues/879 
+*/
+.header-article__inner .header-article-items__end,
+.header-article__inner .header-article-items__start {
+    align-items: start;
+    display: flex;
+    gap: .5rem;
+}
+
+/* 
+SPHINX-BOOK-THEME HOTFIX (right column vertical stretching fix): 
+https://github.com/executablebooks/sphinx-book-theme/issues/879 
+*/
+.toc-entry a.nav-link {
+    padding: .125rem 0 .125rem 1rem;
+}
+
+/* 
+h3 font weight fix (from extra heavy to normal):
+https://github.com/executablebooks/sphinx-book-theme/issues/879 
+*/
+h3 {
+    font-size: 125%;
+    font-weight: normal;
+}
diff --git a/docs/source/api/exports.rst b/docs/source/api/exports.rst
@@ -15,10 +15,6 @@ Exports
     :members:
     :show-inheritance:
 
-.. autoclass:: TXTExports
-    :members:
-    :show-inheritance:
-
 .. autoclass:: TrapDensityXDMF
     :members:
     :show-inheritance:

diff --git a/docs/source/api/meshing.rst b/docs/source/api/meshing.rst
@@ -15,10 +15,6 @@ Meshing
     :members:
     :show-inheritance:
 
-.. autoclass:: MeshFromRefinements
-    :members:
-    :show-inheritance:
-
 .. autoclass:: MeshFromXDMF
     :members:
     :show-inheritance:
diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst
@@ -1,3 +1,5 @@
+.. _developers_guide:
+
 =================
 Developer's Guide
 =================
@@ -24,24 +26,59 @@ And/or contribute to the source code by:
 Contributing to the code
 ------------------------
 
+For complete information on contributions with GitHub see this guide on `GitHub <https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project>`_.
+
 .. tip::
 
    If you're a beginner, look for `issues tagged with "Good first issue" <https://github.com/festim-dev/FESTIM/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_.
 
    These issues are usually relatively easy to tackle and perfect for newcomers.
 
-1) `Fork the repository <https://github.com/festim-dev/FESTIM/fork>`_
+#. `Fork the repository <https://github.com/festim-dev/FESTIM/fork>`_
+
+   By forking the repository, you create a copy where you can safely make changes.
+
+#. Clone your fork
+
+   .. code-block:: bash
+
+      git clone https://github.com/[your_username]/FESTIM
+
+   Remember to replace ``[your_username]`` with your GitHub username.
+
+#. Make your changes
+
+   Commit your changes locally and push them to your fork.
+
+   .. code-block:: bash
+
+      git add [modified files]
+      git commit -m "Your commit message"
+      git push
+
+#. Test your code
+
+   If you are adding new features or fixing bugs, it is important to test your code.
+   See :ref:`Test suite` for more information.
+
+#. Format your code using `Black <https://github.com/psf/black>`_.
+
+   The source code of FESTIM is formated with the Black code formatter. Using of a unified code style simplifies the code review
+   and increases its readability. See :ref:`Code formatting` for more information.
 
-By forking the repository, you create a copy where you can safely make changes.
+#. Optional: Build the documentation
 
-2) Make your changes
-3) `Open a PR <https://github.com/festim-dev/FESTIM/compare>`_
-4) Wait for a :ref:`maintainer<Maintainers>` to review your PR
+   You may want to build the documentation to see if your changes are correctly reflected or if you are updating the docs.
+   See :ref:`Documentation guide` for more information.
 
-Before merging your changes, they have to be reviewed. We ensure the changes don't break anything during the review and eventually propose/request improvements.
-The time before the review will depend on the maintainers' availability.
+#. `Open a PR <https://github.com/festim-dev/FESTIM/compare>`_
 
-5) When everything is in order, the maintainers will merge your PR!
+#. Wait for a :ref:`maintainer<Maintainers>` to review your PR
+
+   Before merging your changes, they have to be reviewed. We ensure the changes don't break anything during the review and eventually propose/request improvements.
+   The time before the review will depend on the maintainers' availability.
+
+#. When everything is in order, the maintainers will merge your PR!
 
 -----------
 Maintainers
@@ -69,6 +106,8 @@ Click `here <https://www.atlassian.com/continuous-delivery/continuous-integratio
 
 All the tests can be found in the `test folder <https://github.com/festim-dev/FESTIM/tree/main/test>`_ at the root of the FESTIM repository.
 
+You need to have the right dependencies installed to test your code (see :ref:`installation<Installation>`).
+
 .. note::
 
    Make sure to install ``pytest`` to run the test suite locally:
@@ -124,6 +163,33 @@ Implementing a new feature
 #. Open a PR
 
 
+----------------
+Code formatting
+----------------
+
+Before merging your PR, the modified scripts should be formatted to maintain the consistency of the coding style. FESTIM is formatted using 
+`Black <https://github.com/psf/black>`_. To install Black, run the following command:
+
+.. code-block:: bash
+
+   pip install black
+
+After the installation, you can format a file using:
+
+.. code-block:: bash
+
+   black my_script.py
+
+Alternatively, you can format all files in the current directory with:
+
+.. code-block:: bash
+
+   black .
+
+
+If you use Visual Studio Code, you can install the `extension <https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter>`_ 
+with support for the Black formatter. Then, you can set Black as a default formatter for python and enable formatting "on save" for your code. 
+
 -------------------
 Documentation guide
 -------------------
@@ -183,4 +249,16 @@ When contributing to the documentation, make sure to:
 #. Write clear and concise documentation
 #. Use the right syntax
 #. Update the documentation when new features are added
+#. Test the documentation using:
+
+.. code-block:: bash
+
+   cd docs/source
+   make doctest
+
+or using: 
 
+.. code-block:: bash
+
+   cd docs
+   sphinx-build -b doctest source build
diff --git a/docs/source/images/gmsh_tut_1.png b/docs/source/images/gmsh_tut_1.png
diff --git a/docs/source/images/gmsh_tut_2.png b/docs/source/images/gmsh_tut_2.png
diff --git a/docs/source/images/gmsh_tut_3.png b/docs/source/images/gmsh_tut_3.png
diff --git a/docs/source/images/gmsh_tut_4.png b/docs/source/images/gmsh_tut_4.png
diff --git a/docs/source/images/gmsh_tut_5.png b/docs/source/images/gmsh_tut_5.png
diff --git a/docs/source/images/icons/book-2-svgrepo-com.svg b/docs/source/images/icons/book-2-svgrepo-com.svg
diff --git a/docs/source/images/icons/check-square-svgrepo-com.svg b/docs/source/images/icons/check-square-svgrepo-com.svg
diff --git a/docs/source/images/icons/clapperboard-play-svgrepo-com.svg b/docs/source/images/icons/clapperboard-play-svgrepo-com.svg
diff --git a/docs/source/images/icons/code-square-svgrepo-com.svg b/docs/source/images/icons/code-square-svgrepo-com.svg
diff --git a/docs/source/images/icons/keyboard-svgrepo-com.svg b/docs/source/images/icons/keyboard-svgrepo-com.svg
diff --git a/docs/source/images/icons/running-2-svgrepo-com.svg b/docs/source/images/icons/running-2-svgrepo-com.svg
diff --git a/docs/source/images/user_logos/Beihang_University.png b/docs/source/images/user_logos/Beihang_University.png
diff --git a/docs/source/images/user_logos/Commonwealth_Fusion_Systems Devens_MA_USA.png b/docs/source/images/user_logos/Commonwealth_Fusion_Systems Devens_MA_USA.png
diff --git a/docs/source/images/user_logos/Cranfield_University_UK.png b/docs/source/images/user_logos/Cranfield_University_UK.png
diff --git a/docs/source/images/user_logos/ENEA.png b/docs/source/images/user_logos/ENEA.png
diff --git a/docs/source/images/user_logos/ENI.png b/docs/source/images/user_logos/ENI.png
diff --git a/docs/source/images/user_logos/Frazer_Nash.png b/docs/source/images/user_logos/Frazer_Nash.png
diff --git a/docs/source/images/user_logos/IRFM_cadarache_France.png b/docs/source/images/user_logos/IRFM_cadarache_France.png
diff --git a/docs/source/images/user_logos/ITER_organization_France.png b/docs/source/images/user_logos/ITER_organization_France.png
diff --git a/docs/source/images/user_logos/Institut_Jožef_Stefan.png b/docs/source/images/user_logos/Institut_Jožef_Stefan.png
diff --git a/...e/images/user_logos/Institute_of_plasma_physics_Chinese_academy_of_sciences.png b/...e/images/user_logos/Institute_of_plasma_physics_Chinese_academy_of_sciences.png
diff --git a/docs/source/images/user_logos/Kyoto_Fusioneering.png b/docs/source/images/user_logos/Kyoto_Fusioneering.png
diff --git a/docs/source/images/user_logos/LSPM_Villetaneuse_France.png b/docs/source/images/user_logos/LSPM_Villetaneuse_France.png
diff --git a/docs/source/images/user_logos/Logo_of_University_of_Tsukuba.png b/docs/source/images/user_logos/Logo_of_University_of_Tsukuba.png
diff --git a/docs/source/images/user_logos/MEPhI_moscow_Russia.png b/docs/source/images/user_logos/MEPhI_moscow_Russia.png
diff --git a/docs/source/images/user_logos/MIT_Cambridge_MA_USA.png b/docs/source/images/user_logos/MIT_Cambridge_MA_USA.png
diff --git a/docs/source/images/user_logos/Marathon_Fusion_USA.png b/docs/source/images/user_logos/Marathon_Fusion_USA.png
diff --git a/docs/source/images/user_logos/Oak_Ridge_National_Laboratory.png b/docs/source/images/user_logos/Oak_Ridge_National_Laboratory.png
diff --git a/docs/source/images/user_logos/Politecnico_di_Torino.png b/docs/source/images/user_logos/Politecnico_di_Torino.png
diff --git a/docs/source/images/user_logos/Thea_Energy_USA.png b/docs/source/images/user_logos/Thea_Energy_USA.png
diff --git a/docs/source/images/user_logos/UKAEA_UK.png b/docs/source/images/user_logos/UKAEA_UK.png
diff --git a/docs/source/images/user_logos/University_San_Diego.png b/docs/source/images/user_logos/University_San_Diego.png
diff --git a/docs/source/images/user_logos/University_Wisconsin_Madison_USA.png b/docs/source/images/user_logos/University_Wisconsin_Madison_USA.png
diff --git a/docs/source/images/user_logos/University_of_Surrey.png b/docs/source/images/user_logos/University_of_Surrey.png
diff --git a/docs/source/images/user_logos/University_of_Tsukuba.png b/docs/source/images/user_logos/University_of_Tsukuba.png
diff --git a/docs/source/images/user_logos/Zap_Energy.png b/docs/source/images/user_logos/Zap_Energy.png
diff --git a/docs/source/images/user_logos/digiLab_UK.png b/docs/source/images/user_logos/digiLab_UK.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,6 +11,49 @@ The tool is based on the finite element methods to solve the McNabb & Foster tra
 It is capable of solving 1D/2D/3D multimaterial simulations and provides support for a wide-range of boundary conditions, which makes it a very versatile tool that can be adapted to many use cases.
 Moreover, users can rapidly get started with FESTIM thanks to its python API.
 
+.. All the logos are from this collection https://www.svgrepo.com/collection/solar-linear-icons/
+
+.. grid:: 3
+      :gutter: 2
+
+      .. grid-item::
+
+         .. card:: Installation
+            :img-top: images/icons/running-2-svgrepo-com.svg
+            :link: installation
+            :link-type: doc
+
+      .. grid-item::
+
+         .. card:: User guide
+            :img-top: images/icons/book-2-svgrepo-com.svg
+            :link: userguide/index
+            :link-type: doc
+
+      .. grid-item::
+
+         .. card:: Tutorials
+            :img-top: images/icons/clapperboard-play-svgrepo-com.svg
+            :link: https://github.com/festim-dev/FESTIM-workshop
+
+      .. grid-item::
+
+         .. card:: Developer guide
+            :img-top: images/icons/code-square-svgrepo-com.svg
+            :link: devguide/index
+            :link-type: doc
+
+      .. grid-item::
+         .. card:: V&V
+            :img-top: images/icons/check-square-svgrepo-com.svg
+            :link: https://festim-vv-report.readthedocs.io/en/latest/
+
+      .. grid-item::
+         .. card:: API reference
+            :img-top: images/icons/keyboard-svgrepo-com.svg
+            :link: api/festim
+            :link-type: doc
+
 FESTIM was originally developed at the `Institute for Magnetic Fusion Research (IRFM) <https://irfm.cea.fr/en/index.php>`_ and the `Process and Materials Sciences Laboratory (LSPM) <https://www.lspm.cnrs.fr/en/home/>`_.
 Various research institutions and private companies now contribute actively to FESTIM's development.
 For more information, feel free to ask questions on the `FESTIM Discourse Page <https://festim.discourse.group/>`_.