commit dadc60164aa91c85804aeb76fb9700304872203b
Author: Carles Marti <carles.marti-aliod@ens-lyon.fr>
Date:   Wed Jun 17 11:36:20 2020 +0200

    Minor changes in variable names, order in functions, documentation and TODOS

diff --git a/modules/screening.py b/modules/screening.py
index 597aef3..54ceff5 100644
--- a/modules/screening.py
+++ b/modules/screening.py
@@ -24,18 +24,19 @@ def get_vect_angle(v1, v2, degrees=False):
 def vect_avg(vects):
     """Computes the element-wise mean of a set of vectors.
 
-    @param vects: np.ndarray with shape (num_vectors, length_vector).
+    @param vects: list of lists-like: containing the vectors (num_vectors,
+        length_vector).
     @return: vector average computed doing the element-wise mean.
     """
     from utilities import try_command
     err = "vect_avg parameter vects must be a list-like, able to be converted" \
           " np.array"
-    vects = try_command(np.array, [(ValueError, err)], vects)
-    if len(vects.shape) == 1:
-        return vects
+    array = try_command(np.array, [(ValueError, err)], vects)
+    if len(array.shape) == 1:
+        return array
     else:
-        num_vects = vects.shape[1]
-        return np.array([np.average(vects[:, i]) for i in range(num_vects)])
+        num_vects = array.shape[1]
+        return np.array([np.average(array[:, i]) for i in range(num_vects)])
 
 
 def get_atom_coords(atoms: ase.Atoms, ctrs_list):
@@ -65,7 +66,7 @@ def get_atom_coords(atoms: ase.Atoms, ctrs_list):
     return np.array(coords)
 
 
-def add_adsorbate(slab, adsorbate, surf_pos, mol_pos, height, offset=None,
+def add_adsorbate(slab, adsorbate, site_coord, ctr_coord, height, offset=None,
                   norm_vect=(0, 0, 1)):
     """Add an adsorbate to a surface.
 
@@ -76,29 +77,29 @@ def add_adsorbate(slab, adsorbate, surf_pos, mol_pos, height, offset=None,
     @param slab: ase.Atoms object containing the coordinates of the surface
     @param adsorbate: ase.Atoms object containing the coordinates of the
         adsorbate.
-    @param surf_pos: The coordinates of the adsorption site on the surface.
-    @param mol_pos: The coordinates of the adsorption center in the molecule.
-    @param height: The height above the surface
+    @param site_coord: The coordinates of the adsorption site on the surface.
+    @param ctr_coord: The coordinates of the adsorption center in the molecule.
+    @param height: The height above the surface where to adsorb.
     @param offset: Offsets the adsorbate by a number of unit cells. Mostly
         useful when adding more than one adsorbate.
     @param norm_vect: The vector perpendicular to the surface.
     """
     info = slab.info.get('adsorbate_info', {})
-    pos = np.array([0.0, 0.0, 0.0])  # (x, y, z) part
+    pos = np.array([0.0, 0.0, 0.0])  # part of absolute coordinates
     spos = np.array([0.0, 0.0, 0.0])  # part relative to unit cell
-    norm_vect = np.array(norm_vect) / np.linalg.norm(norm_vect)
+    norm_vect_u = np.array(norm_vect) / np.linalg.norm(norm_vect)
     if offset is not None:
         spos += np.asarray(offset, float)
-    if isinstance(surf_pos, str):
+    if isinstance(site_coord, str):
         # A site-name:
         if 'sites' not in info:
             raise TypeError('If the atoms are not made by an ase.build '
                             'function, position cannot be a name.')
-        if surf_pos not in info['sites']:
-            raise TypeError('Adsorption site %s not supported.' % surf_pos)
-        spos += info['sites'][surf_pos]
+        if site_coord not in info['sites']:
+            raise TypeError('Adsorption site %s not supported.' % site_coord)
+        spos += info['sites'][site_coord]
     else:
-        pos += surf_pos
+        pos += site_coord
     if 'cell' in info:
         cell = info['cell']
     else:
@@ -112,9 +113,9 @@ def add_adsorbate(slab, adsorbate, surf_pos, mol_pos, height, offset=None,
     else:
         # Assume it is a string representing a single Atom
         ads = ase.Atoms([ase.Atom(adsorbate)])
-    pos += height * norm_vect
+    pos += height * norm_vect_u
     # Move adsorbate into position
-    ads.translate(pos - mol_pos)
+    ads.translate(pos - ctr_coord)
     # Attach the adsorbate
     slab.extend(ads)
 
@@ -132,7 +133,7 @@ def ads_chemcat(site, ctr, pts_angle):
 
 
 def adsorb_confs(conf_list, surf, ads_ctrs, sites, algo, num_pts, neigh_ctrs,
-                 norm_vect):
+                 norm_vect, coll_bttm):
     """Generates a number of adsorbate-surface structure coordinates.
 
     Given a list of conformers, a surface, a list of atom indices (or list of
@@ -148,6 +149,7 @@ def adsorb_confs(conf_list, surf, ads_ctrs, sites, algo, num_pts, neigh_ctrs,
     @param neigh_ctrs: the indices of the neighboring atoms to the adsorption
     atoms.
     @param norm_vect: The vector perpendicular to the surface.
+    @param coll_bttm: The lowermost height for which to detect a collision
     @return: list of ase.Atoms for the adsorbate-surface structures
     """
     surf_ads_list = []
@@ -158,11 +160,12 @@ def adsorb_confs(conf_list, surf, ads_ctrs, sites, algo, num_pts, neigh_ctrs,
         for site in sites_coords:
             for i, molec_ctr in enumerate(molec_ctr_coords):
                 if algo == 'euler':
-                    surf_ads_list.append(ads_euler(conf, surf, site, molec_ctr,
+                    surf_ads_list.extend(ads_euler(conf, surf, molec_ctr, site,
                                                    num_pts, norm_vect,
+                                                   coll_bttm,
                                                    molec_neigh_coords[i]))
                 elif algo == 'chemcat':
-                    surf_ads_list.append(ads_chemcat(site, molec_ctr, num_pts))
+                    surf_ads_list.extend(ads_chemcat(site, molec_ctr, num_pts))
     return surf_ads_list
 
 
@@ -185,18 +188,19 @@ def run_screening(inp_vars):
         raise ValueError(err)
 
     conf_list = read_coords(inp_vars['code'], 'isolated', 'rdkit')
-    # TODO Implement neighbors algorithm
+    # TODO Implement neighbors algorithm / align molecule to surface
     # neigh_list = get_neighbors(conf_list[0], inp_vars['molec_ads_ctrs'])
     conf_enrgs = read_energies(inp_vars['code'], 'isolated')
     mois = np.array([get_moments_of_inertia(conf)[0] for conf in conf_list])
     rmsd_mtx = get_rmsd(conf_list)
-    exemplars = clustering(rmsd_mtx)
-    conf_list = [conf_list[idx] for idx in exemplars]
-    conf_list = [rdkit_mol_to_ase_atoms(conf) for conf in conf_list]
+    exemplars = clustering(rmsd_mtx)  # TODO Kind of Clustering
+    clust_conf_list = [conf_list[idx] for idx in exemplars]
+    conf_list = [rdkit_mol_to_ase_atoms(conf) for conf in clust_conf_list]
     surf = adapt_format('ase', inp_vars['surf_file'])
     surf_ads_list = adsorb_confs(conf_list, surf, inp_vars['molec_ads_ctrs'],
                                  inp_vars['sites'], inp_vars['ads_algo'],
                                  inp_vars['sample_points_per_angle'],
                                  inp_vars['molec_neigh_ctrs'],
-                                 inp_vars['surf_norm_vect'])
+                                 inp_vars['surf_norm_vect'],
+                                 inp_vars['collision_bottom'])
     run_calc('screening', inp_vars, surf_ads_list)
