diff --git a/force_bdss/data_sources/base_data_source.py b/force_bdss/data_sources/base_data_source.py
index 11b053a92178485249b548e49e26716ed4f6aa5b..3a9fedbadbc7688f3dfcabc49509280758794ccf 100644
--- a/force_bdss/data_sources/base_data_source.py
+++ b/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.
+ """
diff --git a/force_bdss/data_sources/base_data_source_bundle.py b/force_bdss/data_sources/base_data_source_bundle.py
index d099bf3aee36b362a676e32bcce1946fef9570ca..585e31b0b4e1f553dda42a469c4c24ebdf27662a 100644
--- a/force_bdss/data_sources/base_data_source_bundle.py
+++ b/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
diff --git a/force_bdss/data_sources/data_source_parameters.py b/force_bdss/data_sources/data_source_parameters.py
index ca2b5a4834965804c24d2ac6a96246d9c06d41dd..378ad26c4ee99d2f565382e286239048cc125861 100644
--- a/force_bdss/data_sources/data_source_parameters.py
+++ b/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):
diff --git a/force_bdss/data_sources/data_source_result.py b/force_bdss/data_sources/data_source_result.py
index 76bddc08eae5055d7f1359a436721567245bc9af..d19c16b203e57b8192753eba1836dbb31f8e2fa6 100644
--- a/force_bdss/data_sources/data_source_result.py
+++ b/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):
diff --git a/force_bdss/data_sources/i_data_source_bundle.py b/force_bdss/data_sources/i_data_source_bundle.py
index d3fda63e1f3fb3be3f3dd6b2c340c60a72c23c8b..cad0857442fd70406d6a1c6cf6ff8270fbcd90fe 100644
--- a/force_bdss/data_sources/i_data_source_bundle.py
+++ b/force_bdss/data_sources/i_data_source_bundle.py
@@ -1,14 +1,19 @@
-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.
diff --git a/force_bdss/kpi/base_kpi_calculator.py b/force_bdss/kpi/base_kpi_calculator.py
index dc10bd41eb87e52a7e822187adbda12f27388081..0d8664794acb1e3c00df58767cfecb317e9ff0f5 100644
--- a/force_bdss/kpi/base_kpi_calculator.py
+++ b/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.
"""
diff --git a/force_bdss/kpi/base_kpi_calculator_bundle.py b/force_bdss/kpi/base_kpi_calculator_bundle.py
index 3d83553325789e861fbb45ba242ffd1f0f8b70c2..44e934fbcd4f360d7f48ca938cc7650aac67f5f6 100644
--- a/force_bdss/kpi/base_kpi_calculator_bundle.py
+++ b/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
diff --git a/force_bdss/kpi/i_kpi_calculator_bundle.py b/force_bdss/kpi/i_kpi_calculator_bundle.py
index 3c815d66745505d87bb0fca73b8a26b5a2b9462e..df71c49477ad76d4015ce81b15046a4d42198e70 100644
--- a/force_bdss/kpi/i_kpi_calculator_bundle.py
+++ b/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()
diff --git a/force_bdss/kpi/kpi_calculator_result.py b/force_bdss/kpi/kpi_calculator_result.py
index 237b8740c6dc71452b0c2905f407d899399f88c4..dce0df90bd0fc895ccfee194f5ec10fe47335405 100644
--- a/force_bdss/kpi/kpi_calculator_result.py
+++ b/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):
diff --git a/force_bdss/mco/base_mco.py b/force_bdss/mco/base_mco.py
index 30d162663b41989386a8a3a76fcc5055d6cd8051..d2afbec85a54984a41b2fecd733b775d8ff5b14a 100644
--- a/force_bdss/mco/base_mco.py
+++ b/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()
+ """
diff --git a/force_bdss/mco/base_mco_bundle.py b/force_bdss/mco/base_mco_bundle.py
index 2fb6fbb3b485796acbe69c279b324061bc8bd164..5fe9fdb648e9c738d92273f10d3f6fb0a08652ca 100644
--- a/force_bdss/mco/base_mco_bundle.py
+++ b/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
"""
diff --git a/force_bdss/mco/base_mco_communicator.py b/force_bdss/mco/base_mco_communicator.py
index 25829db56fa10c1fb8e8043ad163cb29fdddb256..4cb0f3bf2b534f6c804a5fbbcd1049a11933b65f 100644
--- a/force_bdss/mco/base_mco_communicator.py
+++ b/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.
"""
diff --git a/force_bdss/mco/i_mco_bundle.py b/force_bdss/mco/i_mco_bundle.py
index 69d4657ae4423ec23c16987eca49fb44b079864d..644f2b988d49e7d9064cb9085dbf205b539f15ec 100644
--- a/force_bdss/mco/i_mco_bundle.py
+++ b/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()