Standard interface_v0.1

Overview

The srm-modules standard interface is the common basis shared by all modules. Module being simple scripts, the standard interface is the formalism with which arguments and parameters are specified during script calls for data refinement processing and their storage.

Formally, srm-modules are constituted of two scripts, a main script used to call the srm-module processing chain and a kernel script that implement the processing chain itself. Script are implemented in this way to allows the usage of GNU parallel for the parallel processing.

Presentation

The first element of the standard interface are given by simple rules that have to be followed by any srm-module being part of the kernel or not. Those rules fix the way argument and parameters are specified and the way data refinement results have to be stored.

The first rule modules are subject to is related to the way arguments and parameters are handled to produce to module hash sum used for data refinement results storage :

Any given argument, specified with '--' or '-' switches, has to
come with a parameter. In other work, arguments cannot be given
without one and only one parameter

The second rules is also linked to the way module hash sums are computed on the basis of the command line :

A argument starting with '--' switch is not considered in the
computation of the module hash sum. In other words, arguments 
starting with '-' switch are the only arguments kept for this
computation.

It follows from that a srm-module called with the exact same arguments and parameters except for one single difference in the parameter of an '-' switch argument will generates two different hash sum and so two different storage for the refined data. This consideration motivates the last following rule :

Arguments specified with '-' switch cannot have default values.

It means that an argument engaged in the computation of the hash sum required by the module has to be formally given at each srm-module call. The module has not the right to used a default value.

Finally, a last good practice about implementation of the srm-module processing kernel concern re-processing of the same data using the same processing chain : srm-module have the responsibility to detects already processed data, at the level of the poses, in order not to process them more than once. Moreover, srm-modules have to check if the forced reprocessing parameter is provided to reprocess already processed data.

Standard interface

The standard interface formalise the way arguments and parameters not engaged in the computation of the srm-module hash sums have to be specified. Those arguments and parameters are common to all srm-modules and concern specification of the parameters that are not linked to the proper data refinement parameterisation. Starting with the data storage related arguments :

--mount-point

The parameter of this argument gives the root path on which the 
standard data storage is mounted on the considered computer

The following arguments are related to the srm-module script execution :

--display

The parameter of this argument gives the execution mode of the
srm-module. The default value is 'default' and trigger the
module data processing.

If 'nodes' is provided and if the mount point of the standard
storage structure is specified, the modules dumps on the
standard error output the list of the storage node containing
data that can be considered by the srm-module as input data.

If 'hash' is provided, the module dumps on the standard error
output the value of the hash it will create for the output data
storage node considering the given arguments and their
parameters.

If 'iclass' or 'iclass' is provided as parameter, the module
dumps in the standard error output the input and output
classification of the input and output data it considers in it
processing chain, respectively.

--thread

The parameter of the argument can be both a number or a path to
a GNU parallel SSH configuration file.

If a number is provided, the module executes its task on the
local machine using the provided number as thread count. If a
configuration file is provided, the module uses it to specify
GNU parallel the available node and thread count for its data
processing.

--force

If the parameter of this argument is 'false', the module do not
reprocess data already processed. If 'true' is provided as
parameter, the module process data and also reprocess data 
already processed.

Finally, the following arguments are used to signify to srm-modules which data have to be considered for the refinement they have to perform :

--address

The parameter of this argument is MMSR addresses used to
determine which poses have to be considered by the module
processing stage.

This argument allows only one single MMSR as parameter. Now,
this argument can be respecified with a parameter as many times
as necessary.

-n

Formally, the parameter of this argument is not part of the
standard interface being engage in the computation of the module 
hash. Nevertheless it is documented here because it appears in
each srm-module call.

The parameter of this argument is used to identify the data 
storage node to consider for searching poses to process using
the provided MMSR addresses. A list of the possible node can be
displayed using 

    --display nodes (--mount-point required)

as argument and parameter of the module.

More documentation about MMSR can be found on the following page.