docstringed new set of configurators

MDANSE/Framework/Configurators/IConfigurator.py

@@ -79,8 +79,8 @@ class ConfiguratorError(Error):
 class IConfigurator(dict):
     '''
     This class implements the base class for configurator objects. A configurator object is a dictionary-derived object that is used 
-    to configure one input value of a given configuration. Once the input value is configured, the dictionary is updated with keys/values 
-    that depend on the type of configurator type in use.
+    to configure one item of a given configuration. Once the input value given for that item is configured, the dictionary is updated 
+    with keys/values providing information about this item.
     
     A configurator is not designed to be used as a stand-alone object. It should be used within the scope of a Configurable object that 
     will store a complete configuration for a given task (e.g. job, Q vectors, instrument resolution ...).

MDANSE/Framework/Configurators/IntegerConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 from MDANSE.Framework.Configurators.IConfigurator import IConfigurator, ConfiguratorError

MDANSE/Framework/Configurators/InterpolationOrderConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 from MDANSE.Framework.Configurators.IConfigurator import ConfiguratorError

MDANSE/Framework/Configurators/MMTKTrajectoryConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import os
@@ -37,16 +37,30 @@ from MDANSE import PLATFORM, REGISTRY
 from MDANSE.Framework.Configurators.InputFileConfigurator import InputFileConfigurator
 
 class MMTKNetCDFTrajectoryConfigurator(InputFileConfigurator):
-    """
-    MMTK trajectory file is a NetCDF file that store various data related to 
-    molecular dynamics : atomic positions, velocities, energies, energy gradients etc. 
-    """
+    '''
+    This configurator allow to input a MMTK trajectory file.
+    
+    MMTK trajectory file is the format used in MDANSE to store Molecular Dynamics trajectories. It is a NetCDF file 
+    that store various data related to the molecular dynamics : atomic positions, velocities, energies, energy gradients etc...
+    
+    To use trajectories derived from MD packages different from MMTK, it is compulsory to convert them before to a MMTK trajectory file.
+    
+    :attention: once configured, the MMTK trajectory file will be opened for reading.    
+    '''
     
     type = 'mmtk_trajectory'
     
-    _default = os.path.join('waterbox_in_periodic_universe.nc')
+    _default = 'waterbox_in_periodic_universe.nc'
                         
     def configure(self, configuration, value):
+        '''
+        Configure a MMTK trajectory file. 
+                
+        :param configuration: the current configuration.
+        :type configuration: a MDANSE.Framework.Configurable.Configurable object
+        :param value: the path for the MMTK trajectory file.
+        :type value: str 
+        '''
                 
         InputFileConfigurator.configure(self, configuration, value)
         
@@ -70,6 +84,12 @@ class MMTKNetCDFTrajectoryConfigurator(InputFileConfigurator):
         self['has_velocities'] = 'velocities' in self['instance'].variables()
                 
     def get_information(self):
+        '''
+        Returns some basic informations about the contents of the MMTK trajectory file.
+        
+        :return: the informations about the contents of the MMTK trajectory file.
+        :rtype: str
+        '''
                 
         info = ["MMTK input trajectory: %r\n" % self["filename"]]
         info.append("Number of steps: %d\n" % self["length"])

MDANSE/Framework/Configurators/McStasInstrumentConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 from MDANSE.Framework.Configurators.InputFileConfigurator import InputFileConfigurator

MDANSE/Framework/Configurators/McStasOptionsConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import os

MDANSE/Framework/Configurators/McStasParametersConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import re

MDANSE/Framework/Configurators/MultipleChoicesConfigurator.py

@@ -27,14 +27,16 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 from MDANSE.Framework.Configurators.IConfigurator import IConfigurator, ConfiguratorError
 
 class MultipleChoicesConfigurator(IConfigurator):
     """
-     This Configurator allows to select several items among multiple choices.
+    This Configurator allows to select several items among multiple choices.
+     
+    :attention: all the selected items must belong to the allowed selection list. 
     """
     
     type = "multiple_choices"
@@ -42,14 +44,32 @@ class MultipleChoicesConfigurator(IConfigurator):
     _default = []
             
     def __init__(self, name, choices=None, nChoices=None, **kwargs):
+        '''
+        Initializes the configurator.
+
+        :param name: the name of the configurator as it will be appear in the configuration.
+        :type name: str
+        :param choices: the list of values allowed for selection.
+        :type choices: list
+        :param nChoices: the maximum number of values that can be selected or None if there is no restriction on this number.
+        :type nChoices: int or None
+        '''
         
         IConfigurator.__init__(self, name, **kwargs)
         
-        self._choices = choices if choices is not None else []
+        self._choices = choices
         
         self._nChoices = nChoices
 
     def configure(self, configuration, value):
+        '''
+        Configure the input selection list.
+                
+        :param configuration: the current configuration
+        :type configuration: a MDANSE.Framework.Configurable.Configurable object
+        :param value: the input selection list.
+        :type value: list
+        '''
 
         if self._nChoices is not None:
             if len(value) != self._nChoices:
@@ -62,17 +82,32 @@ class MultipleChoicesConfigurator(IConfigurator):
             except ValueError:                        
                 raise ConfiguratorError("%r item is not a valid choice" % v, self)
             
+        if not indexes:
+                raise ConfiguratorError("Empty choices selection.", self)
+
         self["indexes"] = indexes
         self["choices"] = [self._choices[i] for i in indexes]
         self["value"] = self["choices"]
             
     @property
     def choices(self):
+        '''
+        Returns the list of allowed selection items.
+        
+        :return: the list of allowed selection items.
+        :rtype: list
+        '''
         
         return self._choices
     
     @property
     def nChoices(self):
+        '''
+        Returns the maximum number items that can be selected or None if there is no restriction on this number.
+                
+        :return: the maximum number items that can be selected.
+        :rtype: int or None
+        '''
         
         return self._nChoices
 

MDANSE/Framework/Configurators/NetCDFInputFileConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 from Scientific.IO.NetCDF import NetCDFFile
@@ -37,7 +37,12 @@ from MDANSE.Framework.Configurators.InputFileConfigurator import InputFileConfig
 
 class NetCDFInputFileConfigurator(InputFileConfigurator):
     """
-    This configurator allows to input a NetCDF file.
+    This configurator allows to input a NetCDF file as input file.
+    
+    NetCDF is a set of software libraries and self-describing, machine-independent data formats that 
+    support the creation, access, and sharing of array-oriented scientific data.
+    
+    For more information, please consult the NetCDF website: http://www.unidata.ucar.edu/software/netcdf/
     """
     
     type = 'netcdf_input_file'
@@ -45,13 +50,29 @@ class NetCDFInputFileConfigurator(InputFileConfigurator):
     _default = ''
         
     def __init__(self, name, variables=None, **kwargs):
+        '''
+        Initializes the configurator.
         
+        :param name: the name of the configurator as it will be appear in the configuration.
+        :type name: str
+        :param variables: the list of NetCDF variables that must be present in the input NetCDF file or None if there is no compulsory variable.
+        :type variables: list of str or None
+        '''        
+
         # The base class constructor.
         InputFileConfigurator.__init__(self, name, **kwargs)
         
         self._variables = variables if variables is not None else []
            
     def configure(self, configuration, value):
+        '''
+        Configure a MMTK trajectory file. 
+                
+        :param configuration: the current configuration.
+        :type configuration: a MDANSE.Framework.Configurable.Configurable object
+        :param value: the path for the MMTK trajectory file.
+        :type value: str 
+        '''
                 
         InputFileConfigurator.configure(self, configuration, value)
         
@@ -69,9 +90,28 @@ class NetCDFInputFileConfigurator(InputFileConfigurator):
 
     @property
     def variables(self):
+        '''
+        Returns the list of NetCDF variables that must be present in the NetCDF file.
+        
+        :return: the list of NetCDF variables that must be present in the NetCDF file.
+        :rtype: list of str
+        '''
         
         return self._variables
 
     def get_information(self):
+        '''
+        Returns some basic informations about the contents of the MMTK trajectory file.
+        
+        :return: the informations about the contents of the MMTK trajectory file.
+        :rtype: str
+        '''
         
-        return "NetCDF input file: %r" % self["value"]
\ No newline at end of file
+        info = ["NetCDF input file: %r" % self["value"]]
+        
+        if self.has_key('instance'):
+            info.append("Contains the following variables:")
+            for v in self['instance'].variables:
+                info.append(v)
+            
+        return "\n".join(info)
\ No newline at end of file

MDANSE/Framework/Configurators/OutputDirectoryConfigurator.py

@@ -45,12 +45,28 @@ class OutputDirectoryConfigurator(IConfigurator):
     _default = os.getcwd()
 
     def __init__(self, name, new=False, **kwargs):
+        '''
+        Initializes the configurator.
+        
+        :param name: the name of the configurator as it will be appear in the configuration.
+        :type name: str
+        :param new: if True the output directory path will be checked for being new. 
+        :type new: bool
+        '''        
                 
         IConfigurator.__init__(self, name, **kwargs)
         
         self._new = new
 
     def configure(self, configuration, value):
+        '''
+        Configure an output directory. 
+                
+        :param configuration: the current configuration.
+        :type configuration: a MDANSE.Framework.Configurable.Configurable object
+        :param value: the path for the output directory.
+        :type value: str 
+        '''
         
         value = PLATFORM.get_path(value)
         
@@ -59,12 +75,13 @@ class OutputDirectoryConfigurator(IConfigurator):
                 raise ConfiguratorError("the output directory must not exist", self)
                                                 
         self['value'] = value        
-        
-    @property
-    def new(self):
-        
-        return self._new
-    
+            
     def get_information(self):
+        '''
+        Returns string information about this configurator.
+        
+        :return: the information about this configurator.
+        :rtype: str
+        '''
         
         return "Output directory: %r" % self['value']
\ No newline at end of file

MDANSE/Framework/Configurators/OutputFilesConfigurator.py

@@ -27,7 +27,7 @@
 ''' 
 Created on Mar 30, 2015
 
-@author: pellegrini
+@author: Eric C. Pellegrini
 '''
 
 import os
@@ -37,8 +37,14 @@ from MDANSE.Framework.Configurators.IConfigurator import IConfigurator, Configur
                 
 class OutputFilesConfigurator(IConfigurator):
     """
-    The output file configurator allow to select : the output directory, 
-    the basename, and the format of the file resulting from the analysis.
+    This configurator allows to define the output directory, the basename, and the format(s) of the output file(s) resulting from an 
+    analysis.
+    
+    Once configured, this configurator will provide a list of files built by joining the given output directory, the basename and the 
+    extensions corresponding to the input file formats.
+    
+    Currently MDANSE supports ASCII, NetCDF and SVG file formats. To define a new output file format for an analysis, you must inherit from
+    MDANSE.Framework.Formats.IFormat.IFormat interface.   
     """
     
     type = 'output_files'
@@ -46,12 +52,29 @@ class OutputFilesConfigurator(IConfigurator):
     _default = (os.getcwd(), "output", ["netcdf"])
                     
     def __init__(self, name, formats=None, **kwargs):
+        '''
+        Initializes the configurator.
+        
+        :param name: the name of the configurator as it will be appear in the configuration.
+        :type name: str
+        :param formats: the list of output file formats suported.  
+        :type formats: list of str
+        '''        
                         
         IConfigurator.__init__(self, name, **kwargs)
 
         self._formats = formats if formats is not None else ["netcdf"]
     
     def configure(self, configuration, value):
+        '''
+        Configure a set of output files for an analysis. 
+                
+        :param configuration: the current configuration.
+        :type configuration: a MDANSE.Framework.Configurable.Configurable object
+        :param value: the output files specifications. Must be a 3-tuple whose 1st element if the output directory, 2nd element the basename and 3rd element
+        a list of file formats.
+        :type value: 3-tuple
+        '''
         
         dirname, basename, formats = value
                 
@@ -85,9 +108,21 @@ class OutputFilesConfigurator(IConfigurator):
 
     @property
     def formats(self):
+        '''
+        Returns the list of output file formats suported.
+        
+        :return: the list of file formats suported.
+        :rtype: list of str
+        '''
         return self._formats
 
     def get_information(self):
+        '''
+        Returns string information about this configurator.
+        
+        :return: the information about this configurator.
+        :rtype: str
+        '''
         
         info = ["Input files:\n"]
         for f in self["files"]: