Merge pull request #57 from force-h2020/documentation

Added some initial documentation

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``