documentation

force_bdss/data_sources/base_data_source.py

@@ -19,5 +19,21 @@ class BaseDataSource(ABCHasStrictTraits):
 
     @abc.abstractmethod
     def run(self, model, parameters):
-        """Executes the data source evaluation/fetching and returns
-        the list of results as a DataSourceResult instance."""
+        """
+        Executes the KPI evaluation and returns the results it computes.
+        Reimplement this method in your specific KPI calculator.
+
+        Parameters
+        ----------
+        model: BaseDataSourceModel
+            The model of the DataSource, instantiated through create_model()
+
+        parameters: DataSourceParameters
+            a DataResultParameters instance containing the information coming
+            from the MCO
+
+        Returns
+        -------
+        DataSourceResult
+            Instance that holds the results computed by this DataSource.
+        """

force_bdss/data_sources/base_data_source_bundle.py

@@ -19,6 +19,7 @@ class BaseDataSourceBundle(ABCHasStrictTraits):
     #: A human readable name of the bundle. Spaces allowed
     name = String()
 
+    #: Reference to the plugin that carries this bundle
     plugin = Instance(Plugin)
 
     def __init__(self, plugin, *args, **kwargs):
@@ -30,13 +31,6 @@ class BaseDataSourceBundle(ABCHasStrictTraits):
         """Factory method.
         Must return the bundle-specific BaseDataSource instance.
 
-        Parameters
-        ----------
-        application: Application
-            The envisage application.
-        model: BaseDataSourceModel
-            The model of the data source, instantiated with create_model()
-
         Returns
         -------
         BaseDataSource

force_bdss/data_sources/data_source_parameters.py

@@ -2,8 +2,14 @@ from traits.api import HasStrictTraits, Array, List, String
 
 
 class DataSourceParameters(HasStrictTraits):
+    """Contains the parameters as passed from the MCO."""
+    #: The user-defined names associated to the values.
     value_names = List(String)
+
+    #: The CUBA types associated to the values
     value_types = List(String)
+
+    #: The values as a single array.
     values = Array(shape=(None,))
 
     def __str__(self):

force_bdss/data_sources/data_source_result.py

@@ -4,19 +4,36 @@ from .base_data_source import BaseDataSource
 
 
 class DataSourceResult(HasTraits):
-    """Represents the result of a simulator.
-    It contains the resulting cuba key, the associated uncertainty and the
-    originating simulator.
-    Difference between uncertainty and quality: uncertainty is a numerical
-    value of the value, as in the case of an experimental simulation.
-    quality is the level of accuracy of the (e.g. computational) method, as
-    the importance and reliability of that value. It should be an enumeration
-    value such as HIGH, MEDIUM, POOR"""
+    """Represents the result of a DataSource evaluation.
+
+    Note
+    ----
+    Difference between accuracy and quality:
+      - uncertainty is a numerical quantity defining the accuracy of the value.
+        For example, a pressure can be 10.4 +/- 0.1, with 0.1 being the
+        accuracy
+      - quality is the level of importance and reliability of that value.
+        It should be considered as a weight of how much trust one should hold
+        on this information.
+    """
+
+    #: A reference to the DataSource that computed this result.
     originator = Instance(BaseDataSource)
+
+    #: The user-defined names associated to each result.
     value_names = List(String)
+
+    #: The CUBA types of each value.
     value_types = List(String)
+
+    #: The values for each entry. Note that this is a NxM array, allowing
+    #: to propagate more than single scalar values associated to a given value.
     values = Array(shape=(None, None))
+
+    #: If present, the numerical accuracy of the above values.
     accuracy = ArrayOrNone(shape=(None, None))
+
+    #: If present, the assessed quality of the above values.
     quality = ArrayOrNone(shape=(None, None))
 
     def __str__(self):

force_bdss/data_sources/i_data_source_bundle.py

-from traits.api import Interface, String
+from envisage.api import Plugin
+from traits.api import Interface, String, Instance
 
 
 class IDataSourceBundle(Interface):
-    #: Unique identifier that identifies the bundle uniquely in the
-    #: universe of bundles. Create one with the function bundle_id()
+    """Envisage required interface for the BaseDataSourceBundle.
+    You should not need to use this directly.
+
+    Refer to the BaseDataSourceBundle for documentation.
+    """
     id = String()
 
-    #: A human readable name of the bundle
     name = String()
 
+    plugin = Instance(Plugin)
+
     def create_data_source(self):
         """Factory method.
         Must return the bundle-specific BaseDataSource instance.

force_bdss/kpi/base_kpi_calculator.py

@@ -20,12 +20,22 @@ class BaseKPICalculator(ABCHasStrictTraits):
     @abc.abstractmethod
     def run(self, model, data_source_results):
         """
-        Executes the KPI evaluation and returns the list of results.
+        Executes the KPI evaluation and returns the results it computes.
         Reimplement this method in your specific KPI calculator.
 
         Parameters
         ----------
+        model: BaseKPICalculatorModel
+            The model of the KPI Calculator, instantiated through
+            create_model()
+
         data_source_results:
             a list of DataSourceResult instances containing the results of the
-            evaluation.
+            evaluation. Each DataSourceResult contains the results from one
+            specific DataSource.
+
+        Returns
+        -------
+        KPICalculatorResult
+            Instance that holds the results computed by this KPICalculator.
         """

force_bdss/kpi/base_kpi_calculator_bundle.py

@@ -20,9 +20,17 @@ class BaseKPICalculatorBundle(ABCHasStrictTraits):
     #: A UI friendly name for the bundle. Can contain spaces.
     name = String()
 
+    #: A reference to the plugin that holds this bundle.
     plugin = Instance(Plugin)
 
     def __init__(self, plugin, *args, **kwargs):
+        """Initializes the instance.
+
+        Parameters
+        ----------
+        plugin: Plugin
+            The plugin that holds this bundle.
+        """
         self.plugin = plugin
         super(BaseKPICalculatorBundle, self).__init__(*args, **kwargs)
 
@@ -32,13 +40,6 @@ class BaseKPICalculatorBundle(ABCHasStrictTraits):
         Creates and returns an instance of a KPI Calculator, associated
         to the given application and model.
 
-        Parameters
-        ----------
-        application: Application
-            The envisage application.
-        model: BaseKPICalculatorModel
-            The model of the calculator, instantiated with create_model()
-
         Returns
         -------
         BaseKPICalculator

force_bdss/kpi/i_kpi_calculator_bundle.py

@@ -4,7 +4,10 @@ from envisage.plugin import Plugin
 
 class IKPICalculatorBundle(Interface):
     """Envisage required interface for the BaseKPICalculatorBundle.
-    You should not need to use this directly."""
+    You should not need to use this directly.
+
+    Refer to the BaseKPICalculatorBundle for documentation.
+    """
     id = String()
 
     name = String()

force_bdss/kpi/kpi_calculator_result.py

@@ -4,11 +4,24 @@ from .base_kpi_calculator import BaseKPICalculator
 
 
 class KPICalculatorResult(HasTraits):
+    """Contains the results from a single KPICalculator evaluation"""
+
+    #: The originating KPI calculator
     originator = Instance(BaseKPICalculator)
+
+    #: The user-attributed names of each computed value
     value_names = List(String)
+
+    #: The CUBA types of each of the computed values
     value_types = List(String)
+
+    #: The values, as a single array of values
     values = Array(shape=(None, ))
+
+    #: If present, the numerical accuracy of the above values.
     accuracy = ArrayOrNone(shape=(None, ))
+
+    #: If present, the quality of the above values.
     quality = ArrayOrNone(shape=(None, ))
 
     def __str__(self):

force_bdss/mco/base_mco.py

@@ -14,10 +14,24 @@ class BaseMCO(ABCHasStrictTraits):
     bundle = Instance(IMCOBundle)
 
     def __init__(self, bundle, *args, **kwargs):
+        """Initializes the MCO.
+
+        Parameters
+        ----------
+        bundle: BaseMCOBundle
+            The bundle this BaseMCO belongs to
+        """
         self.bundle = bundle
         super(BaseMCO, self).__init__(*args, **kwargs)
 
     @abc.abstractmethod
     def run(self, model):
-        """Reimplement this method to perform the MCO operations."""
-        pass
+        """Performs the actual MCO operations.
+        Reimplement this method to tailor to your MCO.
+
+        Parameters
+        ----------
+        model: BaseMCOModel
+            An instance of the model information, as created from
+            create_model()
+        """

force_bdss/mco/base_mco_bundle.py

@@ -19,6 +19,7 @@ class BaseMCOBundle(ABCHasStrictTraits):
     #: A user friendly name of the bundle. Spaces allowed.
     name = String()
 
+    #: A reference to the Plugin that holds this bundle.
     plugin = Instance(Plugin)
 
     def __init__(self, plugin, *args, **kwargs):
@@ -31,14 +32,6 @@ class BaseMCOBundle(ABCHasStrictTraits):
         Creates the optimizer with the given application
         and model and returns it to the caller.
 
-        Parameters
-        ----------
-        application: Application
-            The envisage application instance
-        model: BaseMCOModel
-            The model to associate to the optimizer, instantiated through
-            create_model()
-
         Returns
         -------
         BaseMCOOptimizer
@@ -70,11 +63,8 @@ class BaseMCOBundle(ABCHasStrictTraits):
         """Factory method. Returns the communicator class that allows
         exchange between the MCO and the evaluator code.
 
-        Parameters
-        ----------
-        application: Application
-            The envisage application instance
-        model: BaseMCOModel
-            The model to associate to the optimizer, instantiated through
-            create_model()
+        Returns
+        -------
+        BaseMCOCommunicator
+            An instance of the communicator
         """

force_bdss/mco/base_mco_communicator.py

@@ -32,6 +32,11 @@ class BaseMCOCommunicator(ABCHasStrictTraits):
         Must return a single DataSourceParameters object, containing
         the parameters as passed by the MCO.
 
+        Parameters
+        ----------
+        model: BaseMCOModel
+            The model of the optimizer, instantiated through create_model()
+
         Returns
         -------
         DataSourceParameters
@@ -48,6 +53,9 @@ class BaseMCOCommunicator(ABCHasStrictTraits):
 
         Parameters
         ----------
+        model: BaseMCOModel
+            The model of the optimizer, instantiated through create_model()
+
         kpi_results: List(KPICalculatorResult)
             A list of KPI calculator results, one per each KPI calculator.
         """

force_bdss/mco/i_mco_bundle.py

@@ -3,8 +3,10 @@ from envisage.plugin import Plugin
 
 
 class IMCOBundle(Interface):
-    """Interface for the MultiCriteria Optimizer bundle.
+    """Interface for the BaseMCOBundle.
     You should not need it, as its main use is for envisage support.
+
+    Refer to BaseMCOBundle for documentation
     """
     id = String()