Merge pull request #10 from michaelhush/DiffEvo

Differential evolution added to M-LOOP.

docs/contributing.rst

@@ -5,7 +5,7 @@ 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/>`_. 
+- If you use M-LOOP be sure to cite the 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:MichaelRHush@gmail.com>`_. 
 - 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.

docs/install.rst

@@ -2,13 +2,15 @@
 
 Installation
 ============
-M-LOOP is available on PyPI and can be installed with your favorite package manager. However, we currently recommend you install from the source code to ensure you have the latest improvements and bug fixes. 
+M-LOOP is available on PyPI and can be installed with your favorite package manager. Simply search for 'M-LOOP' and install. For those new to python, we also provide a more comprehensive list of instructions on how to install below.
 
 The installation process involves three steps.
 
 1. Get a Python distribution with the standard scientific packages. We recommend installing :ref:`sec-anaconda`.
-2. Install the development version of :ref:`sec-M-LOOP`.
-3. :ref:`Test<sec-Testing>` your M-LOOP install.
+2. Install the latest release of :ref:`sec-M-LOOP`.
+3. (Optional) :ref:`Test<sec-Testing>` your M-LOOP install.
+
+If you are having any trouble with the installation you may need to check your the :ref:`package dependencies<sec-dependencies>` have been correctly installed. If you ares still having trouble, you can report an issue on the `Link github <https://github.com/michaelhush/M-LOOP/issues>`_. 
 
 .. _sec-anaconda:
 
@@ -20,13 +22,30 @@ https://www.continuum.io/downloads
 
 Follow the installation instructions they provide.
 
-M-LOOP is targeted at python 3.\* but also supports 2.7. Please use python 3.\* if you do not have a reason to use 2.7, see :ref:`sec-py3vpy2` for details.
+M-LOOP is targeted at python 3 but also supports 2. Please use python 3 if you do not have a reason to use 2, see :ref:`sec-py3vpy2` for details.
 
 .. _sec-m-loop:
 
 M-LOOP
 ------
-M-LOOP can be installed from the source code with three commands::
+
+You have two options when installing M-LOOP, you can get the last stable release using pip or you can install from source to get the latest features and bug fixes.
+
+Installing with pip
+^^^^^^^^^^^^^^^^^^^
+
+M-LOOP can be installed with pip with a single command::
+
+   pip install M-LOOP
+   
+If you are using linux or MacOS you may need admin privileges to run the command. To update M-LOOP to the latest version use::
+
+   pip install M-LOOP --upgrade
+
+Installing from source
+^^^^^^^^^^^^^^^^^^^^^^
+
+M-LOOP can be installed from the latest source code with three commands::
 
    git clone git://github.com/michaelhush/M-LOOP.git
    cd ./M-LOOP
@@ -42,19 +61,56 @@ in the M-LOOP directory.
 
 .. _sec-Testing:
 
-Test Installation
------------------
+Testing
+-------
 
-To test your M-LOOP installation use the command::
+If you have installed from source, to test you installation use the command::
 
    python setup.py test
    
 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>`_.
 
+If you installed M-LOOP using pip, you will not need to test your installation. 
+
+.. _sec-dependencies:
+
+Dependencies
+------------
+M-LOOP requires the following packages to run correctly.
+
+============   =======
+Package        Version
+============   =======
+docutils       >=0.3
+matplotlib     >=1.5
+numpy          >=1.11
+pip            >=7.0  
+pytest         >=2.9
+setuptools     >=26   
+scikit-learn   >=0.18
+scipy          >=0.17 
+============   =======  
+
+These packages should be automatically installed by pip or the script setup.py when you install M-LOOP.
+
+However if you are using Anaconda some packages that are managed by the conda command may not be correctly updated, even if your installation passes all the tests. In this case you will have to update these packages yourself manually. You can check what packages you have installed and their version with the command::
+
+   conda list
+   
+To install a package that is missing, say for example pytest, use the command::
+
+   conda install pytest
+   
+To update a package to the latest version, say for example scikit-learn, use the command::
+
+   conda update scikit-learn
+
+Once you install and update all the required packages with conda M-LOOP should run correctly. 
+
 Documentation
 -------------
 
-If you would also like a local copy of the documentation enter the docs folder and use the command::
+The latest documentation will always be available here online. If you would also like a local copy of the documentation enter the docs folder and use the command::
 
    make html
    
@@ -65,6 +121,6 @@ Which will generate the documentation in docs/_build/html.
 Python 3 vs 2
 -------------
 
-M-LOOP is developed in python 3.\* and it gets the best performance in this environment. This is primarily because other packages that M-LOOP uses, like numpy, run fastest in python 3. The tests typically take about 20% longer to complete in python 2 than 3.
+M-LOOP is developed in python 3 and it gets the best performance in this environment. This is primarily because other packages that M-LOOP uses, like numpy, run fastest in python 3. The tests typically take about 20% longer to complete in python 2 than 3.
 
-If you have a specific reason to stay in a python 2.7 environment, you may use other packages which are not python 3 compatible, then you can still use M-LOOP without upgrading to 3.\*. However, if you do not have a specific reason to stay with python 2, it is highly recommended you use the latest python 3.\* package.
+If you have a specific reason to stay in a python 2 environment (you may use other packages which are not python 3 compatible) then you can still use M-LOOP without upgrading to 3. However, if you do not have a specific reason to stay with python 2, it is highly recommended you use the latest python 3 package.

examples/differential_evolution_complete_config.txt

@@ -0,0 +1,19 @@
+#Differential Evolution Complete Options
+#---------------------------------------
+
+#General options
+max_num_runs = 500              #number of planned runs
+target_cost = 0.1               #cost to beat
+
+#Differential evolution controller options
+controller_type = 'differential_evolution'
+num_params = 2                  #number of parameters
+min_boundary = [-1.2,-2]        #minimum boundary
+max_boundary = [10.0,4]         #maximum boundary
+trust_region = [3.2,3.1]        #maximum move distance from best params
+first_params = None          	#first parameters to try if None a random set of parameters is chosen
+evolution_strategy='best2'		#evolution strategy can be 'best1', 'best2', 'rand1' and 'rand2'. Best uses the best point, rand uses a random one, the number indicates the number of directions added.
+population_size=10				#a multiplier for the population size of a generation
+mutation_scale=(0.4, 1.1)		#the minimum and maximum value for the mutation scale factor. Each generation is randomly selected from this. Each value must be between 0 and 2.
+cross_over_probability=0.8     	#the probability a parameter will be resampled during a mutation in a new generation
+restart_tolerance=0.02			#the fraction the standard deviation in the costs of the population must reduce from the initial sample, before the search is restarted.

examples/differential_evolution_simple_config.txt

@@ -0,0 +1,15 @@
+#Differential Evolution Basic Options
+#------------------------------------
+
+#General options
+max_num_runs = 500              #number of planned runs
+target_cost = 0.1               #cost to beat
+
+#Differential evolution controller options
+controller_type = 'differential_evolution'
+num_params = 1                  #number of parameters
+min_boundary = [-4.8]           #minimum boundary
+max_boundary = [10.0]           #maximum boundary
+trust_region = 0.6              #maximum % move distance from best params
+first_params = [5.3]            #first parameters to try
+

mloop/controllers.py

@@ -11,8 +11,8 @@
 import logging
 import os
 
-controller_dict = {'random':1,'nelder_mead':2,'gaussian_process':3}
-number_of_controllers = 3
+controller_dict = {'random':1,'nelder_mead':2,'gaussian_process':3,'differential_evolution':4}
+number_of_controllers = 4
 default_controller_archive_filename = 'controller_archive'
 default_controller_archive_file_type = 'txt'
 
@@ -47,6 +47,8 @@ def create_controller(interface,
     controller_type = str(controller_type)
     if controller_type=='gaussian_process':
         controller = GaussianProcessController(interface, **controller_config_dict)
+    elif controller_type=='differential_evolution':
+        controller = DifferentialEvolutionController(interface, **controller_config_dict)
     elif controller_type=='nelder_mead':
         controller = NelderMeadController(interface, **controller_config_dict)
     elif controller_type=='random':
@@ -489,6 +491,37 @@ def _next_params(self):
         self.learner_costs_queue.put(cost)
         return self.learner_params_queue.get()
 
+class DifferentialEvolutionController(Controller):
+    '''
+    Controller for the differential evolution learner. 
+    
+    Args:
+        params_out_queue (queue): Queue for parameters to next be run by experiment.
+        costs_in_queue (queue): Queue for costs (and other details) that have been returned by experiment.
+        **kwargs (Optional [dict]): Dictionary of options to be passed to Controller parent class and differential evolution learner.
+    '''
+    def __init__(self, interface,
+                **kwargs):
+        super(DifferentialEvolutionController,self).__init__(interface, **kwargs)    
+        
+        self.learner = mll.DifferentialEvolutionLearner(start_datetime = self.start_datetime,
+                                                        **self.remaining_kwargs)
+        
+        self._update_controller_with_learner_attributes()
+        self.out_type.append('differential_evolution')
+    
+    def _next_params(self):
+        '''
+        Gets next parameters from differential evolution learner.
+        '''
+        if self.curr_bad:
+            cost = float('inf')
+        else:
+            cost = self.curr_cost       
+        self.learner_costs_queue.put(cost)
+        return self.learner_params_queue.get()
+
+
 
 
 class GaussianProcessController(Controller):
@@ -506,7 +539,7 @@ class GaussianProcessController(Controller):
     '''
     
     def __init__(self, interface, 
-                 training_type='random',
+                 training_type='differential_evolution',
                  num_training_runs=None,
                  no_delay=True,
                  num_params=None,
@@ -550,9 +583,21 @@ def __init__(self, interface,
                                                  num_params=num_params,
                                                  min_boundary=min_boundary,
                                                  max_boundary=max_boundary,
-                                                 learner_archive_filename='training_learner_archive',
+                                                 learner_archive_filename=None,
                                                  learner_archive_file_type=learner_archive_file_type,
                                                  **self.remaining_kwargs)
+        
+        elif self.training_type == 'differential_evolution':
+            self.learner = mll.DifferentialEvolutionLearner(start_datetime=self.start_datetime,
+                                                            num_params=num_params,
+                                                            min_boundary=min_boundary,
+                                                            max_boundary=max_boundary,
+                                                            trust_region=trust_region,
+                                                            evolution_strategy='rand2',
+                                                            learner_archive_filename=None,
+                                                            learner_archive_file_type=learner_archive_file_type,
+                                                            **self.remaining_kwargs)    
+        
         else:
             self.log.error('Unknown training type provided to Gaussian process controller:' + repr(training_type))
         
@@ -601,12 +646,12 @@ def _next_params(self):
         '''
         Gets next parameters from training learner.
         '''
-        if self.training_type == 'nelder_mead':
+        if self.training_type == 'differential_evolution' or self.training_type == 'nelder_mead':
             #Copied from NelderMeadController
-            if self.curr_bad:
+            if self.last_training_bad:
                 cost = float('inf')
             else:
-                cost = self.curr_cost       
+                cost = self.last_training_cost       
             self.learner_costs_queue.put(cost)
             temp = self.learner_params_queue.get()