# Tutorials

Mystic provides a large set of examples that are bundled with the source code, available for download here. All examples that begin with the prefix "test" are intended to serve as tests of the included solvers and models. Examples that begin with the prefix "example" are intended to demonstrate mystic's major features, and serve as the basis of the online tutorial.

While mystic does not require matplotlib, several of the aforementioned examples do. Make sure you have read mystic's installation instructions before you proceed *(NOTE: Mac users, see ticket #36)*.

#### Examples

Minimal solver interface:

Expanded solver interface:

Cost function generator:

#### Usage Notes

Probably the best way to get started is to look at a few of the examples provided within mystic. See `mystic.examples` for a set of scripts that demonstrate the configuration and launching of optimization jobs for one of the sample models in `mystic.models`. Many of the included examples are standard optimization test problems.

Instructions on building a new model are in `mystic.models.abstract_model`. Mystic provides base classes for two types of models::

- AbstractFunction [evaluates f(x) for given evaluation points x]
- AbstractModel [generates f(x,p) for given coefficients p]

It is, however, not necessary to use the base classes in your own model. Your new model may be as simple as a python function. Mystic also provides some convienence functions to help you build a model instance and a cost function instance on-the-fly. For more information, see `mystic.mystic.forward_model`.

All mystic solvers are highly configurable, and provide a robust set of methods to help customize the solver for your particular optimization problem. For each solver, a minimal interface is also provided for users who prefer to configure their solvers in a single function call. For more information, see `mystic.mystic.abstract_solver` for the solver API, and each of the individual solvers for their minimal (non-API compliant) interface.

Important classes and functions are found here::

- mystic.mystic.abstract_solver [the solver API definition]
- mystic.mystic.termination [solver termination conditions]
- mystic.mystic.stragegy [solver population mutation strategies]
- mystic.models.abstract_model [the model API definition]
- mystic.mystic.forward_model [cost function generator]
- mystic.mystic.tools [monitors, function wrappers, and other useful tools]

Solvers are found here::

- mystic.mystic.differential_evolution [Differential Evolution solvers]
- mystic.mystic.scipy_optimize [Nelder-Mead and Powell's Directional solvers]

Mystic extends the solver API to parallel computing by providing a solver
class that utilizes the parallel map-reduce algorithm. Mystic includes
a set of defaults in `mystic.mystic.python_map` that mirror the behavior
of serial python and the built-in python map function. Mystic solvers
built on map-reduce can utilize the distributed and parallel tools provided
by the `pathos` package, and thus with little new code solvers are
extended to high-performance computing. For more information, see
`mystic.mystic.abstract_map_solver`, `mystic.mystic.abstract_nested_solver`,
and the pathos documentation at http://trac.mystic.cacr.caltech.edu/project/pathos.

#### More Information

Please see the reference manual or release notes for further information.