update docstrings

Appli-iso3dfd/ACO.py

@@ -9,24 +9,23 @@ import tools
 import launcher_SUBP
 
 def ACO(Me, NbP, comm, alpha, rho, Q, nb_ants, tau_0, n_iter, n1_max=256, n2_max=256, n3_max=256,
-        fancy_strategy='AS', sub_threshold=0.1, sup_threshold=10**9,
-        nb_threads=8, reps=100):
+        fancy_strategy='AS', sub_threshold=0.1, sup_threshold=10**9, nb_threads=8, reps=100):
     """ Ant colony optimization of the cache blocking parameters for the execution of
     the iso3dfd programm.
 
     Args:
         Me (int): index of process running the function
         NbP (int): number of processes
-        comm (): mpi communication object
+        comm (MPI object): mpi communication object
         alpha (float): hyperparameter alpha of ACO
         rho (float): evaporation rate between 0 and 1
         Q (float): quantity of pheromones deposited by an ant on an edge
         nb_ants (int): number of ants
         tau_0 (float): initial quantity of pheromones on each edge
         n_iter (int): number of cycles done for ACO
-        n1_max (int, optional): Maximal first dimension of matrix. Defaults to 256.
-        n2_max (int, optional): Maximal second dimension of matrix. Defaults to 256.
-        n3_max (int, optional): Maximal third dimension of matrix. Defaults to 256.
+        n1_max (int, optional): Maximal first dimension of the problem. Defaults to 256.
+        n2_max (int, optional): Maximal second dimension of the problem. Defaults to 256.
+        n3_max (int, optional): Maximal third dimension of the problem. Defaults to 256.
         fancy_strategy (string, optional): Strategy used to update tau. Defaults to 'AS'.
         sub_threshold (float, optional): Inferior threshold for Min-Max strategy. Defaults to 0.1.
         sup_threshold (float, optional): Superior threshold for Min-Max strategy. Defaults to 10**9.
@@ -34,7 +33,7 @@ def ACO(Me, NbP, comm, alpha, rho, Q, nb_ants, tau_0, n_iter, n1_max=256, n2_max
         reps (int, optional): Max number of iteration before stopping the process. Defaults to 100.
 
     Returns:
-        (np.array, float): optimal path [cbx, cby, cbz] and the associated cost
+        (tuple: list, float): optimal path [n1, n2, n3, cbx, cby, cbz] and the associated cost
     """
 
     # Initialisation of the graph and pheromon matrix

Appli-iso3dfd/compute_path.py

@@ -4,6 +4,24 @@ import numpy as np
 #tau : pheromone matrix, size : 1 + n1_size + n2_size + n3_size + n1_max//16 + n2_max x 1 + n1_size + n2_size + n3_size + n1//16 + n2 + n3
 
 def proba(i, alpha, tau, n1_size, n2_size, n3_size, n_cbx, n_cby, n_cbz):
+  """Based on i, deduce which parameter you want to choose from. 
+  Returns possibles choices and associated weights. 
+
+  Args:
+      i (int): Index in matrix
+      alpha (float): Parameter to compute weights
+      tau (np.array): Pheromon matrix
+      n1_size (int): First dimension of the problem
+      n2_size (int): Second dimension of the problem
+      n3_size (int): Third dimension of the problem
+      n_cbx (int): First dimension of the cache
+      n_cby (int): Second dimension of the cache
+      n_cbz (int): Third dimension of the cache
+
+  Returns:
+      (tuple: np.array, np.array): possibles choices (sequence) and their weights (weights)
+  """
+
     n1_max = (2**(n1_size-1)) * 16
     n2_max = (2**(n2_size-1)) * 256
     n3_max = (2**(n3_size-1)) * 256
@@ -46,6 +64,18 @@ def proba(i, alpha, tau, n1_size, n2_size, n3_size, n_cbx, n_cby, n_cbz):
     return (sequence, weights)
 
 def compute_path(tau, alpha, n1_size, n2_size, n3_size):
+  """From the sizes of the problem and the pheromon matrix, give a ant path.
+
+  Args:
+      tau (np.array): Pheromon matrix
+      alpha (foat): Parameter impacting weights when choosing path
+      n1_size (int): First dimension of the problem
+      n2_size (int): Second dimension of the problem
+      n3_size (int): Third dimension of the problem
+
+  Returns:
+      (list[int]): path choosen by the ant (n1, n2, n3, cbx, cby, cbz)
+  """
 
     #n_cbx, n_cby, n_cbz will be initialized after the choice of n1, n2, n3
     n_cbx = 0

Appli-iso3dfd/launcher_SUBP.py

@@ -13,17 +13,17 @@ def deploySUBP(n1, n2, n3, nb_threads, reps, cbx, cby, cbz):
     """Launch MPI execution based on exe file in bin/, and returns average fitness
 
     Args:
-        n1 (int): First dimension of matrix.
-        n2 (int): Second dimension of matrix.
-        n3 (int): Third dimension of matrix.
-        nb_threads (int): Number of threads per MPI process.
-        reps (int): Max number of iteration before stopping the process.
-        cbx (int): First cache blocking matrix dimension.
-        cby (int): Second cache blocking matrix dimension.
-        cbz (int): Third cache blocking matrix dimension.
+        n1 (int): First dimension of the problem
+        n2 (int): Second dimension of the problem
+        n3 (int): Third dimension of the problem
+        nb_threads (int): Number of threads per MPI process
+        reps (int): Max number of iteration before stopping the process
+        cbx (int): First dimension of the cache
+        cby (int): Second dimension of the cache
+        cbz (int): Third dimension of the cache
 
     Returns:
-        float: calculated fitness (average of MPI processes executions caracteristic)
+        float: calculated fitness (average of MPI processes executions throughputs)
     """
 
     # Get the name of the exe file

Appli-iso3dfd/tools.py

@@ -100,14 +100,14 @@ def add_pheromones(tau, paths, costs, Q, n1_size, n2_size, n3_size, n_cbx, n_cby
         paths (np.array): Array of the paths taken by the ants: paths[i]=(cb_x//16,cb_y,cb_z)
         costs (np.array): Column array containing the costs.
         Q (float): quantity of pheromones added by an ant on an edge
-        n1_size (int): First dimension of matrix
-        n2_size (int): Second dimension of matrix
-        n3_size (int): Third dimension of matrix
+        n1_size (int): First dimension of the problem
+        n2_size (int): Second dimension of the problem
+        n3_size (int): Third dimension of problem
         n_cbx (int): First dimension of the cache
         n_cby (int): Second dimension of the cache
 
     Returns:
-        (np.array, list, float): the updated pheromon matrix, the best path and the associated cost
+        (np.array): the updated pheromon matrix
     """
 
     for i in range(len(costs)):