Context Navigation

-                      r708c667
+                      r274f9ef
     def __init__(self, filename):
+        '''
+        @Description:
+            Initialises the instance of ControlFile class and defines
+            all class attributes with default values. Afterwards calls
+            function __read_controlfile__ to read parameter from
+            Control file.
+        @Input:
+            self: instance of ControlFile class
+                Description see class documentation.
+            filename: string
+                Name of CONTROL file.
+        @Return:
+            <nothing>
+        '''Initialises the instance of ControlFile class and defines
+        all class attributes with default values. Afterwards calls
+        function __read_controlfile__ to read parameter from Control file.
+        Parameters
+        ----------
+        filename : :obj:`string`
+            Name of CONTROL file.
+        Return
+        ------
         '''
 …
     def __read_controlfile__(self):
+        '''
+        @Description:
+            Read CONTROL file and assign all CONTROL file variables.
+        @Input:
+            self: instance of ControlFile class
+                Description see class documentation.
+        @Return:
+            <nothing>
+        '''Read CONTROL file and assign all CONTROL file variables.
+        Parameters
+        ----------
+        Return
+        ------
         '''
 …
     def __str__(self):
         '''
         @Description:
             Prepares a string which have all the ControlFile
+            class attributes with its associated values.
             Each attribute is printed in one line and in
             alphabetical order.
             Example:
             'age': 10
             'color': 'Spotted'
             'kids': 0
             'legs': 2
+            'name': 'Dog'
             'smell': 'Alot'
+        @Input:
             self: instance of ControlFile class
                 Description see class documentation.
         @Return:
             string of ControlFile class attributes with their values
+        '''Prepares a string which have all the ControlFile class attributes
+        with its associated values. Each attribute is printed in one line and
+        in alphabetical order.
+        Example
+        -------
+        'age': 10
+        'color': 'Spotted'
+        'kids': 0
+        'legs': 2
+        'name': 'Dog'
+        'smell': 'Alot'
+        Parameters
+        ----------
+        Return
+        ------
+        string
+            Single string of concatenated ControlFile class attributes
+            with their values
         '''
         import collections
 …
     def assign_args_to_control(self, args):
+        '''
+        @Description:
+            Overwrites the existing ControlFile instance attributes with
+            the command line arguments.
+        @Input:
+            self: instance of ControlFile class
+                Description see class documentation.
+            args: instance of ArgumentParser
+                Contains the commandline arguments from script/program call.
+        @Return:
+            <nothing>
+        '''Overwrites the existing ControlFile instance attributes with
+        the command line arguments.
+        Parameters
+        ----------
+        args : :obj:`Namespace`
+            Contains the commandline arguments from script/program call.
+        Return
+        ------
         '''
 …
     def assign_envs_to_control(self, envs):
         '''
+        @Description:
             Assigns the ECMWF environment parameter.
         @Input:
             envs: dict of strings
                 Contains the ECMWF environment parameternames "ECUID", "ECGID",
                 "DESTINATION" and "GATEWAY" with its corresponding values.
+                They were read from the file "ECMWF_ENV".
         @Return:
+            <nothing>
+        '''Assigns the ECMWF environment parameter.
+        Parameters
+        ----------
+        envs : :obj:`dictionary` of :obj:`strings`
+            Contains the ECMWF environment parameternames "ECUID", "ECGID",
+            "DESTINATION" and "GATEWAY" with its corresponding values.
+            They were read from the file "ECMWF_ENV".
+        Return
+        ------
         '''
 …
     def check_conditions(self, queue):
+        '''
+        @Description:
+            Checks a couple of necessary attributes and conditions,
+            such as if they exist and contain values.
+            Otherwise set default values.
+        @Input:
+            self: instance of ControlFile class
+                Description see class documentation.
+            queue: string
+                Name of the queue if submitted to the ECMWF servers.
+                Used to check if ecuid, ecgid, gateway and destination
+                are set correctly and are not empty.
+        @Return:
+            <nothing>
+        '''Checks a couple of necessary attributes and conditions,
+        such as if they exist and contain values.
+        Otherwise set default values.
+        Parameters
+        ----------
+        queue : :obj:`string`
+            Name of the queue if submitted to the ECMWF servers.
+            Used to check if ecuid, ecgid, gateway and destination
+            are set correctly and are not empty.
+        Return
+        ------
         '''
         from mods.tools import my_error
 …
     def check_install_conditions(self):
+        '''
+        @Description:
+            Checks a couple of necessary attributes and conditions
+            for the installation such as if they exist and contain values.
+            Otherwise set default values.
+        @Input:
+            self: instance of ControlFile class
+                Description see class documentation.
+        @Return:
+            <nothing>
+        '''Checks a couple of necessary attributes and conditions
+        for the installation such as if they exist and contain values.
+        Otherwise set default values.
+        Parameters
+        ----------
+        Return
+        ------
         '''
 …
     def to_list(self):
+        '''
+        @Description:
+            Just generates a list of strings containing the attributes and
+            assigned values except the attributes "_expanded", "exedir",
+        '''Just generates a list of strings containing the attributes and
+        assigned values except the attributes "_expanded", "exedir",
+        "ecmwfdatadir" and "flexpart_root_scripts".
+        Parameters
+        ----------
+        Return
+        ------
+        l : :obj:`list`
+            A sorted list of the all ControlFile class attributes with
+            their values except the attributes "_expanded", "exedir",
             "ecmwfdatadir" and "flexpart_root_scripts".
-        @Input:
-            self: instance of ControlFile class
-                Description see class documentation.
-        @Return:
-            l: list
-                A sorted list of the all ControlFile class attributes with
-                their values except the attributes "_expanded", "exedir",
-                "ecmwfdatadir" and "flexpart_root_scripts".
         '''

source/python/classes/EcFlexpart.py

-                      r0934db1
+                      r274f9ef
     # --------------------------------------------------------------------------
     def __init__(self, c, fluxes=False):
+        '''
+        @Description:
+            Creates an object/instance of EcFlexpart with the
+            associated settings of its attributes for the retrieval.
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            c: instance of class ControlFile
+                Contains all the parameters of CONTROL file and
+                command line.
+                For more information about format and content of the parameter
+                see documentation.
+            fluxes: boolean, optional
+                Decides if the flux parameter settings are stored or
+                the rest of the parameter list.
+                Default value is False.
+        @Return:
+            <nothing>
+        '''Creates an object/instance of EcFlexpart with the associated
+        settings of its attributes for the retrieval.
+        Parameters:
+        -----------
+        c : :obj:`ControlFile`
+            Contains all the parameters of CONTROL file and
+            command line.
+        fluxes : :obj:`boolean`, optional
+            Decides if the flux parameter settings are stored or
+            the rest of the parameter list.
+            Default value is False.
+        Return
+        ------
         '''
         # set a counter for the number of mars requests generated
 …
     def _mk_targetname(self, ftype, param, date):
         '''
         @Description:
+            Creates the filename for the requested grib data to be stored in.
             This name is passed as the "target" parameter in the request.
         @Input:
             ftype: string
+                Shortcut name of the type of the field. E.g. AN, FC, PF, ...
             param: string
                 Shortcut of the grid type. E.g. SH__ML, SH__SL, GG__ML,
+                GG__SL, OG__ML, OG__SL, OG_OROLSM_SL, OG_acc_SL
             date: string
+                The date period of the grib data to be stored in this file.
         @Return:
             targetname: string
                 The target filename for the grib data.
+        '''Creates the filename for the requested grib data to be stored in.
+        This name is passed as the "target" parameter in the request.
+        Parameters
+        ----------
+        ftype : :obj:`string`
+            Shortcut name of the type of the field. E.g. AN, FC, PF, ...
+        param : :obj:`string`
+            Shortcut of the grid type. E.g. SH__ML, SH__SL, GG__ML,
+            GG__SL, OG__ML, OG__SL, OG_OROLSM_SL, OG_acc_SL
+        date : :obj:`string`
+            The date period of the grib data to be stored in this file.
+        Return
+        ------
+        targetname : :obj:`string`
+            The target filename for the grib data.
         '''
         targetname = (self.inputdir + '/' + ftype + param + '.' + date + '.' +
 …
     def _start_retrievement(self, request, par_dict):
+        '''
+        @Description:
+            Creates the Mars Retrieval and prints or submits the request
+            depending on the status of the request variable.
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            request: integer
+                Selects the mode of retrieval.
+: Retrieves the data from ECMWF.
+: Prints the mars requests to an output file.
+: Retrieves the data and prints the mars request.
+            par_dict: dictionary
+                Contains all parameter which have to be set for creating the
+                Mars Retrievals. The parameter are:
+                marsclass, dataset, stream, type, levtype, levelist, resol,
+                gaussian, accuracy, grid, target, area, date, time, number,
+                step, expver, param
+        @Return:
+            <nothing>
+        '''Creates the Mars Retrieval and prints or submits the request
+        depending on the status of the request variable.
+        Parameters
+        ----------
+        request : :obj:`integer`
+            Selects the mode of retrieval.
+: Retrieves the data from ECMWF.
+: Prints the mars requests to an output file.
+: Retrieves the data and prints the mars request.
+        par_dict : :obj:`dictionary`
+            Contains all parameter which have to be set for creating the
+            Mars Retrievals. The parameter are:
+            marsclass, dataset, stream, type, levtype, levelist, resol,
+            gaussian, accuracy, grid, target, area, date, time, number,
+            step, expver, param
+        Return
+        ------
         '''
         # increase number of mars requests
 …
     def _mk_index_values(self, inputdir, inputfiles, keys):
         '''
         @Description:
+            Creates an index file for a set of grib parameter keys.
             The values from the index keys are returned in a list.
         @Input:
             keys: dictionary
+                List of parameter names which serves as index.
             inputfiles: instance of UioFiles
+                Contains a list of files.
         @Return:
             iid: grib_index
                 This is a grib specific index structure to access
                 messages in a file.
             index_vals: list
                 Contains the values from the keys used for a distinct selection
                 of grib messages in processing  the grib files.
                 Content looks like e.g.:
                 index_vals[0]: ('20171106', '20171107', '20171108') ; date
                 index_vals[1]: ('0', '1200', '1800', '600') ; time
                 index_vals[2]: ('0', '12', '3', '6', '9') ; stepRange
+        '''Creates an index file for a set of grib parameter keys.
+        The values from the index keys are returned in a list.
+        Parameters
+        ----------
+        keys : :obj:`dictionary`
+            List of parameter names which serves as index.
+        inputfiles : :obj:`UioFiles`
+            Contains a list of files.
+        Return
+        ------
+        iid : :obj:`grib_index`
+            This is a grib specific index structure to access
+            messages in a file.
+        index_vals : :obj:`list`
+            Contains the values from the keys used for a distinct selection
+            of grib messages in processing  the grib files.
+            Content looks like e.g.:
+            index_vals[0]: ('20171106', '20171107', '20171108') ; date
+            index_vals[1]: ('0', '1200', '1800', '600') ; time
+            index_vals[2]: ('0', '12', '3', '6', '9') ; stepRange
         '''
         iid = None
 …
     def retrieve(self, server, dates, public, request, inputdir='.'):
+        '''
+        @Description:
+            Finalizing the retrieval information by setting final details
+            depending on grid type.
+            Prepares MARS retrievals per grid type and submits them.
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            server: instance of ECMWFService or ECMWFDataServer
+                The connection to the ECMWF server. This is different
+                for member state users which have full access and non
+                member state users which have only access to the public
+                data sets. The decision is made from command line argument
+                "public"; for public access its True (ECMWFDataServer)
+                for member state users its False (ECMWFService)
+            dates: string
+                Contains start and end date of the retrieval in the format
+                "YYYYMMDD/to/YYYYMMDD"
+            request: integer
+                Selects the mode of retrieval.
+: Retrieves the data from ECMWF.
+: Prints the mars requests to an output file.
+: Retrieves the data and prints the mars request.
+            inputdir: string, optional
+                Path to the directory where the retrieved data is about
+                to be stored. The default is the current directory ('.').
+        @Return:
+            <nothing>
+        '''Finalizing the retrieval information by setting final details
+        depending on grid type.
+        Prepares MARS retrievals per grid type and submits them.
+        Parameters
+        ----------
+        server : :obj:`ECMWFService` or :obj:`ECMWFDataServer`
+            The connection to the ECMWF server. This is different
+            for member state users which have full access and non
+            member state users which have only access to the public
+            data sets. The decision is made from command line argument
+            "public"; for public access its True (ECMWFDataServer)
+            for member state users its False (ECMWFService)
+        dates : :obj:`string`
+            Contains start and end date of the retrieval in the format
+            "YYYYMMDD/to/YYYYMMDD"
+        request : :obj:`integer`
+            Selects the mode of retrieval.
+: Retrieves the data from ECMWF.
+: Prints the mars requests to an output file.
+: Retrieves the data and prints the mars request.
+        inputdir : :obj:`string`, optional
+            Path to the directory where the retrieved data is about
+            to be stored. The default is the current directory ('.').
+        Return
+        ------
         '''
         self.dates = dates
 …
     def write_namelist(self, c):
+        '''
+        @Description:
+            Creates a namelist file in the temporary directory and writes
+            the following values to it: maxl, maxb, mlevel,
+            mlevelist, mnauf, metapar, rlo0, rlo1, rla0, rla1,
+            momega, momegadiff, mgauss, msmooth, meta, metadiff, mdpdeta
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            c: instance of class ControlFile
+                Contains all the parameters of CONTROL file and
+                command line.
+                For more information about format and content of the parameter
+                see documentation.
+            filename: string
+        '''Creates a namelist file in the temporary directory and writes
+        the following values to it: maxl, maxb, mlevel,
+        mlevelist, mnauf, metapar, rlo0, rlo1, rla0, rla1,
+        momega, momegadiff, mgauss, msmooth, meta, metadiff, mdpdeta
+        Parameters
+        ----------
+        c : :obj:`ControlFile`
+            Contains all the parameters of CONTROL file and
+            command line.
+        filename : :obj:`string`
                 Name of the namelist file.
+        @Return:
+            <nothing>
+        Return
+        ------
         '''
 …
     def deacc_fluxes(self, inputfiles, c):
+        '''
+        @Description:
+            Goes through all flux fields in ordered time and de-accumulate
+            the fields. Afterwards the fields are disaggregated in time.
+            Different versions of disaggregation is provided for rainfall
+            data (darain, modified linear) and the surface fluxes and
+            stress data (dapoly, cubic polynomial).
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            inputfiles: instance of UioFiles
+                Contains a list of files.
+            c: instance of class ControlFile
+                Contains all the parameters of CONTROL file and
+                command line.
+                For more information about format and content of the parameter
+                see documentation.
+        @Return:
+            <nothing>
+        '''Goes through all flux fields in ordered time and de-accumulate
+        the fields. Afterwards the fields are disaggregated in time.
+        Different versions of disaggregation is provided for rainfall
+        data (darain, modified linear) and the surface fluxes and
+        stress data (dapoly, cubic polynomial).
+        Parameters
+        ----------
+        inputfiles : :obj:`UioFiles`
+            Contains a list of files.
+        c : :obj:`ControlFile`
+            Contains all the parameters of CONTROL file and
+            command line.
+        Return
+        ------
         '''
 …
     def create(self, inputfiles, c):
+        '''
+        @Description:
+            This method is based on the ECMWF example index.py
+            https://software.ecmwf.int/wiki/display/GRIB/index.py
+            An index file will be created which depends on the combination
+            of "date", "time" and "stepRange" values. This is used to iterate
+            over all messages in each grib file which were passed through the
+            parameter "inputfiles" to seperate specific parameters into fort.*
+            files. Afterwards the FORTRAN program is called to convert
+            the data fields all to the same grid and put them in one file
+            per unique time step (combination of "date", "time" and
+            "stepRange").
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            inputfiles: instance of UioFiles
+                Contains a list of files.
+            c: instance of class ControlFile
+                Contains all the parameters of CONTROL file and
+                command line.
+                For more information about format and content of the parameter
+                see documentation.
+        @Return:
+            <nothing>
+        '''An index file will be created which depends on the combination
+        of "date", "time" and "stepRange" values. This is used to iterate
+        over all messages in each grib file which were passed through the
+        parameter "inputfiles" to seperate specific parameters into fort.*
+        files. Afterwards the FORTRAN program is called to convert
+        the data fields all to the same grid and put them in one file
+        per unique time step (combination of "date", "time" and
+        "stepRange").
+        Note
+        ----
+        This method is based on the ECMWF example index.py
+        https://software.ecmwf.int/wiki/display/GRIB/index.py
+        Parameters
+        ----------
+        inputfiles : :obj:`UioFiles`
+            Contains a list of files.
+        c : :obj:`ControlFile`
+            Contains all the parameters of CONTROL file and
+            command line.
+        Return
+        ------
         '''
 …
     def process_output(self, c):
+        '''
+        @Description:
+            The grib files are postprocessed depending on the selection in
+            CONTROL file. The resulting files are moved to the output
+            directory if its not equal to the input directory.
+            The following modifications might be done if
+            properly switched in CONTROL file:
+            GRIB2 - Conversion to GRIB2
+            ECTRANS - Transfer of files to gateway server
+            ECSTORAGE - Storage at ECMWF server
+        @Input:
+            self: instance of EcFlexpart
+                The current object of the class.
+            c: instance of class ControlFile
+                Contains all the parameters of CONTROL file and
+                command line.
+                For more information about format and content of the parameter
+                see documentation.
+        @Return:
+            <nothing>
+        '''The grib files are postprocessed depending on the selection in
+        CONTROL file. The resulting files are moved to the output
+        directory if its not equal to the input directory.
+        The following modifications might be done if
+        properly switched in CONTROL file:
+        GRIB2 - Conversion to GRIB2
+        ECTRANS - Transfer of files to gateway server
+        ECSTORAGE - Storage at ECMWF server
+        Parameters
+        ----------
+        c : :obj:`ControlFile`
+            Contains all the parameters of CONTROL file and
+            command line.
+        Return
+        ------
         '''
 …
     def prepare_fp_files(self, c):
+        '''
+        @Description:
+            Conversion of GRIB files to FLEXPART binary format.
+        @Input:
+            c: instance of class ControlFile
+                Contains all the parameters of CONTROL file and
+                command line.
+                For more information about format and content of the parameter
+                see documentation.
+        @Return:
+            <nothing>
+        '''Conversion of GRIB files to FLEXPART binary format.
+        Parameters
+        ----------
+        c : :obj:`ControlFile`
+            Contains all the parameters of CONTROL file and
+            command line.
+        Return
+        ------
         '''
         # generate AVAILABLE file

source/python/classes/GribTools.py

-                      r0934db1
+                      r274f9ef
     # --------------------------------------------------------------------------
     def __init__(self, filenames):
+        '''
+        @Description:
+            Initialise an object of GribTools and assign a list
+            of filenames.
+        @Input:
+            filenames: list of strings
+                A list of filenames.
+        @Return:
+            <nothing>
+        '''Initialise an object of GribTools and assign a list of filenames.
+        Parameters
+        ----------
+        filenames : :obj:`list` of :obj:`strings`
+             A list of filenames.
+        Return
+        ------
         '''
 …
     def get_keys(self, keynames, wherekeynames=[], wherekeyvalues=[]):
         '''
         @Description:
+            get keyvalues for a given list of keynames
             a where statement can be given (list of key and list of values)
         @Input:
             keynames: list of strings
+                List of keynames.
             wherekeynames: list of strings, optional
+                Default value is an empty list.
             wherekeyvalues: list of strings, optional
+                Default value is an empty list.
         @Return:
             return_list: list of strings
                 List of keyvalues for given keynames.
+        '''Get keyvalues for a given list of keynames a where statement
+        can be given (list of key and list of values)
+        Parameters
+        ----------
+        keynames : :obj:`list` of :obj:`string`
+            List of keynames.
+        wherekeynames : :obj:`list` of :obj:`string`, optional
+            Default value is an empty list.
+        wherekeyvalues : :obj:`list` of :obj:`string`, optional
+            Default value is an empty list.
+        Return
+        ------
+        return_list : :obj:`list` of :obj:`string`
+            List of keyvalues for given keynames.
         '''
 …
     def set_keys(self, fromfile, keynames, keyvalues, wherekeynames=[],
                  wherekeyvalues=[], strict=False, filemode='w'):
+        '''
+        @Description:
+            Opens the file to read the grib messages and then write
+            them to a new output file. By default all messages are
+            written out. Also, the keyvalues of the passed list of
+            keynames are set or only those meeting the where statement.
+            (list of key and list of values).
+        @Input:
+            fromfile: string
+                Filename of the input file to read the grib messages from.
+            keynames: list of strings
+                List of keynames. Default is an empty list.
+            keyvalues: list of strings
+                List of keynames. Default is an empty list.
+            wherekeynames: list of strings, optional
+                Default value is an empty list.
+            wherekeyvalues: list of strings, optional
+                Default value is an empty list.
+            strict: boolean, optional
+                Decides if everything from keynames and keyvalues
+                is written out the grib file (False) or only those
+                meeting the where statement (True). Default is False.
+            filemode: string, optional
+                Sets the mode for the output file. Default is "w".
+        @Return:
+            <nothing>
+        '''Opens the file to read the grib messages and then write
+        them to a new output file. By default all messages are
+        written out. Also, the keyvalues of the passed list of
+        keynames are set or only those meeting the where statement.
+        (list of key and list of values).
+        Parameters
+        ----------
+        fromfile : :obj:`string`
+            Filename of the input file to read the grib messages from.
+        keynames : :obj:`list` of :obj:`string`
+            List of keynames. Default is an empty list.
+        keyvalues : :obj:`list` of :obj:`string`
+            List of keynames. Default is an empty list.
+        wherekeynames : :obj:`list` of :obj:`string`, optional
+            Default value is an empty list.
+        wherekeyvalues : :obj:`list` of :obj:`string`, optional
+            Default value is an empty list.
+        strict : :obj:`boolean`, optional
+            Decides if everything from keynames and keyvalues
+            is written out the grib file (False) or only those
+            meeting the where statement (True). Default is False.
+        filemode : :obj:`string`, optional
+            Sets the mode for the output file. Default is "w".
+        Return
+        ------
         '''
 …
     def copy(self, filename_in, selectWhere=True,
              keynames=[], keyvalues=[], filemode='w'):
+        '''
+        Add the content of another input grib file to the objects file but
+        '''Add the content of another input grib file to the objects file but
         only messages corresponding to keys/values passed to the function.
         The selectWhere switch decides if to copy the keys equal to (True) or
         different to (False) the keynames/keyvalues list passed to the function.
+        @Input:
+            filename_in: string
+                Filename of the input file to read the grib messages from.
+            selectWhere: boolean, optional
+                Decides if to copy the keynames and values equal to (True) or
+                different to (False) the keynames/keyvalues list passed to the
+                function. Default is True.
+            keynames: list of strings, optional
+                List of keynames. Default is an empty list.
+            keyvalues: list of strings, optional
+                List of keynames. Default is an empty list.
+            filemode: string, optional
+                Sets the mode for the output file. Default is "w".
+        @Return:
+            <nothing>
+        Parameters
+        ----------
+        filename_in : :obj:`string`
+            Filename of the input file to read the grib messages from.
+        selectWhere : :obj:`boolean`, optional
+            Decides if to copy the keynames and values equal to (True) or
+            different to (False) the keynames/keyvalues list passed to the
+            function. Default is True.
+        keynames : :obj:`list` of :obj:`string`, optional
+            List of keynames. Default is an empty list.
+        keyvalues : :obj:`list` of :obj:`string`, optional
+            List of keynames. Default is an empty list.
+        filemode : :obj:`string`, optional
+            Sets the mode for the output file. Default is "w".
+        Return
+        ------
         '''
 …
     def index(self, index_keys=["mars"], index_file="my.idx"):
         '''
         @Description:
+            Create index file from a list of files if it does not exist or
             read an index file.
         @Input:
             index_keys: list of strings, optional
                 Contains the list of key parameter names from
                 which the index is to be created.
+                Default is a list with a single entry string "mars".
             index_file: string, optional
                 Filename where the indices are stored.
+                Default is "my.idx".
         @Return:
             iid: integer
                 Grib index id.
+        '''Create index file from a list of files if it does not exist or
+        read an index file.
+        Parameters
+        ----------
+        index_keys: :obj:`list` of :obj:`string`, optional
+            Contains the list of key parameter names from
+            which the index is to be created.
+            Default is a list with a single entry string "mars".
+        index_file: :obj:`string`, optional
+            Filename where the indices are stored.
+            Default is "my.idx".
+        Return
+        ------
+        iid: :obj:`integer`
+            Grib index id.
         '''
         print("... index will be done")

source/python/classes/MarsRetrieval.py

-                      r70fee58
+                      r274f9ef
 # ------------------------------------------------------------------------------
 class MarsRetrieval(object):
+    '''
+    Class for submitting MARS retrievals.
+    '''Class for submitting MARS retrievals.
     A description of MARS keywords/arguments and examples of their
 …
     https://software.ecmwf.int/wiki/display/UDOC/\
                    Identification+keywords#Identificationkeywords-class
     '''
 …
                  number="", accuracy="", grid="", gaussian="", target="",
                  param=""):
+        '''
+        @Description:
+            Initialises the instance of the MarsRetrieval class and
+            defines and assigns a set of the necessary retrieval parameters
+            for the FLEXPART input data.
+            A description of MARS keywords/arguments, their dependencies
+            on each other and examples of their values can be found here:
+            https://software.ecmwf.int/wiki/display/UDOC/MARS+keywords
+        @Input:
+            self: instance of MarsRetrieval
+                For description see class documentation.
+            server: instance of ECMWFService (from ECMWF Web-API)
+                This is the connection to the ECMWF data servers.
+                It is needed for the pythonic access of ECMWF data.
+            public: integer
+                Decides which Web API version is used:
+: member-state users and full archive access
+: public access and limited access to the public server and
+                   datasets. Needs the parameter dataset.
+                Default is "0" and for member-state users.
+            marsclass: string, optional
+                Characterisation of dataset. E.g. EI (ERA-Interim),
+                E4 (ERA40), OD (Operational archive), ea (ERA5).
+                Default is the ERA-Interim dataset "ei".
+            dataset: string, optional
+                For public datasets there is the specific naming and parameter
+                dataset which has to be used to characterize the type of
+                data. Usually there is less data available, either in times,
+                domain or parameter.
+                Default is an empty string.
+            type: string, optional
+                Determines the type of fields to be retrieved.
+                Selects between observations, images or fields.
+                Examples for fields: Analysis (an), Forecast (fc),
+                Perturbed Forecast (pf), Control Forecast (cf) and so on.
+                Default is an empty string.
+            levtype: string, optional
+                Denotes type of level. Has a direct implication on valid
+                levelist values!
+                E.g. model level (ml), pressure level (pl), surface (sfc),
+                potential vorticity (pv), potential temperature (pt)
+                and depth (dp).
+                Default is an empty string.
+            levelist: string, optional
+                Specifies the required levels. It has to have a valid
+                correspondence to the selected levtype.
+                Examples: model level: 1/to/137, pressure levels: 500/to/1000
+                Default is an empty string.
+            repres: string, optional
+                Selects the representation of the archived data.
+                E.g. sh - spherical harmonics, gg - Gaussian grid,
+                ll - latitude/longitude, ...
+                Default is an empty string.
+            date: string, optional
+                Specifies the Analysis date, the Forecast base date or
+                Observations date. Valid formats are:
+                Absolute as YYYY-MM-DD or YYYYMMDD.
+                Default is an empty string.
+            resol: string, optional
+                Specifies the desired triangular truncation of retrieved data,
+                before carrying out any other selected post-processing.
+                The default is automatic truncation (auto), by which the lowest
+                resolution compatible with the value specified in grid is
+                automatically selected for the retrieval.
+                Users wanting to perform post-processing from full spectral
+                resolution should specify Archived Value (av).
+                The following are examples of existing resolutions found in
+                the archive: 63, 106, 159, 213, 255, 319, 399, 511, 799 or 1279.
+                This keyword has no meaning/effect if the archived data is
+                not in spherical harmonics representation.
+                The best selection can be found here:
+                https://software.ecmwf.int/wiki/display/UDOC/\
+                      Retrieve#Retrieve-Truncationbeforeinterpolation
+                Default is an empty string.
+            stream: string, optional
+                Identifies the forecasting system used to generate the data.
+                E.g. oper (Atmospheric model), enfo (Ensemble forecats), ...
+                Default is an empty string.
+            area: string, optional
+                Specifies the desired sub-area of data to be extracted.
+                Areas can be defined to wrap around the globe.
+                Latitude values must be given as signed numbers, with:
+                    north latitudes (i.e. north of the equator)
+                        being positive (e.g: 40.5)
+                    south latitutes (i.e. south of the equator)
+                        being negative (e.g: -50.5)
+                Longtitude values must be given as signed numbers, with:
+                    east longitudes (i.e. east of the 0 degree meridian)
+                        being positive (e.g: 35.0)
+                    west longitudes (i.e. west of the 0 degree meridian)
+                        being negative (e.g: -20.5)
+                E.g.: North/West/South/East
+                Default is an empty string.
+            time: string, optional
+                Specifies the time of the data in hours and minutes.
+                Valid values depend on the type of data: Analysis time,
+                Forecast base time or First guess verification time
+                (all usually at synoptic hours: 00, 06, 12 and 18 ).
+                Observation time (any combination in hours and minutes is valid,
+                subject to data availability in the archive).
+                The syntax is HHMM or HH:MM. If MM is omitted it defaults to 00.
+                Default is an empty string.
+            step: string, optional
+                Specifies the forecast time step from forecast base time.
+                Valid values are hours (HH) from forecast base time. It also
+                specifies the length of the forecast which verifies at
+                First Guess time.
+                E.g. 1/3/6-hourly
+                Default is an empty string.
+            expver: string, optional
+                The version of the dataset. Each experiment is assigned a
+                unique code (version). Production data is assigned 1 or 2,
+                and experimental data in Operations 11, 12 ,...
+                Research or Member State's experiments have a four letter
+                experiment identifier.
+                Default is "1".
+            number: string, optional
+                Selects the member in ensemble forecast run. (Only then it
+                is necessary.) It has a different meaning depending on
+                the type of data.
+                E.g. Perturbed Forecasts: specifies the Ensemble forecast member
+                Default is an empty string.
+            accuracy: string, optional
+                Specifies the number of bits per value to be used in the
+                generated GRIB coded fields.
+                A positive integer may be given to specify the preferred number
+                of bits per packed value. This must not be greater than the
+                number of bits normally used for a Fortran integer on the
+                processor handling the request (typically 32 or 64 bit).
+                Within a compute request the accuracy of the original fields
+                can be passed to the result field by specifying accuracy=av.
+                Default is an empty string.
+            grid: string, optional
+                Specifies the output grid which can be either a Gaussian grid
+                or a Latitude/Longitude grid. MARS requests specifying
+                grid=av will return the archived model grid.
+                Lat/Lon grid: The grid spacing needs to be an integer
+                fraction of 90 degrees e.g. grid = 0.5/0.5
+                Gaussian grid: specified by a letter denoting the type of
+                Gaussian grid followed by an integer (the grid number)
+                representing the number of lines between the Pole and Equator,
+                e.g.
+                grid = F160 - full (or regular) Gaussian grid with
+latitude lines between the pole and equator
+                grid = N320 - ECMWF original reduced Gaussian grid with
+latitude lines between the pole and equator,
+                       see Reduced Gaussian Grids for grid numbers used at ECMWF
+                grid = O640 - ECMWF octahedral (reduced) Gaussian grid with
+latitude lines between the pole and equator
+                Default is an empty string.
+            gaussian: string, optional
+                This parameter is deprecated and should no longer be used.
+                Specifies the desired type of Gaussian grid for the output.
+                Valid Gaussian grids are quasi-regular (reduced) or regular.
+                Keyword gaussian can only be specified together with
+                keyword grid. Gaussian without grid has no effect.
+                Default is an empty string.
+            target: string, optional
+                Specifies a file into which data is to be written after
+                retrieval or manipulation. Path names should always be
+                enclosed in double quotes. The MARS client supports automatic
+                generation of multiple target files using MARS keywords
+                enclosed in square brackets [ ].  If the environment variable
+                MARS_MULTITARGET_STRICT_FORMAT is set to 1 before calling mars,
+                the keyword values will be used in the filename as shown by
+                the ecCodes GRIB tool grib_ls -m, e.g. with
+                MARS_MULTITARGET_STRICT_FORMAT set to 1 the keywords time,
+                expver and param will be formatted as 0600, 0001 and 129.128
+                rather than 600, 1 and 129.
+                Default is an empty string.
+            param: string, optional
+                Specifies the meteorological parameter.
+                The list of meteorological parameters in MARS is extensive.
+                Their availability is directly related to their meteorological
+                meaning and, therefore, the rest of directives specified
+                in the MARS request.
+                Meteorological parameters can be specified by their
+                GRIB code (param=130), their mnemonic (param=t) or
+                full name (param=temperature).
+                The list of parameter should be seperated by a "/"-sign.
+                E.g. 130/131/133
+                Default is an empty string.
+        @Return:
+            <nothing>
+        '''Initialises the instance of the MarsRetrieval class and
+        defines and assigns a set of the necessary retrieval parameters
+        for the FLEXPART input data.
+        A description of MARS keywords/arguments, their dependencies
+        on each other and examples of their values can be found here:
+        https://software.ecmwf.int/wiki/display/UDOC/MARS+keywords
+        Parameters
+        ----------
+        server : :obj:`ECMWFService`
+            This is the connection to the ECMWF data servers.
+            It is needed for the pythonic access of ECMWF data.
+        public : :obj:`integer`
+            Decides which Web API version is used:
+: member-state users and full archive access
+: public access and limited access to the public server and
+               datasets. Needs the parameter dataset.
+            Default is "0" and for member-state users.
+        marsclass : :obj:`string`, optional
+            Characterisation of dataset. E.g. EI (ERA-Interim),
+            E4 (ERA40), OD (Operational archive), ea (ERA5).
+            Default is the ERA-Interim dataset "ei".
+        dataset : :obj:`string`, optional
+            For public datasets there is the specific naming and parameter
+            dataset which has to be used to characterize the type of
+            data. Usually there is less data available, either in times,
+            domain or parameter.
+            Default is an empty string.
+        type : :obj:`string`, optional
+            Determines the type of fields to be retrieved.
+            Selects between observations, images or fields.
+            Examples for fields: Analysis (an), Forecast (fc),
+            Perturbed Forecast (pf), Control Forecast (cf) and so on.
+            Default is an empty string.
+        levtype : :obj:`string`, optional
+            Denotes type of level. Has a direct implication on valid
+            levelist values!
+            E.g. model level (ml), pressure level (pl), surface (sfc),
+            potential vorticity (pv), potential temperature (pt)
+            and depth (dp).
+            Default is an empty string.
+        levelist : :obj:`string`, optional
+            Specifies the required levels. It has to have a valid
+            correspondence to the selected levtype.
+            Examples: model level: 1/to/137, pressure levels: 500/to/1000
+            Default is an empty string.
+        repres : :obj:`string`, optional
+            Selects the representation of the archived data.
+            E.g. sh - spherical harmonics, gg - Gaussian grid,
+            ll - latitude/longitude, ...
+            Default is an empty string.
+        date : :obj:`string`, optional
+            Specifies the Analysis date, the Forecast base date or
+            Observations date. Valid formats are:
+            Absolute as YYYY-MM-DD or YYYYMMDD.
+            Default is an empty string.
+        resol : :obj:`string`, optional
+            Specifies the desired triangular truncation of retrieved data,
+            before carrying out any other selected post-processing.
+            The default is automatic truncation (auto), by which the lowest
+            resolution compatible with the value specified in grid is
+            automatically selected for the retrieval.
+            Users wanting to perform post-processing from full spectral
+            resolution should specify Archived Value (av).
+            The following are examples of existing resolutions found in
+            the archive: 63, 106, 159, 213, 255, 319, 399, 511, 799 or 1279.
+            This keyword has no meaning/effect if the archived data is
+            not in spherical harmonics representation.
+            The best selection can be found here:
+            https://software.ecmwf.int/wiki/display/UDOC/\
+                  Retrieve#Retrieve-Truncationbeforeinterpolation
+            Default is an empty string.
+        stream : :obj:`string`, optional
+            Identifies the forecasting system used to generate the data.
+            E.g. oper (Atmospheric model), enfo (Ensemble forecats), ...
+            Default is an empty string.
+        area : :obj:`string`, optional
+            Specifies the desired sub-area of data to be extracted.
+            Areas can be defined to wrap around the globe.
+            Latitude values must be given as signed numbers, with:
+                north latitudes (i.e. north of the equator)
+                    being positive (e.g: 40.5)
+                south latitutes (i.e. south of the equator)
+                    being negative (e.g: -50.5)
+            Longtitude values must be given as signed numbers, with:
+                east longitudes (i.e. east of the 0 degree meridian)
+                    being positive (e.g: 35.0)
+                west longitudes (i.e. west of the 0 degree meridian)
+                    being negative (e.g: -20.5)
+            E.g.: North/West/South/East
+            Default is an empty string.
+        time : :obj:`string`, optional
+            Specifies the time of the data in hours and minutes.
+            Valid values depend on the type of data: Analysis time,
+            Forecast base time or First guess verification time
+            (all usually at synoptic hours: 00, 06, 12 and 18 ).
+            Observation time (any combination in hours and minutes is valid,
+            subject to data availability in the archive).
+            The syntax is HHMM or HH:MM. If MM is omitted it defaults to 00.
+            Default is an empty string.
+        step : :obj:`string`, optional
+            Specifies the forecast time step from forecast base time.
+            Valid values are hours (HH) from forecast base time. It also
+            specifies the length of the forecast which verifies at
+            First Guess time.
+            E.g. 1/3/6-hourly
+            Default is an empty string.
+        expver : :obj:`string`, optional
+            The version of the dataset. Each experiment is assigned a
+            unique code (version). Production data is assigned 1 or 2,
+            and experimental data in Operations 11, 12 ,...
+            Research or Member State's experiments have a four letter
+            experiment identifier.
+            Default is "1".
+        number : :obj:`string`, optional
+            Selects the member in ensemble forecast run. (Only then it
+            is necessary.) It has a different meaning depending on
+            the type of data.
+            E.g. Perturbed Forecasts: specifies the Ensemble forecast member
+            Default is an empty string.
+        accuracy : :obj:`string`, optional
+            Specifies the number of bits per value to be used in the
+            generated GRIB coded fields.
+            A positive integer may be given to specify the preferred number
+            of bits per packed value. This must not be greater than the
+            number of bits normally used for a Fortran integer on the
+            processor handling the request (typically 32 or 64 bit).
+            Within a compute request the accuracy of the original fields
+            can be passed to the result field by specifying accuracy=av.
+            Default is an empty string.
+        grid : :obj:`string`, optional
+            Specifies the output grid which can be either a Gaussian grid
+            or a Latitude/Longitude grid. MARS requests specifying
+            grid=av will return the archived model grid.
+            Lat/Lon grid: The grid spacing needs to be an integer
+            fraction of 90 degrees e.g. grid = 0.5/0.5
+            Gaussian grid: specified by a letter denoting the type of
+            Gaussian grid followed by an integer (the grid number)
+            representing the number of lines between the Pole and Equator,
+            e.g.
+            grid = F160 - full (or regular) Gaussian grid with
+latitude lines between the pole and equator
+            grid = N320 - ECMWF original reduced Gaussian grid with
+latitude lines between the pole and equator,
+                   see Reduced Gaussian Grids for grid numbers used at ECMWF
+            grid = O640 - ECMWF octahedral (reduced) Gaussian grid with
+latitude lines between the pole and equator
+            Default is an empty string.
+        gaussian : :obj:`string`, optional
+            This parameter is deprecated and should no longer be used.
+            Specifies the desired type of Gaussian grid for the output.
+            Valid Gaussian grids are quasi-regular (reduced) or regular.
+            Keyword gaussian can only be specified together with
+            keyword grid. Gaussian without grid has no effect.
+            Default is an empty string.
+        target : :obj:`string`, optional
+            Specifies a file into which data is to be written after
+            retrieval or manipulation. Path names should always be
+            enclosed in double quotes. The MARS client supports automatic
+            generation of multiple target files using MARS keywords
+            enclosed in square brackets [ ].  If the environment variable
+            MARS_MULTITARGET_STRICT_FORMAT is set to 1 before calling mars,
+            the keyword values will be used in the filename as shown by
+            the ecCodes GRIB tool grib_ls -m, e.g. with
+            MARS_MULTITARGET_STRICT_FORMAT set to 1 the keywords time,
+            expver and param will be formatted as 0600, 0001 and 129.128
+            rather than 600, 1 and 129.
+            Default is an empty string.
+        param : :obj:`string`, optional
+            Specifies the meteorological parameter.
+            The list of meteorological parameters in MARS is extensive.
+            Their availability is directly related to their meteorological
+            meaning and, therefore, the rest of directives specified
+            in the MARS request.
+            Meteorological parameters can be specified by their
+            GRIB code (param=130), their mnemonic (param=t) or
+            full name (param=temperature).
+            The list of parameter should be seperated by a "/"-sign.
+            E.g. 130/131/133
+            Default is an empty string.
+        Return
+        ------
         '''
 …
     def display_info(self):
+        '''
+        @Description:
+            Prints all class attributes and their values to the
+            standard output.
+        @Input:
+            self: instance of MarsRetrieval
+                For description see class documentation.
+        @Return:
+            <nothing>
+        '''Prints all class attributes and their values to the
+        standard output.
+        Parameters
+        ----------
+        Return
+        ------
         '''
         # Get all class attributes and their values as a dictionary
 …
     def print_info(self, inputdir, request_number):
+        '''
+        @Description:
+            Prints all mars requests to an extra file for debugging and
+            information.
+        @Input:
+            self: instance of MarsRetrieval
+                For description see class documentation.
+            inputdir: string
+                The path where all data from the retrievals are stored.
+            request_number: integer
+                Number of mars requests for flux and non-flux data.
+            @Return:
+            <nothing>
+        '''Prints all mars requests to an extra file for debugging and
+        information.
+        Parameters
+        ----------
+        inputdir : :obj:`string`
+            The path where all data from the retrievals are stored.
+        request_number : :obj:`integer`
+            Number of mars requests for flux and non-flux data.
+        Return
+        ------
         '''
         # Get all class attributes and their values as a dictionary
 …
     def print_infodata_csv(self, inputdir, request_number):
+        '''
+        @Description:
+            Write all request parameter in alpabetical order into a "csv" file.
+        @Input:
+            self: instance of MarsRetrieval
+                For description see class documentation.
+            inputdir: string
+                The path where all data from the retrievals are stored.
+            request_number: integer
+                Number of mars requests for flux and non-flux data.
+        @Return:
+            <nothing>
+        '''Write all request parameter in alpabetical order into a "csv" file.
+        Parameters
+        ----------
+        inputdir : :obj:`string`
+            The path where all data from the retrievals are stored.
+        request_number : :obj:`integer`
+            Number of mars requests for flux and non-flux data.
+        Return
+        ------
         '''
 …
     def data_retrieve(self):
+        '''
+        @Description:
+            Submits a MARS retrieval. Depending on the existence of
+            ECMWF Web-API it is submitted via Python or a
+            subprocess in the Shell. The parameter for the mars retrieval
+            are taken from the defined class attributes.
+        @Input:
+            self: instance of MarsRetrieval
+                For description see class documentation.
+        @Return:
+            <nothing>
+        '''Submits a MARS retrieval. Depending on the existence of
+        ECMWF Web-API it is submitted via Python or a
+        subprocess in the Shell. The parameter for the mars retrieval
+        are taken from the defined class attributes.
+        Parameters
+        ----------
+        Return
+        ------
         '''
         # Get all class attributes and their values as a dictionary

source/python/classes/UioFiles.py

-                      rca867de
+                      r274f9ef
 class UioFiles(object):
+    '''
+    Class to manipulate files. At initialisation it has the pattern
+    '''Class to manipulate files. At initialisation it has the pattern
     which stores a regular expression pattern for the files, the path
     to the files and the files already.
 …
     # --------------------------------------------------------------------------
     def __init__(self, path, pattern):
+        '''
+        @Description:
+            Assignes a specific pattern for these files.
+        '''Assignes a specific pattern for these files.
+        @Input:
+            self: instance of UioFiles
+                Description see class documentation.
+        Parameters
+        ----------
+        path : :obj:`string`
+            Directory where to list the files.
             path: string
                 Directory where to list the files.
+        pattern : :obj:`string`
+            Regular expression pattern. For example: '\*.grb'
             pattern: string
                 Regular expression pattern. For example: '*.grb'
+        Return
+        ------
-        @Return:
-            <nothing>
         '''
 …
     #@profiling.timefn
     def __list_files__(self, path):
+        '''
+        @Description:
+            Lists all files in the directory with the matching
+            regular expression pattern.
+        '''Lists all files in the directory with the matching
+        regular expression pattern.
+        @Input:
+            self: instance of UioFiles
+                Description see class documentation.
+        Parameters
+        ----------
+        path : :obj:`string`
+            Path to the files.
             path: string
                 Path to the files.
+        Return
+        ------
-        @Return:
-            <nothing>
         '''
         # Get the absolute path
 …
     def __str__(self):
+        '''
+        @Description:
+            Converts the list of files into a single string.
+            The entries are sepereated by "," sign.
+        '''Converts the list of files into a single string.
+        The entries are sepereated by "," sign.
+        @Input:
+            self: instance of UioFiles
+                Description see class documentation.
+        Parameters
+        ----------
+        @Return:
+            files_string: string
+                The content of the list as a single string.
+        Return
+        ------
+        files_string : :obj:`string`
+            The content of the list as a single string.
         '''
 …
     def delete_files(self):
+        '''
+        @Description:
+            Deletes the files.
+        '''Deletes the files.
+        @Input:
+            self: instance of UioFiles
+                Description see class documentation.
+        Parameters
+        ----------
+        @Return:
+            <nothing>
+        Return
+        ------
         '''

source/python/install.py

-                      rc5074d2
+                      r274f9ef
 # ------------------------------------------------------------------------------
 def main():
+    '''
+    @Description:
+        Controls the installation process. Calls the installation function
+        if target is specified.
+    @Intput:
+        <nothing>
+    @Return:
+        <nothing>
+    '''Controls the installation process. Calls the installation function
+    if target is specified.
+    Parameters
+    ----------
+    Return
+    ------
     '''
 …
 def get_install_cmdline_arguments():
+    '''
+    @Description:
+        Decomposes the command line arguments and assigns them to variables.
+        Apply default values for non mentioned arguments.
+    @Input:
+        <nothing>
+    @Return:
+        args: instance of ArgumentParser
+            Contains the commandline arguments from script/program call.
+    '''Decomposes the command line arguments and assigns them to variables.
+    Apply default values for non mentioned arguments.
+    Parameters
+    ----------
+    Return
+    ------
+    args : :obj:`Namespace`
+        Contains the commandline arguments from script/program call.
     '''
     parser = ArgumentParser(description='Install flex_extract software locally or \
 …
 def install_via_gateway(c):
+    '''
+    @Description:
+        Perform the actual installation on local machine or prepare data
+        transfer to remote gate and submit a job script which will
+        install everything on the remote gate.
+    @Input:
+        c: instance of class ControlFile
+            Contains all the parameters of CONTROL file and
+            command line.
+            For more information about format and content of the parameter
+            see documentation.
+    @Return:
+        <nothing>
+    '''Perform the actual installation on local machine or prepare data
+    transfer to remote gate and submit a job script which will
+    install everything on the remote gate.
+    Parameters
+    ----------
+    c : :obj:`ControlFile`
+        Contains all the parameters of CONTROL file and
+        command line.
+    Return
+    ------
     '''
     import tarfile
 …
 def mk_tarball(tarball_path, target):
     '''
     @Description:
         Creates a tarball with all necessary files which need to be sent to the
         installation directory.
         It does not matter if this is local or remote.
         Collects all python files, the Fortran source and makefiles,
+        the ECMWF_ENV file, the CONTROL files as well as the
         template files.
     @Input:
         tarball_path: string
             The complete path to the tar file which will contain all
+            relevant data for flex_extract.
         target: string
+            The queue where the job is submitted to.
     @Return:
+        <nothing>
+    '''Creates a tarball with all necessary files which need to be sent to the
+    installation directory.
+    It does not matter if this is local or remote.
+    Collects all python files, the Fortran source and makefiles,
+    the ECMWF_ENV file, the CONTROL files as well as the
+    template files.
+    Parameters
+    ----------
+    tarball_path : :obj:`string`
+        The complete path to the tar file which will contain all
+        relevant data for flex_extract.
+    target : :obj:`string`
+        The queue where the job is submitted to.
+    Return
+    ------
     '''
     import tarfile
 …
 def un_tarball(tarball_path):
     '''
+    @Description:
         Extracts the given tarball into current directory.
     @Input:
         tarball_path: string
             The complete path to the tar file which will contain all
+            relevant data for flex_extract.
     @Return:
+        <nothing>
+    '''Extracts the given tarball into current directory.
+    Parameters
+    ----------
+    tarball_path : :obj:`string`
+        The complete path to the tar file which will contain all
+        relevant data for flex_extract.
+    Return
+    ------
     '''
     import tarfile
 …
 def mk_env_vars(ecuid, ecgid, gateway, destination):
     '''
     @Description:
         Creates a file named ECMWF_ENV which contains the
+        necessary environmental variables at ECMWF servers.
         It is based on the template ECMWF_ENV.template.
     @Input:
         ecuid: string
+            The user id on ECMWF server.
         ecgid: string
+            The group id on ECMWF server.
         gateway: string
+            The gateway server the user is using.
         destination: string
             The remote destination which is used to transfer files
+            from ECMWF server to local gateway server.
     @Return:
+        <nothing>
+    '''Creates a file named ECMWF_ENV which contains the
+    necessary environmental variables at ECMWF servers.
+    It is based on the template ECMWF_ENV.template.
+    Parameters
+    ----------
+    ecuid : :obj:`string`
+        The user id on ECMWF server.
+    ecgid : :obj:`string`
+        The group id on ECMWF server.
+    gateway : :obj:`string`
+        The gateway server the user is using.
+    destination : :obj:`string`
+        The remote destination which is used to transfer files
+        from ECMWF server to local gateway server.
+    Return
+    ------
     '''
     from genshi.template.text import NewTextTemplate
 …
 def mk_compilejob(makefile, target, ecuid, ecgid, fp_root):
     '''
     @Description:
         Modifies the original job template file so that it is specified
+        for the user and the environment were it will be applied. Result
         is stored in a new file "job.temp" in the python directory.
     @Input:
         makefile: string
             Name of the makefile which should be used to compile FORTRAN
+            CONVERT2 program.
         target: string
+            The target where the installation should be done, e.g. the queue.
         ecuid: string
+            The user id on ECMWF server.
         ecgid: string
+            The group id on ECMWF server.
         fp_root: string
            Path to the root directory of FLEXPART environment or flex_extract
+           environment.
     @Return:
+        <nothing>
+    '''Modifies the original job template file so that it is specified
+    for the user and the environment were it will be applied. Result
+    is stored in a new file "job.temp" in the python directory.
+    Parameters
+    ----------
+    makefile : :obj:`string`
+        Name of the makefile which should be used to compile FORTRAN
+        CONVERT2 program.
+    target : :obj:`string`
+        The target where the installation should be done, e.g. the queue.
+    ecuid : :obj:`string`
+        The user id on ECMWF server.
+    ecgid : :obj:`string`
+        The group id on ECMWF server.
+    fp_root : :obj:`string`
+       Path to the root directory of FLEXPART environment or flex_extract
+       environment.
+    Return
+    ------
     '''
     from genshi.template.text import NewTextTemplate
 …
 def mk_job_template(ecuid, ecgid, gateway, destination, fp_root):
     '''
     @Description:
         Modifies the original job template file so that it is specified
+        for the user and the environment were it will be applied. Result
         is stored in a new file.
     @Input:
         ecuid: string
+            The user id on ECMWF server.
         ecgid: string
+            The group id on ECMWF server.
         gateway: string
+            The gateway server the user is using.
         destination: string
             The remote destination which is used to transfer files
+            from ECMWF server to local gateway server.
         fp_root: string
            Path to the root directory of FLEXPART environment or flex_extract
+           environment.
     @Return:
+        <nothing>
+    '''Modifies the original job template file so that it is specified
+    for the user and the environment were it will be applied. Result
+    is stored in a new file.
+    Parameters
+    ----------
+    ecuid : :obj:`string`
+        The user id on ECMWF server.
+    ecgid : :obj:`string`
+        The group id on ECMWF server.
+    gateway : :obj:`string`
+        The gateway server the user is using.
+    destination : :obj:`string`
+        The remote destination which is used to transfer files
+        from ECMWF server to local gateway server.
+    fp_root : :obj:`string`
+       Path to the root directory of FLEXPART environment or flex_extract
+       environment.
+    Return
+    ------
     '''
     from genshi.template.text import NewTextTemplate
 …
 def delete_convert_build(src_path):
     '''
     @Description:
+        Clean up the Fortran source directory and remove all
         build files (e.g. *.o, *.mod and CONVERT2)
     @Input:
         src_path: string
+            Path to the fortran source directory.
     @Return:
+        <nothing>
+    '''Clean up the Fortran source directory and remove all
+    build files (e.g. \*.o, \*.mod and CONVERT2)
+    Parameters
+    ----------
+    src_path : :obj:`string`
+        Path to the fortran source directory.
+    Return
+    ------
     '''
 …
 def make_convert_build(src_path, makefile):
     '''
+    @Description:
         Compiles the Fortran code and generates the executable.
     @Input:
         src_path: string
+            Path to the fortran source directory.
         makefile: string
+            The name of the makefile which should be used.
     @Return:
+        <nothing>
+    '''Compiles the Fortran code and generates the executable.
+    Parameters
+    ----------
+    src_path : :obj:`string`
+        Path to the fortran source directory.
+    makefile : :obj:`string`
+        The name of the makefile which should be used.
+    Return
+    ------
     '''

source/python/mods/get_mars_data.py

-                      r70fee58
+                      r274f9ef
 # ------------------------------------------------------------------------------
 def main():
+    '''
+    @Description:
+        If get_mars_data is called directly from command line,
+        the program flow and calls the argumentparser function and
+        the get_mars_data function for retrieving EC data.
+    @Input:
+        <nothing>
+    @Return:
+        <nothing>
+    '''Controls the program to get data out of mars.
+    This is done if it is called directly from command line.
+    Then it also takes program call arguments and control file input.
+    Parameters
+    ----------
+    Return
+    ------
     '''
 …
 def get_mars_data(c):
+    '''
+    @Description:
+        Retrieves the EC data needed for a FLEXPART simulation.
+        Start and end dates for retrieval period is set. Retrievals
+        are divided into smaller periods if necessary and datechunk parameter
+        is set.
+    @Input:
+        c: instance of class ControlFile
+            Contains all the parameters of CONTROL file and
+            command line.
+            For more information about format and content of the parameter
+            see documentation.
+    @Return:
+        <nothing>
+    '''Retrieves the EC data needed for a FLEXPART simulation.
+    Start and end dates for retrieval period is set. Retrievals
+    are divided into smaller periods if necessary and datechunk parameter
+    is set.
+    Parameters
+    ----------
+    c : :obj:`ControlFile`
+        Contains all the parameters of CONTROL file and
+        command line.
+    Return
+    ------
     '''
 …
 def do_retrievement(c, server, start, end, delta_t, fluxes=False):
+    '''
+    @Description:
+        Divides the complete retrieval period in smaller chunks and
+        retrieves the data from MARS.
+    @Input:
+        c: instance of class ControlFile
+            Contains all the parameters of CONTROL file and
+            command line.
+            For more information about format and content of the parameter
+            see documentation.
+        server: instance of ECMWFService
+            The server connection to ECMWF
+        start: instance of datetime
+            The start date of the retrieval.
+        end: instance of datetime
+            The end date of the retrieval.
+        delta_t: instance of datetime
+            Delta_t +1 is the maximal time period of a single
+            retrieval.
+        fluxes: boolean, optional
+            Decides if the flux parameters are to be retrieved or
+            the rest of the parameter list.
+            Default value is False.
+    @Return:
+        <nothing>
+    '''Divides the complete retrieval period in smaller chunks and
+    retrieves the data from MARS.
+    Parameters
+    ----------
+    c : :obj:`ControlFile`
+        Contains all the parameters of CONTROL file and
+        command line.
+    server : :obj:`ECMWFService`
+            The server connection to ECMWF.
+    start : :obj:`datetime`
+        The start date of the retrieval.
+    end : :obj:`datetime`
+        The end date of the retrieval.
+    delta_t : :obj:`datetime`
+        Delta_t + 1 is the maximal time period of a single
+        retrieval.
+    fluxes : :obj:`boolean`, optional
+        Decides if the flux parameters are to be retrieved or
+        the rest of the parameter list.
+        Default value is False.
+    Return
+    ------
     '''

source/python/mods/prepare_flexpart.py

-                      r70fee58
+                      r274f9ef
 # ------------------------------------------------------------------------------
 def main():
+    '''
+    @Description:
+        If prepare_flexpart is called from command line, this function controls
+        the program flow and calls the argumentparser function and
+        the prepare_flexpart function for preparation of GRIB data for FLEXPART.
+    '''Controls the program to prepare flexpart input files from mars data.
     @Input:
         <nothing>
+    This is done if it is called directly from command line.
+    Then it also takes program call arguments and control file input.
+    @Return:
+        <nothing>
+    Parameters
+    ----------
+    Return
+    ------
     '''
 …
 def prepare_flexpart(ppid, c):
+    '''
+    @Description:
+        Lists all grib files retrieved from MARS with get_mars_data and
+        uses prepares data for the use in FLEXPART. Specific data fields
+        are converted to a different grid and the flux data are going to be
+        disaggregated. The data fields are collected by hour and stored in
+        a file with a specific FLEXPART relevant naming convention.
+    '''Converts the mars data into flexpart ready input files.
     @Input:
         ppid: int
             Contains the ppid number of the current ECMWF job. If it is called
             from this script, it is "None".
+    Specific data fields are converted to a different grid and the flux
+    data are going to be disaggregated. The data fields are collected by
+    hour and stored in a file with a specific FLEXPART relevant naming
+    convention.
         c: instance of class ControlFile
             Contains all the parameters of CONTROL file and
             command line.
             For more information about format and content of the parameter
             see documentation.
+    Parameters
+    ----------
+    ppid : :obj:`int`
+        Contains the ppid number of the current ECMWF job. It will be None if
+        the method was called within this module.
+    @Return:
+        <nothing>
+    c : :obj:`ControlFile`
+        Contains all the parameters of CONTROL file and
+        command line.
+    Return
+    ------
     '''

source/python/mods/tools.py

-                      r5bad6ec
+                      r274f9ef
 def none_or_str(value):
     '''
     @Description:
+        Converts the input string into pythons None-type if the string
         contains "None".
     @Input:
         value: string
+            String to be checked for the "None" word.
     @Return:
         None or value:
             Return depends on the content of the input value. If it was "None",
             then the python type None is returned. Otherwise the string itself.
+    '''Converts the input string into pythons None-type if the string
+    contains string "None".
+    Parameters
+    ----------
+    value : :obj:`string`
+        String to be checked for the "None" word.
+    Return
+    ------
+    None or value:
+        Return depends on the content of the input value. If it was "None",
+        then the python type None is returned. Otherwise the string itself.
     '''
     if value == 'None':
 …
 def none_or_int(value):
     '''
     @Description:
+        Converts the input string into pythons None-type if the string
         contains "None". Otherwise it is converted to an integer value.
     @Input:
         value: string
+            String to be checked for the "None" word.
     @Return:
         None or int(value):
             Return depends on the content of the input value. If it was "None",
             then the python type None is returned. Otherwise the string is
             converted into an integer value.
+    '''Converts the input string into pythons None-type if the string
+    contains string "None". Otherwise it is converted to an integer value.
+    Parameters
+    ----------
+    value : :obj:`string`
+        String to be checked for the "None" word.
+    Return
+    ------
+    None or int(value):
+        Return depends on the content of the input value. If it was "None",
+        then the python type None is returned. Otherwise the string is
+        converted into an integer value.
     '''
     if value == 'None':
 …
 def get_cmdline_arguments():
+    '''
+    @Description:
+        Decomposes the command line arguments and assigns them to variables.
+        Apply default values for non mentioned arguments.
+    @Input:
+        <nothing>
+    @Return:
+        args: instance of ArgumentParser
+            Contains the commandline arguments from script/program call.
+    '''Decomposes the command line arguments and assigns them to variables.
+    Apply default values for non mentioned arguments.
+    Parameters
+    ----------
+    Return
+    ------
+    args : :obj:`Namespace`
+        Contains the commandline arguments from script/program call.
     '''
 …
 def read_ecenv(filename):
     '''
     @Description:
+        Reads the file into a dictionary where the key values are the parameter
         names.
     @Input:
         filename: string
+            Path to file where the ECMWV environment parameters are stored.
     @Return:
         envs: dict
             Contains the environment parameter ecuid, ecgid, gateway
             and destination for ECMWF server environments.
+    '''Reads the file into a dictionary where the key values are the parameter
+    names.
+    Parameters
+    ----------
+    filename : :obj:`string`
+        Path to file where the ECMWF environment parameters are stored.
+    Return
+    ------
+    envs : :obj:`dictionary`
+        Contains the environment parameter ecuid, ecgid, gateway
+        and destination for ECMWF server environments.
     '''
     envs= {}
 …
 def clean_up(c):
+    '''
+    @Description:
+        Remove all files from intermediate directory
+        (inputdir from CONTROL file).
+    @Input:
+        c: instance of class ControlFile
+            Contains all the parameters of CONTROL file and
+            command line.
+            For more information about format and content of the parameter
+            see documentation.
+    @Return:
+        <nothing>
+    '''Remove all files from intermediate directory (inputdir).
+    Parameters
+    ----------
+    c : :obj:`ControlFile`
+        Contains all the parameters of CONTROL file and
+        command line.
+    Return
+    ------
     '''
 …
 def my_error(users, message='ERROR'):
     '''
     @Description:
+        Prints a specified error message which can be passed to the function
         before exiting the program.
     @Input:
         user: list of strings
             Contains all email addresses which should be notified.
             It might also contain just the ecmwf user name which wil trigger
+            mailing to the associated email address for this user.
         message: string, optional
+            Error message. Default value is "ERROR".
     @Return:
+        <nothing>
+    '''Prints a specified error message which can be passed to the function
+    before exiting the program.
+    Parameters
+    ----------
+    user : :obj:`list` of :obj:`string`
+        Contains all email addresses which should be notified.
+        It might also contain just the ecmwf user name which wil trigger
+        mailing to the associated email address for this user.
+    message : :obj:`string`, optional
+        Error message. Default value is "ERROR".
+    Return
+    ------
     '''
 …
 def normal_exit(users, message='Done!'):
+    '''
+    @Description:
+        Prints a specific exit message which can be passed to the function.
+    @Input:
+        user: list of strings
+            Contains all email addresses which should be notified.
+            It might also contain just the ecmwf user name which wil trigger
+            mailing to the associated email address for this user.
+        message: string, optional
+            Message for exiting program. Default value is "Done!".
+    @Return:
+        <nothing>
+    '''Prints a specific exit message which can be passed to the function.
+    Parameters
+    ----------
+    user : :obj:`list` of :obj:`string`
+        Contains all email addresses which should be notified.
+        It might also contain just the ecmwf user name which wil trigger
+        mailing to the associated email address for this user.
+    message : :obj:`string`, optional
+        Message for exiting program. Default value is "Done!".
+    Return
+    ------
     '''
 …
 def product(*args, **kwds):
+    '''
+    @Description:
+        This method is taken from an example at the ECMWF wiki website.
+        https://software.ecmwf.int/wiki/display/GRIB/index.py; 2018-03-16
+        This method combines the single characters of the passed arguments
+        with each other. So that each character of each argument value
+        will be combined with each character of the other arguments as a tuple.
+        Example:
+        product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
+        product(range(2), repeat = 3) --> 000 001 010 011 100 101 110 111
+    @Input:
+        *args: tuple
+            Positional arguments (arbitrary number).
+        **kwds: dictionary
+            Contains all the keyword arguments from *args.
+    @Return:
+        prod: tuple
+            Return will be done with "yield". A tuple of combined arguments.
+            See example in description above.
+    '''This method combines the single characters of the passed arguments
+    with each other. So that each character of each argument value
+    will be combined with each character of the other arguments as a tuple.
+    Note
+    ----
+    This method is taken from an example at the ECMWF wiki website.
+    https://software.ecmwf.int/wiki/display/GRIB/index.py; 2018-03-16
+    Example
+    -------
+    product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
+    product(range(2), repeat = 3) --> 000 001 010 011 100 101 110 111
+    Parameters
+    ----------
+    \*args : :obj:`tuple`
+        Positional arguments (arbitrary number).
+    \*\*kwds : :obj:`dictionary`
+        Contains all the keyword arguments from \*args.
+    Return
+    ------
+    prod : :obj:`tuple`
+        Return will be done with "yield". A tuple of combined arguments.
+        See example in description above.
     '''
     pools = map(tuple, args) * kwds.get('repeat', 1)
 …
 def silent_remove(filename):
     '''
     @Description:
+        Remove file if it exists.
         The function does not fail if the file does not exist.
     @Input:
         filename: string
+            The name of the file to be removed without notification.
     @Return:
+        <nothing>
+    '''Remove file if it exists.
+    The function does not fail if the file does not exist.
+    Parameters
+    ----------
+    filename : :obj:`string`
+        The name of the file to be removed without notification.
+    Return
+    ------
     '''
     try:
 …
 def init128(filepath):
     '''
+    @Description:
         Opens and reads the grib file with table 128 information.
     @Input:
         filepath: string
+            Path to file of ECMWF grib table number 128.
     @Return:
         table128: dictionary
             Contains the ECMWF grib table 128 information.
             The key is the parameter number and the value is the
             short name of the parameter.
+    '''Opens and reads the grib file with table 128 information.
+    Parameters
+    ----------
+    filepath : :obj:`string`
+        Path to file of ECMWF grib table number 128.
+    Return
+    ------
+    table128 : :obj:`dictionary`
+        Contains the ECMWF grib table 128 information.
+        The key is the parameter number and the value is the
+        short name of the parameter.
     '''
     table128 = dict()
 …
 def to_param_id(pars, table):
+    '''
+    @Description:
+        Transform parameter names to parameter ids
+        with ECMWF grib table 128.
+    @Input:
+        pars: string
+            Addpar argument from CONTROL file in the format of
+            parameter names instead of ids. The parameter short
+            names are sepearted with "/" and they are passed as
+            one single string.
+        table: dictionary
+            Contains the ECMWF grib table 128 information.
+            The key is the parameter number and the value is the
+            short name of the parameter.
+    @Return:
+        ipar: list of integer
+            List of addpar parameters from CONTROL file transformed to
+            parameter ids in the format of integer.
+    '''Transform parameter names to parameter ids with ECMWF grib table 128.
+    Parameters
+    ----------
+    pars : :obj:`string`
+        Addpar argument from CONTROL file in the format of
+        parameter names instead of ids. The parameter short
+        names are sepearted with "/" and they are passed as
+        one single string.
+    table : :obj:`dictionary`
+        Contains the ECMWF grib table 128 information.
+        The key is the parameter number and the value is the
+        short name of the parameter.
+    Return
+    ------
+    ipar : :obj:`list` of :obj:`integer`
+        List of addpar parameters from CONTROL file transformed to
+        parameter ids in the format of integer.
     '''
     cpar = pars.upper().split('/')
 …
 def get_list_as_string(list_obj, concatenate_sign=', '):
     '''
+    @Description:
         Converts a list of arbitrary content into a single string.
     @Input:
         list_obj: list
+            A list with arbitrary content.
         concatenate_sign: string, optional
             A string which is used to concatenate the single
+            list elements. Default value is ", ".
     @Return:
         str_of_list: string
             The content of the list as a single string.
+    '''Converts a list of arbitrary content into a single string.
+    Parameters
+    ----------
+    list_obj : :obj:`list`
+        A list with arbitrary content.
+    concatenate_sign : :obj:`string`, optional
+        A string which is used to concatenate the single
+        list elements. Default value is ", ".
+    Return
+    ------
+    str_of_list : :obj:`string`
+        The content of the list as a single string.
     '''
 …
 def make_dir(directory):
     '''
     @Description:
+        Creates a directory and gives a warning if the directory
         already exists. The program stops only if there is another problem.
     @Input:
         directory: string
+            The directory name including the path which should be created.
     @Return:
+        <nothing>
+    '''Creates a directory and gives a warning if the directory
+    already exists. The program stops only if there is another problem.
+    Parameters
+    ----------
+    directory : :obj:`string`
+        The directory name including the path which should be created.
+    Return
+    ------
     '''
     try:
 …
 def put_file_to_ecserver(ecd, filename, target, ecuid, ecgid):
+    '''
+    @Description:
+        Uses the ecaccess-file-put command to send a file to the ECMWF servers.
+        NOTE:
+        The return value is just for testing reasons. It does not have
+        to be used from the calling function since the whole error handling
+        is done in here.
+    @Input:
+        ecd: string
+            The path were the file is stored.
+        filename: string
+            The name of the file to send to the ECMWF server.
+        target: string
+            The target queue where the file should be sent to.
+        ecuid: string
+            The user id on ECMWF server.
+        ecgid: string
+            The group id on ECMWF server.
+    @Return:
+        rcode: string
+            Resulting code of command execution. If successful the string
+            will be empty.
+    '''Uses the ecaccess-file-put command to send a file to the ECMWF servers.
+    Note
+    ----
+    The return value is just for testing reasons. It does not have
+    to be used from the calling function since the whole error handling
+    is done in here.
+    Parameters
+    ----------
+    ecd : :obj:`string`
+        The path were the file is stored.
+    filename : :obj:`string`
+        The name of the file to send to the ECMWF server.
+    target : :obj:`string`
+        The target queue where the file should be sent to.
+    ecuid : :obj:`string`
+        The user id on ECMWF server.
+    ecgid : :obj:`string`
+        The group id on ECMWF server.
+    Return
+    ------
+    rcode : :obj:`string`
+        Resulting code of command execution. If successful the string
+        will be empty.
     '''
 …
 def submit_job_to_ecserver(target, jobname):
+    '''
+    @Description:
+        Uses ecaccess-job-submit command to submit a job to the ECMWF server.
+        NOTE:
+        The return value is just for testing reasons. It does not have
+        to be used from the calling function since the whole error handling
+        is done in here.
+    @Input:
+        target: string
+            The target where the file should be sent to, e.g. the queue.
+        jobname: string
+            The name of the jobfile to be submitted to the ECMWF server.
+    @Return:
+        rcode: string
+            Resulting code of command execution. If successful the string
+            will contain an integer number, representing the id of the job
+            at the ecmwf server.
+    '''Uses ecaccess-job-submit command to submit a job to the ECMWF server.
+    Note
+    ----
+    The return value is just for testing reasons. It does not have
+    to be used from the calling function since the whole error handling
+    is done in here.
+    Parameters
+    ----------
+    target : :obj:`string`
+        The target where the file should be sent to, e.g. the queue.
+    jobname : :obj:`string`
+        The name of the jobfile to be submitted to the ECMWF server.
+    Return
+    ------
+    rcode : :obj:`string`
+        Resulting code of command execution. If successful the string
+        will contain an integer number, representing the id of the job
+        at the ecmwf server.
     '''

source/python/submit.py

-                      r27fe969
+                      r274f9ef
 def main():
+    '''
+    @Description:
+        Get the arguments from script call and from CONTROL file.
+        Decides from the argument "queue" if the local version
+        is done "queue=None" or the gateway version with "queue=ecgate"
+        or "queue=cca".
+    '''Get the arguments from script call and from CONTROL file.
+    Decides from the argument "queue" if the local version
+    is done "queue=None" or the gateway version with "queue=ecgate"
+    or "queue=cca".
     @Input:
         <nothing>
+    Parameters
+    ----------
+    @Return:
+        <nothing>
+    Return
+    ------
     '''
 …
 def submit(jtemplate, c, queue):
+    '''
+    @Description:
+        Prepares the job script and submit it to the specified queue.
+    '''Prepares the job script and submit it to the specified queue.
+    @Input:
+        jtemplate: string
+            Job template file from sub-directory "_templates" for
+            submission to ECMWF. It contains all necessary
+            module and variable settings for the ECMWF environment as well as
+            the job call and mail report instructions.
+            Default is "job.temp".
+    Parameters
+    ----------
+    jtemplate : :obj:`string`
+        Job template file from sub-directory "_templates" for
+        submission to ECMWF. It contains all necessary
+        module and variable settings for the ECMWF environment as well as
+        the job call and mail report instructions.
+        Default is "job.temp".
+        c: instance of class ControlFile
+            Contains all the parameters of CONTROL file and
+            command line.
+            For more information about format and content of the parameter
+            see documentation.
+    c : :obj:`ControlFile`
+        Contains all the parameters of CONTROL file and
+        command line.
         queue: string
             Name of queue for submission to ECMWF (e.g. ecgate or cca )
+    queue : :obj:`string`
+        Name of queue for submission to ECMWF (e.g. ecgate or cca )
+    @Return:
+        <nothing>
+    Return
+    ------
     '''

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 274f9ef in flex_extract.git for source

Legend:

Download in other formats: