Update for official release

Completed documentation. Fixed a few bugs with file writing formats with ‘txt’ in particular
michaelhush · Sep 1, 2016 · 40f84ae · 40f84ae
1 parent b64a9c7
commit 40f84ae
Show file tree

Hide file tree

Showing 50 changed files with 322 additions and 125 deletions.
diff --git a/README.rst b/README.rst
@@ -12,7 +12,7 @@ In the M-LOOP source folder.
 
 For more details on how to use the package see the documentation. You can see it online at
 
-?
+http://m-loop.readthedocs.io/
 
 Or you can build it by entering the docs folder and running:
 

diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
diff --git a/doc/source/images/M-LOOP_logo.pdf b/doc/source/images/M-LOOP_logo.pdf
diff --git a/doc/source/images/M-LOOP_logo.png b/doc/source/images/M-LOOP_logo.png
diff --git a/doc/source/options.rst b/doc/source/options.rst
diff --git a/doc/source/visualizations.rst b/doc/source/visualizations.rst
diff --git a/doc/Makefile → docs/Makefile b/doc/Makefile → docs/Makefile
@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -15,9 +15,9 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help
 help:

diff --git a/doc/source/images/M-LOOP_diagram.png → docs/_static/M-LOOP_diagram.png b/doc/source/images/M-LOOP_diagram.png → docs/_static/M-LOOP_diagram.png
diff --git a/doc/source/images/M-LOOP_logo.ico → docs/_static/M-LOOP_logo.ico b/doc/source/images/M-LOOP_logo.ico → docs/_static/M-LOOP_logo.ico
diff --git a/docs/_static/M-LOOP_logo.png b/docs/_static/M-LOOP_logo.png
diff --git a/docs/_static/M-LOOP_visualizations.png b/docs/_static/M-LOOP_visualizations.png
diff --git a/doc/source/images/M-LOOPandBEC.png → docs/_static/M-LOOPandBEC.png b/doc/source/images/M-LOOPandBEC.png → docs/_static/M-LOOPandBEC.png
diff --git a/doc/source/api/controllers.rst → docs/api/controllers.rst b/doc/source/api/controllers.rst → docs/api/controllers.rst
diff --git a/doc/source/api/index.rst → docs/api/index.rst b/doc/source/api/index.rst → docs/api/index.rst
diff --git a/doc/source/api/interfaces.rst → docs/api/interfaces.rst b/doc/source/api/interfaces.rst → docs/api/interfaces.rst
diff --git a/doc/source/api/launchers.rst → docs/api/launchers.rst b/doc/source/api/launchers.rst → docs/api/launchers.rst
diff --git a/doc/source/api/learners.rst → docs/api/learners.rst b/doc/source/api/learners.rst → docs/api/learners.rst
diff --git a/doc/source/api/mloop.rst → docs/api/mloop.rst b/doc/source/api/mloop.rst → docs/api/mloop.rst
diff --git a/doc/source/api/t_esting.rst → docs/api/t_esting.rst b/doc/source/api/t_esting.rst → docs/api/t_esting.rst
diff --git a/doc/source/api/utilities.rst → docs/api/utilities.rst b/doc/source/api/utilities.rst → docs/api/utilities.rst
diff --git a/doc/source/api/visualizations.rst → docs/api/visualizations.rst b/doc/source/api/visualizations.rst → docs/api/visualizations.rst
diff --git a/doc/source/conf.py → docs/conf.py b/doc/source/conf.py → docs/conf.py
@@ -15,6 +15,7 @@
 
 import sys
 import os
+import mloop
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -70,9 +71,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.0'
+version = mloop.__version__
 # The full version, including alpha/beta/rc tags.
-release = '2.0.1'
+release = mloop.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -127,10 +128,25 @@
 # a list of builtin themes.
 html_theme = 'alabaster'
 
+# Custom sidebar templates, maps document names to template names.
+html_sidebars =  { '**': ['about.html','navigation.html','relations.html', 'searchbox.html'], }
+
+#'globaltoc.html',
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {'logo':'M-LOOP_logo.png',
+'logo_name':True,
+'description':'Machine-Learning Online Optimization Package',
+'github_user':'michaelhush',
+'github_repo':'M-LOOP',
+'github_banner':True,
+'font_family':"Arial, Helvetica, sans-serif",
+'head_font_family':"Arial, Helvetica, sans-serif",
+'analytics_id':'UA-83520804-1'}
+
+#'github_button':True,
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -144,12 +160,12 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = 'images/M-LOOP_logo.png'
+#html_logo = '_static/M-LOOP_logo.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = 'images/M-LOOP_logo.ico'
+html_favicon = '_static/M-LOOP_logo.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -170,9 +186,6 @@
 # typographically correct entities.
 #html_use_smartypants = True
 
-# Custom sidebar templates, maps document names to template names.
-html_sidebars =  { '**': ['globaltoc.html', 'relations.html', 'searchbox.html'], }
-
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
@@ -247,7 +260,7 @@
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-latex_logo = 'images/M-LOOP_logo.pdf'
+#latex_logo = 'M-LOOP_logo.pdf'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -0,0 +1,37 @@
+.. _sec-contributing:
+
+Contributing
+============
+
+If you use M-LOOP please consider contributing to the project. There are many quick and easy ways to help out.
+
+- If you use M-LOOP be sure to cite paper where it first used: `'Fast machine-learning online optimization of ultra-cold-atom experiments', Sci Rep 6, 25890 (2016) <http://www.nature.com/srep/>`_. 
+- Star and watch the `M-LOOP github <https://github.com/michaelhush/M-LOOP/watchers>`_.
+- Make a suggestion on what features you would like added, or report an issue, on the `github <https://github.com/michaelhush/M-LOOP/watchers>`_ or by `email <mailto:[email protected]>`_. 
+- Contribute your own code to the `M-LOOP github <https://github.com/michaelhush/M-LOOP/watchers>`_, this could be the interface you designed, more options or a completely new solver.
+
+Finally spread the word! Let others know the success you have had with M-LOOP and recommend they try it too.
+
+Contributors
+------------
+
+M-LOOP is written and maintained by `Michael R Hush <http://www.michaelhush.com>`_ <[email protected]>
+
+Other contributors, listed alphabetically, are:
+
+* John W. Bastian - design, first demonstration
+* Patrick J. Everitt - testing, design, first demonstration
+* Kyle S. Hardman - design, first demonstration
+* Anton van den Hengel - design, first demonstration
+* Joe J. Hope - design, first demonstration
+* Carlos C. N. Kuhn - first demonstration
+* Andre N. Luiten - first demonstration
+* Gordon D. McDonald - first demonstration
+* Manju Perumbil - first demonstration
+* Ian R. Petersen - first demonstration
+* Ciaron D. Quinlivan - first demonstration
+* Alex Ratcliff - testing
+* Nick P. Robins - first demonstration
+* Mahasen A. Sooriyabandara - first demonstration
+* Richard Taylor - testing
+* Paul B. Wigley - testing, design, first demonstration
diff --git a/doc/source/data.rst → docs/data.rst b/doc/source/data.rst → docs/data.rst
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,102 @@
+.. _sec-examples:
+
+Examples
+========
+
+M-LOOP includes a series of example configuration files for each of the controllers and interfaces. The examples can be found in examples folder.  For some controllers there are two files, ones ending with *_basic_config* which includes the standard configuration options and *_complete_config* which include a comprehensive list of all the configuration options available.
+
+The options available are also comprehensively documented in the :ref:`sec-api` as keywords for each of the classes. However, the quickest and easiest way to learn what options are available, if you are not familiar with python, is to just look at the provided examples.
+
+Each of the example files is used when running tests of M-LOOP. So please copy and modify them elsewhere if you use them as a starting point for your configuration file. 
+
+Interfaces
+----------
+
+There is currently one interface supported: 'file'. You can specify which interface you want with the option::
+
+   interface_type = [name]
+
+The default will be 'file'. The specific options for each of the interfaces are described below.
+
+File Interface
+~~~~~~~~~~~~~~
+
+You can change the names of the files used for the file interface and their type. The file interface options are described in *file_interface_config.txt*.
+
+.. include:: ../examples/file_interface_config.txt
+   :literal:
+
+Controllers
+-----------
+
+There are currently three controller types supported: 'gaussian_process', 'random' and 'nelder_mead'. The default is 'gaussian_process'. You can set which interface you want to use with the option::
+
+   controller_type = [name]
+
+Each of the controllers and their specific options are described below. There is also a set of common options shared by all controllers which is described in *controller_options.txt*. The common options include the parameter settings and the halting conditions.
+
+.. include:: ../examples/controller_config.txt
+   :literal:
+
+Gaussian Process
+~~~~~~~~~~~~~~~~
+
+The Gaussian-process controller is the default controller and is the currently the most sophisticated machine learner algorithm. It uses a `Link Gaussian process <http://scikit-learn.org/dev/modules/gaussian_process.html>`_ to develop a model for how the parameters relate to the measured cost, effectively creating a model for how the experiment operates. This model is then used when picking new points to test. 
+
+There are two example files for the Gaussian-process controller: *gaussian_process_simple_config.txt* which contains the basic options.
+
+.. include:: ../examples/gaussian_process_simple_config.txt
+   :literal:
+
+*gaussian_process_complete_config.txt* which contains a comprehensive list of options.
+
+.. include:: ../examples/gaussian_process_complete_config.txt
+   :literal:
+
+Nelder Mead
+~~~~~~~~~~~
+
+The Nelder Mead controller implements the `Link Nelder-Mead method <https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method>`_ for optimization. You can control the starting point and size of the initial simplex of the method with the configuration file.
+
+There are two example files for the Nelder-Mead controller: *nelder_mead_simple_config.txt* which contains the basic options.
+
+.. include:: ../examples/nelder_mead_simple_config.txt
+   :literal:
+
+*nelder_mead_complete_config.txt* which contains a comprehensive list of options.
+
+.. include:: ../examples/nelder_mead_complete_config.txt
+   :literal:
+
+Random
+~~~~~~
+
+The random optimization algorithm picks parameters randomly from a uniform distribution from within the parameter bounds or trust region. 
+
+There are two example files for the random controller: *random_simple_config.txt* which contains the basic options.
+
+.. include:: ../examples/random_simple_config.txt
+   :literal:
+
+*random_complete_config.txt* which contains a comprehensive list of options.
+
+.. include:: ../examples/random_complete_config.txt
+   :literal:
+
+Logging
+-------
+
+You can control the filename of the logs and also the level which is reported to the file and the console. For more information see `Link logging levels <https://docs.python.org/3.6/library/logging.html#levels>`_. The logging options are described in *logging_config.txt*.
+
+.. include:: ../examples/logging_config.txt
+   :literal:
+
+Extras
+------
+
+Extras refers to options related to post processing your data once the optimization is complete. Currently the only extra option is for visualizations. The extra options are described in *extras_config.txt*.
+
+.. include:: ../examples/extras_config.txt
+   :literal:
+
+
diff --git a/doc/source/index.rst → docs/index.rst b/doc/source/index.rst → docs/index.rst
@@ -4,12 +4,12 @@ M-LOOP
 
 The Machine-Learner Online Optimization Package is designed to automatically and rapidly optimize the parameters of a scientific experiment or computer controller system. 
 
-.. figure:: images/M-LOOPandBEC.png
+.. figure:: _static/M-LOOPandBEC.png
    :alt: M-LOOP optimizing a BEC.
 
-   M-LOOP in control of a ultra-cold atom experiment. M-LOOP was able to find an optimal set of ramps to evaporatively cool a thermal gas and form a Bose-Einstein Condensate. 
+   M-LOOP in control of an ultra-cold atom experiment. M-LOOP was able to find an optimal set of ramps to evaporatively cool a thermal gas and form a Bose-Einstein Condensate. 
 
-Using M-LOOP is simple, once the parameters of your experiment is computer controller, all you need to do is determine a cost function that quantifies the performance of an experiment after a single run. You can then hand over control of the experiment to M-LOOP which will find a global optimal set of parameters that minimize the cost function, by performing a few experiments and testing different parameters. M-LOOP uses machine-learning to predict how the parameters of the experiment relate to the cost, it uses this model to pick the next best parameters to test to find an optimum as quickly as possible. 
+Using M-LOOP is simple, once the parameters of your experiment is computer controlled, all you need to do is determine a cost function that quantifies the performance of an experiment after a single run. You can then hand over control of the experiment to M-LOOP which will find a global optimal set of parameters that minimize the cost function, by performing a few experiments and testing different parameters. M-LOOP uses machine-learning to predict how the parameters of the experiment relate to the cost, it uses this model to pick the next best parameters to test to find an optimum as quickly as possible. 
 
 M-LOOP not only finds an optimal set of parameters for the experiment it also provides a model of how the parameters are related to the costs which can be used to improve the experiment. 
 
@@ -35,7 +35,6 @@ Contents
    interfaces
    data
    visualizations
-   options
    examples
    contributing
    api/index

diff --git a/doc/source/install.rst → docs/install.rst b/doc/source/install.rst → docs/install.rst
@@ -75,9 +75,9 @@ In the M-LOOP source code directory. The tests should take around five minutes t
 Documentation
 -------------
 
-If you would also like a local copy of the documentation enter the doc folder and use the command::
+If you would also like a local copy of the documentation enter the docs folder and use the command::
 
    make html
    
-Which will generate the documentation in doc/build/html.
+Which will generate the documentation in docs/_build/html.
 
diff --git a/doc/source/interfaces.rst → docs/interfaces.rst b/doc/source/interfaces.rst → docs/interfaces.rst
diff --git a/doc/make.bat → docs/make.bat b/doc/make.bat → docs/make.bat
@@ -5,9 +5,9 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
-set I18NSPHINXOPTS=%SPHINXOPTS% source
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%

diff --git a/doc/source/tutorial.rst → docs/tutorial.rst b/doc/source/tutorial.rst → docs/tutorial.rst
@@ -3,7 +3,7 @@
 Tutorial
 ========
 
-Here we provide a tutorial on how to use M-LOOP to optimize a generic experiment. M-LOOP is flexible and can be customized with a variety of :ref:`sec-options` and :ref:`sec-interfaces`, it can be run from the command line or used as a :ref:`python API <sec-api>`. Here we introduce the basic settings to get M-LOOP up and running as quick as possible. 
+Here we provide a tutorial on how to use M-LOOP to optimize a generic experiment. M-LOOP is flexible and can be customized with a variety of :ref:`options <sec-examples>` and :ref:`sec-interfaces`, it can be run from the command line or used as a :ref:`python API <sec-api>`. Here we introduce the basic settings to get M-LOOP up and running as quick as possible. 
 
 Overview
 --------
@@ -12,7 +12,7 @@ The basic operation of M-LOOP is sketched below.
 
 .. _fig-mloop-diag:
 
-.. figure:: images/M-LOOP_diagram.png
+.. figure:: _static/M-LOOP_diagram.png
    :alt: M-LOOP in a loop with an experiment sending parameters and receiving costs.
 
 There are three stages: 
@@ -47,7 +47,7 @@ The configuration file contains a list of options and settings for the optimizat
 
    [keyword] = [value]
    
-You can add comments to your file using #, everything past # will be ignored. Examples of relevant keywords and syntax for the values is provided in :ref:`sec-examples` and a comprehensive list of options is described in :ref:`sec-options`. The values should be formatted with python syntax, strings should be surrounded with single or double quotes and arrays of values can be surrounded with square brackets/parentheses with numbers separated with commas. In this tutorial we will examine the example file *tutoral_config.txt*::
+You can add comments to your file using #, everything past # will be ignored. Examples of relevant keywords and syntax for the values is provided in :ref:`sec-examples` and a comprehensive list of options is described in :ref:`sec-examples`. The values should be formatted with python syntax, strings should be surrounded with single or double quotes and arrays of values can be surrounded with square brackets/parentheses with numbers separated with commas. In this tutorial we will examine the example file *tutoral_config.txt*::
 
    #Tutorial Config
    #---------------
@@ -110,7 +110,7 @@ If you do not want one of the halting conditions, simply delete it from your fil
 Learner specific options
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are many learner specific options (and different learner algorithms) described in :ref:`sec-options`. Here we consider just a couple of the most commonly used ones. M-LOOP has been designed to find an optimum quickly with no custom configuration as long as the experiment is able to provide a cost for every parameter it provides.
+There are many learner specific options (and different learner algorithms) described in :ref:`sec-examples`. Here we consider just a couple of the most commonly used ones. M-LOOP has been designed to find an optimum quickly with no custom configuration as long as the experiment is able to provide a cost for every parameter it provides.
 
 However if your experiment will fail to work if there are sudden and significant changes to your parameters you may need to set the following options::
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,7 +12,7 @@ In the M-LOOP source folder. @@
     For more details on how to use the package see the documentation. You can see it online at
-    ?
+    http://m-loop.readthedocs.io/
     Or you can build it by entering the docs folder and running:
@@ Expand Down @@