Added tutorial to documentation

Added another example for the tutoiral, and made a corresponding test.

Fixed bug with reading matlab files for plots.

Changed some keywords to do with file_types and files.

Moved version to 2.0.1

doc/source/api/controllers.rst

@@ -1,3 +1,5 @@
+.. _api-controllers:
+
 controllers
 -----------
 

doc/source/api/index.rst

@@ -1,3 +1,5 @@
+.. _sec-api:
+
 M-LOOP API
 ==========
 

doc/source/api/learners.rst

@@ -1,3 +1,5 @@
+.. _api-learners:
+
 learners
 ---------
 

doc/source/contributing.rst

@@ -0,0 +1,8 @@
+.. _sec-contributing:
+
+Contributing
+============
+
+
+
+

doc/source/data.rst

@@ -0,0 +1,36 @@
+.. _sec-data:
+
+Data
+====
+
+M-LOOP saves all data produced by the experiment in archives which are saved to disk during and after the optimization run. The archives also contain information derived from the data, including the machine learning model for how the experiment works. Here we explain how to interpret the file archives. 
+
+File Formats
+------------
+
+M-LOOP currently supports three file formats for all file input and output. 
+
+- 'txt' text files: Human readable text files. This is the default file format for all outputs. The advantage of text files is they are easy to read, and there will be no format compatibility issues in the future. However, there will be some loss of precision in your data. To ensure you keep all significant figure you may want to use 'pkl' or 'mat'.
+- 'mat' MATLAB files: Matlab files that can be opened and written with MATLAB or `numpy <http://www.numpy.org/>`_.
+- 'pkl' pickle files: a serialization of a python dictionary made with `pickle <https://docs.python.org/3/library/pickle.html>`. Your data can be retrieved from this dictionary using the appropriate keywords. 
+
+File Keywords
+-------------
+
+The archives contain a set of keywords/variable names with associated data. The quickest way to understand what the values mean for a particular keyword is to :ref:`search` the documentation for a description. 
+
+For a comprehensive list of all the keywords looks at the attributes described in the API. 
+
+For the controller archive see :ref:`api-controllers`.
+
+For the learner archive see :ref:`api-learners`. The generic keywords are described in the class Learner, with learner specific options described in the derived classes, for example GaussianProcessLearner.
+
+Converting files
+----------------
+
+If for whatever reason you want to convert files between the formats you can do so using the utilities module of M-LOOP. For example the following python code will convert the file controller_archive_2016-08-18_12-18.pkl from a 'pkl' file to a 'mat' file::
+
+   import mloop.utilities as mlu
+
+   saved_dict = mlu.get_dict_from_file('./M-LOOP_archives/controller_archive_2016-08-18_12-18.pkl','pkl') 
+   mlu.save_dict_to_file(saved_dict,'./M-LOOP_archives/controller_archive_2016-08-18_12-18.mat','mat')

doc/source/examples.rst

@@ -1,3 +1,6 @@
+.. _sec-examples:
+
 Examples
---------
-I like turtles side 8
+========
+
+Blah

doc/source/index.rst

@@ -32,8 +32,12 @@ Contents
 
    install
    tutorial
+   interfaces
+   data
+   visualizations
    options
    examples
+   contributing
    api/index
 
 Indices

doc/source/install.rst

@@ -11,7 +11,6 @@ The installation process involves four steps.
 3. Install the development version of :ref:`sec-M-LOOP`.
 4. :ref:`Test<sec-Testing>` your M-LOOP install.
 
-
 .. _sec-anaconda:
 
 Anaconda
@@ -56,16 +55,22 @@ M-LOOP can be installed from the source code with three commands::
 
 The first command downloads the latest source code for M-LOOP from github into the current directory, the second moves into the M-LOOP source directory, and the third link builds the package and creates a link from you python package to the source. You may need admin privileges to run the setup script.
 
+At any time you can update M-LOOP to the latest version from github by running the command::
+
+   git pull origin master
+
+in the M-LOOP directory. 
+
 .. _sec-Testing:
 
 Test Installation
 -----------------
 
 To test your M-LOOP installation use the command::
 
-   python setup.py pytest
+   python setup.py test
    
-In the M-LOOP source code directory. The tests should take around three minutes to complete. If you find a error please consider contributing to the project by reporting a bug on the github.
+In the M-LOOP source code directory. The tests should take around five minutes to complete. If you find a error please consider :ref:`sec-contributing` to the project and report a bug on the `github <https://github.com/michaelhush/M-LOOP>`_.
 
 Documentation
 -------------

doc/source/interfaces.rst

@@ -0,0 +1,43 @@
+.. _sec-interfaces:
+
+Interfaces
+==========
+
+Currently M-LOOP only support the File interface, which is also described in :ref:`sec-tutorial`. There will be more added very soon. If you have any suggestions for interfaces please consider :ref:`sec-contributing` to the project.
+
+File Interface
+--------------
+
+The simplest method to connect your experiment to M-LOOP is with the file interface where data is exchanged by writing files to disk. To use this interface you can include the option::
+
+   interface='file'
+   
+in you configuration file. The file interface happens to be the default, so this is not necessary. 
+
+The file interface works under the assumption that you experiment follows the following algorithm.
+
+1. Wait for the file *exp_input.txt* to be made on the disk in the same folder M-LOOP is run.
+2. Read the parameters for the next experiment from the file (named params).
+3. Delete the file  *exp_input.txt*.
+4. Run the experiment with the parameters provided and calculate a cost, and optionally the uncertainty.
+5. Write the cost to the file *exp_output.txt*. Go back to step 1.
+
+It is important you delete the file *exp_input.txt* after reading it, since it is used to as an indicator for the next experiment to run.
+
+When writing the file *exp_output.txt* there are three keywords and values you can include in your file, for example after the first run your experiment may produce the following::
+
+   cost = 0.5
+   uncer = 0.01
+   bad = false
+
+cost refers to the cost calculated from the experimental data. uncer, is optional, and refers to the uncertainty in the cost measurement made. Note, M-LOOP by default assumes there is some noise corrupting costs, which is fitted and compensated for. Hence, if there is some noise in your costs which you are unable to predict from a single measurement, do not worry, you do not have to estimate uncer, you can just leave it out. Lastly bad can be used to indicate an experiment failed and was not able to produce a cost. If the experiment worked set bad = false and if it failed set bad = true.
+
+Note you do not have to include all of the keywords, you must provide at least a cost or the bad keyword set to false. For example a succesful run can simply be::
+
+   cost = 0.3
+   
+and failed experiment can be as simple as::
+
+   bad = True
+   
+Once the *exp_output.txt* has been written to disk, M-LOOP will read it and delete it. 

doc/source/options.rst

@@ -1,3 +1,5 @@
+.. _sec-options:
+
 Options
 -------
 I like turtles 3