API documentation for fenicsx branch

.gitignore

@@ -110,4 +110,11 @@ venv.bak/
 *.bp
 *.xdmf
 *.h5
-*.txt
+*.txt
+
+# Docs files
+docs/source/_build/
+docs/source/_static/
+
+# Visual Studio Code settings
+.vscode/

docs/source/api/index.rst

@@ -1,30 +1,80 @@
-FESTIM API
-==========
+#############
+API reference
+#############
 
-.. warning::
 
-    🔨 This page is under construction. 🔨
+.. automodule:: festim.boundary_conditions
+    :members:
+    :show-inheritance:
 
+.. automodule:: festim.exports
+    :members:
+    :show-inheritance:
 
-.. automodule:: festim.boundary_conditions
+.. automodule:: festim.mesh
     :members:
     :show-inheritance:
-    :exclude-members: __weakref__
-    :private-members:
-    :inherited-members:
 
+.. automodule:: festim.subdomain
+    :members:
+    :show-inheritance:
 
-.. .. automodule:: festim.hydrogen_transport_problem
-..     :members:
-..     :show-inheritance:
-..     :exclude-members: __weakref__
-..     :private-members:
-..     :inherited-members:
+.. automodule:: festim.advection
+    :members:
+    :show-inheritance:
 
+.. automodule:: festim.coupled_heat_hydrogen_problem
+    :members:
+    :show-inheritance:
 
+.. automodule:: festim.heat_transfer_problem
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.helpers_discontinuity
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.helpers
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.hydrogen_transport_problem
+    :members:
+    :show-inheritance:
 
-.. .. automodule:: festim.heat_transfer_problem
-..     :members:
-..     :show-inheritance:
-..     :exclude-members: __weakref__
-..     :inherited-members:
+.. automodule:: festim.initial_condition
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.material
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.problem
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.reaction
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.settings
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.source
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.species
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.stepsize
+    :members:
+    :show-inheritance:
+
+.. automodule:: festim.trap
+    :members:
+    :show-inheritance:

src/festim/__init__.py

@@ -9,7 +9,6 @@
 R = 8.314462618  # Gas constant J.mol-1.K-1
 k_B = 8.6173303e-5  # Boltzmann constant eV.K-1
 
-
 from .advection import AdvectionTerm, VelocityField
 from .boundary_conditions.dirichlet_bc import (
     DirichletBC,
@@ -45,10 +44,9 @@
     as_mapped_function,
     get_interpolation_points,
 )
-from .problem import ProblemBase
 from .hydrogen_transport_problem import (
-    HydrogenTransportProblemDiscontinuous,
     HydrogenTransportProblem,
+    HydrogenTransportProblemDiscontinuous,
     HydrogenTransportProblemDiscontinuousChangeVar,
 )
 from .initial_condition import (
@@ -60,6 +58,7 @@
 from .mesh.mesh import Mesh
 from .mesh.mesh_1d import Mesh1D
 from .mesh.mesh_from_xdmf import MeshFromXDMF
+from .problem import ProblemBase
 from .reaction import Reaction
 from .settings import Settings
 from .source import HeatSource, ParticleSource, SourceBase

src/festim/boundary_conditions/__init__.py

@@ -1,11 +1,18 @@
-from .dirichlet_bc import FixedConcentrationBC, FixedTemperatureBC
-from .flux_bc import HeatFluxBC, ParticleFluxBC
-from .surface_reaction import SurfaceReactionBC
+from .dirichlet_bc import DirichletBCBase, FixedConcentrationBC, FixedTemperatureBC
+from .flux_bc import FluxBCBase, HeatFluxBC, ParticleFluxBC
+from .henrys_bc import HenrysBC
+from .sieverts_bc import SievertsBC
+from .surface_reaction import SurfaceReactionBC, SurfaceReactionBCpartial
 
 __all__ = [
+    "DirichletBCBase",
     "FixedConcentrationBC",
     "FixedTemperatureBC",
+    "FluxBCBase",
+    "HeatFluxBC",
+    "HenrysBC",
     "ParticleFluxBC",
+    "SievertsBC",
     "SurfaceReactionBC",
-    "HeatFluxBC",
+    "SurfaceReactionBCpartial",
 ]

src/festim/boundary_conditions/dirichlet_bc.py

@@ -3,10 +3,10 @@
 import numpy as np
 import numpy.typing as npt
 import ufl
-from dolfinx import fem
-from dolfinx import mesh as _mesh
 import ufl.core
 import ufl.core.expr
+from dolfinx import fem
+from dolfinx import mesh as _mesh
 
 from festim import helpers
 from festim import subdomain as _subdomain
@@ -152,10 +152,13 @@ class FixedConcentrationBC(DirichletBCBase):
 
     Examples:
 
-        .. highlight:: python
-        .. code-block:: python
+        .. testsetup:: FixedConcentrationBC
+
+            from festim import FixedConcentrationBC, SurfaceSubdomain
+            my_subdomain = SurfaceSubdomain(id=1)
+
+        .. testcode:: FixedConcentrationBC
 
-            from festim import FixedConcentrationBC
             FixedConcentrationBC(subdomain=my_subdomain, value=1, species="H")
             FixedConcentrationBC(subdomain=my_subdomain,
                                  value=lambda x: 1 + x[0], species="H")

src/festim/boundary_conditions/flux_bc.py

@@ -3,15 +3,22 @@
 from dolfinx import fem
 
 import festim as F
+from festim.subdomain.surface_subdomain import SurfaceSubdomain
 
 
 class FluxBCBase:
     """
     Flux boundary condition class
 
     Ensuring the gradient of the solution u at a boundary:
-    -A * grad(u) * n = f
-    where A is some material property (diffusivity for particle flux and thermal conductivity for heat flux), n is the outwards normal vector of the boundary, f is a function of space and time.
+
+    .. math::
+
+        -A \\nabla u \\cdot \\mathbf{n} = f
+
+    where :math:`A` is some material property (diffusivity for particle flux and thermal
+    conductivity for heat flux), :math:`\\mathbf{n}` is the outwards normal vector of
+    the boundary, :math:`f` is a function of space and time.
 
 
     Args:
@@ -30,7 +37,7 @@ class FluxBCBase:
 
     """
 
-    def __init__(self, subdomain, value):
+    def __init__(self, subdomain: SurfaceSubdomain, value):
         self.subdomain = subdomain
         self.value = value
 
@@ -47,10 +54,10 @@ def value_fenics(self, value):
             self._value_fenics = value
             return
         if not isinstance(
-            value, (fem.Function, fem.Constant, np.ndarray, ufl.core.expr.Expr)
+            value, fem.Function | fem.Constant | np.ndarray | ufl.core.expr.Expr
         ):
             raise TypeError(
-                f"Value must be a dolfinx.fem.Function, dolfinx.fem.Constant, np.ndarray or ufl.core.expr.Expr not {type(value)}"
+                f"Value must be a dolfinx.fem.Function, dolfinx.fem.Constant, np.ndarray or ufl.core.expr.Expr not {type(value)}"  # noqa: E501
             )
         self._value_fenics = value
 
@@ -158,17 +165,22 @@ class ParticleFluxBC(FluxBCBase):
             where "name" is the variable name in the callable value and species is a festim.Species object.
 
 
-    Usage:
-    .. testcode::
+    Examples:
+
+        .. testsetup:: ParticleFluxBC
 
-        from festim import ParticleFluxBC
+            from festim import SurfaceSubdomain, ParticleFluxBC, Species
+            my_subdomain = SurfaceSubdomain(id=1)
+            species1 = Species(name="1")
 
-        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:: 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={}):
@@ -242,14 +254,20 @@ class HeatFluxBC(FluxBCBase):
             update the value_fenics
 
 
-    Usage:
-    .. testcode::
+    Examples:
+
+        .. testsetup:: HeatFluxBC
+
+                from festim import SurfaceSubdomain, HeatFluxBC, Species
+                my_subdomain = SurfaceSubdomain(id=1)
+                species1 = Species(name="1")
+
+        .. testcode:: HeatFluxBC
 
-        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)
+            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):

src/festim/boundary_conditions/henrys_bc.py

@@ -1,15 +1,16 @@
 import ufl
 
-import festim as F
+from festim import k_B
+from festim.boundary_conditions import FixedConcentrationBC
 
 
 def henrys_law(T, H_0, E_H, pressure):
     """Applies the Henry's law to compute the concentration at the boundary"""
-    H = H_0 * ufl.exp(-E_H / F.k_B / T)
+    H = H_0 * ufl.exp(-E_H / k_B / T)
     return H * pressure
 
 
-class HenrysBC(F.DirichletBC):
+class HenrysBC(FixedConcentrationBC):
     """
     Henrys boundary condition class
 
@@ -33,13 +34,20 @@ class HenrysBC(F.DirichletBC):
         E_H (float or fem.Constant): the Henrys constant activation energy (eV)
         pressure (float or callable): the pressure at the boundary (Pa)
 
-    Usage:
-        >>> from festim import HenrysBC
-        >>> HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=1e5, species="H")
-        >>> HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda x: 1e5 + x[0], species="H")
-        >>> HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda t: 1e5 + t, species="H")
-        >>> HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda T: 1e5 + T, species="H")
-        >>> HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda x, t: 1e5 + x[0] + t, species="H")
+    Examples:
+
+        .. testsetup:: HenrysBC
+
+            from festim import HenrysBC, SurfaceSubdomain
+            my_subdomain = SurfaceSubdomain(id=1)
+
+        .. testcode:: HenrysBC
+
+            HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=1e5, species="H")
+            HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda x: 1e5 + x[0], species="H")
+            HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda t: 1e5 + t, species="H")
+            HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda T: 1e5 + T, species="H")
+            HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda x, t: 1e5 + x[0] + t, species="H")
     """
 
     def __init__(self, subdomain, H_0, E_H, pressure, species) -> None:

src/festim/boundary_conditions/sieverts_bc.py

@@ -1,15 +1,16 @@
 import ufl
 
-import festim as F
+from festim import k_B
+from festim.boundary_conditions import FixedConcentrationBC
 
 
 def sieverts_law(T, S_0, E_S, pressure):
     """Applies the Sieverts law to compute the concentration at the boundary"""
-    S = S_0 * ufl.exp(-E_S / F.k_B / T)
+    S = S_0 * ufl.exp(-E_S / k_B / T)
     return S * pressure**0.5
 
 
-class SievertsBC(F.DirichletBC):
+class SievertsBC(FixedConcentrationBC):
     """
     Sieverts boundary condition class
 
@@ -33,13 +34,20 @@ class SievertsBC(F.DirichletBC):
         E_S (float or fem.Constant): the Sieverts constant activation energy (eV)
         pressure (float or callable): the pressure at the boundary (Pa)
 
-    Usage:
-        >>> from festim import SievertsBC
-        >>> SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=1e5, species="H")
-        >>> SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda x: 1e5 + x[0], species="H")
-        >>> SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda t: 1e5 + t, species="H")
-        >>> SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda T: 1e5 + T, species="H")
-        >>> SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda x, t: 1e5 + x[0] + t, species="H")
+    Examples:
+
+        .. testsetup:: SievertsBC
+
+            from festim import SievertsBC, SurfaceSubdomain
+            my_subdomain = SurfaceSubdomain(id=1)
+
+        .. testcode:: SievertsBC
+
+            SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=1e5, species="H")
+            SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda x: 1e5 + x[0], species="H")
+            SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda t: 1e5 + t, species="H")
+            SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda T: 1e5 + T, species="H")
+            SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda x, t: 1e5 + x[0] + t, species="H")
     """
 
     def __init__(self, subdomain, S_0, E_S, pressure, species) -> None: