diff --git a/.github/workflows/doctest.yml b/.github/workflows/doctest.yml new file mode 100644 index 000000000..9584b560f --- /dev/null +++ b/.github/workflows/doctest.yml @@ -0,0 +1,21 @@ +name: Documentation test + +on: [push, pull_request] + +jobs: + docbuild: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set up Conda + uses: conda-incubator/setup-miniconda@v2 + with: + activate-environment: festim2-docs + environment-file: docs/environment.yml + + - name: Doc Tests + shell: bash -l {0} + run: sphinx-build -b doctest docs/source docs/_build/doctest diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 575d783f0..7f8f14f50 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,7 @@ version: 2 conda: - environment: docs/source/environment.yaml + environment: docs/environment.yml build: os: "ubuntu-20.04" @@ -16,13 +16,11 @@ build: # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/source/conf.py - # If using Sphinx, optionally build your docs in additional formats such as PDF # formats: # - pdf # # Optionally declare the Python requirements required to build your docs -python: - install: - - method: pip - path: . +# python: +# install: +# - requirements: docs/requirements.txt diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 000000000..c6aa7743e --- /dev/null +++ b/docs/environment.yml @@ -0,0 +1,20 @@ +name: festim2-docs +channels: + - conda-forge + - defaults +dependencies: + - fenics-dolfinx + - matplotlib==3.7.1 + - pip>=20.1 + - sphinx<8 # sphinxcontrib-images is not compatible with sphinx 8 + - folium + - numpy==1.24 + - tqdm + - scifem>=0.2.8 + - sphinx-design + - sphinxcontrib-bibtex + - sphinxcontrib-images + - sympy + - sphinx-book-theme + - sphinx-copybutton + - pillow diff --git a/docs/source/Makefile b/docs/source/Makefile index 73a28c713..d4bb2cbb9 100644 --- a/docs/source/Makefile +++ b/docs/source/Makefile @@ -1,20 +1,20 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css new file mode 100644 index 000000000..ba64e9e20 --- /dev/null +++ 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; +} \ No newline at end of file diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 2d6fef3c5..de9ae47fa 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -1,6 +1,10 @@ FESTIM API ========== +.. warning:: + + 🔨 This page is under construction. 🔨 + .. automodule:: festim.boundary_conditions :members: diff --git a/docs/source/bibliography/references.bib b/docs/source/bibliography/references.bib new file mode 100644 index 000000000..79eb74285 --- /dev/null +++ b/docs/source/bibliography/references.bib @@ -0,0 +1,111 @@ +@article{McNabb1963, + title = {{A New Analysis of the Diffusion of Hydrogen in Iron and Ferritic Steels}}, + author = {McNabb, A. and Foster, P. K.}, + year = 1963, + journal = {Trans. Metall. Soc. AIME}, + volume = 227, + pages = 618 +} +@article{Longhurst1985, + title = {{The soret effect and its implications for fusion reactors}}, + author = {Longhurst, G. R.}, + year = 1985, + journal = {J. Nucl. Mater.}, + volume = 131, + number = 1, + pages = {61--69}, + issn = {00223115}, + url = {https://linkinghub.elsevier.com/retrieve/pii/0022311585904258} +} +@techreport{Pendergrass1976, + title = {{Temperature-dependent ordinary and thermal diffusion of hydrogen isotopes through thermonuclear reactor components}}, + author = {Pendergrass, J. H.}, + year = 1976, + url = {http://www.osti.gov/servlets/purl/7333557/}, + institution = {Los Alamos National Laboratory (LANL)} +} +@article{Delaporte-Mathurin2021, + title = {{Influence of interface conditions on hydrogen transport studies}}, + author = {Delaporte-Mathurin, R. and Hodille, E. A. and Mougenot, J. and Charles, Y. and {De Temmerman}, G. and Leblond, F. and Grisolia, C.}, + year = 2021, + journal = {Nucl. Fusion}, + volume = 61, + number = 3, + pages = {036038}, + issn = {0029-5515}, + url = {https://iopscience.iop.org/article/10.1088/1741-4326/abd95f} +} +@phdthesis{Delaporte-Mathurin2022, + title = {{Hydrogen transport in tokamaks : Estimation of the ITER divertor tritium inventory and influence of helium exposure}}, + author = {Delaporte-Mathurin, R.}, + year = 2022, + number = {2022PA131054}, + url = {https://theses.hal.science/tel-04004369}, + school = {{Universit{\'e} Paris-Nord - Paris XIII}}, + keywords = {Hydrogen ; Finite elements ; Numerical modelling ; Hydrog{\`e}ne ; El{\'e}ments finis ; Mod{\'e}lisation num{\'e}rique}, + type = {Theses} +} +@article{Schmid2016, + title = {{Diffusion-trapping modelling of hydrogen recycling in tungsten under ELM-like heat loads}}, + author = {Schmid, K.}, + year = 2016, + journal = {Phys. Scr.}, + volume = {T167}, + pages = {014025}, + issn = {0031-8949}, + url = {https://iopscience.iop.org/article/10.1088/0031-8949/T167/1/014025} +} +@article{Guterl2019, + title = {Effects of surface processes on hydrogen outgassing from metal in desorption experiments}, + author = {Guterl, Jerome and Smirnov, RD and Snyder, P}, + year = 2019, + journal = {Nuclear Fusion}, + publisher = {IOP Publishing}, + volume = 59, + number = 9, + pages = {096042}, + url = {https://iopscience.iop.org/article/10.1088/1741-4326/ab280a/meta} +} +@article{Pick1985, + title = {A model for atomic hydrogen-metal interactions—application to recycling, recombination and permeation}, + author = {Pick, MA and Sonnenberg, K}, + year = 1985, + journal = {Journal of Nuclear Materials}, + publisher = {Elsevier}, + volume = 131, + number = {2-3}, + pages = {208--220}, + url = {https://www.sciencedirect.com/science/article/abs/pii/0022311585904593} +} +@article{Hodille2017, + title = {Simulations of atomic deuterium exposure in self-damaged tungsten}, + author = {Hodille, EA and Zalo{\v{z}}nik, A and Markelj, S and Schwarz-Selinger, T and Becquart, CS and Bisson, R{\'e}gis and Grisolia, Christian}, + year = 2017, + journal = {Nuclear Fusion}, + publisher = {IOP Publishing}, + volume = 57, + number = 5, + pages = {056002}, + url = {https://iopscience.iop.org/article/10.1088/1741-4326/aa5aa5/meta} +} +@article{Schmid2021, + title = {On the use of recombination rate coefficients in hydrogen transport calculations}, + author = {Schmid, K and Zibrov, M}, + year = 2021, + journal = {Nuclear Fusion}, + publisher = {IOP Publishing}, + volume = 61, + number = 8, + pages = {086008}, + url = {https://iopscience.iop.org/article/10.1088/1741-4326/ac07b2/meta} +} +@article{Hamamoto2020, + title = {Comprehensive modeling of hydrogen transport and accumulation in titanium and zirconium}, + author = {Hamamoto, Yoshiki and Uchikoshi, Takeru and Tanabe, Katsuaki}, + year = 2020, + journal = {Nuclear Materials and Energy}, + publisher = {Elsevier}, + volume = 23, + pages = 100751, + url = {https://www.sciencedirect.com/science/article/pii/S2352179120300272} +} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 9d852f2bd..6fe9fee93 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,15 +12,33 @@ import os import sys -sys.path.insert(0, os.path.abspath("../..")) +sys.path.insert(0, os.path.abspath("../../src")) + + +# Generate the map + +# Add the directory containing your Python script to the Python path +sys.path.insert(0, os.path.abspath(".")) + +import map + +m = map.generate_map() +current_dir = os.path.dirname(__file__) +html_path = os.path.join(current_dir, "_static", "map.html") + +# create _static directory if it doesn't exist +os.makedirs(os.path.dirname(html_path), exist_ok=True) + +m.save(html_path) # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "FESTIM" -copyright = "2022, Remi Delaporte-Mathurin" -author = "Remi Delaporte-Mathurin" -release = "v0.10.2" +copyright = "2022-2023, FESTIM contributors" +author = "FESTIM-dev" +release = "1.0.0" +version = "1.0" # -- General configuration --------------------------------------------------- @@ -37,10 +55,17 @@ "sphinx.ext.coverage", "sphinx.ext.napoleon", "sphinx.ext.viewcode", + "sphinx_copybutton", "sphinx_design", + "sphinxcontrib.bibtex", "matplotlib.sphinxext.plot_directive", + "sphinxcontrib.images", ] +suppress_warnings = ["autosectionlabel.*"] + +napoleon_use_ivar = True # needed to correctly format class attributes + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -62,6 +87,9 @@ # shorten module names in readme add_module_names = False +# bibliography file +bibtex_bibfiles = ["bibliography/references.bib"] + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -72,11 +100,41 @@ html_css_files = ["style.css"] html_theme_options = { - "repository_url": "https://github.com/RemDelaporteMathurin/FESTIM", + "repository_url": "https://github.com/festim-dev/FESTIM", "use_repository_button": True, "use_edit_page_button": True, "repository_branch": "main", "path_to_docs": "./docs/source", + "icon_links": [ + { + "name": "PyPI", + "url": "https://pypi.org/project/FESTIM/", + "icon": "https://img.shields.io/pypi/dw/festim", + "type": "url", + }, + { + "name": "Support Forum", + "url": "https://festim.discourse.group/", + "icon": "fa-brands fa-discourse", + }, + { + "name": "Slack", + "url": "https://join.slack.com/t/festim-dev/shared_invite/zt-246hw8d6o-htWASLsbdosUo_2nRKCf9g", + "icon": "fa-brands fa-slack", + }, + ], + "article_header_end": [ + "navbar-icon-links", + "article-header-buttons", + ], +} + +html_sidebars = { + "**": [ + "navbar-logo", + "search-button-field", + "sbt-sidebar-nav", + ], } -html_title = "FESTIM" +html_title = "FESTIM Documentation" diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index 734ceea43..755a37303 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -22,61 +22,106 @@ And/or contribute to the source code by: * Fixing bugs * Implementing new features -.. _contributing to the code: - ------------------------ Contributing to the code ------------------------ -.. admonition:: Tip - :class: tip +For complete information on contributions with GitHub see this guide on `GitHub `_. + +.. tip:: + + If you're a beginner, look for `issues tagged with "Good first issue" `_. + + These issues are usually relatively easy to tackle and perfect for newcomers. + +#. `Fork the repository `_ + + 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 `_. + + 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. - If you're a beginner, look for `issues tagged with "Good first issue" `_. +#. Optional: Build the documentation - These issues are usually fairly easy to tackle and therefore perfect for newcomers. + 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. -1) `Fork the repository `_ +#. `Open a PR `_ -By forking the repository, you create a copy of it where you can safely make changes. +#. Wait for a :ref:`maintainer` to review your PR -2) Make your changes -3) `Open a PR `_ -4) Wait for a maintainer 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. -Before merging your changes, they have to be reviewed. During the review, we make sure the changes don't break anything 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! -5) When everything is in order, the maintainers will merge your PR! +----------- +Maintainers +----------- + +The maintainers are the people who have the right to merge PRs to the repository. +They consist of the following individuals: + +- Remi Delaporte-Mathurin (`@RemDelaporteMathurin `_) +- James Dark (`@jhdark `_) +- Vladimir Kulagin (`@KulaginVladimir `_) + +The project lead is Remi Delaporte-Mathurin. ---------- Test suite ---------- -FESTIM uses continuous integration (CI) to ensure code quality and eliminate as much bugs as possible. +FESTIM uses continuous integration (CI) to ensure code quality and eliminate as many bugs as possible. In a nutshell, every time a change is pushed to the repository (or to a PR), a suite of tests is automatically triggered. This is to make sure the changes don't break existing functionalities. It is also very useful to catch bugs that developers could have missed. Click `here `_ for more information on CI. -All the tests can be found in the `test folder `_ at the root of the FESTIM repository. +All the tests can be found in the `test folder `_ at the root of the FESTIM repository. + +You need to have the right dependencies installed to test your code (see :ref:`installation`). + +.. note:: -.. admonition:: Tip - :class: tip + Make sure to install ``pytest`` to run the test suite locally: - If you have installed the FEniCS Anaconda python package, make sure to install pytest to run the test suite locally: + .. code-block:: bash pip install pytest And then run the tests using: + .. code-block:: bash + pytest test/ - Although if you are running the Docker image, pytest packages are prebuilt, thus use the command: - - pytest-3 test/ - - Whenever contributors open a PR, **the tests must pass** in order for the PR to be merged in. In some cases, new tests need to be written to account for more use cases or to catch bugs that weren't previously caught. @@ -87,7 +132,7 @@ Debugging When you find a bug in the code, there are several steps to follow to make things easier for maintainers. -#. | `Raise an issue `_ +#. | `Raise an issue `_ | | This is important to keep track of things. | The issue is a place to talk about the bug, troubleshoot users and sometimes find workarounds. @@ -104,13 +149,116 @@ When you find a bug in the code, there are several steps to follow to make thing Implementing a new feature -------------------------- -#. | `Raise an issue `_ +#. | `Raise an issue `_ | | Before spending time implementing a new great feature, it is better to open an issue first to discuss with the maintainers. | For all you know, someone is already working at implementing it and all your time would be spent for nothing. | | It is also beneficial to discuss with the community on how this new feature would be used. -#. :ref:`Make your changes` +#. :ref:`Make your changes`. Don't forget to :ref:`adapt the documentation ` if necessary. #. Write a test to test your 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 `_. 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 `_ +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 +------------------- + +The documentation is a crucial part of the project. It is the first thing users will see when they want to use FESTIM. +It is important to keep it up to date and clear. + +The documentation is written in `reStructuredText `_ and is located in the `docs folder `_ at the root of the FESTIM repository. + +The documentation is built using `Sphinx `_. + +To build the documentation locally, you can use the following command: + +.. code-block:: bash + + cd docs/source + make html + +This will generate the documentation in the `docs/source/_build/html` folder. +You can then open the `index.html` file in your browser to see the documentation. +To remove everything and start from scratch, you can use the following command: + +.. code-block:: bash + + make clean + +Alternatively, you can use the following command to build the documentation in one line: + +.. code-block:: bash + + cd docs + sphinx-build -b html source build + +.. note:: + + Make sure to have the right dependencies installed. You can create a new conda environment with the following command: + + .. code-block:: bash + + conda env create -f docs/environment.yml + + This will create a new environment called `festim2-docs` with all the necessary dependencies. + Activate it using: + + .. code-block:: bash + + conda activate festim2-docs + +The documentation is hosted on `Read the Docs `_ and is automatically updated when a new commit is pushed to the repository or to a Pull Request. + +.. note:: + + The documentation is built using the `sphinx_book_theme `_ theme. + +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 \ No newline at end of file diff --git a/docs/source/environment.yaml b/docs/source/environment.yaml deleted file mode 100644 index 6f2800bc7..000000000 --- a/docs/source/environment.yaml +++ /dev/null @@ -1,12 +0,0 @@ -name: fenics -channels: - - conda-forge -dependencies: - - fenics-dolfinx==0.9.0 - - pip>=20.1 - - matplotlib==3.7.1 - - scifem - - pip: - - sphinx_book_theme==1.0.1 - - sphinx==6.2.1 - - sphinx-design==0.4.1 diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 13bc531a5..5c9cacaf1 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -1,4 +1,6 @@ Examples ******** -You can find examples and tutorials on the `FESTIM workshop `_. +.. warning:: + + 🔨 This page is under construction. 🔨 diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst deleted file mode 100644 index fb57bcf48..000000000 --- a/docs/source/getting_started.rst +++ /dev/null @@ -1,46 +0,0 @@ -=============== -Getting started -=============== - -Install -******* - -Installing FEniCS ------------------ - -FESTIM requires FEniCS to run. - -FEniCS can be installed with Anaconda on MacOs and Linux. -In order to use the Anaconda distribution on Windows, use the `Windows Subsystem for Linux `_. -First `install Anaconda `_ then run the following commands:: - - conda create -n festim-env - conda activate festim-env - conda install mamba - mamba install -c conda-forge fenics - -Alternatively, It can be installed using `Docker `_:: - - docker run -ti -v $(pwd):/home/fenics/shared quay.io/fenicsproject/stable:latest - -.. note:: - :code:`$(pwd)` needs to be replaced by :code:`${PWD}` on Windows - - -For more information on how to install FEniCS, see `Download `_ on the FEniCS website. - - -Installing FESTIM ------------------ - -FESTIM can then be installed using pip:: - - pip install FESTIM - -Specific versions of FESTIM can be installed with:: - - pip install FESTIM==[version] - -with the desired version tag. For example:: - - pip install FESTIM==0.9 diff --git a/docs/source/images/gmsh_tut_1.png b/docs/source/images/gmsh_tut_1.png new file mode 100644 index 000000000..b6911f6da Binary files /dev/null and b/docs/source/images/gmsh_tut_1.png differ diff --git a/docs/source/images/gmsh_tut_2.png b/docs/source/images/gmsh_tut_2.png new file mode 100644 index 000000000..0d31ab2ce Binary files /dev/null and b/docs/source/images/gmsh_tut_2.png differ diff --git a/docs/source/images/gmsh_tut_3.png b/docs/source/images/gmsh_tut_3.png new file mode 100644 index 000000000..ecd0a1320 Binary files /dev/null and b/docs/source/images/gmsh_tut_3.png differ diff --git a/docs/source/images/gmsh_tut_4.png b/docs/source/images/gmsh_tut_4.png new file mode 100644 index 000000000..f76841413 Binary files /dev/null and b/docs/source/images/gmsh_tut_4.png differ diff --git a/docs/source/images/gmsh_tut_5.png b/docs/source/images/gmsh_tut_5.png new file mode 100644 index 000000000..6ee334035 Binary files /dev/null and b/docs/source/images/gmsh_tut_5.png differ diff --git a/docs/source/images/icons/book-2-svgrepo-com.svg b/docs/source/images/icons/book-2-svgrepo-com.svg new file mode 100644 index 000000000..b24aa3976 --- /dev/null +++ b/docs/source/images/icons/book-2-svgrepo-com.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/source/images/icons/check-square-svgrepo-com.svg b/docs/source/images/icons/check-square-svgrepo-com.svg new file mode 100644 index 000000000..fbdfb91c6 --- /dev/null +++ b/docs/source/images/icons/check-square-svgrepo-com.svg @@ -0,0 +1,5 @@ + + + + + \ No newline at end of file diff --git a/docs/source/images/icons/clapperboard-play-svgrepo-com.svg b/docs/source/images/icons/clapperboard-play-svgrepo-com.svg new file mode 100644 index 000000000..3d68ad02d --- /dev/null +++ b/docs/source/images/icons/clapperboard-play-svgrepo-com.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/source/images/icons/code-square-svgrepo-com.svg b/docs/source/images/icons/code-square-svgrepo-com.svg new file mode 100644 index 000000000..142d36bf7 --- /dev/null +++ b/docs/source/images/icons/code-square-svgrepo-com.svg @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/docs/source/images/icons/keyboard-svgrepo-com.svg b/docs/source/images/icons/keyboard-svgrepo-com.svg new file mode 100644 index 000000000..027f70f42 --- /dev/null +++ b/docs/source/images/icons/keyboard-svgrepo-com.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/source/images/icons/running-2-svgrepo-com.svg b/docs/source/images/icons/running-2-svgrepo-com.svg new file mode 100644 index 000000000..f0699589a --- /dev/null +++ b/docs/source/images/icons/running-2-svgrepo-com.svg @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/docs/source/images/paraview_guide_1.png b/docs/source/images/paraview_guide_1.png new file mode 100644 index 000000000..a0cfb9a00 Binary files /dev/null and b/docs/source/images/paraview_guide_1.png differ diff --git a/docs/source/images/paraview_guide_2.png b/docs/source/images/paraview_guide_2.png new file mode 100644 index 000000000..148440ac4 Binary files /dev/null and b/docs/source/images/paraview_guide_2.png differ diff --git a/docs/source/images/potential_diagram.png b/docs/source/images/potential_diagram.png new file mode 100644 index 000000000..6033ce03e Binary files /dev/null and b/docs/source/images/potential_diagram.png differ diff --git a/docs/source/images/recomb_sketch.png b/docs/source/images/recomb_sketch.png new file mode 100644 index 000000000..3b3469316 Binary files /dev/null and b/docs/source/images/recomb_sketch.png differ diff --git a/docs/source/images/salome_guide_1.png b/docs/source/images/salome_guide_1.png new file mode 100644 index 000000000..4085cec99 Binary files /dev/null and b/docs/source/images/salome_guide_1.png differ diff --git a/docs/source/images/salome_guide_10.png b/docs/source/images/salome_guide_10.png new file mode 100644 index 000000000..8dcf61c19 Binary files /dev/null and b/docs/source/images/salome_guide_10.png differ diff --git a/docs/source/images/salome_guide_11.png b/docs/source/images/salome_guide_11.png new file mode 100644 index 000000000..0ec9ef87a Binary files /dev/null and b/docs/source/images/salome_guide_11.png differ diff --git a/docs/source/images/salome_guide_12.png b/docs/source/images/salome_guide_12.png new file mode 100644 index 000000000..9f45f4293 Binary files /dev/null and b/docs/source/images/salome_guide_12.png differ diff --git a/docs/source/images/salome_guide_13.png b/docs/source/images/salome_guide_13.png new file mode 100644 index 000000000..6e9372dbb Binary files /dev/null and b/docs/source/images/salome_guide_13.png differ diff --git a/docs/source/images/salome_guide_14.png b/docs/source/images/salome_guide_14.png new file mode 100644 index 000000000..478dea365 Binary files /dev/null and b/docs/source/images/salome_guide_14.png differ diff --git a/docs/source/images/salome_guide_2.png b/docs/source/images/salome_guide_2.png new file mode 100644 index 000000000..278798623 Binary files /dev/null and b/docs/source/images/salome_guide_2.png differ diff --git a/docs/source/images/salome_guide_3.png b/docs/source/images/salome_guide_3.png new file mode 100644 index 000000000..a1dfad426 Binary files /dev/null and b/docs/source/images/salome_guide_3.png differ diff --git a/docs/source/images/salome_guide_4.png b/docs/source/images/salome_guide_4.png new file mode 100644 index 000000000..13aeb52c5 Binary files /dev/null and b/docs/source/images/salome_guide_4.png differ diff --git a/docs/source/images/salome_guide_5.png b/docs/source/images/salome_guide_5.png new file mode 100644 index 000000000..43bb25303 Binary files /dev/null and b/docs/source/images/salome_guide_5.png differ diff --git a/docs/source/images/salome_guide_6.png b/docs/source/images/salome_guide_6.png new file mode 100644 index 000000000..557f6b3bd Binary files /dev/null and b/docs/source/images/salome_guide_6.png differ diff --git a/docs/source/images/salome_guide_7.png b/docs/source/images/salome_guide_7.png new file mode 100644 index 000000000..922d8bb1c Binary files /dev/null and b/docs/source/images/salome_guide_7.png differ diff --git a/docs/source/images/salome_guide_8.png b/docs/source/images/salome_guide_8.png new file mode 100644 index 000000000..8b1afffc4 Binary files /dev/null and b/docs/source/images/salome_guide_8.png differ diff --git a/docs/source/images/salome_guide_9.png b/docs/source/images/salome_guide_9.png new file mode 100644 index 000000000..26e951981 Binary files /dev/null and b/docs/source/images/salome_guide_9.png differ diff --git a/docs/source/images/salome_guide_cad_1.png b/docs/source/images/salome_guide_cad_1.png new file mode 100644 index 000000000..ec5d153ed Binary files /dev/null and b/docs/source/images/salome_guide_cad_1.png differ diff --git a/docs/source/images/salome_guide_cad_2.png b/docs/source/images/salome_guide_cad_2.png new file mode 100644 index 000000000..80bea5ad4 Binary files /dev/null and b/docs/source/images/salome_guide_cad_2.png differ diff --git a/docs/source/images/salome_guide_cad_3.png b/docs/source/images/salome_guide_cad_3.png new file mode 100644 index 000000000..70bd36533 Binary files /dev/null and b/docs/source/images/salome_guide_cad_3.png differ diff --git a/docs/source/images/user_logos/Beihang_University.png b/docs/source/images/user_logos/Beihang_University.png new file mode 100644 index 000000000..e2d81600a Binary files /dev/null and b/docs/source/images/user_logos/Beihang_University.png differ 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 new file mode 100644 index 000000000..f97ff9cd8 Binary files /dev/null and b/docs/source/images/user_logos/Commonwealth_Fusion_Systems Devens_MA_USA.png differ diff --git a/docs/source/images/user_logos/Cranfield_University_UK.png b/docs/source/images/user_logos/Cranfield_University_UK.png new file mode 100644 index 000000000..11b2e3577 Binary files /dev/null and b/docs/source/images/user_logos/Cranfield_University_UK.png differ diff --git a/docs/source/images/user_logos/ENEA.png b/docs/source/images/user_logos/ENEA.png new file mode 100644 index 000000000..5a4f178b0 Binary files /dev/null and b/docs/source/images/user_logos/ENEA.png differ diff --git a/docs/source/images/user_logos/ENI.png b/docs/source/images/user_logos/ENI.png new file mode 100644 index 000000000..8f037eb12 Binary files /dev/null and b/docs/source/images/user_logos/ENI.png differ diff --git a/docs/source/images/user_logos/Frazer_Nash.png b/docs/source/images/user_logos/Frazer_Nash.png new file mode 100644 index 000000000..449e6da6b Binary files /dev/null and b/docs/source/images/user_logos/Frazer_Nash.png differ diff --git a/docs/source/images/user_logos/IRFM_cadarache_France.png b/docs/source/images/user_logos/IRFM_cadarache_France.png new file mode 100644 index 000000000..d6ed14df5 Binary files /dev/null and b/docs/source/images/user_logos/IRFM_cadarache_France.png differ diff --git a/docs/source/images/user_logos/ITER_organization_France.png b/docs/source/images/user_logos/ITER_organization_France.png new file mode 100644 index 000000000..e0f95adb4 Binary files /dev/null and b/docs/source/images/user_logos/ITER_organization_France.png differ diff --git "a/docs/source/images/user_logos/Institut_Jo\305\276ef_Stefan.png" "b/docs/source/images/user_logos/Institut_Jo\305\276ef_Stefan.png" new file mode 100644 index 000000000..d0565a12e Binary files /dev/null and "b/docs/source/images/user_logos/Institut_Jo\305\276ef_Stefan.png" differ diff --git a/docs/source/images/user_logos/Institute_of_plasma_physics_Chinese_academy_of_sciences.png b/docs/source/images/user_logos/Institute_of_plasma_physics_Chinese_academy_of_sciences.png new file mode 100644 index 000000000..2e71c599c Binary files /dev/null and b/docs/source/images/user_logos/Institute_of_plasma_physics_Chinese_academy_of_sciences.png differ diff --git a/docs/source/images/user_logos/Kyoto_Fusioneering.png b/docs/source/images/user_logos/Kyoto_Fusioneering.png new file mode 100644 index 000000000..f10af646d Binary files /dev/null and b/docs/source/images/user_logos/Kyoto_Fusioneering.png differ diff --git a/docs/source/images/user_logos/LSPM_Villetaneuse_France.png b/docs/source/images/user_logos/LSPM_Villetaneuse_France.png new file mode 100644 index 000000000..04191b8e8 Binary files /dev/null and b/docs/source/images/user_logos/LSPM_Villetaneuse_France.png differ 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 new file mode 100644 index 000000000..5b7481536 Binary files /dev/null and b/docs/source/images/user_logos/Logo_of_University_of_Tsukuba.png differ diff --git a/docs/source/images/user_logos/MEPhI_moscow_Russia.png b/docs/source/images/user_logos/MEPhI_moscow_Russia.png new file mode 100644 index 000000000..e840e3867 Binary files /dev/null and b/docs/source/images/user_logos/MEPhI_moscow_Russia.png differ diff --git a/docs/source/images/user_logos/MIT_Cambridge_MA_USA.png b/docs/source/images/user_logos/MIT_Cambridge_MA_USA.png new file mode 100644 index 000000000..4bb975269 Binary files /dev/null and b/docs/source/images/user_logos/MIT_Cambridge_MA_USA.png differ diff --git a/docs/source/images/user_logos/Marathon_Fusion_USA.png b/docs/source/images/user_logos/Marathon_Fusion_USA.png new file mode 100644 index 000000000..836701951 Binary files /dev/null and b/docs/source/images/user_logos/Marathon_Fusion_USA.png differ diff --git a/docs/source/images/user_logos/Oak_Ridge_National_Laboratory.png b/docs/source/images/user_logos/Oak_Ridge_National_Laboratory.png new file mode 100644 index 000000000..17657a2ff Binary files /dev/null and b/docs/source/images/user_logos/Oak_Ridge_National_Laboratory.png differ diff --git a/docs/source/images/user_logos/Politecnico_di_Torino.png b/docs/source/images/user_logos/Politecnico_di_Torino.png new file mode 100644 index 000000000..68a94666d Binary files /dev/null and b/docs/source/images/user_logos/Politecnico_di_Torino.png differ diff --git a/docs/source/images/user_logos/Thea_Energy_USA.png b/docs/source/images/user_logos/Thea_Energy_USA.png new file mode 100644 index 000000000..b95242b4a Binary files /dev/null and b/docs/source/images/user_logos/Thea_Energy_USA.png differ diff --git a/docs/source/images/user_logos/UKAEA_UK.png b/docs/source/images/user_logos/UKAEA_UK.png new file mode 100644 index 000000000..c89479cc3 Binary files /dev/null and b/docs/source/images/user_logos/UKAEA_UK.png differ diff --git a/docs/source/images/user_logos/University_San_Diego.png b/docs/source/images/user_logos/University_San_Diego.png new file mode 100644 index 000000000..3ae9aada3 Binary files /dev/null and b/docs/source/images/user_logos/University_San_Diego.png differ diff --git a/docs/source/images/user_logos/University_Wisconsin_Madison_USA.png b/docs/source/images/user_logos/University_Wisconsin_Madison_USA.png new file mode 100644 index 000000000..1ab19fcca Binary files /dev/null and b/docs/source/images/user_logos/University_Wisconsin_Madison_USA.png differ diff --git a/docs/source/images/user_logos/University_of_Surrey.png b/docs/source/images/user_logos/University_of_Surrey.png new file mode 100644 index 000000000..04a5b10b5 Binary files /dev/null and b/docs/source/images/user_logos/University_of_Surrey.png differ diff --git a/docs/source/images/user_logos/University_of_Tsukuba.png b/docs/source/images/user_logos/University_of_Tsukuba.png new file mode 100644 index 000000000..a4664b90a Binary files /dev/null and b/docs/source/images/user_logos/University_of_Tsukuba.png differ diff --git a/docs/source/images/user_logos/Zap_Energy.png b/docs/source/images/user_logos/Zap_Energy.png new file mode 100644 index 000000000..7daa09ae6 Binary files /dev/null and b/docs/source/images/user_logos/Zap_Energy.png differ diff --git a/docs/source/images/user_logos/digiLab_UK.png b/docs/source/images/user_logos/digiLab_UK.png new file mode 100644 index 000000000..334d8188d Binary files /dev/null and b/docs/source/images/user_logos/digiLab_UK.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 7a103b06f..61dd86309 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,8 +1,3 @@ -.. FESTIM documentation master file, created by - sphinx-quickstart on Thu Jul 28 11:09:03 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - FESTIM ====== @@ -11,15 +6,73 @@ 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/index + :link-type: doc + FESTIM was originally developed at the `Institute for Magnetic Fusion Research (IRFM) `_ and the `Process and Materials Sciences Laboratory (LSPM) `_. +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 `_. .. admonition:: Recommended publication for citing :class: tip - Rémi Delaporte-Mathurin, Etienne A. Hodille, Jonathan Mougenot, Yann Charles, and Christian Grisolia. - "`Finite Element Analysis of Hydrogen Retention in ITER Plasma Facing Components Using FESTIM. - Nuclear Materials and Energy 21 (2019): 100709. `_", + Rémi Delaporte-Mathurin, James Dark, Gabriele Ferrero, Etienne A. Hodille, Vladimir Kulagin, Samuele Meschini, + "`FESTIM: An open-source code for hydrogen transport simulations. + International Journal of Hydrogen Energy 63 (2024): 786-802. `_", + +Map of FESTIM users +------------------- + +.. raw:: html + + + + +.. admonition:: Add your institution + + If you would like your institution to be added to this map, please `open an issue `_. + -------- Contents @@ -28,18 +81,10 @@ Contents .. toctree:: :maxdepth: 1 - getting_started + installation examples theory userguide/index devguide/index - publications api/index - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + publications \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 000000000..0c913fb5c --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,50 @@ +============ +Installation +============ + +FESTIM is installed in two steps: + 1. `Installing FEniCSx`_ through Anaconda or Docker + 2. `Installing FESTIM`_ through pip in the FEniCS environment + +Installing FEniCSx +----------------- + +FEniCSx can be installed with Anaconda on MacOs and Linux. +In order to use the Anaconda distribution on Windows, +use the `Windows Subsystem for Linux `_. + +.. tip:: + You can install `WSL `_ by running + :code:`wsl --install` on a command prompt window. + To launch into WSL, simply enter :code:`wsl`. + + `Visual Studio Code `_ is the recommended IDE to + use with Windows due to the + `WSL extension `_. + +First `install Anaconda `_, + +.. tip:: + + You can install Anaconda on most Linux distributions by entering:: + + curl -O https://repo.anaconda.com/archive/Anaconda3-2024.06-1-Linux-x86_64.sh + bash ./Anaconda3-2024.06-1-Linux-x86_64.sh + + You can install other versions by replacing :code:`Anaconda3-2024.06-1-Linux-x86_64.sh` + with another from `the official repository `_. + +then run the following commands:: + + conda create -n festim-env + conda activate festim-env + conda install -c conda-forge fenics-dolfinx tqdm + + +Installing FESTIM +----------------- + +This version of FESTIM is under development and is not yet available on PyPI. +FESTIM can then be installed using pip:: + + pip install git+https://github.com/FESTIM-dev/FESTIM@fenicsx diff --git a/docs/source/map.json b/docs/source/map.json new file mode 100644 index 000000000..d6e7ed232 --- /dev/null +++ b/docs/source/map.json @@ -0,0 +1,355 @@ +{ + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -84.3101, + 35.9312 + ] + }, + "properties": { + "name": "Oak Ridge National Laboratory", + "path": "images/user_logos/Oak_Ridge_National_Laboratory.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 5.7843, + 43.7254 + ] + }, + "properties": { + "name": "IRFM cadarache France", + "path": "images/user_logos/IRFM_cadarache_France.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 2.3458, + 48.9583 + ] + }, + "properties": { + "name": "LSPM Villetaneuse France", + "path": "images/user_logos/LSPM_Villetaneuse_France.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -71.0921, + 42.3601 + ] + }, + "properties": { + "name": "MIT Cambridge, MA USA", + "path": "images/user_logos/MIT_Cambridge_MA_USA.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -74.6596903, + 40.35006468849364 + ] + }, + "properties": { + "name": "Thea Energy USA", + "path": "images/user_logos/Thea_Energy_USA.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -71.6152, + 42.5406 + ] + }, + "properties": { + "name": "Commonwealth Fusion Systems Devens, MA USA", + "path": "images/user_logos/Commonwealth_Fusion_Systems Devens_MA_USA.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -89.4012, + 43.0761 + ] + }, + "properties": { + "name": "University Wisconsin Madison USA", + "path": "images/user_logos/University_Wisconsin_Madison_USA.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -122.41135340346865, + 37.77479335835942 + ] + }, + "properties": { + "name": "Marathon Fusion USA", + "path": "images/user_logos/Marathon_Fusion_USA.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -117.1611, + 32.7157 + ] + }, + "properties": { + "name": "University San Diego", + "path": "images/user_logos/University_San_Diego.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 37.6649462235042, + 55.66362336404334 + ] + }, + "properties": { + "name": "MEPhI moscow Russia", + "path": "images/user_logos/MEPhI_moscow_Russia.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 5.0266, + 43.5455 + ] + }, + "properties": { + "name": "ITER organization France", + "path": "images/user_logos/ITER_organization_France.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -1.229138717146069, + 51.65868576158049 + ] + }, + "properties": { + "name": "UKAEA UK", + "path": "images/user_logos/UKAEA_UK.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -3.530686738097156, + 50.719235968686455 + ] + }, + "properties": { + "name": "digiLab UK", + "path": "images/user_logos/digiLab_UK.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -0.4269, + 52.0720 + ] + }, + "properties": { + "name": "Cranfield University UK", + "path": "images/user_logos/Cranfield_University_UK.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 7.6818, + 45.0703 + ] + }, + "properties": { + "name": "Politecnico di Torino", + "path": "images/user_logos/Politecnico_di_Torino.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 116.3056, + 39.9923 + ] + }, + "properties": { + "name": "Beihang University", + "path": "images/user_logos/Beihang_University.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 117.2703, + 31.8669 + ] + }, + "properties": { + "name": "Institute of Plasma Physics, Chinese Academy of Sciences", + "path": "images/user_logos/Institute_of_plasma_physics_Chinese_academy_of_sciences.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 14.487728061376515, + 46.043586411058726 + ] + }, + "properties": { + "name": "Institut Jožef Stefan", + "path": "images/user_logos/Institut_Jožef_Stefan.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 139.76446527724698, + 35.68673663876397 + ] + }, + "properties": { + "name": "Kyoto Fusioneering", + "path": "images/user_logos/Kyoto_Fusioneering.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 12.455144726473035, + 41.818823289415484 + ] + }, + "properties": { + "name": "ENI", + "path": "images/user_logos/ENI.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 12.670768074076161, + 41.83511773016589 + ] + }, + "properties": { + "name": "ENEA", + "path": "images/user_logos/ENEA.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -122.2637636728507, + 47.94311816450899 + ] + }, + "properties": { + "name": "Zap Energy", + "path": "images/user_logos/Zap_Energy.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -0.3409612613765139, + 51.305321198230246 + ] + }, + "properties": { + "name": "Frazer Nash", + "path": "images/user_logos/Frazer_Nash.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + -0.5894234846558715, + 51.243827970913635 + ] + }, + "properties": { + "name": "University of Surrey", + "path": "images/user_logos/University_of_Surrey.png" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [ + 140.10389, + 36.11139 + ] + }, + "properties": { + "name": "University of Tsukuba", + "path": "images/user_logos/Logo_of_University_of_Tsukuba.png" + } + } + ] +} \ No newline at end of file diff --git a/docs/source/map.py b/docs/source/map.py new file mode 100644 index 000000000..998f45adb --- /dev/null +++ b/docs/source/map.py @@ -0,0 +1,62 @@ +import json +from folium.plugins import MarkerCluster +import folium + +import requests +from PIL import Image +from io import BytesIO + +LOGO_HEIGHT = 60 + + +def generate_map(clustered=True, draggable=False): + # Load GeoJSON data + with open("map.json") as f: + data = json.load(f) + + # Create a map centered on a specific location + m = folium.Map( + location=[42.256349987281666, -37.61204625889672], + zoom_start=3, + tiles="cartodbpositron", + ) + if clustered: + marker_cluster = MarkerCluster().add_to(m) + # Iterate over features in the GeoJSON data + for feature in data["features"]: + name = feature["properties"]["name"] + print(name) + coordinates = feature["geometry"]["coordinates"] + + # Get the dimensions of the image from local images + + if "path" in feature["properties"]: + path = feature["properties"]["path"] + image_dimensions = Image.open(path).size + + if image_dimensions: + height_to_width_ratio = image_dimensions[1] / image_dimensions[0] + image_dimensions = (LOGO_HEIGHT, int(LOGO_HEIGHT * height_to_width_ratio)) + else: + image_dimensions = (LOGO_HEIGHT, LOGO_HEIGHT) + # Create a marker with a custom icon and popup + if coordinates != [0, 0]: + icon = folium.CustomIcon(path, icon_size=image_dimensions) + marker = folium.Marker( + location=[coordinates[1], coordinates[0]], + icon=icon, + draggable=draggable, + ) + if clustered: + marker.add_to(marker_cluster) + else: + marker.add_to(m) + else: + print("no coordinates for", name) + return m + + +if __name__ == "__main__": + m = generate_map(clustered=False, draggable=True) + m.save("map.html") + print("Map saved to map.html") diff --git a/docs/source/theory.rst b/docs/source/theory.rst index 66cb29c81..98fbe7523 100644 --- a/docs/source/theory.rst +++ b/docs/source/theory.rst @@ -1,8 +1,367 @@ -.. _theory: - ====== Theory ====== +-------------- +Bulk physics +-------------- + +H transport +^^^^^^^^^^^ +The model developed by McNabb & Foster :cite:`McNabb1963` is used to model hydrogen transport in materials in FESTIM. +The principle is to separate mobile hydrogen :math:`c_\mathrm{m}\,[\mathrm{m}^{-3}]` and trapped hydrogen :math:`c_\mathrm{t}\,[\mathrm{m}^{-3}]`. +The diffusion of mobile particles is governed by Fick’s law of diffusion where the hydrogen flux is + +.. math:: + :label: eq_difflux + + J = -D \nabla c_\mathrm{m} + +where :math:`D=D(T)\,[\mathrm{m}^{2}\,\mathrm{s}^{-1}]` is the diffusivity. +Each trap :math:`i` is associated with a trapping and a detrapping rate :math:`k_i\,[\mathrm{m}^{3}\,\mathrm{s}^{-1}]` and :math:`p_i\,[\mathrm{s}^{-1}]`, respectively, as well as a trap density :math:`n_i\,[\mathrm{m}^{-3}]`. + +The temporal evolution of :math:`c_\mathrm{m}` and :math:`c_{\mathrm{t}, i}` are then given by: + +.. math:: + :label: eq_mobile_conc + + \frac {\partial c_\mathrm{m}} { \partial t} = \nabla \cdot (D\nabla c_\mathrm{m}) - \sum_i \frac{\partial c_{\mathrm{t},i}} { \partial t} + \sum_j S_j + +.. math:: + :label: eq_trapped_conc + + \frac {\partial c_{\mathrm{t}, i}} { \partial t} = k_i c_\mathrm{m} (n_i - c_{\mathrm{t},i}) - p_i c_{\mathrm{t},i} + +where :math:`S_j=S_j(x,y,z,t)\,[\mathrm{m}^{-3}\,\mathrm{s}^{-1}]` is a source :math:`j` of mobile hydrogen. In FESTIM, source terms can be space and time dependent. These are used to simulate plasma implantation in materials, tritium generation from neutron interactions, etc. +These equations can be solved in cartesian coordinates but also in cylindrical and spherical coordinates. This is useful, for instance, when simulating hydrogen transport in a pipe or in a pebble. FESTIM can solve steady-state hydrogen transport problems. + +Soret effect +^^^^^^^^^^^^ +FESTIM can include the Soret effect :cite:`Pendergrass1976,Longhurst1985` (also called thermophoresis, temperature-assisted diffusion, or even thermodiffusion) to hydrogen transport. The flux of hydrogen :math:`J` is then written as: + +.. math:: + :label: eq_Soret + + J = -D \nabla c_\mathrm{m} - D\frac{Q^* c_\mathrm{m}}{k_B T^2} \nabla T + +where :math:`Q^*\,[\mathrm{eV}]` is the Soret coefficient (also called heat of transport) and :math:`k_B` is the Boltzmann constant. + +Conservation of chemical potential at interfaces +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Continuity of local partial pressure :math:`P\,[\mathrm{Pa}]` at interfaces between materials has to be ensured. In the case of a material behaving according to Sievert’s law of solubility (metals), the partial pressure is expressed as: + +.. math:: + :label: eq_Sievert + + P = \left(\frac{c_\mathrm{m}}{K_S}\right)^2 + +where :math:`K_S\,[\mathrm{m}^{-3}\,\mathrm{Pa}^{-0.5}]` is the material solubility (or Sivert's constant). + +In the case of a material behaving according to Henry's law of solubility, the partial pressure is expressed as: + +.. math:: + :label: eq_Henry + + P = \frac{c_\mathrm{m}}{K_H} + +where :math:`K_H\,[\mathrm{m}^{-3}\,\mathrm{Pa}^{-1}]` is the material solubility (or Henry's constant). + +Two different interface cases can then occur. At the interface between two Sievert or two Henry materials, the continuity of partial pressure yields: + +.. math:: + :label: eq_continuity + + \begin{eqnarray} + \frac{c_\mathrm{m}^-}{K_S^-}&=&\frac{c_\mathrm{m}^+}{K_S^+} \\ + &\mathrm{or}& \\ + \frac{c_\mathrm{m}^-}{K_H^-}&=&\frac{c_\mathrm{m}^+}{K_H^+} + \end{eqnarray} + +where exponents :math:`+` and :math:`-` denote both sides of the interface. + +At the interface between a Sievert and a Henry material: + +.. math:: + :label: eq_continuity_HS + + \left(\frac{c_\mathrm{m}^-}{K_S^-}\right)^2 = \frac{c_\mathrm{m}^+}{K_H^+} + +It appears from these equilibrium equations that a difference in solubilities introduces a concentration jump at interfaces. + +In FESTIM, the conservation of chemical potential is obtained by a change of variables :cite:`Delaporte-Mathurin2021`. The variable :math:`\theta\,[\mathrm{Pa}]` is introduced and: + +.. math:: + :label: eq_theta + + \theta = + \begin{cases} + \left(\dfrac{c_\mathrm{m}}{K_S}\right)^2 & \text{in Sievert materials} \\ + \\ + \dfrac{c_\mathrm{m}}{K_H} & \text{in Henry materials} + \end{cases} + +The variable :math:`\theta` is continuous at interfaces. + +Equations :eq:`eq_mobile_conc` and :eq:`eq_trapped_conc` are then rewritten and solved for :math:`\theta`. Note, the boundary conditions are also rewritten. Once solved, the discontinuous :math:`c_\mathrm{m}` field is obtained from :math:`\theta` and the solubilities by solving Equation :eq:`eq_theta` for :math:`c_\mathrm{m}`. + +Arrhenius law +^^^^^^^^^^^^^^ +Many processes involved in hydrogen transport (e.g., diffusion, trapping/detrapping, desorption, etc.) are thermally activated. The coefficients characterising these processes (e.g., diffusivity, trapping/detrapping rates, recombination coefficients, etc.) are usually assumed to be temperature dependent and follow the Arrhenius law. +According to the latter, the rate :math:`k(T)` of a thermally activated process can be expressed as: + +.. math:: + :label: eq_arrhenius_law + + k(T) = k_0 \exp \left[-\frac{E_k}{k_B T} \right] + +where :math:`k_0` is the pre-exponential factor, :math:`E_k\,[\mathrm{eV}]` is the process activation energy, and :math:`T\,[\mathrm{K}]` is the temperature. + +Radioactive decay +^^^^^^^^^^^^^^^^^ + +Radioactive decay can be included in FESTIM. Neglecting other terms (diffusion, trapping...), the temporal evolution of the concentration of a species :math:`c` is governed by: + +.. math:: + :label: eq_radioactive_decay + + \frac{\partial c}{ \partial t} = -\lambda c + +where :math:`\lambda\,[\mathrm{s}^{-1}]` is the decay constant. +In FESTIM it is possible to include radioactive decay in the evolution of the mobile hydrogen concentration and/or the trapped hydrogen concentrations. + +Heat transfer +^^^^^^^^^^^^^^ +To properly account for the temperature-dependent parameters, an accurate representation of the temperature field is often required. FESTIM can solve a heat transfer problem governed by the heat equation: + +.. math:: + :label: eq_heat_transfer + + \rho C_p \frac{\partial T}{\partial t} = \nabla \cdot (\lambda \nabla T) + \sum_i Q_i + +where :math:`T` is the temperature, :math:`C_p\,[\mathrm{J}\,\mathrm{kg}^{-1}\,\mathrm{K}^{-1}]` is the specific heat capacity, :math:`\rho\,[\mathrm{kg}\,\mathrm{m}^{-3}]` is the material's density, +:math:`\lambda\,[\mathrm{W}\,\mathrm{m}^{-1}\,\mathrm{K}^{-1}]` is the thermal conductivity and :math:`Q_i\,[\mathrm{W}\,\mathrm{m}^{-3}]` is a volumetric heat source :math:`i`. As for the hydrogen transport problem, the heat equation can be solved in steady state. In FESTIM, the thermal properties of materials can be arbitrary functions of temperature. + +--------------- +Surface physics +--------------- +To fully pose the hydrogen transport problem and optionally the heat transfer problem, boundary conditions are required. Boundary conditions are separated in three categories: 1) enforcing the value of the solution at a boundary (Dirichlet’s condition) 2) enforcing the value of gradient of the solution (Neumann’s condition) 3) enforcing the value of the gradient as a function of the solution itself (Robin’s condition). + +Dirichlet BC +^^^^^^^^^^^^^ + +In FESTIM, users can fix the mobile hydrogen concentration :math:`c_\mathrm{m}` and the temperature :math:`T` at boundaries :math:`\delta \Omega` (Dirichlet): + +.. math:: + :label: eq_DirichletBC_c + + c_\mathrm{m} = f(x,y,z,t)~\text{on}~\delta\Omega + +.. math:: + :label: eq_DirichletBC_T + + T = f(x,y,z,t)~\text{on}~\delta\Omega + +where :math:`f` is an arbitrary function of coordinates :math:`x,y,z` and time :math:`t`. + +FESTIM has built-in Dirichlet’s boundary conditions for Sievert’s condition, Henry’s condition (see Equations :eq:`eq_DirichletBC_Sievert` and :eq:`eq_DirichletBC_Henry`, respectively). + +.. math:: + :label: eq_DirichletBC_Sievert + + c_\mathrm{m} = K_S \sqrt{P}~\text{on}~\delta\Omega + +.. math:: + :label: eq_DirichletBC_Henry + + c_\mathrm{m} = K_H P~\text{on}~\delta\Omega + +Plasma implantation approximation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dirichlet’s boundary conditions can also be used to approximate plasma implantation in near surface regions to be more computationally efficient :cite:`Delaporte-Mathurin2022`. +Let us consider a volumetric source term of hydrogen :math:`\Gamma=\varphi_{\mathrm{imp}}f(x)`, where :math:`f(x)` is a narrow Gaussian distribution. The concentration profile of mobile species can be approximated by a triangular shape :cite:`Schmid2016` with maximum at :math:`x=R_p` (see the figure below). + +.. figure:: images/recomb_sketch.png + :align: center + :width: 700 + :alt: Concentration profile with recombination flux and volumetric source term at :math:`x=R_p`. Dashed lines correspond to the time evolution + + Concentration profie with recombination flux and volumetric source term at :math:`x=R_p`. Dashed lines correspond to the time evolution + +The expression of maximum concentration value :math:`c_{\mathrm{m}}` can be obtained by expressing the flux balance at equilibrium: + +.. math:: + :label: eq_flux_balance + + \varphi_{\mathrm{imp}} = \varphi_{\mathrm{recomb}} + \varphi_{\mathrm{bulk}} + +where :math:`\varphi_{\mathrm{recomb}}` is the recombination flux and :math:`\varphi_{\mathrm{bulk}}` is the migration flux into the bulk. :math:`\varphi_{\mathrm{bulk}}` can be expressed as: + +.. math:: + :label: eq_bulk_flux + + \varphi_{\mathrm{bulk}} = D \cdot \frac{c_{\mathrm{m}}}{R_d(t)-R_p} + +with :math:`R_d` the diffusion depth and :math:`R_p` the implantation range. When :math:`R_d \gg R_p`, +:math:`\varphi_{\mathrm{bulk}} \rightarrow 0`. Equation :eq:`eq_flux_balance` can therefore be written as: + +.. math:: + :label: eq_flux_balance_approx1 + + \begin{eqnarray} + \varphi_{\mathrm{recomb}} &=& D \cdot \frac{c_{\mathrm{m}} - c_0}{R_p} = \varphi_{\mathrm{imp}}\\ + \Leftrightarrow c_{\mathrm{m}} &=& \frac{\varphi_{\mathrm{imp}} R_p}{D} + c_0 + \end{eqnarray} + +Assuming second order recombination, :math:`\varphi_{\mathrm{recomb}}` can also be expressed as a function of the recombination coefficient :math:`K_r`: + +.. math:: + :label: eq_flux_balance_approx2 + + \begin{eqnarray} + \varphi_{\mathrm{recomb}} &=& K_r c_0^2 = \varphi_{\mathrm{imp}}\\ + \Leftrightarrow c_0 &=& \sqrt{\frac{\varphi_{\mathrm{imp}}}{K_r}} + \end{eqnarray} + +By substituting Equation :eq:`eq_flux_balance_approx2` into :eq:`eq_flux_balance_approx1` one can obtain: + +.. math:: + :label: eq_DirichletBC_triangle_recomb + + c_\mathrm{m} = \frac{\varphi_{\mathrm{imp}} R_p}{D} + \sqrt{\frac{\varphi_{\mathrm{imp}}}{K_r}} + +Similarly, dissociation can be accounted for: + +.. math:: + :label: eq_DirichletBC_triangle_full + + c_\mathrm{m} = \frac{\varphi_{\mathrm{imp}} R_p}{D} + \sqrt{\frac{\varphi_{\mathrm{imp}}+K_d P}{K_r}} + +where :math:`K_d` is the dissociation coefficient. + +When recombination is fast (i.e. :math:`K_r\rightarrow\infty`), Equation :eq:`eq_DirichletBC_triangle_full` can be reduced to: + +.. math:: + :label: eq_DirichletBC_triangle + + c_\mathrm{m} = \frac{\varphi_{\mathrm{imp}} R_p}{D} + +Since the main driver of for the diffusion is the value :math:`c_{\mathrm{m}}`, when :math:`R_p` is negligible compared to the dimension of the simulation domain, one can simply impose Equations :eq:`eq_DirichletBC_triangle_full` and :eq:`eq_DirichletBC_triangle` at boundaries :math:`\delta \Omega`. + +Neumann BC +^^^^^^^^^^^^ + +One can also impose hydrogen fluxes or heat fluxes at boundaries (Neumann). Note: we will assume for simplicity that the Soret effect is not included and :math:`J = -D\nabla c_\mathrm{m}`: + +.. math:: + :label: eq_NeumannBC_c + + J \cdot \mathrm{\textbf{n}} = -D\nabla c_\mathrm{m} \cdot \mathrm{\textbf{n}} + =f(x,y,z,t)~\text{on}~\delta\Omega + +.. math:: + :label: eq_NeumannBC_T + + -\lambda\nabla T \cdot \mathrm{\textbf{n}} = f(x,y,z,t)~\text{on}~\delta\Omega + +where :math:`\mathrm{\textbf{n}}` is the normal vector of the boundary. + +Robin BC +^^^^^^^^^^ + +Recombination and dissociation fluxes can also be applied: + +.. math:: + :label: eq_NeumannBC_DisRec + + J \cdot \mathrm{\textbf{n}} = -D\nabla c_\mathrm{m} \cdot \mathrm{\textbf{n}} + = K_d P - K_r c_\mathrm{m}^{\{1,2\}} ~\text{on}~\delta\Omega + +In Equation :eq:`eq_NeumannBC_DisRec`, the exponent of :math:`c_\mathrm{m}` is either 1 or 2 depending on the reaction order. +These boundary conditions are Robin boundary conditions since the gradient is imposed as a function of the solution. + +Finally, convective heat fluxes can be applied to boundaries: + +.. math:: + :label: eq_convective + + -\lambda\nabla T \cdot \mathrm{\textbf{n}} = h (T-T_{\mathrm{ext}})~\text{on}~\delta\Omega + +where :math:`h` is the heat transfer coefficient and :math:`T_{\mathrm{ext}}` is the external temperature. + +Kinetic surface model +^^^^^^^^^^^^^^^^^^^^^ + +Modelling hydrogen retention or outgassing might require considering the kinetics of surface processes. +A representative example is the hydrogen uptake from a gas phase, when the energy of incident atoms/molecules is not high enough to +overcome the surface barrier for implantation. The general approach to account for surface kinetics :cite:`Pick1985, Hodille2017, Guterl2019, Schmid2021` consists in +introducing hydrogen surface species :math:`c_\mathrm{s}\,[\mathrm{m}^{-2}]`. + +Evolution of hydrogen surface concentration is determined by the atomic flux balance at the surface, as sketched in the simplified energy diagram below. + +.. thumbnail:: images/potential_diagram.png + :align: center + :width: 800 + + Idealised potential energy diagram for hydrogen near a surface of an endothermic metal. Energy levels are measured from the :math:`\mathrm{H}_2` state + +The governing equation for surface species is: + +.. math:: + :label: eq_surf_conc + + \dfrac{d c_\mathrm{s}}{d t} = J_\mathrm{bs} - J_\mathrm{sb} + J_\mathrm{vs}~\text{on}~\delta\Omega + +where :math:`J_\mathrm{bs}\,[\mathrm{m}^{-2}\,\mathrm{s}^{-1}]` is the flux of hydrogen atoms from the subsurface (bulk region just beneath the surface) onto the surface, +:math:`J_\mathrm{sb}\,[\mathrm{m}^{-2}\,\mathrm{s}^{-1}]` is the flux of hydrogen atoms from the surface into the subsurface, and :math:`J_\mathrm{vs}\,[\mathrm{m}^{-2}\,\mathrm{s}^{-1}]` +is the net flux of hydrogen atoms from the vaccuum onto the surface. The latter is defined as :math:`J_\mathrm{vs}=J_\mathrm{in}-J_\mathrm{out}`, where :math:`J_\mathrm{in}\,[\mathrm{m}^{-2}\,\mathrm{s}^{-1}]` +is the sum of all fluxes coming from the vacuum onto the surface and :math:`J_\mathrm{out}\,[\mathrm{m}^{-2}\,\mathrm{s}^{-1}]` is the sum of all fluxes coming from the surface to the vacuum. +:math:`J_\mathrm{in}` can be used to set up adsorption fluxes from different processes such as molecular dissociation, adsorption of low-energy atoms, etc. Similarly, +:math:`J_\mathrm{out}` can be used to define desorption fluxes from various processes such as Langmuir-Hinshelwood recombination, Eley-Rideal recombination, sputtering, etc. +It worth noticing that the current model does not account for possible surface diffusion and is available only for 1D hydrogen transport simulations. + +The connection condition between surface and bulk domains represents the Robin boundary condition for the hydrogen transport problem. + +.. math:: + :label: eq_subsurf_conc + + -D \nabla c_\mathrm{m} \cdot \mathbf{n} = \lambda_{\mathrm{IS}} \dfrac{\partial c_{\mathrm{m}}}{\partial t} + J_{\mathrm{bs}} - J_{\mathrm{sb}}~\text{on}~\delta\Omega + +where :math:`\lambda_\mathrm{IS}\,[\mathrm{m}]` is the distance between two interstitial sites in the bulk. + +.. note:: + + At the left boundary, the normal vector :math:`\textbf{n}` is :math:`-\vec{x}`. The steady-state approximation of eq. :eq:`eq_subsurf_conc` at the left boundary + is, therefore, :math:`D\frac{\partial c_\mathrm{m}}{\partial x}=J_\mathrm{bs}-J_\mathrm{sb}` representing eq. (12) in the original work of M.A. Pick & K. Sonnenberg :cite:`Pick1985`. + +The fluxes for subsurface-to-surface and surface-to-subsurface transitions are defined as follows: + +.. math:: + :label: eq_Jbs + + J_\mathrm{bs} = k_\mathrm{bs} \lambda_\mathrm{abs} c_\mathrm{m} \left(1-\dfrac{c_\mathrm{s}}{n_\mathrm{surf}}\right) + +.. math:: + :label: eq_Jsb + + J_\mathrm{sb} = k_\mathrm{sb} c_\mathrm{s} \left(1-\dfrac{c_\mathrm{m}}{n_\mathrm{IS}}\right) + +where :math:`n_\mathrm{surf}\,[\mathrm{m}^{-2}]` is the surface concentration of adsorption sites, :math:`n_\mathrm{IS}\,[\mathrm{m}^{-3}]` is the bulk concentration of interstitial sites, +:math:`\lambda_\mathrm{abs}=n_\mathrm{surf}/n_\mathrm{IS}\,[\mathrm{m}]` is the characteristic distance between surface and subsurface sites, :math:`k_\mathrm{bs}\,[\mathrm{s}^{-1}]` +and :math:`k_\mathrm{sb}\,[\mathrm{s}^{-1}]` are the rate constants for subsurface-to-surface and surface-to-subsurface transitions, respectively. +Usually, these rate constants are expressed in the Arrhenius form: :math:`k_i=k_{i,0}\exp(-E_{k,i} / kT)`. Both these processes are assumed to take place +if there are available sites on the surface (in the subsurface). Possible surface/subsurface saturation is accounted for with terms in brackets. + +.. note:: + + In eq. :eq:`eq_Jsb`, the last term in brackets is usually omitted :cite:`Guterl2019, Pick1985, Hodille2017, Schmid2021`, + since :math:`c_\mathrm{m} \ll n_\mathrm{IS}` is assumed. However, this term is included in some works (e.g. :cite:`Hamamoto2020`) + to better reproduce the experimental results. + + +------------ +References +------------ -WIP \ No newline at end of file +.. bibliography:: bibliography/references.bib + :style: unsrt \ No newline at end of file diff --git a/docs/source/userguide/beginners_guide.rst b/docs/source/userguide/beginners_guide.rst index 8020a670c..1401b365e 100644 --- a/docs/source/userguide/beginners_guide.rst +++ b/docs/source/userguide/beginners_guide.rst @@ -6,16 +6,22 @@ A beginner's guide to FESTIM What do I need to know? ----------------------- -To make the most out of FESTIM, a basic knowledge of `Python `_ is required. +Basic knowledge of `Python `_ is required to make the most out of FESTIM. -Depending on how you install FESTIM, new users should familiarise with either `Docker `_ or `Conda `_. +New users should familiarise themselves with `Conda `_. -FESTIM is under version control with `git `_. Even though users don't need git to install FESTIM, it is convenient to have a basic understanding of how it works. You can find `git tutorials `_ to help you getting started. The `FESTIM source code `_ is hosted on GitHub. Git knowledge and a GitHub account is required to open issues and :ref:`contribute to the code `. +FESTIM is under version control with `git `_. Even though users don't need git to install FESTIM, it is convenient to have a basic understanding of how it works. You can find `git tutorials `_ to help you getting started. The `FESTIM source code `_ is hosted on GitHub. +Git knowledge and a GitHub account is required to open issues and :ref:`contribute to the code `. ---------------------- Where can I find help? ---------------------- -If you're having an issue, the best way to find help is to `raise an issue `_ on the FESTIM GitHub repository. -Before raising an issue, please check that someone didn't have the same problem to avoid duplicates. +If you're having an issue, the best way to find help is to join the `FESTIM discourse `_. Engage in discussions, ask questions, and connect with other users. This collaborative space allows you to share your experiences and seek assistance. `Slack `_ is also a good place to discuss. + +-------------- +Install FESTIM +-------------- + +Follow the :ref:`installation instructions` to install FESTIM on your computer. diff --git a/docs/source/userguide/boundary_conditions.rst b/docs/source/userguide/boundary_conditions.rst index a48e49899..8a45cfedd 100644 --- a/docs/source/userguide/boundary_conditions.rst +++ b/docs/source/userguide/boundary_conditions.rst @@ -1,175 +1,9 @@ .. _boundary conditions: + =================== Boundary conditions =================== -The boundary conditions (BCs) are essential to FESTIM simulations. They describe the mathematical problem at the boundaries of the simulated domain. -If no BC is set on a boundary, it is assumed that the flux is null. This is also called a symmetry BC. - ---------------- -Basic BCs ---------------- -These BCs can be used for heat transfer or hydrogen transport simulations. - -Imposing the solution -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: python - - my_bc = DirichletBC(surfaces=[2, 4], value=10, field=0) - -.. admonition:: Note - :class: tip - - Here, we set :code:`field=0` to specify this BC applies to the mobile hydrogen concentration. :code:`1` would stand for the trap 1 concentration and :code:`"T"` for temperature. - -The `value` argument can be space and time dependent by making use of the FESTIM variables ``x``, ``y``, ``z`` and ``t``: - -.. code-block:: python - - from festim import x, y, z, t - my_bc = DirichletBC(surfaces=3, value=10 + x**2 + t, field="T") - - -To use more complicated mathematical expressions, you can use the sympy package: - -.. code-block:: python - - from festim import x, y, z, t - import sympy as sp - - my_bc = DirichletBC(surfaces=3, value=10*sp.exp(-t), field="T") - -- CustomDirichlet - -The value of the concentration field can be temperature-dependent (useful when dealing with heat-transfer solvers) with :code:`CustomDirichlet`: - -.. code-block:: python - - def value(T): - return 3*T + 2 - - my_bc = CustomDirichlet(surfaces=3, function=value, field=0) - -Imposing the flux -^^^^^^^^^^^^^^^^^ - -When the flux needs to be imposed on a boundary, use the :code:`FluxBC` class. - - -.. code-block:: python - - my_bc = FluxBC(surfaces=3, value=10 + x**2 + t, field="T") - - -As for the Dirichlet boundary conditions, the flux can be dependent on temperature and mobile hydrogen concentration: - -.. code-block:: python - - def value(T, mobile): - return mobile**2 + T - - my_bc = CustomFlux(surfaces=3, function=value, field=0) - - ----------------------- -Hydrogen transport BCs ----------------------- - -Some BCs are specific to hydrogen transport. FESTIM provides a handful of convenience classes making things a bit easier for the users. - -Recombination flux -^^^^^^^^^^^^^^^^^^ - -Recombination flux can be set on boundaries as: :math:`Kr \, c_\mathrm{m}^n`. -Where :math:`Kr` is the recombination coefficient, :math:`c_\mathrm{m}` is the mobile hydrogen concentration and :math:`n` is the recombination order. - -.. code-block:: python - - my_bc = RecombinationFlux(surfaces=3, Kr_0=2, E_Kr=0.1, order=2) - - -Dissociation flux -^^^^^^^^^^^^^^^^^^ - -Dissociation flux can be set on boundaries as: :math:`Kd \, P`. -Where :math:`Kd` is the dissociation coefficient, :math:`P` is the partial pressure of hydrogen. - -.. code-block:: python - - my_bc = DissociationFlux(surfaces=2, Kd_0=2, E_Kd=0.1, P=1e05) - - -Sievert's law of solubility -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Impose the mobile concentration of hydrogen as :math:`c_\mathrm{m} = S(T) \sqrt{P}` where :math:`S` is the Sievert's solubility and :math:`P` is the partial pressure of hydrogen. - -.. code-block:: python - - from festim import t - - my_bc = SievertsBC(surfaces=3, S_0=2, E_S=0.1, pressure=2 + t) - - -Henry's law of solubility -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Similarily, the mobile concentration can be set from Henry's law of solubility :math:`c_\mathrm{m} = K_H P` where :math:`K_H` is the Henry solubility. - - -.. code-block:: python - - from festim import t - - my_bc = HenrysBC(surfaces=3, H_0=2, E_H=0.1, pressure=2 + t) - -Plasma implantation approximation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A plasma implantation can be approximated by: - -.. math:: - - c_\mathrm{m} = \frac{\varphi_\mathrm{imp} \, R_p}{D} + \sqrt{\frac{\varphi_\mathrm{imp} + Kd \cdot P}{Kr}} - -Where :math:`\varphi_\mathrm{imp}` is the implanted flux, :math:`R_p` is the implantation depth, :math:`D` is the diffusion coefficient, :math:`Kd` is the dissociation coefficient, :math:`P` is the partial pressure of hydrogen, and :math:`Kr` is the recombination coefficient. - -When :math:`P = 0`: - -.. math:: - c_\mathrm{m} = \frac{\varphi_\mathrm{imp} \, R_p}{D} + \sqrt{\frac{\varphi_\mathrm{imp}}{Kr}} - -Moreover, assuming an instantaneous recombination :math:`Kr = \infty`: - -.. math:: - c_\mathrm{m} = \frac{\varphi_\mathrm{imp} \, R_p}{D} - -.. admonition:: Note - :class: tip - - Refer to the :ref:`theory` section for more details. - -.. code-block:: python - - from festim import t - - # instantaneous recombination - my_bc = ImplantationDirichlet(surfaces=3, phi=1e10 + t, R_p=1e-9, D_0=1, E_D=0.1) - - # non-instantaneous recombination - my_bc = ImplantationDirichlet(surfaces=3, phi=1e10 + t, R_p=1e-9, D_0=1, E_D=0.1, Kr_0=2, E_Kr=0.2) - - ------------------ -Heat transfer BCs ------------------ - - -A convective heat flux can be set as :math:`\mathrm{flux} = - h (T - T_\mathrm{ext})`. - -.. code-block:: python - - from festim import t +.. warning:: - my_bc = ConvectiveFlux(surfaces=3, h_coeff=0.1, T_ext=600 + 10*t) + 🔨 This page is under construction. 🔨 diff --git a/docs/source/userguide/export_post_processing.rst b/docs/source/userguide/export_post_processing.rst index b6a5601bc..cb749cf24 100644 --- a/docs/source/userguide/export_post_processing.rst +++ b/docs/source/userguide/export_post_processing.rst @@ -1,3 +1,7 @@ =============== Post-processing -=============== \ No newline at end of file +=============== + +.. warning:: + + 🔨 This page is under construction. 🔨 diff --git a/docs/source/userguide/index.rst b/docs/source/userguide/index.rst index 094df1ce3..fa7a0207e 100644 --- a/docs/source/userguide/index.rst +++ b/docs/source/userguide/index.rst @@ -13,8 +13,7 @@ User's Guide sources temperature mesh - traps settings export_post_processing - simulations - troubleshooting \ No newline at end of file + troubleshooting + running_in_parallel \ No newline at end of file diff --git a/docs/source/userguide/materials.rst b/docs/source/userguide/materials.rst index 7781253ff..ae78fb273 100644 --- a/docs/source/userguide/materials.rst +++ b/docs/source/userguide/materials.rst @@ -2,45 +2,15 @@ Materials ========= -Materials are key components of hydrogen transport simulations. They hold the properties like diffusivity, solubility and even thermal properties like thermal conductivity or heat capacity. +.. warning:: -To define a material, use the :code:`Material` class: - -.. code-block:: python - - mat1 = Material(id=1, D_0=2, E_D=0.1) - mat2 = Material(id=2, D_0=3, E_D=0.4) - - -Materials are then assigned to the model: - -.. code-block:: python - - my_model = Simulation(materials=[mat1, mat2]) - ----------------------- -Parameters description ----------------------- - -The :code:`Material` class has three required arguments: - -* :code:`id`: a unique id given to the material/volume. It is useful when defining volumetric source terms or exports. Several ids can be given to the same material if multiple volumes have the same material. -* :code:`D_0`: the diffusivity pre-exponential factor expressed in m2/s -* :code:`E_D`: the diffusivity activation energy in eV - -Some other parameters are optional and are only required for some types of simulations: - -* :code:`S_0`: the solubility pre-exponential factor, its units depend on the solubility law (Sievert's or Henry) -* :code:`E_S`: the solubility activation energy in eV -* :code:`thermal_cond`: the thermal conductivity in W/m/K -* :code:`heat_capacity`: the heat capacity in J/kg/K -* :code:`rho`: the volumetric density in kg/m3 + 🔨 This page is under construction. 🔨 -------------------- Integration with HTM -------------------- -H-transport-materials (HTM) is a python database of hydrogen transport properties. +H-transport-materials (HTM) is a Python database of hydrogen transport properties. Using this database will avoid making copy-pasting errors and add consistency across simulations by making sure the same properties are used. -HTM can be easily `integrated with FESTIM `_. +HTM can be easily `integrated with FESTIM `_. \ No newline at end of file diff --git a/docs/source/userguide/mesh.rst b/docs/source/userguide/mesh.rst index f7b40b879..2baefbdf8 100644 --- a/docs/source/userguide/mesh.rst +++ b/docs/source/userguide/mesh.rst @@ -2,61 +2,6 @@ Mesh ==== -Meshes are required to discretise the geometrical domain of the simulation. -As FESTIM is not a meshing tool, the meshing capabilities are limited to simple 1D meshes. +.. warning:: ---------- -1D meshes ---------- - -The easiest way to define a 1D mesh in FESTIM is to define it from a list of vertices: - -.. code-block:: python - - mesh = MeshFromVertices([0, 1, 2, 4, 5, 10]) - -For bigger meshes, use the numpy library to generate an array of vertices. - -.. code-block:: python - - import numpy as np - - mesh = MeshFromVertices(np.linspace(0, 10, num=1000)) - -Numpy arrays can be combined to have local refinements: - -.. code-block:: python - - import numpy as np - - vertices = np.concatenate( - [ - np.linspace(0, 1e-6, num=100), # 99 cells between 0 and 1 micron - np.linspace(1e-6, 1e-4, num=100), # 99 cells between 1 micron and 0.1 mm - np.linspace(1e-4, 1e-2, num=10) # 9 cells between 0.1 mm and 1 cm - ] - ) - mesh = MeshFromVertices(vertices) - ----------------- -Meshes from XDMF ----------------- - -More complex meshes can be read from XDMF files: - -.. code-block:: python - - mesh = MeshFromXDMF(volume_file="volume_file.xdmf", boundary_file="boundary_file.xdmf") - -The recommended workflow is to mesh your geometry with your favourite meshing software (`SALOME `_, `gmsh `_...) and convert the produced mesh with `meshio `_. - -GMSH example ------------- - -The DOLFINx tutorial gives an `example `_ of mesh generation with gmsh. - ------------------- -meshes from FEniCS ------------------- - -See the `FEniCS documentation `_ for more built-in meshes. + 🔨 This page is under construction. 🔨 diff --git a/docs/source/userguide/running_in_parallel.rst b/docs/source/userguide/running_in_parallel.rst new file mode 100644 index 000000000..81a20df16 --- /dev/null +++ b/docs/source/userguide/running_in_parallel.rst @@ -0,0 +1,9 @@ +=================== +Running in parallel +=================== + +FESTIM can be run in parallel on N cores using the command: + +.. code:: + + mpirun -np N python your_FESTIM_script.py \ No newline at end of file diff --git a/docs/source/userguide/settings.rst b/docs/source/userguide/settings.rst index 4c99a64c1..94e34f6b6 100644 --- a/docs/source/userguide/settings.rst +++ b/docs/source/userguide/settings.rst @@ -9,10 +9,9 @@ The settings of a FESTIM simulation are defined with a :code:`Settings` object. import festim as F my_settings = F.Settings( - absolute_tolerance=1e10, - relative_tolerance=1e-10, + atol=1e10, + rtol=1e-10, transient=False, - chemical_pot=True, ) @@ -25,8 +24,3 @@ Here you define: * the absolute and relative tolerance of the Newton solver * the maximum iterations of the Newton solver -More advanced settings are also available: - -* the type of finite elements for traps (DG elements can be useful to account for discontinuities) -* Wether to update the jacobian at each iteration or not -* the linear solver diff --git a/docs/source/userguide/simulations.rst b/docs/source/userguide/simulations.rst deleted file mode 100644 index d7e5805f9..000000000 --- a/docs/source/userguide/simulations.rst +++ /dev/null @@ -1,10 +0,0 @@ -=========== -Simulations -=========== - - -WIP - ------------------ -Adaptive timestep ------------------ diff --git a/docs/source/userguide/sources.rst b/docs/source/userguide/sources.rst index d0ccbc192..231bf58da 100644 --- a/docs/source/userguide/sources.rst +++ b/docs/source/userguide/sources.rst @@ -5,4 +5,6 @@ Sources ======= -WIP \ No newline at end of file +.. warning:: + + 🔨 This page is under construction. 🔨 diff --git a/docs/source/userguide/temperature.rst b/docs/source/userguide/temperature.rst index 934ee5a8d..4a37cdc94 100644 --- a/docs/source/userguide/temperature.rst +++ b/docs/source/userguide/temperature.rst @@ -2,66 +2,6 @@ Temperature =========== -Definition of a temperature field or problem is essential for hydrogen transport -and FESTIM as a whole. +.. warning:: ----------------------- -Analytical expressions ----------------------- - -The temperature can be defined as a constant value in Kelvin (K): - -.. code-block:: python - - my_temperature = Temperature(value=300) - - -Temperature can also be defined as an expression of time and/or space. -For example: - -.. math:: - - T = 300 + 2 x + 3 t - -would be passed to FESTIM as: - -.. code-block:: python - - from festim import x, t - - my_temp = Temperature(300+2*x+3*t) - -More complex expressions can be expressed with sympy: - -.. math:: - - T = \exp(x) \ \sin(t) - -would be passed to FESTIM as: - -.. code-block:: python - - from festim import x, t - import sympy as sp - - my_temp = Temperature(sp.exp(x)*sp.sin(t)) - ---------------------------- -From a heat transfer solver ---------------------------- - -Temperature can also be obtained by solving the heat equation. -Users can define heat transfer problems using :code:`HeatTransferProblem`. - - -.. code-block:: python - - my_temp = HeatTransferProblem() - -For a steady-state problem: - -.. code-block:: python - - my_temp = HeatTransferProblem(transient=False) - -:ref:`Boundary conditions` and :ref:`heat sources` can then be applied to this heat transfer problem. + 🔨 This page is under construction. 🔨 diff --git a/docs/source/userguide/traps.rst b/docs/source/userguide/traps.rst deleted file mode 100644 index cc85f78ea..000000000 --- a/docs/source/userguide/traps.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _traps: - -===== -Traps -===== - ------------- -Basic traps ------------- - - -A trap in FESTIM is defined by: - -* its trapping coefficient -* its detrapping coefficient -* its density -* the materials where it is located - -.. code-block:: python - - import festim as F - - my_material = F.Material(id=1, D_0=1, E_D=0) - - my_trap = F.Trap(k_0=1e-16, E_k=0.2, p_0=1e13, E_p=0.8, density=1e16, materials=my_material) - -If the trap is located in several materials, instead of creating another :code:`Trap` object, simply use a list of materials: - -.. code-block:: python - - import festim as F - - mat1 = F.Material(id=1, D_0=1, E_D=0) - mat2 = F.Material(id=2, D_0=2, E_D=0) - - my_trap = F.Trap(k_0=1e-16, E_k=0.2, p_0=1e13, E_p=0.8, density=1e16, materials=[mat1, mat2]) - -The trap density can be a function of space and time. For example: - -.. code-block:: python - - import festim as F - - my_trap = F.Trap( - k_0=1e-16, - E_k=0.2, - p_0=1e13, - E_p=0.8, - density=1e16 + F.t + F.x, - materials=my_material - ) - -Boolean expressions can also be used to restrict the trap to certain regions: - -.. code-block:: python - - import festim as F - - import sympy as sp - - my_trap = F.Trap( - k_0=1e-16, - E_k=0.2, - p_0=1e13, - E_p=0.8, - density=sp.Piecewise((1e16, F.x < 0.1), (0, True)), - materials=my_material - ) - -In this case, the trap's density will be :math:`10^{16} \ \mathrm{m^{-3}}` for all :math:`x < 0.1 \ \mathrm{m}`, else zero. - ---------------- -Extrinsic traps ---------------- - -An extrinsic trap is defined as a trap with a density evolving over time. -If the temporal evolution of the trap's density is known `a priori`, then a "normal" trap can be used with a time dependent expression as density (see above). - -.. code-block:: python - - import festim as F - - mat1 = F.Material(id=1, D_0=1, E_D=0) - mat2 = F.Material(id=2, D_0=2, E_D=0) - - trap1 = F.Trap(k_0=1e-16, E_k=0.2, p_0=1e13, E_p=0.8, density=1e16, materials=mat1) - trap2 = F.Trap(k_0=1e-16, E_k=0.2, p_0=1e13, E_p=1.0, density=1e16, materials=mat2) - ------------- -Grouped-trap ------------- - -Let's imaging a case where you have two subdomains. Trap 1 is defined only in the first subdomain, whereas Trap 2 is defined in the second. -It would be possible to simply define one trap in each subdomain. - - -But grouping traps together helps saving computational time. - -.. code-block:: python - - import festim as F - - mat1 = F.Material(id=1, D_0=1, E_D=0) - mat2 = F.Material(id=2, D_0=2, E_D=0) - - grouped_trap = F.Trap( - k_0=[1e-16, 1e-16], - E_k=[0.2, 0.2], - p_0=[1e13, 1e13], - E_p=[0.8, 1.0], - density=[1e16, 1e16], - materials=[mat1, mat2], - ) - diff --git a/docs/source/userguide/troubleshooting.rst b/docs/source/userguide/troubleshooting.rst index af6f1dd1e..5763270ea 100644 --- a/docs/source/userguide/troubleshooting.rst +++ b/docs/source/userguide/troubleshooting.rst @@ -2,18 +2,62 @@ Troubleshooting =============== -WIP +---------------------- +Where can I find help? +---------------------- -------------------- -Where to find help? -------------------- +If you're having an issue, the best way to find help is to join the `FESTIM discourse `_. Engage in discussions, ask questions, and connect with other users. This collaborative space allows you to share your experiences and seek assistance. -- Github issues +------------- +Common issues +------------- ------------------- -Convergence issues ------------------- +Although FESTIM is designed to be easy to use, users may encounter some common issues. This section provides some guidance on how to resolve these issues. +We are simply solving a set of equations using the finite element method, and are, therefore, subject to the same issues that other FEM codes face. -- Converges with 0 iterations -- Try and visualise the fields -- Mesh refinement or time refinement \ No newline at end of file +^^^^^^^^^^^^^^^^^^^^^^^ +Solver doesn't converge +^^^^^^^^^^^^^^^^^^^^^^^ + +The first thing to check is the details of the Newton solver iterations. +To do so, you must set the ``log_level`` to ``20`` (default is ``40``). +This will provide more information during the solving stage. + +.. testcode:: + + import dolfinx + + dolfinx.log.set_log_level(dolfinx.log.LogLevel.INFO) + +From there, depending on the behaviour of the solver, you can try the following: + +- if the solver diverges, try reducing the time step and/or mesh refinement. It is often helpful to inspect the fields to see if there are any obvious issues (like lack of refinement). +- If the solver converges to a value above the tolerance, try increasing the tolerance. Sometimes, the absolute tolerance is too low for the problem at hand, especially when dealing with large numbers. + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Solution is zero everywhere +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes, the solver converges fine but the solution is zero everywhere. +This is often due to an excessively high absolute tolerance. +The Newton solver then converges in zero iterations. In other words, nothing is solved. +First, check that this is the case by setting the log level to INFO: + +.. testcode:: + + import dolfinx + + dolfinx.log.set_log_level(dolfinx.log.LogLevel.INFO) + +Then increase the absolute tolerance of the solver: + +.. testcode:: + + import festim as F + + my_model = F.HydrogenTransportProblem() + my_model.settings = F.Settings( + atol=1e10, + rtol=1e-10, + ) \ No newline at end of file diff --git a/src/festim/boundary_conditions/flux_bc.py b/src/festim/boundary_conditions/flux_bc.py index fea235571..99349a0f1 100644 --- a/src/festim/boundary_conditions/flux_bc.py +++ b/src/festim/boundary_conditions/flux_bc.py @@ -159,13 +159,16 @@ class ParticleFluxBC(FluxBCBase): Usage: - >>> from festim import ParticleFluxBC - >>> ParticleFluxBC(subdomain=my_subdomain, value=1, species="H") - >>> ParticleFluxBC(subdomain=my_subdomain, value=lambda x: 1 + x[0], species="H") - >>> ParticleFluxBC(subdomain=my_subdomain, value=lambda t: 1 + t, species="H") - >>> ParticleFluxBC(subdomain=my_subdomain, value=lambda T: 1 + T, species="H") - >>> ParticleFluxBC(subdomain=my_subdomain, value=lambda x, t: 1 + x[0] + t, species="H") - >>> ParticleFluxBC(subdomain=my_subdomain, value=lambda c1: 2 * c1**2, species="H", species_dependent_value={"c1": species1}) + .. testcode:: + + from festim import ParticleFluxBC + + ParticleFluxBC(subdomain=my_subdomain, value=1, species="H") + ParticleFluxBC(subdomain=my_subdomain, value=lambda x: 1 + x[0], species="H") + ParticleFluxBC(subdomain=my_subdomain, value=lambda t: 1 + t, species="H") + ParticleFluxBC(subdomain=my_subdomain, value=lambda T: 1 + T, species="H") + ParticleFluxBC(subdomain=my_subdomain, value=lambda x, t: 1 + x[0] + t, species="H") + ParticleFluxBC(subdomain=my_subdomain, value=lambda c1: 2 * c1**2, species="H", species_dependent_value={"c1": species1}) """ def __init__(self, subdomain, value, species, species_dependent_value={}): @@ -240,11 +243,13 @@ class HeatFluxBC(FluxBCBase): Usage: - >>> from festim import HeatFluxBC - >>> HeatFluxBC(subdomain=my_subdomain, value=1) - >>> HeatFluxBC(subdomain=my_subdomain, value=lambda x: 1 + x[0]) - >>> HeatFluxBC(subdomain=my_subdomain, value=lambda t: 1 + t) - >>> HeatFluxBC(subdomain=my_subdomain, value=lambda x, t: 1 + x[0] + t) + .. testcode:: + + from festim import HeatFluxBC + HeatFluxBC(subdomain=my_subdomain, value=1) + HeatFluxBC(subdomain=my_subdomain, value=lambda x: 1 + x[0]) + HeatFluxBC(subdomain=my_subdomain, value=lambda t: 1 + t) + HeatFluxBC(subdomain=my_subdomain, value=lambda x, t: 1 + x[0] + t) """ def __init__(self, subdomain, value):