source: mystic/setup.py @ 857

Revision 857, 12.6 KB checked in by mmckerns, 3 months ago (diff)

nudging to klepto-0.1.2

Line 
1#!/usr/bin/env python
2#
3# Author: Mike McKerns (mmckerns @caltech and @uqfoundation)
4# Copyright (c) 1997-2016 California Institute of Technology.
5# License: 3-clause BSD.  The full license text is available at:
6#  - http://trac.mystic.cacr.caltech.edu/project/mystic/browser/mystic/LICENSE
7
8from __future__ import with_statement
9import os
10import sys
11
12# set version numbers
13stable_version = '0.2a1'
14target_version = '0.2a2'
15is_release = False
16
17# check if easy_install is available
18try:
19#   import __force_distutils__ #XXX: uncomment to force use of distutills
20    from setuptools import setup
21    has_setuptools = True
22except ImportError:
23    from distutils.core import setup
24    has_setuptools = False
25
26# generate version number
27if os.path.exists('mystic/info.py'):
28    # is a source distribution, so use existing version
29   #from mystic.info import this_version #FIXME?
30    this_version = stable_version
31elif stable_version == target_version:
32    # we are building a stable release
33    this_version = stable_version
34else:
35    # we are building a distribution
36    this_version = target_version + '.dev0'
37    if is_release:
38      from datetime import date
39      today = "".join(date.isoformat(date.today()).split('-'))
40      this_version += "-" + today
41
42# get the license info
43with open('LICENSE') as file:
44    license_text = file.read()
45
46# generate the readme text
47long_description = \
48"""------------------------------------------------------
49mystic: a simple model-independent inversion framework
50------------------------------------------------------
51
52The mystic framework provides a collection of optimization algorithms
53and tools that allows the user to more robustly (and readily) solve
54optimization problems. All optimization algorithms included in mystic
55provide workflow at the fitting layer, not just access to the algorithms
56as function calls. Mystic gives the user fine-grained power to both
57monitor and steer optimizations as the fit processes are running.
58
59Where possible, mystic optimizers share a common interface, and thus can
60be easily swapped without the user having to write any new code. Mystic
61solvers all conform to a solver API, thus also have common method calls
62to configure and launch an optimization job. For more details, see
63`mystic.abstract_solver`. The API also makes it easy to bind a favorite
643rd party solver into the mystic framework.
65
66By providing a robust interface designed to allow the user to easily
67configure and control solvers, mystic reduces the barrier to implementing
68a target fitting problem as stable code. Thus the user can focus on
69building their physical models, and not spend time hacking together an
70interface to optimization code.
71
72Mystic is in the early development stages, and any user feedback is
73highly appreciated. Contact Mike McKerns [mmckerns at caltech dot edu]
74with comments, suggestions, and any bugs you may find.  A list of known
75issues is maintained at http://dev.danse.us/trac/mystic/query.
76
77
78Major Features
79==============
80
81Mystic provides a stock set of configurable, controllable solvers with::
82
83    - a common interface
84    - the ability to impose solver-independent bounds constraints
85    - the ability to apply solver-independent monitors
86    - the ability to configure solver-independent termination conditions
87    - a control handler yielding: [pause, continue, exit, and user_callback]
88    - ease in selecting initial conditions: [initial_guess, random]
89    - ease in selecting mutation strategies (for differential evolution)
90
91To get up and running quickly, mystic also provides infrastructure to::
92
93    - easily generate a fit model (several example models are included)
94    - configure and auto-generate a cost function from a model
95    - extend fit jobs to parallel & distributed resources
96    - couple models with optimization parameter constraints [COMING SOON]
97
98
99Current Release
100===============
101
102The latest stable release version is mystic-%(relver)s. You can download it here.
103The latest stable version of mystic is always available at:
104
105    http://dev.danse.us/trac/mystic
106
107
108Development Release
109===================
110
111If you like living on the edge, and don't mind the promise
112of a little instability, you can get the latest development
113release with all the shiny new features at:
114
115    http://dev.danse.us/packages.
116
117
118Installation
119============
120
121Mystic is packaged to install from source, so you must
122download the tarball, unzip, and run the installer::
123
124    [download]
125    $ tar -xvzf mystic-%(thisver)s.tgz
126    $ cd mystic-%(thisver)s
127    $ python setup py build
128    $ python setup py install
129
130You will be warned of any missing dependencies and/or settings
131after you run the "build" step above. Mystic depends on dill, numpy
132and sympy, so you should install them first. There are several
133functions within mystic where scipy is used if it is available;
134however, scipy is an optional dependency. Having matplotlib installed
135is necessary for running several of the examples, and you should
136probably go get it even though it's not required. Matplotlib is
137also required by mystic's "analysis viewers".
138
139Alternately, mystic can be installed with easy_install::
140
141    [download]
142    $ easy_install -f . mystic
143
144For Windows users, source code and examples are available in zip format.
145A binary installer is also provided::
146
147    [download]
148    [double-click]
149
150
151Requirements
152============
153
154Mystic requires::
155
156    - python, version >= 2.5, version < 3.0
157    - numpy, version >= 1.0
158    - sympy, version >= 0.6.7
159    - dill, version >= 0.2.5
160    - klepto, version >= 0.1.2
161
162Optional requirements::
163
164    - setuptools, version >= 0.6
165    - matplotlib, version >= 0.91
166    - scipy, version >= 0.6.0
167    - pathos, version >= 0.2a1.dev0
168    - pyina, version >= 0.2a1.dev0
169
170
171Usage Notes
172===========
173
174Probably the best way to get started is to look at a few of the
175examples provided within mystic. See `mystic.examples` for a
176set of scripts that demonstrate the configuration and launching of
177optimization jobs for one of the sample models in `mystic.models`.
178Many of the included examples are standard optimization test problems.
179
180Instr1ctions on building a new model are in `mystic.models.abstract_model`.
181Mystic provides base classes for two types of models::
182
183    - AbstractFunction   [evaluates f(x) for given evaluation points x]
184    - AbstractModel      [generates f(x,p) for given coefficients p]
185
186It is, however, not necessary to use the base classes in your own model.
187Mystic also provides some convienence functions to help you build a
188model instance and a cost function instance on-the-fly. For more
189information, see `mystic.mystic.forward_model`.
190
191All mystic solvers are highly configurable, and provide a robust set of
192methods to help customize the solver for your particular optimization
193problem. For each solver, a minimal interface is also provided for users
194who prefer to configure their solvers in a single function call. For more
195information, see `mystic.mystic.abstract_solver` for the solver API, and
196each of the individual solvers for their minimal (non-API compliant)
197interface.
198
199Mystic extends the solver API to parallel computing by providing a solver
200class that utilizes the parallel map-reduce algorithm. Mystic includes
201a set of defaults in `mystic.mystic.python_map` that mirror the behavior
202of serial python and the built-in python map function. Mystic solvers
203built on map-reduce can utilize the distributed and parallel tools provided
204by the `pathos` package, and thus with little new code solvers are
205extended to high-performance computing. For more information, see
206`mystic.mystic.abstract_map_solver`, `mystic.mystic.abstract_ensemble_solver`,
207and the pathos documentation at http://dev.danse.us/trac/pathos.
208
209Important classes and functions are found here::
210
211    - mystic.mystic.solvers                  [solver optimization algorithms]
212    - mystic.mystic.termination              [solver termination conditions]
213    - mystic.mystic.strategy                 [solver population mutation strategies]
214    - mystic.mystic.monitors                 [optimization monitors]
215    - mystic.mystic.tools                    [function wrappers, etc]
216    - mystic.mystic.forward_model            [cost function generator]
217    - mystic.models                          [a collection of standard models]
218    - mystic.math                            [some mathematical functions and tools]
219
220Solver and model API definitions are found here::
221
222    - mystic.mystic.abstract_solver          [the solver API definition]
223    - mystic.mystic.abstract_map_solver      [the parallel solver API]
224    - mystic.mystic.abstract_ensemble_solver [the ensemble solver API]
225    - mystic.models.abstract_model           [the model API definition]
226
227
228License
229=======
230
231Mystic is distributed under a 3-clause BSD license.
232
233    >>> import mystic
234    >>> print mystic.license()
235
236
237Citation
238========
239
240If you use mystic to do research that leads to publication,
241we ask that you acknowledge use of mystic by citing the
242following in your publication::
243
244    M.M. McKerns, L. Strand, T. Sullivan, A. Fang, M.A.G. Aivazis,
245    "Building a framework for predictive science", Proceedings of
246    the 10th Python in Science Conference, 2011;
247    http://arxiv.org/pdf/1202.1056
248
249    Michael McKerns, Patrick Hung, and Michael Aivazis,
250    "mystic: a simple model-independent inversion framework", 2009- ;
251    http://dev.danse.us/trac/mystic
252
253
254More Information
255================
256
257Please see http://dev.danse.us/trac/mystic or http://arxiv.org/pdf/1202.1056 for further information.
258
259""" % {'relver' : stable_version, 'thisver' : this_version}
260
261# write readme file
262with open('README', 'w') as file:
263    file.write(long_description)
264
265# generate 'info' file contents
266def write_info_py(filename='mystic/info.py'):
267    contents = """# THIS FILE GENERATED FROM SETUP.PY
268this_version = '%(this_version)s'
269stable_version = '%(stable_version)s'
270readme = '''%(long_description)s'''
271license = '''%(license_text)s'''
272"""
273    with open(filename, 'w') as file:
274        file.write(contents % {'this_version' : this_version,
275                               'stable_version' : stable_version,
276                               'long_description' : long_description,
277                               'license_text' : license_text })
278    return
279
280# write info file
281write_info_py()
282
283# build the 'setup' call
284setup_code = """
285setup(name='mystic',
286      version='%s',
287      description='a simple interactive inversion analysis framework',
288      long_description = '''%s''',
289      author = 'Mike McKerns',
290      maintainer = 'Mike McKerns',
291      maintainer_email = 'mmckerns@caltech.edu',
292      license = 'BSD',
293      platforms = ['any'],
294      url = 'http://www.cacr.caltech.edu/~mmckerns',
295      classifiers = ('Intended Audience :: Developers',
296                     'Programming Language :: Python',
297                     'Topic :: Physics Programming'),
298
299      packages = ['mystic','mystic.models','mystic.math','mystic.cache'],
300      package_dir = {'mystic':'mystic','mystic.models':'models',
301                     'mystic.math':'_math','mystic.cache':'cache'},
302""" % (target_version, long_description)
303
304# add dependencies
305if sys.version_info[:2] < (2.6):
306    numpy_version = '>=1.0, <1.8.0'
307    sympy_version = '>=0.6.7'#, <0.7.1'
308else:
309    numpy_version = '>=1.0'
310    sympy_version = '>=0.6.7'#, <0.7.4'
311dill_version = '>=0.2.5'
312klepto_version = '>=0.1.2'
313scipy_version = '>=0.6.0'
314matplotlib_version = '>=0.91'
315if has_setuptools:
316    setup_code += """
317      zip_safe=False,
318      dependency_links = ['http://dev.danse.us/packages/'],
319      install_requires = ('numpy%s', 'sympy%s', 'klepto%s', 'dill%s'),
320""" % (numpy_version, sympy_version, klepto_version, dill_version)
321
322# add the scripts, and close 'setup' call
323setup_code += """
324    scripts=['scripts/mystic_log_reader.py',
325             'scripts/mystic_model_plotter.py',
326             'scripts/support_convergence.py',
327             'scripts/support_hypercube.py',
328             'scripts/support_hypercube_measures.py',
329             'scripts/support_hypercube_scenario.py'])
330"""
331
332# exec the 'setup' code
333exec setup_code
334
335# if dependencies are missing, print a warning
336try:
337    import numpy
338    import sympy
339    import klepto
340    import dill
341    #import scipy
342    #import matplotlib #XXX: has issues being zip_safe
343except ImportError:
344    print "\n***********************************************************"
345    print "WARNING: One of the following dependencies is unresolved:"
346    print "    numpy %s" % numpy_version
347    print "    sympy %s" % sympy_version
348    print "    klepto %s" % klepto_version
349    print "    dill %s" % dill_version
350    print "    scipy %s (optional)" % scipy_version
351    print "    matplotlib %s (optional)" % matplotlib_version
352    print "***********************************************************\n"
353
354
355if __name__=='__main__':
356    pass
357
358# end of file
Note: See TracBrowser for help on using the repository browser.