From a8e8beedf4912931c487f3df8f8d3a220c6322f0 Mon Sep 17 00:00:00 2001
From: Stefano Borini <sborini@enthought.com>
Date: Fri, 28 Jul 2017 11:09:29 +0100
Subject: [PATCH] documentation
---
force_bdss/data_sources/base_data_source.py | 20 +++++++++--
.../data_sources/base_data_source_bundle.py | 8 +----
.../data_sources/data_source_parameters.py | 6 ++++
force_bdss/data_sources/data_source_result.py | 33 ++++++++++++++-----
.../data_sources/i_data_source_bundle.py | 13 +++++---
force_bdss/kpi/base_kpi_calculator.py | 14 ++++++--
force_bdss/kpi/base_kpi_calculator_bundle.py | 15 +++++----
force_bdss/kpi/i_kpi_calculator_bundle.py | 5 ++-
force_bdss/kpi/kpi_calculator_result.py | 13 ++++++++
force_bdss/mco/base_mco.py | 18 ++++++++--
force_bdss/mco/base_mco_bundle.py | 20 +++--------
force_bdss/mco/base_mco_communicator.py | 8 +++++
force_bdss/mco/i_mco_bundle.py | 4 ++-
13 files changed, 128 insertions(+), 49 deletions(-)
diff --git a/force_bdss/data_sources/base_data_source.py b/force_bdss/data_sources/base_data_source.py
index 11b053a..3a9fedb 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 d099bf3..585e31b 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 ca2b5a4..378ad26 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 76bddc0..d19c16b 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 d3fda63..cad0857 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 dc10bd4..0d86647 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 3d83553..44e934f 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 3c815d6..df71c49 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 237b874..dce0df9 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 30d1626..d2afbec 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 2fb6fbb..5fe9fdb 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 25829db..4cb0f3b 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 69d4657..644f2b9 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()
--
GitLab