Added documentation to 'ANN_Data_Generator'.

ANN_Data_Generator.py

@@ -9,6 +9,7 @@ TODO: Improve verbose output -> Done
 TODO: Change order of methods -> Done
 TODO: Fix bug in initialization of input matrix -> Done
 TODO: Improve function selection (more even distribution) -> Done
+TODO: Add documentation -> Done
 
 """
 
@@ -21,8 +22,45 @@ import timeit
 
 
 class TrainingDataGenerator(object):
+    """Class for training data generator.
+
+    Generate random training data for given initial conditions.
+
+    Attributes
+    ----------
+    smooth_functions : list
+        List of smooth initial/continuous conditions.
+    troubled_functions : list
+        List of discontinuous initial conditions.
+    data_dir : str
+        Path to directory in which training data is saved.
+
+    Methods
+    -------
+    build_training_data()
+        Builds random training data.
+
+    """
     def __init__(self, initial_conditions, left_bound=-1, right_bound=1, balance=0.5,
                  stencil_length=3, directory=None):
+        """Initializes TrainingDataGenerator.
+
+        Parameters
+        ----------
+        initial_conditions : list
+            List of names of initial conditions for training.
+        left_bound : float, optional
+            Left boundary of interval. Default: -1.
+        right_bound : float, optional
+            Right boundary of interval. Default: 1.
+        balance: float, optional
+            Ratio between smooth and discontinuous training data. Default: 0.5.
+        stencil_length : int, optional
+            Size of training data array. Default: 3.
+        directory : str, optional
+            Path to directory in which training data is saved. Default: 'test_data'.
+
+        """
         self._balance = balance
         self._left_bound = left_bound
         self._right_bound = right_bound
@@ -49,6 +87,21 @@ class TrainingDataGenerator(object):
             os.makedirs(self._data_dir)
 
     def build_training_data(self, num_samples):
+        """Builds random training data.
+
+        Creates training data consisting of random ANN input and saves it.
+
+        Parameters
+        ----------
+        num_samples : int
+            Number of training data samples to generate.
+
+        Returns
+        -------
+        data_dict : dict
+            Dictionary containing input (normalized and non-normalized) and output data.
+
+        """
         tic = timeit.default_timer()
         print('Calculating training data...\n')
         data_dict = self._calculate_data_set(num_samples)
@@ -60,6 +113,22 @@ class TrainingDataGenerator(object):
         return data_dict
 
     def _calculate_data_set(self, num_samples):
+        """Calculates random training data of given stencil length.
+
+        Creates training data with a given ratio between smooth and discontinuous samples and
+        fixed stencil length.
+
+        Parameters
+        ----------
+        num_samples : int
+            Number of training data samples to generate.
+
+        Returns
+        -------
+        dict
+            Dictionary containing input (normalized and non-normalized) and output data.
+
+        """
         num_smooth_samples = round(num_samples * self._balance)
         smooth_input, smooth_output = self._generate_cell_data(num_smooth_samples,
                                                                self._smooth_functions, True)
@@ -84,6 +153,28 @@ class TrainingDataGenerator(object):
                 'normalized_input': norm_input_matrix}
 
     def _generate_cell_data(self, num_samples, initial_conditions, is_smooth):
+        """Generates random training input and output.
+
+        Generates random training input and output for either smooth or discontinuous
+        initial_conditions.
+
+        Parameters
+        ----------
+        num_samples : int
+            Number of training data samples to generate.
+        initial_conditions : list
+            List of names of initial conditions for training.
+        is_smooth : boolean
+            Flag whether initial conditions are smooth.
+
+        Returns
+        -------
+        input_data : np.array
+            Array containing input data.
+        output_data : np.array
+            Array containing output data.
+
+        """
         troubled_indicator = 'without' if is_smooth else 'with'
         print('Calculating data ' + troubled_indicator + ' troubled cells...')
         print('Samples to complete:', num_samples)
@@ -131,6 +222,20 @@ class TrainingDataGenerator(object):
         return input_data, output_data
 
     def _build_stencil(self):
+        """Builds random stencil.
+
+        Calculates fixed number of cell centers around a random point in a given 1D domain.
+
+        Returns
+        -------
+        interval : np.array
+            List containing left and right bound of interval.
+        stencil : np.array
+            List of cell centers in stencil.
+        grid_spacing: float
+            Length of cell in grid.
+
+        """
         # Calculating Cell centers for a given 1D domain with n elements, and
         # Calculating Corresponding Legendre Basis Coefficients for given polynomial_degree
         # Create stencil and basis_coefficients for smooth_function mapped onto stencil
@@ -156,6 +261,19 @@ class TrainingDataGenerator(object):
 
     @staticmethod
     def _normalize_data(input_data):
+        """Normalize data.
+
+        Parameters
+        ----------
+        input_data : np.array
+            Array containing input data.
+
+        Returns
+        -------
+        np.array
+            Array containing normalized input data.
+
+        """
         normalized_input_data = input_data
         for i in range(len(input_data)):
             max_function_value = max(max(np.absolute(input_data[i])), 1)
@@ -163,6 +281,7 @@ class TrainingDataGenerator(object):
         return normalized_input_data
 
     def _save_data(self, data):
+        """Saves data."""
         print('Saving training data.')
         for key in data.keys():
             name = self._data_dir + '/' + key + '_data.npy'