commit 4e82c42518028d082a166f735e32991aaccb71ca
Author: Carles Martí <carles.marti2@gmail.com>
Date:   Thu Feb 11 19:45:42 2021 +0100

    Extended the documentation

diff --git a/modules/dos_input.py b/modules/dos_input.py
index 5b45a9b..13c5c0d 100644
--- a/modules/dos_input.py
+++ b/modules/dos_input.py
@@ -1,47 +1,90 @@
 """Functions to deal with DockOnSurf input files.
 
-Functions
-try_command:Tries to run a command and logs its exceptions (expected and not).
+List of functions:
+
+Auxiliary functions
+-------------------
 str2lst: Converts a string of integers, and groups of them, to a list of lists.
 check_expect_val: Checks whether the value of an option has an adequate value.
-read_input: Sets up the calculation by reading the parameters from input file.
+check_inp_files: Checks if the CP2K/VASP input files are consistent.
+
+Functions to read parameters in the Global section
+--------------------------------------------------
 get_run_type: Gets 'run_type' value and checks that its value is acceptable.
 get_code: Gets 'code' value and checks that its value is acceptable.
 get_batch_q_sys: Gets 'batch_q_sys' value and checks that its value is
-acceptable.
+    acceptable.
+get_pbc_cell: Gets 'pbc_cell' value and checks that its value is acceptable.
+get_subm_script: Gets 'subm_script' value and checks that its value is
+    acceptable.
+get_project_name: Gets 'project_name' value and checks that its value is
+    acceptable.
 get_relaunch_err: Gets 'relaunch_err' value and checks that its value is
-acceptable.
+    acceptable. # WARNING: OPTION NOT IMPLEMENTED
 get_max_jobs: Gets 'max_jobs' value and checks that its value is acceptable.
 get_special_atoms: Gets 'special_atoms' value and checks that its value is
-acceptable.
+    acceptable.
+get_potcar_dir: Gets 'potcar_dir' value and checks that its value is
+    acceptable.
+
+Functions to read parameters in the Isolated section
+----------------------------------------------------
 get_isol_inp_file: Gets 'isol_inp_file' value and checks that its value is
-acceptable.
-get_cluster_magns: Gets 'cluster_magns' value and checks that its value is
-acceptable.
+    acceptable.
+get_molec_file: Gets 'molec_file' value and checks that its value is acceptable.
 get_num_conformers: Gets 'num_conformers' value and checks that its value is
-acceptable.
-get_num_prom_cand: Gets 'num_prom_cand' value and checks that its value is
-acceptable.
-get_iso_rmsd: Gets 'iso_rmsd' value and checks that its value is acceptable.
+    acceptable.
 get_pre_opt: Gets 'pre_opt' value and checks that its value is acceptable.
+
+Functions to read parameters in the Screening section
+-----------------------------------------------------
 get_screen_inp_file: Gets 'screen_inp_file' value and checks that its value is
-acceptable.
+    acceptable.
+get_surf_file: Gets 'surf_file' value and checks that its value is acceptable.
 get_sites: Gets 'sites' value and checks that its value is acceptable.
-get_molec_ctrs: Gets 'molec_ctrs' value and checks that its value is
-acceptable.
-get_try_disso: Gets 'try_disso' value and checks that its value is acceptable.
+get_surf_ctrs2: Gets 'surf_ctrs2' value and checks that its value is acceptable.
+get_molec_ctrs: Gets 'molec_ctrs' value and checks that its value is acceptable.
+get_molec_ctrs2: Gets 'molec_ctrs2' value and checks that its value is
+    acceptable.
+get_molec_ctrs3: Gets 'molec_ctrs3' value and checks that its value is
+    acceptable.
+get_max_helic_angle: Gets 'max_helic_angle' value and checks that its value is
+    acceptable.
+get_select_magns: Gets 'select_magns' value and checks that its value is
+    acceptable.
+get_confs_per_magn: Gets 'confs_per_magn' value and checks that its value is
+    acceptable.
+get_surf_norm_vect: Gets 'surf_norm_vect' value and checks that its value is
+    acceptable.
+get_adsorption_height: Gets 'adsorption_height' value and checks that its value
+    is acceptable.
+get_set_angles: Gets 'set_angles' value and checks that its value is
+    acceptable.
 get_pts_per_angle: Gets 'pts_per_angle' value and checks that its value is
-acceptable.
+    acceptable.
+get_max_structures: Gets 'max_structures' value and checks that its value is
+    acceptable.
 get_coll_thrsld: Gets 'coll_thrsld' value and checks that its value is
-acceptable.
-get_screen_rmsd: Gets 'screen_rmsd' value and checks that its value is
-acceptable.
-get_coll_bottom_z: Gets 'coll_bottom_z' value and checks that its value is
-acceptable.
+    acceptable.
+get_min_coll_height: Gets 'coll_bottom_z' value and checks that its value is
+    acceptable.
+get_exclude_ads_ctr: Gets 'exclude_ads_ctr' value and checks that its value is
+    acceptable.
+get_H_donor: Gets 'H_donor' value and checks that its value is
+    acceptable.
+get_H_acceptor: Gets 'H_acceptor' value and checks that its value is
+    acceptable.
+get_use_molec_file: Gets 'use_molec_file' value and checks that its value is
+    acceptable.
+
+Functions to read parameters in the Refinement section
+------------------------------------------------------
 get_refine_inp_file: Gets 'refine_inp_file' value and checks that its value is
-acceptable.
+    acceptable.
 get_energy_cutoff: Gets 'energy_cutoff' value and checks that its value is
-acceptable.
+    acceptable.
+
+read_input: Directs the reading of the parameters in the input file
 """
 import os.path
 import logging
@@ -54,7 +97,7 @@ logger = logging.getLogger('DockOnSurf')
 
 dos_inp = ConfigParser(inline_comment_prefixes='#',
                        empty_lines_in_values=False)
-
+# Define new answers to be interpreted as True or False.
 new_answers = {'n': False, 'none': False, 'nay': False,
                'y': True, 'sí': True, 'aye': True, 'sure': True}
 for answer, val in new_answers.items():
@@ -64,6 +107,7 @@ turn_false_answers = [answer for answer in dos_inp.BOOLEAN_STATES
 turn_true_answers = [answer for answer in dos_inp.BOOLEAN_STATES
                      if dos_inp.BOOLEAN_STATES[answer]]
 
+# Template error messages to be customized in place.
 no_sect_err = "Section '%s' not found on input file"
 no_opt_err = "Option '%s' not found on section '%s'"
 num_error = "'%s' value must be a %s"
@@ -73,7 +117,7 @@ num_error = "'%s' value must be a %s"
 
 def str2lst(cmplx_str, func=int):  # TODO: enable deeper level of nested lists
     # TODO Treat all-enclosing parenthesis as a list instead of list of lists.
-    """Converts a string of integers, and groups of them, to a list.
+    """Converts a string of integers/floats, and groups of them, to a list.
 
     Keyword arguments:
     @param cmplx_str: str, string of integers (or floats) and groups of them
@@ -159,7 +203,14 @@ def check_expect_val(value, expect_vals, err_msg=None):
     return True
 
 
-def check_inp_files(inp_files, code, potcar_dir=None):
+def check_inp_files(inp_files, code: str, potcar_dir=None):
+    """Checks if the CP2K/VASP input files are consistent.
+
+    @param inp_files: List of input files
+    @param code: The code for which the input files are for (VASP or CP2K).
+    @param potcar_dir: The path where POTCARs are found
+    @return: None
+    """
     if code == 'cp2k':
         from pycp2k import CP2K
         if not isinstance(inp_files, str):
@@ -184,7 +235,7 @@ def check_inp_files(inp_files, code, potcar_dir=None):
                                "also enabled via the 'potcar_dir' keyword. The "
                                "POTCAR specified as input_file will be used "
                                "instead of the auto-generated one.")
-        # Check that it inp_files is a list of file paths
+        # Check that if inp_files is a list of file paths
         if not isinstance(inp_files, list) and all(isinstance(inp_file, str)
                                                    for inp_file in inp_files):
             err_msg = "'inp_files' should be a list of file names/paths"
@@ -306,6 +357,7 @@ def get_project_name():
 
 
 def get_relaunch_err():
+    # WARNING: OPTION NOT IMPLEMENTED
     relaunch_err_vals = ['geo_not_conv']
     relaunch_err = dos_inp.get('Global', 'relaunch_err',
                                fallback="False")
@@ -815,8 +867,15 @@ def get_energy_cutoff():
 # Read input parameters
 
 def read_input(in_file):
+    """Directs the reading of the parameters in the input file.
+
+    @param in_file: The path to the DockOnSurf input file.
+    @return inp_vars: Dictionary with the values for every option in the input
+    file.
+    """
     from modules.formats import adapt_format
 
+    # Checks for errors in the Input file.
     err_msg = False
     try:
         dos_inp.read(in_file)
@@ -851,7 +910,7 @@ def read_input(in_file):
             logger.error(no_opt_err % (opt, 'Global'))
             raise NoOptionError(opt, 'Global')
 
-    # Gets which sections are to be carried out
+    # Mandatory options
     isolated, screening, refinement = get_run_type()
     inp_vars['isolated'] = isolated
     inp_vars['screening'] = screening
@@ -882,7 +941,6 @@ def read_input(in_file):
             logger.error(no_sect_err % 'Isolated')
             raise NoSectionError('Isolated')
         # Mandatory options
-        # Checks whether the mandatory options are present.
         iso_mand_opts = ['isol_inp_file', 'molec_file']
         for opt in iso_mand_opts:
             if not dos_inp.has_option('Isolated', opt):
@@ -929,6 +987,7 @@ def read_input(in_file):
             raise NoSectionError('Screening')
         # Mandatory options:
         # Checks whether the mandatory options are present.
+        # Mandatory options
         screen_mand_opts = ['screen_inp_file', 'surf_file', 'sites',
                             'molec_ctrs']
         for opt in screen_mand_opts:
@@ -946,7 +1005,6 @@ def read_input(in_file):
         inp_vars['molec_ctrs'] = get_molec_ctrs()
 
         # Checks for PBC
-        # Checks for PBC
         atms = adapt_format('ase', inp_vars['surf_file'],
                             inp_vars['special_atoms'])
         if inp_vars['code'] == 'vasp' and np.linalg.det(atms.cell) == 0.0 \
