Merge pull request #105 from bottero/feature/adding_comments

Added a whole bunch of comments. Also allowed for new versions of specfem to be used

scripts/sfclean

@@ -1,5 +1,20 @@
 #!/bin/sh
 
-rm -rf output*
+usage="$(basename "$0") [-h] -- delete directories output, output.stat*, output.optim
+and scratch in the current directory
+
+where:
+    -h  show this help text"
+
+while getopts ':hs:' option; do
+  case "$option" in
+    h) echo "$usage"
+       exit
+       ;;
+  esac
+done
+shift $((OPTIND - 1))
+
+rm -rf output output.stat* output.optim
 rm -rf scratch
 

scripts/sfexamples

@@ -1,12 +1,26 @@
 #!/usr/bin/env python
+#
+# This is Seisflows
+#
+# See LICENCE file
+#
+# sfexamples:
+# Prompts user to select SEISFLOWS example, then sets up working directory
+# to run example
+#
+###############################################################################
 
+# Import system modules
 import os
+from os.path import exists
 
-from os.path import exists, join
+# Local imports
 from seisflows.tools import unix
 
 
 def listdir(dir):
+    """ List directories in current directory in a sorted fashion
+    """
     subdirs = []
     for subdir in unix.ls(dir):
         if os.path.isdir(dir+'/'+subdir):
@@ -17,9 +31,12 @@ def listdir(dir):
 
 
 def getpath():
+    """ Return the environment variable 'SEISFLOWS_EXAMPLES' raise en error
+    if it does not exist
+    """
     path = os.getenv('SEISFLOWS_EXAMPLES')
-    if not exists(path):  
-       raise EnvironmentError()
+    if not exists(path):
+        raise EnvironmentError()
     return path
 
 
@@ -33,18 +50,17 @@ if __name__ == '__main__':
         path = getpath()
     print ''
 
-    # select directory
+    # Select directory
     dirs = ['Examples2d', 'Examples3d', 'Examples3dGlobe']
     dir = unix.select(dirs)
     print ''
 
-    # select subdirectory
+    # Select subdirectory
     subdirs = listdir(path+'/'+dir)
     subdir = unix.select(subdirs)
     print ''
 
-    # set up working directory
+    # Set up working directory
     fullpath = path+'/'+dir+'/'+subdir
     unix.cp(fullpath+'/'+'parameters.py', '.')
     unix.cp(fullpath+'/'+'paths.py', '.')
-

scripts/sfresume

@@ -1,52 +1,73 @@
 #!/usr/bin/env python
-
-import argparse, os, sys
-
-from seisflows.config import config, loadpy, names, tilde_expand, Dict, Struct
+#
+# This is Seisflows
+#
+# See LICENCE file
+#
+# sfresume:
+# Workflow submission script
+#
+###############################################################################
+
+# Import system modules
+import argparse
+import os
+import sys
+from os.path import join
+
+# Local imports
+from seisflows.config import loadpy, names, tilde_expand, Dict
 from seisflows.tools import unix
+from seisflows.tools.tools import loadobj
 
 
 def getargs():
+    """ This function run argparse (see
+    https://docs.python.org/2/howto/argparse.html) to process the arguments
+    given by the user along with sfresume. Define default behaviour if they are
+    not given and help message when sfresume -h is run
+    """
     parser = argparse.ArgumentParser()
 
-    parser.add_argument('--workdir', nargs='?', 
-        default=os.getcwd())
+    parser.add_argument('--workdir', nargs='?', default=os.getcwd(),
+                        help="working directory")
 
-    parser.add_argument('--parameter_file', nargs='?', 
-        default='parameters.py')
+    parser.add_argument('--parameter_file', nargs='?', default='parameters.py',
+                        help="parameter file")
 
-    parser.add_argument('--path_file', nargs='?', 
-        default='paths.py')
+    parser.add_argument('--path_file', nargs='?', default='paths.py',
+                        help="paths file")
 
     return parser.parse_args()
 
 
 if __name__ == "__main__":
-    ### workflow submission script
+    """ Workflow submission script
+    """
+
     args = getargs()
 
-    # register parameters
+    # Register parameters
     parameters = loadpy(args.parameter_file)
     sys.modules['seisflows_parameters'] = Dict(parameters)
 
-    # register paths
+    # Register paths
     paths = tilde_expand(loadpy(args.path_file))
     sys.modules['seisflows_paths'] = Dict(paths)
 
     unix.mkdir(args.workdir)
     unix.cd(args.workdir)
 
-    # reload objects
+    # Reload objects
     for name in names:
         fullfile = join(args.workdir, 'output', 'seisflows_'+name+'.p')
         sys.modules['seisflows_'+name] = loadobj(fullfile)
 
-    # parameter checking
+    # Parameter checking
     for name in names:
         sys.modules['seisflows_'+name].check()
 
-    # submit workflow
+    # Submit workflow
     workflow = sys.modules['seisflows_workflow']
     system = sys.modules['seisflows_system']
     system.submit(workflow)
-

scripts/sfsubmit

@@ -4,58 +4,74 @@
 #
 # See LICENCE file
 #
+# sfrun:
+# Workflow submission script
 #
-################################################################################
+###############################################################################
 
 # Import system modules
-import argparse, os, sys
+import argparse
+import os
+import sys
 
 # Local imports
 from seisflows.config import config, loadpy, tilde_expand, Dict
 from seisflows.tools import unix
 
 
 def getargs():
-    """ This function run argparse (see https://docs.python.org/2/howto/argparse.html)
-    to process the arguments given by the user along with sfrun. Define default
-    behaviour if they are not given qnd help message when sfrun -h is run
+    """ This function run argparse
+    (see https://docs.python.org/2/howto/argparse.html) to process the
+    arguments given by the user along with sfrun. Define default behaviour if
+    they are not given and help message when sfrun -h is run
     """
     parser = argparse.ArgumentParser()
 
-    parser.add_argument('--workdir', nargs='?', 
-        default=os.getcwd(), help="workdir : working directory. Default is given by command pwd")
+    parser.add_argument('--workdir', nargs='?', default=os.getcwd(),
+                        help="workdir : working directory. Default is given \
+                              by command pwd")
 
-    parser.add_argument('--parameter_file', nargs='?', 
-        default='parameters.py', help="parameter_file : path to the parameter file. Default is ./parameters.py")
+    parser.add_argument('--parameter_file', nargs='?', default='parameters.py',
+                        help="parameter_file : path to the parameter file. \
+                        Default is ./parameters.py")
 
-    parser.add_argument('--path_file', nargs='?', 
-        default='paths.py', help="path_file : path to the file containing the path to the model and solver. Default is ./paths.py")
+    parser.add_argument('--path_file', nargs='?', default='paths.py',
+                        help="path_file : path to the file containing the \
+                        path to the model and solver. Default is ./paths.py")
 
     return parser.parse_args()
 
 
 if __name__ == "__main__":
     """ Workflow submission script
     """
-    args = getargs() # Parse the arguments given along command sfrun
+    args = getargs()  # Parse the arguments given along command sfrun
 
-    # Load and register parameters
+    # Load file parameters.py and store it in a Dictionnary like structure
     parameters = loadpy(args.parameter_file)
+    # Register the parameters to make them globally accessible.
+    # More precisely we add a new key named 'seisflows_parameters' to the
+    # dictionary sys.modules (mapping modules names to modules which have
+    # already been loaded) we store the parameters inside
     sys.modules['seisflows_parameters'] = Dict(parameters)
 
-    # Load and register paths
+    # Load and register paths.py (same than above for paths)
+    # tilde_expand expands tilde character in path strings
     paths = tilde_expand(loadpy(args.path_file))
     sys.modules['seisflows_paths'] = Dict(paths)
 
-    # Create working directory and open it
+    # Create working directory (if it does not exist) and open it
     unix.mkdir(args.workdir)
     unix.cd(args.workdir)
 
     # Run configuration script
+    # It basically instantiates SeisFlows objects and makes them globally
+    # accessible by registering them in sys.modules
     config()
 
-    # Submit workflow
+    # Submit workflow (we give the newly instantiated class workflow to the
+    # class system through the method submit)
     workflow = sys.modules['seisflows_workflow']
     system = sys.modules['seisflows_system']
-    system.submit(workflow)
 
+    system.submit(workflow)