Merge remote-tracking branch 'upstream/main' into CustomSolver

.github/workflows/ci.yml

@@ -34,6 +34,6 @@ jobs:
         pytest test/ --cov festim --cov-report xml --cov-report term
     
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         token: ${{ secrets.CODECOV_TOKEN }}

festim/exports/derived_quantities/average_surface.py

@@ -3,9 +3,41 @@
 
 
 class AverageSurface(SurfaceQuantity):
+    """
+    Computes the average value of a field on a given surface
+    int(f ds) / int (1 * ds)
+
+    Args:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+
+    Attributes:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+        title (str): the title of the derived quantity
+        show_units (bool): show the units in the title in the derived quantities
+            file
+        function (dolfin.function.function.Function): the solution function of
+            the field
+
+    Notes:
+        Units are in H/m3 for hydrogen concentration and K for temperature
+
+    """
+
     def __init__(self, field, surface) -> None:
         super().__init__(field=field, surface=surface)
-        self.title = "Average {} surface {}".format(self.field, self.surface)
+
+    @property
+    def title(self):
+        quantity_title = f"Average {self.field} surface {self.surface}"
+        if self.show_units:
+            if self.field == "T":
+                return quantity_title + " (K)"
+            else:
+                return quantity_title + " (H m-3)"
+        else:
+            return quantity_title
 
     def compute(self):
         return f.assemble(self.function * self.ds(self.surface)) / f.assemble(

festim/exports/derived_quantities/average_volume.py

@@ -3,9 +3,40 @@
 
 
 class AverageVolume(VolumeQuantity):
+    """
+    Computes the average value of a field in a given volume
+    int(f dx) / int (1 * dx)
+
+    Args:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        volume (int): the volume id
+
+    Attributes:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        volume (int): the volume id
+        title (str): the title of the derived quantity
+        show_units (bool): show the units in the title in the derived quantities
+            file
+        function (dolfin.function.function.Function): the solution function of
+            the field
+
+    Notes:
+        Units are in H/m3 for hydrogen concentration and K for temperature
+    """
+
     def __init__(self, field, volume: int) -> None:
-        super().__init__(field, volume)
-        self.title = "Average {} volume {}".format(self.field, self.volume)
+        super().__init__(field=field, volume=volume)
+
+    @property
+    def title(self):
+        quantity_title = f"Average {self.field} volume {self.volume}"
+        if self.show_units:
+            if self.field == "T":
+                return quantity_title + " (K)"
+            else:
+                return quantity_title + " (H m-3)"
+        else:
+            return quantity_title
 
     def compute(self):
         return f.assemble(self.function * self.dx(self.volume)) / f.assemble(

festim/exports/derived_quantities/derived_quantities.py

@@ -23,6 +23,8 @@ class DerivedQuantities(list):
         nb_iterations_between_exports (int, optional): number of
             iterations between each export. If None, the file will be
             exported at the last timestep. Defaults to None.
+        show_units (bool, optional): will show the units of each
+            derived quantity in the title in export
     """
 
     def __init__(
@@ -31,6 +33,7 @@ def __init__(
         filename: str = None,
         nb_iterations_between_compute: int = 1,
         nb_iterations_between_exports: int = None,
+        show_units=False,
     ) -> None:
         # checks that input is list
         if len(args) == 0:
@@ -43,8 +46,9 @@ def __init__(
         self.filename = filename
         self.nb_iterations_between_compute = nb_iterations_between_compute
         self.nb_iterations_between_exports = nb_iterations_between_exports
+        self.show_units = show_units
 
-        self.data = [self.make_header()]
+        self.data = []
         self.t = []
 
     @property
@@ -108,6 +112,12 @@ def filename(self, value):
     def make_header(self):
         header = ["t(s)"]
         for quantity in self:
+            quantity.show_units = self.show_units
+            if self.show_units is False:
+                warnings.warn(
+                    "The current derived_quantities title style will be deprecated in a future release, please use show_units=True instead",
+                    DeprecationWarning,
+                )
             header.append(quantity.title)
         return header
 
@@ -139,6 +149,11 @@ def compute(self, t):
                 value = quantity.compute(self.volume_markers)
             else:
                 value = quantity.compute()
+
+            # check if first time writing data
+            if len(self.data) == 0:
+                self.data = [self.make_header()]
+
             quantity.data.append(value)
             quantity.t.append(t)
             row.append(value)

festim/exports/derived_quantities/derived_quantity.py

@@ -3,6 +3,8 @@
 
 class DerivedQuantity(Export):
     """
+    Parent class of all derived quantities
+
     Args:
         field (str, int):  the field ("solute", 0, 1, "T", "retention")
     """
@@ -18,16 +20,19 @@ def __init__(self, field) -> None:
         self.Q = None
         self.data = []
         self.t = []
+        self.show_units = False
 
 
 class VolumeQuantity(DerivedQuantity):
-    def __init__(self, field: str or int, volume: int) -> None:
-        """DerivedQuantity relative to a volume
+    """DerivedQuantity relative to a volume
+
+    Args:
+        field (str, int): the field ("solute", 0, 1, "T", "retention")
+        volume (int): the volume id
 
-        Args:
-            field (str, int): the field ("solute", 0, 1, "T", "retention")
-            volume (int): the volume id
-        """
+    """
+
+    def __init__(self, field: str or int, volume: int) -> None:
         super().__init__(field)
         self.volume = volume
 
@@ -44,13 +49,16 @@ def volume(self, value):
 
 
 class SurfaceQuantity(DerivedQuantity):
+    """DerivedQuantity relative to a surface
+
+    Args:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+
+    """
+
     def __init__(self, field: str or int, surface: int) -> None:
-        """DerivedQuantity relative to a surface
 
-        Args:
-            field (str, int):  the field ("solute", 0, 1, "T", "retention")
-            surface (int): the surface id
-        """
         super().__init__(field)
         self.surface = surface
 

festim/exports/derived_quantities/hydrogen_flux.py

@@ -2,7 +2,25 @@
 
 
 class HydrogenFlux(SurfaceFlux):
-    """Equivalent to SurfaceFlux("solute", ...)"""
+    """
+    Computes the surface flux of hydrogen at a given surface
+
+    Args:
+        surface (int): the surface id
+
+    Attribtutes
+        field (str): the hydrogen solute field
+        surface (int): the surface id
+        title (str): the title of the derived quantity
+        show_units (bool): show the units in the title in the derived quantities
+            file
+        function (dolfin.function.function.Function): the solution function of
+            the hydrogen solute field
+
+    Notes:
+        units are in H/m2/s in 1D, H/m/s in 2D and H/s in 3D domains
+
+    """
 
     def __init__(self, surface) -> None:
         super().__init__(field="solute", surface=surface)

festim/exports/derived_quantities/maximum_surface.py

@@ -1,20 +1,43 @@
-from festim import DerivedQuantity
+from festim import SurfaceQuantity
 import fenics as f
 import numpy as np
 
 
-class MaximumSurface(DerivedQuantity):
+class MaximumSurface(SurfaceQuantity):
     """
+    Computes the maximum value of a field on a given surface
+
     Args:
-        field (str): the field from which the maximum
-            is computed (ex: "solute", "retention", "T"...)
-        surface (int): the surface id where the maximum is computed
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+
+    Attributes:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+        title (str): the title of the derived quantity
+        show_units (bool): show the units in the title in the derived quantities
+            file
+        function (dolfin.function.function.Function): the solution function of
+            the field
+
+    Notes:
+        Units are in H/m3 for hydrogen concentration and K for temperature
+
     """
 
     def __init__(self, field, surface) -> None:
-        super().__init__(field)
-        self.surface = surface
-        self.title = "Maximum {} surface {}".format(self.field, self.surface)
+        super().__init__(field=field, surface=surface)
+
+    @property
+    def title(self):
+        quantity_title = f"Maximum {self.field} surface {self.surface}"
+        if self.show_units:
+            if self.field == "T":
+                return quantity_title + " (K)"
+            else:
+                return quantity_title + " (H m-3)"
+        else:
+            return quantity_title
 
     def compute(self, surface_markers):
         """Maximum of f over subdomains facets marked with self.surface"""

festim/exports/derived_quantities/maximum_volume.py

@@ -4,9 +4,40 @@
 
 
 class MaximumVolume(VolumeQuantity):
+    """
+    Computes the maximum value of a field in a given volume
+
+    Args:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        volume (int): the volume id
+
+    Attributes:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        volume (int): the volume id
+        title (str): the title of the derived quantity
+        show_units (bool): show the units in the title in the derived quantities
+            file
+        function (dolfin.function.function.Function): the solution function for
+            the field
+
+    notes:
+        Units are in H/m3 for hydrogen concentration and K for temperature
+
+    """
+
     def __init__(self, field, volume) -> None:
-        super().__init__(field, volume=volume)
-        self.title = "Maximum {} volume {}".format(self.field, self.volume)
+        super().__init__(field=field, volume=volume)
+
+    @property
+    def title(self):
+        quantity_title = f"Maximum {self.field} volume {self.volume}"
+        if self.show_units:
+            if self.field == "T":
+                return quantity_title + " (K)"
+            else:
+                return quantity_title + " (H m-3)"
+        else:
+            return quantity_title
 
     def compute(self, volume_markers):
         """Minimum of f over subdomains cells marked with self.volume"""

festim/exports/derived_quantities/minimum_surface.py

@@ -1,20 +1,43 @@
-from festim import DerivedQuantity
+from festim import SurfaceQuantity
 import fenics as f
 import numpy as np
 
 
-class MinimumSurface(DerivedQuantity):
+class MinimumSurface(SurfaceQuantity):
     """
+    Computes the minimum value of a field on a given surface
+
     Args:
-        field (str): the field from which the minimum
-            is computed (ex: "solute", "retention", "T"...)
-        surface (int): the surface id where the minimum is computed
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+
+    Attributes:
+        field (str, int):  the field ("solute", 0, 1, "T", "retention")
+        surface (int): the surface id
+        title (str): the title of the derived quantity
+        show_units (bool): show the units in the title in the derived quantities
+            file
+        function (dolfin.function.function.Function): the solution function of
+            the field
+
+    Notes:
+        Units are in H/m3 for hydrogen concentration and K for temperature
+
     """
 
     def __init__(self, field, surface) -> None:
-        super().__init__(field)
-        self.surface = surface
-        self.title = "Minimum {} surface {}".format(self.field, self.surface)
+        super().__init__(field=field, surface=surface)
+
+    @property
+    def title(self):
+        quantity_title = f"Minimum {self.field} surface {self.surface}"
+        if self.show_units:
+            if self.field == "T":
+                return quantity_title + " (K)"
+            else:
+                return quantity_title + " (H m-3)"
+        else:
+            return quantity_title
 
     def compute(self, surface_markers):
         """Minimum of f over subdomains facets marked with self.surface"""