Package mystic

Source Code for Package mystic

  1  #!/usr/bin/env python 
  2  # 
  3  # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  4  # 
  5  #                       Mike McKerns & Patrick Hung, Caltech 
  6  #                        (C) 1997-2010  All Rights Reserved 
  7  # 
  8  # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  9  # 
 10  """ 
 11  mystic: a simple model-independent inversion framework 
 12   
 13  The mystic framework provides a collection of optimization algorithms 
 14  and tools that allows the user to more robustly (and readily) solve 
 15  optimization problems. All optimization algorithms included in mystic 
 16  provide workflow at the fitting layer, not just access to the algorithms 
 17  as function calls. Mystic gives the user fine-grained power to both 
 18  monitor and steer optimizations as the fit processes are running. 
 19   
 20  Where possible, mystic optimizers share a common interface, and thus can 
 21  be easily swapped without the user having to write any new code. Mystic 
 22  solvers all conform to a solver API, thus also have common method calls 
 23  to configure and launch an optimization job. For more details, see 
 24  `mystic.abstract_solver`. The API also makes it easy to bind a favorite 
 25  3rd party solver into the mystic framework. 
 26   
 27  By providing a robust interface designed to allow the user to easily 
 28  configure and control solvers, mystic reduces the barrier to implementing 
 29  a target fitting problem as stable code. Thus the user can focus on 
 30  building their physical models, and not spend time hacking together an 
 31  interface to optimization code. 
 32   
 33  Mystic is in the early development stages, and any user feedback is 
 34  highly appreciated. Contact Mike McKerns [mmckerns at caltech dot edu] 
 35  with comments, suggestions, and any bugs you may find.  A list of known 
 36  issues is maintained at http://dev.danse.us/trac/mystic/query. 
 37   
 38   
 39  Major Features 
 40  ============== 
 41   
 42  Mystic provides a stock set of configurable, controllable solvers with:: 
 43      - a common interface 
 44      - the ability to impose solver-independent bounds constraints 
 45      - the ability to apply solver-independent monitors 
 46      - the ability to configure solver-independent termination conditions 
 47      - a control handler yielding: [pause, continue, exit, and user_callback] 
 48      - ease in selecting initial conditions: [initial_guess, random] 
 49      - ease in selecting mutation strategies (for differential evolution) 
 50   
 51  To get up and running quickly, mystic also provides infrastructure to:: 
 52      - easily generate a fit model (several example models are included) 
 53      - configure and auto-generate a cost function from a model 
 54      - extend fit jobs to parallel & distributed resources 
 55      - couple models with optimization parameter constraints [COMING SOON] 
 56   
 57   
 58  Current Release 
 59  =============== 
 60   
 61  This release version is mystic-0.2a1. You can download it here. 
 62  The latest version of mystic is available from:: 
 63      http://dev.danse.us/trac/mystic 
 64   
 65  Mystic is distributed under a modified BSD license. 
 66   
 67   
 68  Installation 
 69  ============ 
 70   
 71  Mystic is packaged to install from source, so you must 
 72  download the tarball, unzip, and run the installer:: 
 73      [download] 
 74      $ tar -xvzf mystic-0.2a1.tgz 
 75      $ cd mystic-0.2a1 
 76      $ python setup py build 
 77      $ python setup py install 
 78   
 79  You will be warned of any missing dependencies and/or settings 
 80  after you run the "build" step above. Mystic depends on numpy, 
 81  so you should install it first. Having matplotlib is necessary 
 82  for running several of the examples, and you should probably go 
 83  get it even though it's not required. 
 84   
 85  Alternately, mystic can be installed with easy_install:: 
 86      [download] 
 87      $ easy_install -f . mystic 
 88   
 89   
 90  Requirements 
 91  ============ 
 92   
 93  Mystic requires:: 
 94      - python, version >= 2.5, version < 3.0 
 95      - numpy, version >= 1.0 
 96   
 97  Optional requirements:: 
 98      - setuptools, version >= 0.6 
 99      - matplotlib, version >= 0.91 
100      - pathos, version >= 0.1a1 
101   
102   
103  Usage Notes 
104  =========== 
105   
106  Probably the best way to get started is to look at a few of the 
107  examples provided within mystic. See `mystic.examples` for a 
108  set of scripts that demonstrate the configuration and launching of  
109  optimization jobs for one of the sample models in `mystic.models`. 
110  Many of the included examples are standard optimization test problems. 
111   
112  Instructions on building a new model are in `mystic.models.abstract_model`. 
113  Mystic provides base classes for two types of models:: 
114      - AbstractFunction   [evaluates f(x) for given evaluation points x] 
115      - AbstractModel      [generates f(x,p) for given coefficients p] 
116   
117  It is, however, not necessary to use the base classes in your own model. 
118  Mystic also provides some convienence functions to help you build a 
119  model instance and a cost function instance on-the-fly. For more 
120  information, see `mystic.mystic.forward_model`. 
121   
122  All mystic solvers are highly configurable, and provide a robust set of 
123  methods to help customize the solver for your particular optimization 
124  problem. For each solver, a minimal interface is also provided for users 
125  who prefer to configure their solvers in a single function call. For more 
126  information, see `mystic.mystic.abstract_solver` for the solver API, and 
127  each of the individual solvers for their minimal (non-API compliant) 
128  interface. 
129   
130  Mystic extends the solver API to parallel computing by providing a solver 
131  class that utilizes the parallel map-reduce algorithm. Mystic includes 
132  a set of defaults in `mystic.mystic.python_map` that mirror the behavior 
133  of serial python and the built-in python map function. Mystic solvers 
134  built on map-reduce can utilize the distributed and parallel tools provided 
135  by the `pathos` package, and thus with little new code solvers are 
136  extended to high-performance computing. For more information, see 
137  `mystic.mystic.abstract_map_solver`, `mystic.mystic.abstract_nested_solver`, 
138  and the pathos documentation at http://dev.danse.us/trac/pathos. 
139   
140  Important classes and functions are found here:: 
141      - mystic.mystic.abstract_solver        [the solver API definition] 
142      - mystic.mystic.abstract_map_solver    [the parallel solver API] 
143      - mystic.mystic.abstract_nested_solver [the nested solver API] 
144      - mystic.mystic.termination            [solver termination conditions] 
145      - mystic.mystic.strategy               [solver population mutation strategies] 
146      - mystic.models.abstract_model         [the model API definition] 
147      - mystic.models.forward_model          [cost function generator] 
148      - mystic.mystic.tools                  [monitors, function wrappers, and other tools] 
149      - mystic.mystic.math                   [some useful mathematical functions and tools] 
150   
151  Solvers are found here:: 
152      - mystic.mystic.differential_evolution [Differential Evolution solvers] 
153      - mystic.mystic.scipy_optimize         [Nelder-Mead and Powell's Directional solvers] 
154      - mystic.mystic.nested                 [Batch Grid and Scattershot solvers] 
155   
156   
157  More Information 
158  ================ 
159   
160  Please see http://dev.danse.us/trac/mystic for further information. 
161  """ 
162  __version__ = '0.2a1' 
163  __author__ = 'Mike McKerns' 
164   
165  __license__ = """ 
166  This software is part of the open-source DANSE project at the California 
167  Institute of Technology, and is available subject to the conditions and 
168  terms laid out below. By downloading and using this software you are 
169  agreeing to the following conditions. 
170   
171  Redistribution and use in source and binary forms, with or without 
172  modification, are permitted provided that the following conditions 
173  are met:: 
174   
175      - Redistribution of source code must retain the above copyright 
176        notice, this list of conditions and the following disclaimer. 
177   
178      - Redistribution in binary form must reproduce the above copyright 
179        notice, this list of conditions and the following disclaimer in the 
180        documentations and/or other materials provided with the distribution. 
181   
182      - Neither the name of the California Institute of Technology nor 
183        the names of its contributors may be used to endorse or promote 
184        products derived from this software without specific prior written 
185        permission. 
186   
187  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
188  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 
189  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
190  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
191  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
192  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
193  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
194  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
195  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
196  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
197  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
198   
199  Copyright (c) 2010 California Institute of Technology. All rights reserved. 
200   
201   
202  If you use this software to do productive scientific research that leads to 
203  publication, we ask that you acknowledge use of the software by citing the 
204  following paper in your publication:: 
205   
206      "mystic: a simple model-independent inversion framework", 
207       Michael McKerns, Patrick Hung, and Michael Aivazis, unpublished; 
208       http://dev.danse.us/trac/mystic 
209   
210  """ 
211   
212  # solvers 
213  import differential_evolution, scipy_optimize, nested 
214   
215  # strategies, termination conditions 
216  import termination 
217  import strategy 
218   
219  # monitors, function wrappers, and other tools 
220  from tools import * 
221   
226   
227  # end of file 
228