Merge branch 'master' into move-parameters-to-mco

doc/source/api/force_bdss.core_plugins.rst

-force\_bdss\.core\_plugins package
-==================================
+force_bdss.core_plugins package
+===============================
 
 Subpackages
 -----------

doc/source/api/force_bdss.data_sources.rst

-force\_bdss\.data\_sources package
-==================================
+force_bdss.data_sources package
+===============================
 
 Subpackages
 -----------
@@ -11,48 +11,48 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.data\_sources\.base\_data\_source module
------------------------------------------------------
+force_bdss.data_sources.base_data_source module
+-----------------------------------------------
 
 .. automodule:: force_bdss.data_sources.base_data_source
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.data\_sources\.base\_data\_source\_bundle module
--------------------------------------------------------------
+force_bdss.data_sources.base_data_source_bundle module
+------------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.base_data_source_bundle
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.data\_sources\.base\_data\_source\_model module
-------------------------------------------------------------
+force_bdss.data_sources.base_data_source_model module
+-----------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.base_data_source_model
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.data\_sources\.data\_source\_parameters module
------------------------------------------------------------
+force_bdss.data_sources.data_source_parameters module
+-----------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.data_source_parameters
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.data\_sources\.data\_source\_result module
--------------------------------------------------------
+force_bdss.data_sources.data_source_result module
+-------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.data_source_result
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.data\_sources\.i\_data\_source\_bundle module
-----------------------------------------------------------
+force_bdss.data_sources.i_data_source_bundle module
+---------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.i_data_source_bundle
     :members:

doc/source/api/force_bdss.data_sources.tests.rst

-force\_bdss\.data\_sources\.tests package
-=========================================
+force_bdss.data_sources.tests package
+=====================================
 
 Submodules
 ----------
 
-force\_bdss\.data\_sources\.tests\.test\_base\_data\_source module
-------------------------------------------------------------------
+force_bdss.data_sources.tests.test_base_data_source module
+----------------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.tests.test_base_data_source
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.data\_sources\.tests\.test\_base\_data\_source\_bundle module
---------------------------------------------------------------------------
+force_bdss.data_sources.tests.test_base_data_source_bundle module
+-----------------------------------------------------------------
 
 .. automodule:: force_bdss.data_sources.tests.test_base_data_source_bundle
     :members:

doc/source/api/force_bdss.io.rst

-force\_bdss\.io package
-=======================
+force_bdss.io package
+=====================
 
 Subpackages
 -----------
@@ -11,16 +11,16 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.io\.workflow\_reader module
-----------------------------------------
+force_bdss.io.workflow_reader module
+------------------------------------
 
 .. automodule:: force_bdss.io.workflow_reader
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.io\.workflow\_writer module
-----------------------------------------
+force_bdss.io.workflow_writer module
+------------------------------------
 
 .. automodule:: force_bdss.io.workflow_writer
     :members:

doc/source/api/force_bdss.io.tests.rst

-force\_bdss\.io\.tests package
-==============================
+force_bdss.io.tests package
+===========================
 
 Submodules
 ----------
 
-force\_bdss\.io\.tests\.test\_workflow\_reader module
------------------------------------------------------
+force_bdss.io.tests.test_workflow_reader module
+-----------------------------------------------
 
 .. automodule:: force_bdss.io.tests.test_workflow_reader
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.io\.tests\.test\_workflow\_writer module
------------------------------------------------------
+force_bdss.io.tests.test_workflow_writer module
+-----------------------------------------------
 
 .. automodule:: force_bdss.io.tests.test_workflow_writer
     :members:

doc/source/api/force_bdss.kpi.rst

-force\_bdss\.kpi package
-========================
+force_bdss.kpi package
+======================
 
 Subpackages
 -----------
@@ -11,40 +11,40 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.kpi\.base\_kpi\_calculator module
-----------------------------------------------
+force_bdss.kpi.base_kpi_calculator module
+-----------------------------------------
 
 .. automodule:: force_bdss.kpi.base_kpi_calculator
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.kpi\.base\_kpi\_calculator\_bundle module
-------------------------------------------------------
+force_bdss.kpi.base_kpi_calculator_bundle module
+------------------------------------------------
 
 .. automodule:: force_bdss.kpi.base_kpi_calculator_bundle
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.kpi\.base\_kpi\_calculator\_model module
------------------------------------------------------
+force_bdss.kpi.base_kpi_calculator_model module
+-----------------------------------------------
 
 .. automodule:: force_bdss.kpi.base_kpi_calculator_model
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.kpi\.i\_kpi\_calculator\_bundle module
----------------------------------------------------
+force_bdss.kpi.i_kpi_calculator_bundle module
+---------------------------------------------
 
 .. automodule:: force_bdss.kpi.i_kpi_calculator_bundle
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.kpi\.kpi\_calculator\_result module
-------------------------------------------------
+force_bdss.kpi.kpi_calculator_result module
+-------------------------------------------
 
 .. automodule:: force_bdss.kpi.kpi_calculator_result
     :members:

doc/source/api/force_bdss.kpi.tests.rst

-force\_bdss\.kpi\.tests package
-===============================
+force_bdss.kpi.tests package
+============================
 
 Submodules
 ----------
 
-force\_bdss\.kpi\.tests\.test\_base\_kpi\_calculator module
------------------------------------------------------------
+force_bdss.kpi.tests.test_base_kpi_calculator module
+----------------------------------------------------
 
 .. automodule:: force_bdss.kpi.tests.test_base_kpi_calculator
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.kpi\.tests\.test\_base\_kpi\_calculator\_bundle module
--------------------------------------------------------------------
+force_bdss.kpi.tests.test_base_kpi_calculator_bundle module
+-----------------------------------------------------------
 
 .. automodule:: force_bdss.kpi.tests.test_base_kpi_calculator_bundle
     :members:

doc/source/api/force_bdss.mco.parameters.rst

-force\_bdss\.mco\.parameters package
-====================================
+force_bdss.mco.parameters package
+=================================
 
 Subpackages
 -----------
@@ -11,32 +11,32 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.mco\.parameters\.base\_mco\_parameter module
----------------------------------------------------------
+force_bdss.mco.parameters.base_mco_parameter module
+---------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.base_mco_parameter
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.parameters\.base\_mco\_parameter\_factory module
-------------------------------------------------------------------
+force_bdss.mco.parameters.base_mco_parameter_factory module
+-----------------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.base_mco_parameter_factory
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.parameters\.core\_mco\_parameters module
-----------------------------------------------------------
+force_bdss.mco.parameters.core_mco_parameters module
+----------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.core_mco_parameters
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.parameters\.mco\_parameter\_factory\_registry module
-----------------------------------------------------------------------
+force_bdss.mco.parameters.mco_parameter_factory_registry module
+---------------------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.mco_parameter_factory_registry
     :members:

doc/source/api/force_bdss.mco.parameters.tests.rst

-force\_bdss\.mco\.parameters\.tests package
-===========================================
+force_bdss.mco.parameters.tests package
+=======================================
 
 Submodules
 ----------
 
-force\_bdss\.mco\.parameters\.tests\.test\_base\_mco\_parameter module
-----------------------------------------------------------------------
+force_bdss.mco.parameters.tests.test_base_mco_parameter module
+--------------------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.tests.test_base_mco_parameter
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.parameters\.tests\.test\_base\_mco\_parameter\_factory module
--------------------------------------------------------------------------------
+force_bdss.mco.parameters.tests.test_base_mco_parameter_factory module
+----------------------------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.tests.test_base_mco_parameter_factory
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.parameters\.tests\.test\_core\_mco\_parameters module
------------------------------------------------------------------------
+force_bdss.mco.parameters.tests.test_core_mco_parameters module
+---------------------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.tests.test_core_mco_parameters
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.parameters\.tests\.test\_parameter\_factory\_registry module
-------------------------------------------------------------------------------
+force_bdss.mco.parameters.tests.test_parameter_factory_registry module
+----------------------------------------------------------------------
 
 .. automodule:: force_bdss.mco.parameters.tests.test_parameter_factory_registry
     :members:

doc/source/api/force_bdss.mco.rst

-force\_bdss\.mco package
-========================
+force_bdss.mco package
+======================
 
 Subpackages
 -----------
@@ -12,40 +12,40 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.mco\.base\_mco module
-----------------------------------
+force_bdss.mco.base_mco module
+------------------------------
 
 .. automodule:: force_bdss.mco.base_mco
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.base\_mco\_bundle module
-------------------------------------------
+force_bdss.mco.base_mco_bundle module
+-------------------------------------
 
 .. automodule:: force_bdss.mco.base_mco_bundle
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.base\_mco\_communicator module
-------------------------------------------------
+force_bdss.mco.base_mco_communicator module
+-------------------------------------------
 
 .. automodule:: force_bdss.mco.base_mco_communicator
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.base\_mco\_model module
------------------------------------------
+force_bdss.mco.base_mco_model module
+------------------------------------
 
 .. automodule:: force_bdss.mco.base_mco_model
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.i\_mco\_bundle module
----------------------------------------
+force_bdss.mco.i_mco_bundle module
+----------------------------------
 
 .. automodule:: force_bdss.mco.i_mco_bundle
     :members:

doc/source/api/force_bdss.mco.tests.rst

-force\_bdss\.mco\.tests package
-===============================
+force_bdss.mco.tests package
+============================
 
 Submodules
 ----------
 
-force\_bdss\.mco\.tests\.test\_base\_mco module
------------------------------------------------
+force_bdss.mco.tests.test_base_mco module
+-----------------------------------------
 
 .. automodule:: force_bdss.mco.tests.test_base_mco
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.tests\.test\_base\_mco\_bundle module
--------------------------------------------------------
+force_bdss.mco.tests.test_base_mco_bundle module
+------------------------------------------------
 
 .. automodule:: force_bdss.mco.tests.test_base_mco_bundle
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.mco\.tests\.test\_base\_mco\_communicator module
--------------------------------------------------------------
+force_bdss.mco.tests.test_base_mco_communicator module
+------------------------------------------------------
 
 .. automodule:: force_bdss.mco.tests.test_base_mco_communicator
     :members:

doc/source/api/force_bdss.rst

-force\_bdss package
-===================
+force_bdss package
+==================
 
 Subpackages
 -----------
@@ -18,70 +18,78 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.api module
------------------------
+force_bdss.api module
+---------------------
 
 .. automodule:: force_bdss.api
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.base\_core\_driver module
---------------------------------------
+force_bdss.base_core_driver module
+----------------------------------
 
 .. automodule:: force_bdss.base_core_driver
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.base\_extension\_plugin module
--------------------------------------------
+force_bdss.base_extension_plugin module
+---------------------------------------
 
 .. automodule:: force_bdss.base_extension_plugin
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.bdss\_application module
--------------------------------------
+force_bdss.bdss_application module
+----------------------------------
 
 .. automodule:: force_bdss.bdss_application
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.bundle\_registry\_plugin module
---------------------------------------------
+force_bdss.bundle_registry_plugin module
+----------------------------------------
 
 .. automodule:: force_bdss.bundle_registry_plugin
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.core\_evaluation\_driver module
---------------------------------------------
+force_bdss.core_evaluation_driver module
+----------------------------------------
 
 .. automodule:: force_bdss.core_evaluation_driver
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.core\_mco\_driver module
--------------------------------------
+force_bdss.core_mco_driver module
+---------------------------------
 
 .. automodule:: force_bdss.core_mco_driver
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.ids module
------------------------
+force_bdss.ids module
+---------------------
 
 .. automodule:: force_bdss.ids
     :members:
     :undoc-members:
     :show-inheritance:
 
+force_bdss.version module
+-------------------------
+
+.. automodule:: force_bdss.version
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 
 Module contents
 ---------------

doc/source/api/force_bdss.tests.fixtures.rst

-force\_bdss\.tests\.fixtures package
-====================================
+force_bdss.tests.fixtures package
+=================================
 
 Module contents
 ---------------

doc/source/api/force_bdss.tests.rst

-force\_bdss\.tests package
-==========================
+force_bdss.tests package
+========================
 
 Subpackages
 -----------
@@ -11,32 +11,32 @@ Subpackages
 Submodules
 ----------
 
-force\_bdss\.tests\.test\_bdss\_application module
---------------------------------------------------
+force_bdss.tests.test_bdss_application module
+---------------------------------------------
 
 .. automodule:: force_bdss.tests.test_bdss_application
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.tests\.test\_bundle\_registry\_plugin module
----------------------------------------------------------
+force_bdss.tests.test_bundle_registry_plugin module
+---------------------------------------------------
 
 .. automodule:: force_bdss.tests.test_bundle_registry_plugin
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.tests\.test\_core\_evaluation\_driver module
----------------------------------------------------------
+force_bdss.tests.test_core_evaluation_driver module
+---------------------------------------------------
 
 .. automodule:: force_bdss.tests.test_core_evaluation_driver
     :members:
     :undoc-members:
     :show-inheritance:
 
-force\_bdss\.tests\.test\_ids module
-------------------------------------
+force_bdss.tests.test_ids module
+--------------------------------
 
 .. automodule:: force_bdss.tests.test_ids
     :members:

doc/source/api/force_bdss.workspecs.rst

-force\_bdss\.workspecs package
-==============================
+force_bdss.workspecs package
+============================
 
 Submodules
 ----------
 
-force\_bdss\.workspecs\.workflow module
----------------------------------------
+force_bdss.workspecs.workflow module
+------------------------------------
 
 .. automodule:: force_bdss.workspecs.workflow
     :members:

doc/source/conf.py

@@ -9,7 +9,9 @@ import os
 sys.path.insert(0, os.path.join(
     os.path.dirname(os.path.abspath(__file__)), "..", "..")
     )
-print(sys.path)
+
+from force_bdss.version import __version__ as RELEASE
+
 MOCK_MODULES=[]
 
 def _warn_node(self, msg, node, **kwargs):
@@ -58,8 +60,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 project = u'FORCE'
 copyright = u'2017, FORCE Project'
-version = '0.1.0'
-release = '0.1.0.dev0'
+version = ".".join(RELEASE.split(".")[0:3])
+release = RELEASE
 pygments_style = 'sphinx'
 html_theme = 'classic'
 html_static_path = ['_static']

doc/source/design.rst

+Design
+------
+
+The application is based on three entities, as written in the introduction:
+
+- Multi Criteria Optimizer (MCO)
+- DataSources
+- Key Performance Indicator (KPI) Calculators
+
+There are a few core assumptions about each of these entities:
+
+- The MCO design must honor the execution model of Dakota, that is, spawn
+  a secondary process that performs a computation starting from a given set
+  of input parameters, and produces a resulting set of output parameters.
+  In our code, this secondary process is ``force_bdss`` itself, invoked with
+  the option ``--evaluate``.
+- The DataSources are entities that, given the MCO parameters, provide some
+  numerical result. This result is passed to the KPI calculators.
+- The KPI calculators now compute the final KPIs that are then returned to
+  the invoker MCO.
+
+
+The result can be represented with the following data flow
+
+
+1. The MCO produces and, by means of a Communicator, injects...
+2. ...DataSourceParameters, that are passed to...
+3. one or more DataSources, each performing some computation or data
+   extraction and produces
+4. DataSourceResult, one per DataSource, are then passed (together with the
+   DataSourceParameters) to...
+5. one or more KPICalculators, which perform final data evaluation on the
+   obtained values, eac producing KPIResult...
+6. Whose values are then returned to the MCO via the Communicator.
+
+The resulting pipeline is therefore just two layers (DataSources, then
+KPICalculators).

doc/source/index.rst

@@ -10,6 +10,8 @@ User Manual
    :maxdepth: 1
 
    Introduction <introduction>
+   Design <design>
+   Plugin development <plugin_development>
 
 
 API Reference

doc/source/introduction.rst

 Introduction
 ------------
+
+The Business Decision System is the CLI support for the evaluation of
+Pareto front computations. It is a single executable ``force_bdss`` that
+interprets a workflow specification file, normally generated via the GUI
+workflow manager.
+
+By itself, the executable and the code implementing it provides no
+functionality. All functionality comes from external plugins, extending the
+API to provide new entities, specifically:
+
+- Multi Criteria Optimizer (MCO)
+- DataSources
+- Key Performance Indicator (KPI) Calculators
+
+Plugin support requires compliancy to the Force BDSS api for plugins.
+Extensions are registered via setuptools entry points.
+
+Execution of the force bdss executable is simple. Invoke with::
+
+    force_bdss workflow.json
+

doc/source/plugin_development.rst

+Plugin Development
+------------------
+
+A single Plugin can provide one or more of the pluggable entities
+described elsewhere (MCO/KPICalculators/DataSources). Multiple plugins can
+be installed to provide a broad range of functionalities.
+
+Plugins must return "Bundles". Each Bundle acts as a Factory, providing
+factory methods for one of the above pluggable entities and its associated
+classes.
+
+To implement a new plugin, you must
+
+- define the entity you want to extend (e.g. ``MyOwnDataSource``) as a derived
+  class of the appropriate class (e.g. BaseDataSource), and reimplement
+  the appropriate methods.
+- Define the model that this DataSource needs, by extending
+  ``BaseDataSourceModel`` and adding, with traits, the appropriate data that
+  are required by your data source to perform its task.
+- Define the Bundle, by reimplementing BaseDataSourceBundle and reimplementing
+  its ``create_*`` methods to return the above entities.
+- Define a ``Plugin`` by reimplementing ``BaseExtensionPlugin`` and
+  reimplementing its initialization defaults methods to return your bundle.
+- add the plugin class in the setup.py entry_point, under the namespace
+  ``force.bdss.extensions``