Added comments and docstrings for the most important code.

runOPAL/opaldict.py

@@ -12,8 +12,16 @@ OpalDictionary class
 
 
 class OpalDict:
+    '''
+    This file contains values from a .data file, plus some user provided values.
+    '''
 
     def __init__(self, template):
+        '''
+        Parameters
+        ==========
+        template: str
+        '''
         self.dict = {}
         self.rangevars = {}
         self.uservars = []
@@ -41,12 +49,18 @@ class OpalDict:
         return self.dict.items()
 
     def fillDictionary(self, fileName):
+        '''
+        Read the given .data file and and the key-value pairs to self.
+        '''
         fp = open(fileName, "r")
         for line in fp:
             if not line == "\n":
                 li = line.strip()
+                # ignore outcommented lines
                 if not li.startswith("#"):
+                    # cut off comments at the end of the line
                     aline = line.split("#")[0]
+                    # the name-value pairs are separated by whitespace
                     name, val = aline.split()
                     self.dict[name.rstrip()] = val.lstrip().rstrip()
         fp.close()
@@ -87,6 +101,14 @@ class OpalDict:
         self.scaleDictVar('GUNSOLB', 1.)
 
     def addUserValues(self, argv):
+        '''
+        Add user-provided key-value pairs to those from the .data fileself.
+
+        Parameters
+        ==========
+        argv: str
+            Command line arguments to runOPAL.py
+        '''
         for arg in argv:
             if arg.find("=") > 0:
 

runOPAL/simulation.py

@@ -55,24 +55,86 @@ class Simulation:
         self.opaldict = opaldict
         self.dirname = ""
 
-    def createDirectory(self, dirname, doKeep, quiet):
+    @staticmethod
+    def createDirectory(dirname, doKeep, quiet):
+        '''
+        Helper method to create a directory.
+
+        Parameters
+        ==========
+        dirname: str
+            directory to create
+        doKeep: bool
+            if True, keep the directory if it alread exists, else delete it
+        quiet: bool
+            if True, do not print output
+
+        Returns
+        =======
+        bool
+            Whether a new directory was created
+        '''
         # If there's already a directory remove it...
-        if os.path.isdir(self.dirname):
+        if os.path.isdir(dirname):
             if doKeep:
-                print('KEEP existing directory {}'.format(self.dirname))
-                print(self.dirname)
+                print('KEEP existing directory {}'.format(dirname))
+                print(dirname)
                 return False
             else:
                 if not quiet:
-                    print('REMOVE existing directory {}'.format(self.dirname))
-                shutil.rmtree(self.dirname)
+                    print('REMOVE existing directory {}'.format(dirname))
+                shutil.rmtree(dirname)
 
         # create directory
-        os.mkdir(self.dirname)
+        os.mkdir(dirname)
         return True
 
     def run(self, N, baseFileName, inputfilePath, tmplFile, oinpFile,
             doTest, doKeep, doNobatch, doOptimize, info, queue, hypert, quiet):
+        '''
+        Run an OPAL simulation.
+
+        Support for batch systems is available.
+
+        Parameters
+        ==========
+        N: int
+            A running number.
+            Useful when multiple output directories are needed
+        baseFileName: str
+            The base name of the simulation.
+            If the template file is called mysim.tmpl,
+            then the data file must be called mysim.data
+            and the base name is mysim
+        inputfilePath: str
+            Path to the directory that contains the .in file
+            (if running an optimisation).
+            If running a single simulation: Path to the directory that
+            contains the .tmpl file(s)
+        tmplFile: str
+            Path to the .tmpl file
+        oinpFile: str
+            Path to the .in file (called Opal in file)
+        doTest: bool
+            if True, does everything but submitting the job
+        doKeep: bool
+            if True:
+                if same simulation has been run before, keep old data and abort
+        doNobatch: bool
+            run OPAL locally not using the batch system
+            and wait until the job is done
+        doOptimize: bool
+            use optimization template (if any)
+        info: int
+            Steers the std-output of OPAL.
+            The range is 0 < num < 6 (default), from minimum to maximum output
+        queue: str
+            Defines in which queue the job goes.
+        hypert: int
+            Defines the number of Hyper-Threads used. Default: 0
+        quiet: bool
+            suppress debug printout
+        '''
         # make directory name indicating changed values
         self.dirname = baseFileName
         if N >= 0: