UPD of developer's guide and docs for materials

docs/source/devguide/index.rst

@@ -56,11 +56,16 @@ For complete information on contributions with GitHub see this guide on `GitHub
       git commit -m "Your commit message"
       git push
 
-#. Optional: Test your code
+#. Test your code
 
    If you are adding new features or fixing bugs, it is important to test your code.
    See :ref:`Test suite` for more information.
 
+#. Format your code using `Black <https://github.com/psf/black>`_.
+
+   The source code of FESTIM is formated with the Black code formatter. Using of a unified code style simplifies the code review
+   and increases its readability. See :ref:`Code formatting` for more information.
+
 #. Optional: Build the documentation
 
    You may want to build the documentation to see if your changes are correctly reflected or if you are updating the docs.
@@ -158,6 +163,33 @@ Implementing a new feature
 #. Open a PR
 
 
+----------------
+Code formatting
+----------------
+
+Before merging your PR, the modified scripts should be formatted to maintain the consistency of the coding style. FESTIM is formatted using 
+`Black <https://github.com/psf/black>`_. To install Black, run the following command:
+
+.. code-block:: bash
+
+   pip install black
+
+After the installation, you can format a file using:
+
+.. code-block:: bash
+
+   black my_script.py
+
+Alternatively, you can format all files in the current directory with:
+
+.. code-block:: bash
+
+   black .
+
+
+If you use Visual Studio Code, you can install the `extension <https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter>`_ 
+with support for the Black formatter. Then, you can set Black as a default formatter for python and enable formatting "on save" for your code. 
+
 -------------------
 Documentation guide
 -------------------
@@ -217,4 +249,16 @@ When contributing to the documentation, make sure to:
 #. Write clear and concise documentation
 #. Use the right syntax
 #. Update the documentation when new features are added
+#. Test the documentation using:
+
+.. code-block:: bash
 
+   cd docs/source
+   make doctest
+
+or using: 
+
+.. code-block:: bash
+
+   cd docs
+   sphinx-build -b doctest source build

docs/source/userguide/materials.rst

@@ -11,37 +11,81 @@ To define a material, use the :class:`festim.Material` class:
 .. testsetup::
 
     from festim import Material, Simulation
+    import fenics
 
 .. testcode::
 
-    mat1 = Material(id=1, D_0=2, E_D=0.1)
-    mat2 = Material(id=2, D_0=3, E_D=0.4)
+    mat = Material(id=1, D_0=2, E_D=0.1)
+
+The :class:`festim.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 id's 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
 
+The diffusivity will be automatically evaluated using the pre-exponential factor and activation energy according to the Arrhenius law.
 
-Materials are then assigned to the model:
+The material is then assigned to the model:
 
 .. testcode::
 
+    my_model = Simulation(materials=mat)
+
+Similarly, several materials can be used in simulations:
+
+.. testcode::
+
+    mat1 = Material(id=1, D_0=2, E_D=0.1)
+    mat2 = Material(id=2, D_0=3, E_D=0.4)
     my_model = Simulation(materials=[mat1, mat2])
 
-----------------------
-Parameters description
-----------------------
+.. note::
 
-The :class:`festim.Material` class has three required arguments:
+    When several materials are considered in one-dimensional simulations, the ``borders`` argument needs to be provided for each material:
 
-* :code:`id`: a unique id given to the material/volume. It is useful when defining volumetric source terms or exports. Several id's 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
+    .. testcode::
 
-Some other parameters are optional and are only required for some types of simulations:
+        mat1 = Material(id=1, D_0=2, E_D=0.1, borders=[0, 0.5])
+        mat2 = Material(id=2, D_0=3, E_D=0.4, borders=[0.5, 1.0])
+
+    ``borders`` determine the domain where the material is defined.
+
+
+Some other parameters are optional and are only required for specific types of simulations. The hydrogen solubility in a material needs to be provided 
+when the conservation of chemical potential at interfaces of materials is considered. It is defined by the following parameters:
 
 * :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:`solubility_law`: the material’s solubility law. Can be :code:`“henry”` or :code:`“sievert”`
+
+For transient heat transfer simulations, thermal conductivity, heat capacity, and density of a material are required. They can be set using the corresponding  
+material attributes:
+
 * :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
-* :code:`Q`: the heat of transport in eV. For more information see :ref:`Soret effect`.
+
+Finally, the :ref:`Soret effect` can be accounted for by invoking:
+
+* :code:`Q`: the heat of transport in eV.
+
+---------------------------------
+Temperature-dependent parameters
+---------------------------------
+
+Thermal properties and the heat of transport can be defined as function of temperature. For example:
+
+.. testcode::
+
+    my_mat = Material(
+        id=1,
+        D_0=2e-7,
+        E_D=0.2,
+        thermal_cond=lambda T: 3 * T + 2 * fenics.exp(-20 * T),
+        heat_capacity=lambda T: 4 * T + 8 * fenics.conditional(T < 400, 5, 8),
+        rho=lambda T: 7 * T + 5,
+        Q=lambda T: -0.5 * T**2,
+    )
 
 --------------------
 Integration with HTM

docs/source/userguide/running_in_parallel.rst

@@ -1,6 +1,6 @@
-============
+===================
 Running in parallel
-============
+===================
 
 FESTIM can be run in parallel on N cores using the command: 
 

docs/source/userguide/settings.rst

@@ -20,18 +20,18 @@ The settings of a FESTIM simulation are defined with a :class:`festim.Settings`
 
 Here you define with:
 
-* ``transient``: wether the simulation is transient or steady-state
+* ``transient``: whether the simulation is transient or steady-state
 * ``final_time``: the final time of the simulation
-* ``chemical_pot``: wether to run the simulation with conservation of chemical potential at interfaces (only useful for multi-materials)
-* ``soret``: wether to turn the Soret effect on or not
+* ``chemical_pot``: whether to run the simulation with conservation of chemical potential at interfaces (only useful for multi-materials)
+* ``soret``: whether to turn the Soret effect on or not
 * ``absolute_tolerance``: the absolute tolerance of the Newton solver
 * ``relative_tolerance``: the relative tolerance of the Newton solver
 * ``maximum_iterations``: the maximum iterations of the Newton solver
 
 More advanced settings are also available:
 
 * ``traps_element_type``: the type of finite elements for traps (DG elements can be useful to account for discontinuities)
-* ``update_jacobian``: wether to update the jacobian at each iteration or not
+* ``update_jacobian``: whether to update the jacobian at each iteration or not
 * ``linear_solver``: linear solver method for the Newton solver
 * ``preconditioner``: preconditioning method for the Newton solver
 

festim/materials/material.py

@@ -29,7 +29,7 @@ class Material:
         my_mat = Material(
             id=1,
             D_0=2e-7,
-            E_d=0.2,
+            E_D=0.2,
             thermal_cond=lambda T: 3 * T + 2,
             heat_capacity=lambda T: 4 * T + 8,
             rho=lambda T: 7 * T + 5,