added docstrings

docs/source/api/exports.rst

@@ -15,10 +15,6 @@ Exports
     :members:
     :show-inheritance:
 
-.. autoclass:: TXTExports
-    :members:
-    :show-inheritance:
-
 .. autoclass:: TrapDensityXDMF
     :members:
     :show-inheritance:

festim/exports/txt_export.py

@@ -27,6 +27,8 @@ class TXTExport(festim.Export):
             is the mesh vertices. Each next column is the field profile at the specific
             export time.
         header (str): the header of the exported file.
+        V (fenics.FunctionSpace): the vector-function space for the exported field.
+
     """
 
     def __init__(
@@ -43,8 +45,8 @@ def __init__(
 
         self.data = None
         self.header = None
+        self.V = None
         self._unique_indices = None
-        self._V = None
 
     @property
     def filename(self):
@@ -60,6 +62,17 @@ def filename(self, value):
         self._filename = value
 
     def is_it_time_to_export(self, current_time):
+        """
+        Checks if the exported field should be written to a file or not
+        based on the current time and the TXTExport.times
+
+        Args:
+            current_time (float): the current simulation time
+
+        Returns:
+            bool: True if the exported field should be written to a file, else False
+        """
+
         if self.times is None:
             return True
         for time in self.times:
@@ -68,6 +81,21 @@ def is_it_time_to_export(self, current_time):
         return False
 
     def is_last(self, current_time, final_time):
+        """
+        Checks if the current simulation step equals to the last export time.
+        based on the final simulation time, TXTExport.times, and the current time
+
+        Args:
+            current_time (float): the current simulation time.
+            final_time (float, None): the final simulation time.
+
+        Returns:
+            bool: True if simulation is steady (final_time is None), if TXTExport.times
+                are not provided and the current time equals to the final time, or if
+                TXTExport.times are provided and the current time equals to the last time in
+                TXTExport.times, else False.
+        """
+
         if final_time is None:
             # write if steady
             return True
@@ -81,17 +109,32 @@ def is_last(self, current_time, final_time):
                 return True
         return False
 
-    def initialise_TXTExport(self, mesh, project_to_DG=False, materials=None):
+    def initialise(self, mesh, project_to_DG=False, materials=None):
+        """
+        Initialises TXTExport. Depending on the project_to_DG flag, defines a function space (DG1 or CG1)
+        for projection of the exported field. After that, an unsorted array of mesh vertices is created for export.
+        The array is then used to obtain indices of sorted elements for the data export.
+
+        .. note::
+            If DG1 is used, the duplicated vertices in the array are filtered except those near interfaces,
+            The interfaces are defined by ``material.borders`` in the ``Materials`` list.
+
+        Args:
+            mesh (fenics.Mesh): the mesh.
+            project_to_DG (bool): if True, the exported field is projected to a DG1 function space.
+                Defaults to False.
+            materials (festim.Materials): the materials. Defaults to None.
+        """
 
         if project_to_DG:
-            self._V = f.FunctionSpace(mesh, "DG", 1)
+            self.V = f.FunctionSpace(mesh, "DG", 1)
         else:
-            self._V = f.FunctionSpace(mesh, "CG", 1)
+            self.V = f.FunctionSpace(mesh, "CG", 1)
 
-        x = f.interpolate(f.Expression("x[0]", degree=1), self._V)
+        x = f.interpolate(f.Expression("x[0]", degree=1), self.V)
         x_column = np.transpose([x.vector()[:]])
 
-        # if chemical_pot is True or trap_element_type is DG, get indices of duplicates near interfaces
+        # if project_to_DG is True, get indices of duplicates near interfaces
         # and indices of the first elements from a pair of duplicates otherwise
         if project_to_DG:
             # Collect all borders
@@ -122,16 +165,24 @@ def initialise_TXTExport(self, mesh, project_to_DG=False, materials=None):
             self._unique_indices = np.array(unique_indices)
 
         else:
-            # Get list of unique indices as integers
+            # Get list of unique indices
             self._unique_indices = np.argsort(x_column, axis=0)[:, 0]
 
         self.data = x_column[self._unique_indices]
         self.header = "x"
 
     def write(self, current_time, final_time):
+        """
+        Modifies the header and writes the data to a file depending on
+        the current and the final times of a simulation.
+
+        Args:
+            current_time (float): the current simulation time.
+            final_time (float, None): the final simulation time.
+        """
 
         if self.is_it_time_to_export(current_time):
-            solution = f.project(self.function, self._V)
+            solution = f.project(self.function, self.V)
             solution_column = np.transpose(solution.vector()[:])
 
             # if the directory doesn't exist

festim/generic_simulation.py

@@ -393,7 +393,7 @@ def initialise(self):
                     self.settings.chemical_pot
                     or self.settings.traps_element_type == "DG"
                 )
-                export.initialise_TXTExport(
+                export.initialise(
                     self.mesh.mesh,
                     project_to_DG,
                     self.materials,

test/unit/test_exports/test_txt_export.py

@@ -43,7 +43,7 @@ def my_export(self, tmpdir):
     def test_file_exists(self, my_export, function, mesh):
         current_time = 1
         my_export.function = function
-        my_export.initialise_TXTExport(mesh)
+        my_export.initialise(mesh)
         my_export.write(
             current_time=current_time,
             final_time=None,
@@ -54,7 +54,7 @@ def test_file_exists(self, my_export, function, mesh):
     def test_file_doesnt_exist(self, my_export, function, mesh):
         current_time = 10
         my_export.function = function
-        my_export.initialise_TXTExport(mesh)
+        my_export.initialise(mesh)
         my_export.write(
             current_time=current_time,
             final_time=None,
@@ -72,7 +72,7 @@ def test_create_folder(self, my_export, function, mesh):
             + "/folder2"
             + my_export.filename[slash_indx:]
         )
-        my_export.initialise_TXTExport(mesh)
+        my_export.initialise(mesh)
         my_export.write(
             current_time=current_time,
             final_time=None,
@@ -83,7 +83,7 @@ def test_create_folder(self, my_export, function, mesh):
     def test_subspace(self, my_export, function_subspace, mesh):
         current_time = 1
         my_export.function = function_subspace
-        my_export.initialise_TXTExport(mesh)
+        my_export.initialise(mesh)
         my_export.write(
             current_time=current_time,
             final_time=None,
@@ -103,7 +103,7 @@ def test_sorted_by_x(self, my_export, function, mesh):
         """Checks that the exported data is sorted by x"""
         current_time = 1
         my_export.function = function
-        my_export.initialise_TXTExport(mesh)
+        my_export.initialise(mesh)
         my_export.write(
             current_time=current_time,
             final_time=None,
@@ -133,7 +133,7 @@ def test_duplicates(
         """
         current_time = 1
         my_export.function = function
-        my_export.initialise_TXTExport(mesh, project_to_DG, materials)
+        my_export.initialise(mesh, project_to_DG, materials)
         my_export.write(
             current_time=current_time,
             final_time=None,