Merge branch 'main' of https://github.com/RemDelaporteMathurin/FESTIM

.github/workflows/test_demos.yml

@@ -7,12 +7,9 @@ on:
   # Triggers the workflow on push or pull request events but only for the master branch
   push:
     branches:
-    - master
+    - main
     - dev
   pull_request:
-    branches:
-    - master
-    - dev
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+
+conda:
+  environment: docs/environment.yml
+
+# # Set the version of Python and other tools you might need
+# build:
+#   os: ubuntu-20.04
+#   tools:
+#     python: "3.9"
+#     # You can also specify other tool versions:
+#     # nodejs: "16"
+#     # rust: "1.55"
+#     # golang: "1.17"
+
+# 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:
+#    - requirements: docs/requirements.txt

README.md

@@ -6,66 +6,65 @@
 ![GitHub stars](https://img.shields.io/github/stars/RemDelaporteMathurin/FESTIM.svg?logo=github&label=Stars&logoColor=white)
 ![GitHub forks](https://img.shields.io/github/forks/RemDelaporteMathurin/FESTIM.svg?logo=github&label=Forks&logoColor=white)
 
-FESTIM (Finite Elements Simulation of Tritium in Materials) is a tool for modeling Hydrogen Isotopes (HIs) transport in materials. 
-The governing equations are composed of:
-- **Fick's law** of diffusion of hydrogen
-- **Soret** effect
-- Trapping/detrapping **macroscopic rate equations**
-- **Heat equation**
+FESTIM (Finite Elements Simulation of Tritium in Materials) is a tool for modeling hydrogen transport in materials. 
+FESTIM simulates the diffusion and trapping of hydrogen, coupled to heat transfer.
 
 
-The following features are included in this tool:
+The following features are included:
 - Mesh import from XDMF files
 - **Adaptive stepsize**
-- **Temperature** can be defined by:
-    - a user-defined expression
-    - solving transient/stationnary heat equation
+- **Temperature** from solving transient/stationnary heat equation
 - Multiple intrinsic/extrinsic traps with **non-homogeneous density distribution**
 - Wide range of built-in boundary conditions (Sievert's law, recombination flux, user-defined expression...)
 - **Derived quantities** computation (surface fluxes, volume integrations, extrema over domains, mean values over domains...)
+- Soret effect
+- ...
 
-FESTIM spatially discretises the PDEs using the Finite Element Methods. To this extent, we chose to use the C++/Python library [FEniCS](https://fenicsproject.org). 
-The implicit time discretisation method is backward Euler.
-PDEs are solved using FEniCS' Newton nonlinear solver. A library of generic functions is provided so that users can run custom simulations in addition to the flexibility of [FEniCS](https://fenicsproject.org) built-in functions.
+FESTIM spatially discretises the PDEs using the Finite Element Methods and heavily relies on [FEniCS](https://fenicsproject.org).
 
-## Run FESTIM in Docker
-The FEniCS project provides a [Docker image](https://hub.docker.com/r/fenicsproject/stable/) with FEniCS and its dependencies (python3, UFL, DOLFIN, numpy, sympy...)  already installed. See their ["FEniCS in Docker" manual](https://fenics.readthedocs.io/projects/containers/en/latest/).
+:point_right: [Examples](https://github.com/RemDelaporteMathurin/FESTIM/tree/main/demos).
 
-Get Docker [here](https://www.docker.com/community-edition).
+:point_right: [Documentation](https://festim.readthedocs.io/en/latest/)
 
-Pull the Docker image and run the container, sharing a folder between the host and container:
 
-For Windows users:
+## Installation
 
-    docker run -ti -v ${PWD}:/home/fenics/shared --name fenics quay.io/fenicsproject/stable:latest
+FESTIM can be installed via pip
 
-For Linux users:
+    pip install FESTIM
 
-    docker run -ti -v $(pwd):/home/fenics/shared --name fenics quay.io/fenicsproject/stable:latest
-
-Clone FESTIM:
-
-    git clone https://github.com/RemDelaporteMathurin/FESTIM
+FESTIM requires FEniCS to run.
+The FEniCS project provides a [Docker image](https://hub.docker.com/r/fenicsproject/stable/) with FEniCS and its dependencies (python3, UFL, DOLFIN, numpy, sympy...)  already installed. See their ["FEniCS in Docker" manual](https://fenics.readthedocs.io/projects/containers/en/latest/).
 
-Alternatively, FESTIM can be installed via pip
+For Windows users:
 
-    pip install git+https://github.com/RemDelaporteMathurin/FESTIM
+    docker run -ti -v ${PWD}:/home/fenics/shared --name fenics quay.io/fenicsproject/stable:latest
 
-To install a specific version of FESTIM
+For Linux users:
 
-    pip install git+https://github.com/RemDelaporteMathurin/[email protected]
+    docker run -ti -v $(pwd):/home/fenics/shared --name fenics quay.io/fenicsproject/stable:latest
 
 Run the tests:
 
     pytest-3 test/
 
 
 ## Visualisation
-FESTIM allows users to export their data to .csv, .txt or to a XDMF format with an XML interface. The latter can then be opened in visualisation tools like [ParaView](https://www.paraview.org/) or [VisIt](https://wci.llnl.gov/simulation/computer-codes/visit/).
+FESTIM results are exported to .csv, .txt or XDMF. The latter can then be opened in visualisation tools like [ParaView](https://www.paraview.org/) or [VisIt](https://wci.llnl.gov/simulation/computer-codes/visit/).
 <p align="center">
   <img alt="performance" src="https://user-images.githubusercontent.com/40028739/69346147-9abb6980-0c72-11ea-80e7-9c0a76659268.png" width="40%"> <img alt="performance" src="https://user-images.githubusercontent.com/40028739/69346752-9d6a8e80-0c73-11ea-96c1-27b6104eb9ff.png" width="40%">
 </p>
 
 ## References
 - R. Delaporte-Mathurin, _et al._, _Finite Element Analysis of Hydrogen Retention in ITER Plasma Facing Components using FESTIM_. Nuclear Materials and Energy 21: 100709. DOI: [10.1016/j.nme.2019.100709](https://doi.org/10.1016/j.nme.2019.100709).
 
+- R. Delaporte-Mathurin, _et al._, _Parametric Optimisation Based on TDS Experiments for Rapid and Efficient Identification of Hydrogen Transport Materials Properties_. Nuclear Materials and Energy, 26 mars 2021, 100984. https://doi.org/10.1016/j.nme.2021.100984.
+
+- R. Delaporte-Mathurin, _et al._, _Parametric Study of Hydrogenic Inventory in the ITER Divertor Based on Machine Learning_. Scientific Reports 10: 17798. https://doi.org/10.1038/s41598-020-74844-w.
+
+- R. Delaporte-Mathurin, _et al._, _Influence of Interface Conditions on Hydrogen Transport Studies_. Nuclear Fusion 61 (2021): 036038. https://doi.org/10.1088/1741-4326/abd95f.
+
+- R. Delaporte-Mathurin, _et al._, _Fuel Retention in WEST and ITER Divertors Based on FESTIM Monoblock Simulations_. Nuclear Fusion 61, nᵒ 12: 126001. https://doi.org/10.1088/1741-4326/ac2bbd.
+
+- E. A. Hodille _et al._, _Modelling of Hydrogen Isotopes Trapping, Diffusion and Permeation in Divertor Monoblocks under ITER-like Conditions_. Nuclear Fusion, 2021. https://doi.org/10.1088/1741-4326/ac2abc.
+

docs/environment.yml

@@ -0,0 +1,9 @@
+name: fenics
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - fenics
+  - pip>=20.1
+  - pip:
+    - sympy

docs/source/api/festim.boundary_conditions.dirichlets.rst

@@ -0,0 +1,53 @@
+festim.boundary\_conditions.dirichlets package
+==============================================
+
+Submodules
+----------
+
+festim.boundary\_conditions.dirichlets.custom\_dc module
+--------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.dirichlets.custom_dc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.dirichlets.dc\_imp module
+-----------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.dirichlets.dc_imp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.dirichlets.dirichlet\_bc module
+-----------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.dirichlets.dirichlet_bc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.dirichlets.henrys\_bc module
+--------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.dirichlets.henrys_bc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.dirichlets.sieverts\_bc module
+----------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.dirichlets.sieverts_bc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: festim.boundary_conditions.dirichlets
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/festim.boundary_conditions.fluxes.rst

@@ -0,0 +1,45 @@
+festim.boundary\_conditions.fluxes package
+==========================================
+
+Submodules
+----------
+
+festim.boundary\_conditions.fluxes.convective\_flux module
+----------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.fluxes.convective_flux
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.fluxes.flux\_bc module
+--------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.fluxes.flux_bc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.fluxes.flux\_custom module
+------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.fluxes.flux_custom
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.boundary\_conditions.fluxes.recombination\_flux module
+-------------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.fluxes.recombination_flux
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: festim.boundary_conditions.fluxes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/festim.boundary_conditions.rst

@@ -0,0 +1,30 @@
+festim.boundary\_conditions package
+===================================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   festim.boundary_conditions.dirichlets
+   festim.boundary_conditions.fluxes
+
+Submodules
+----------
+
+festim.boundary\_conditions.boundary\_condition module
+------------------------------------------------------
+
+.. automodule:: festim.boundary_conditions.boundary_condition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: festim.boundary_conditions
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/festim.concentration.rst

@@ -0,0 +1,45 @@
+festim.concentration package
+============================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   festim.concentration.traps
+
+Submodules
+----------
+
+festim.concentration.concentration module
+-----------------------------------------
+
+.. automodule:: festim.concentration.concentration
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.concentration.mobile module
+----------------------------------
+
+.. automodule:: festim.concentration.mobile
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.concentration.theta module
+---------------------------------
+
+.. automodule:: festim.concentration.theta
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: festim.concentration
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/festim.concentration.traps.rst

@@ -0,0 +1,45 @@
+festim.concentration.traps package
+==================================
+
+Submodules
+----------
+
+festim.concentration.traps.extrinsic\_trap module
+-------------------------------------------------
+
+.. automodule:: festim.concentration.traps.extrinsic_trap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.concentration.traps.neutron\_induced\_trap module
+--------------------------------------------------------
+
+.. automodule:: festim.concentration.traps.neutron_induced_trap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.concentration.traps.trap module
+--------------------------------------
+
+.. automodule:: festim.concentration.traps.trap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+festim.concentration.traps.traps module
+---------------------------------------
+
+.. automodule:: festim.concentration.traps.traps
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: festim.concentration.traps
+   :members:
+   :undoc-members:
+   :show-inheritance: