Update documentation

I fixed a lot of broken links and code examples.

docs/index.rst

@@ -47,15 +47,17 @@ parameter tuning for machine learning and heuristic optimization.
 
 .. code-block:: python
 
-    from metaopt import param
-    from metaopt.main import optimize
+    from metaopt.core.paramspec.util import param
+    from metaopt.core.optimize.optimize import optimize
 
     @param.float("a", interval=[-1, 1])
     @param.float("b", interval=[0, 1])
     def f(a, b):
         return a**2 + b**2
 
-    args = optimize(f, timeout=60)
+    if __name__ == '__main__':
+        args = optimize(f, timeout=60)
+        print(args);
 
 
 MetaOpt has the following notable features:
@@ -96,15 +98,16 @@ values between -1 and 1) and returns *some* value.
 
 .. code-block:: python
 
-    from metaopt.core import param
-    from metaopt.main import optimize
+    from metaopt.core.paramspec.util import param
+    from metaopt.core.optimize.optimize import optimize
 
-    @param.float("a", interval=[-1, 1], step=0.2)
-    @param.float("b", interval=[-1, 1], step=0.5)
+    @param.float("a", interval=[-1, 1], step=0.02)
+    @param.float("b", interval=[0, 1], step=0.01)
     def f(a, b):
         return a**2 + b**2
 
-    args = optimize(f)
+    if __name__ == '__main__':
+        args = optimize(f, timeout=60)
 
 MetaOpt will optimize ``f`` in parellel and finally return a list of arguments
 for which ``f`` is minimal.
@@ -131,12 +134,12 @@ seconds.
 MetaOpt will return the optimal arguments it found after 60 seconds.
 
 To also limit the time of an individual computation of ``f`` we can pass a
-timeout in seconds by using the :class:`metaopt.plugins.timeout.TimeoutPlugin`.
+timeout in seconds by using the :class:`metaopt.plugin.timeout.TimeoutPlugin`.
 
 .. code-block:: python
 
     from metaopt.optimizer.gridsearch import GridSearchOptimizer
-    from metaopt.plugins.timeout import TimeoutPlugin
+    from metaopt.plugin.timeout import TimeoutPlugin
 
     args = optimize(f, timeout=60, optimizer=GridSearchOptimizer(),
                     plugins=[TimeoutPlugin(5)])
@@ -177,9 +180,9 @@ Let's say a particular objective function takes three parameters ``a``, ``b``
 and ``g``, where ``a`` is an integer between -10 and 10, ``b`` is a float
 between 0.0 and 1.0 and ``g`` is a boolean. To specify these, we use the following decorators on the objective function:
 
-* :func:`metaopt.core.param.util.param.int`
-* :func:`metaopt.core.param.util.param.float`
-* :func:`metaopt.core.param.util.param.bool`
+* :func:`metaopt.core.paramspec.util.param.int`
+* :func:`metaopt.core.paramspec.util.param.float`
+* :func:`metaopt.core.paramspec.util.param.bool`
 
 The decorators have to be specified in the same order as the function parameters
 and should have the same name (the first parameter of the decorator). The
@@ -188,11 +191,11 @@ using the same name) and so forth.
 
 .. code-block:: python
 
-    from metaopt.core.param.util import param
+    from metaopt.core.paramspec.util import param
 
-    @param.int("a", interval=[-10, 10])
-    @param.float("b", interval=[0, 1])
-    @param.bool("g", interval=[0, 1])
+    @param.int("a", interval=[-10, 10], title="α")
+    @param.float("b", interval=[0, 1], title="β")
+    @param.bool("g", title="γ")
     def f(a, b, g):
         return some_expensive_computation(a, b, g)
 
@@ -206,16 +209,16 @@ and similar things.
 
 MetaOpt can both maximize and minimize objective functions. To do this, the following decorators can be used:
 
-* :func:`metaopt.core.returns.util.decorator.maximize`
-* :func:`metaopt.core.returns.util.decorator.minimize`
+* :func:`metaopt.core.returnspec.util.decorator.maximize`
+* :func:`metaopt.core.returnspec.util.decorator.minimize`
 
 For example, to maximize the objective function, we use the `maximize` decorator
 as follows.
 
 .. code-block:: python
 
-    from metaopt.core.returns.decorator import maximize
-    from metaopt.core.param.util import param
+    from metaopt.core.returnspec.util.decorator import maximize
+    from metaopt.core.paramspec.util import param
 
     @maximize("Fitness") # Also give the return value a descriptive name
     @param.int("a", interval=[-10, 10])
@@ -244,14 +247,13 @@ whenever its parameter or argument is shown to the user.
 The following parameter decorators are available in MetaOpt. More types may be
 added in future versions of MetaOpt.
 
-.. autofunction:: metaopt.core.param.ulil.param.int
+.. autofunction:: metaopt.core.paramspec.util.param.int
 
-.. autofunction:: metaopt.core.param.util.param.float
+.. autofunction:: metaopt.core.paramspec.util.param.float
 
-.. autofunction:: metaopt.core.param.util.param.bool
+.. autofunction:: metaopt.core.paramspec.util.param.bool
 
-For more details about specifying the parameters of an objective function, see
-:doc:`parameter_specification`.
+.. autofunction:: metaopt.core.paramspec.util.param.multi
 
 .. _optimization-label:
 
@@ -260,20 +262,20 @@ Optimization
 
 With an objective function defined it can be finally optimized. Given an
 objective function ``f``, the easiest way to optimize it is using the function
-:func:`metaopt.core.main.optimize`.
+:func:`metaopt.core.optimize.optimize.optimize`.
 
 .. code-block:: python
 
-    from metaopt.main import optimize
+    from metaopt.core.optimize.optimize import optimize
 
     args = optimize(f)
 
 The result of ``optimize`` is a list of arguments (see
-:class:`metaopt.core.args.Arg`) for which the objective function is optimal
+:class:`metaopt.core.arg.arg.Arg`) for which the objective function is optimal
 (either minimial or maximal).
 
 MetaOpt runs multiple computations of the objective functions in parallel (via the
-:class:`metaopt.invoker.multiprocess.MultiProcessInvoker`). However, other
+:class:`metaopt.concurrent.invoker.multiprocess.MultiProcessInvoker`). However, other
 invokers can choose different ways to compute objective functions. For more
 details, see :ref:`invokers-label`.
 
@@ -283,16 +285,16 @@ optimization. Other optimizers can be selected by passing them to ``optimize``
 
 .. code-block:: python
 
-    from metaopt.main import optimize
+    from metaopt.core.optimize.optimize import optimize
     from metaopt.optimizer.gridsearch import GridSearchOptimizer
 
     args = optimize(f, optimizer=GridSearchOptimizer())
 
 Generally, to optimize an objective function use a suitable function from below.
 
-.. autofunction:: metaopt.core.main.optimize(f, timeout=None, plugins=[], optimizer=SAESOptimizer())
+.. autofunction:: metaopt.core.optimize.optimize.optimize(f, timeout=None, plugins=[], optimizer=SAESOptimizer())
 
-.. autofunction:: metaopt.core.main.custom_optimize(f, invoker, timeout=None, optimizer=SAESOptimizer())
+.. autofunction:: metaopt.core.optimize.optimize.custom_optimize(f, invoker, timeout=None, optimizer=SAESOptimizer())
 
 .. _optimizers-label:
 
@@ -308,11 +310,15 @@ MetaOpt comes a range of built-in optimizers that are suitable for most types of
 objective functions. These are listed below.
 
 
-.. autoclass:: metaopt.optimizer.saes.SAESOptimizer
+.. autoclass:: metaopt.optimizer.cmaes.CMAESOptimizer
+
+.. autoclass:: metaopt.optimizer.gridsearch.GridSearchOptimizer
+
+.. autoclass:: metaopt.optimizer.randomsearch.RandomSearchOptimizer
 
 .. autoclass:: metaopt.optimizer.rechenberg.RechenbergOptimizer
 
-.. autoclass:: metaopt.optimizer.gridsearch.GridSearchOptimizer
+.. autoclass:: metaopt.optimizer.saes.SAESOptimizer
 
 .. For writing your own optimizers see [How to write an Optimizer].
 
@@ -327,20 +333,20 @@ for which arguments the objective function is computed, invokers choose the way
 *how* it is actually computed (or as we call it: invoked).
 
 Other invokers can be used by passing them to
-:func:`metaopt.core.main.custom_optimize`.
+:func:`metaopt.core.optimize.optimize.custom_optimize`.
 
 .. code-block:: python
 
-    from metaopt.main import custom_optimize
-    from metaopt.invoker.multiprocess import MultiProcessInvoker
+    from metaopt.core.optimize.optimize import custom_optimize
+    from metaopt.concurrent.invoker.multiprocess import MultiProcessInvoker
 
-    args = custom_optimize(f, invoker=invoker)
+    args = custom_optimize(f, invoker=MultiProcessInvoker())
 
 The following invokers are available in MetaOpt.
 
-.. autoclass:: metaopt.invoker.multiprocess.MultiProcessInvoker
+.. autoclass:: metaopt.concurrent.invoker.multiprocess.MultiProcessInvoker
 
-.. autoclass:: metaopt.invoker.pluggable.PluggableInvoker
+.. autoclass:: metaopt.concurrent.invoker.pluggable.PluggableInvoker
 
 .. For writing your own invokers, see [How to write an Invoker] for more
 
@@ -351,29 +357,29 @@ Plugins
 
 Plugins change the way objective functions are invoked. They attach handlers to
 various events that occur when an optimizer wants to invoke an objective
-functions via the :class:`metaopt.invoker.pluggable.PluggableInvoker`.
+functions via the :class:`metaopt.concurrent.invoker.pluggable.PluggableInvoker`.
 
-Plugins can be used by passing them to :func:`metaopt.core.main.optimize`.
+Plugins can be used by passing them to :func:`metaopt.core.optimize.optimize.optimize`.
 
 .. code-block:: python
 
-    from metaopt.main import optimize
+    from metaopt.core.optimize.optimize import optimize
 
-    from metaopt.plugins.timeout import TimeoutPlugin
-    from metaopt.plugins.print import PrintPlugin
+    from metaopt.plugin.timeout import TimeoutPlugin
+    from metaopt.plugin.print.status import StatusPrintPlugin
 
-    args = optimize(f, plugins=[PrintPlugin(), TimeoutPlugin(2)])
+    args = optimize(f, plugins=[StatusPrintPlugin(), TimeoutPlugin(2)])
 
-If you use your own custom invoker, :func:`metaopt.core.main.custom_optimize` can be
-used.
+If you use your own custom invoker,
+:func:`metaopt.core.optimize.optimize.custom_optimize` can be used.
 
 .. code-block:: python
 
-    from metaopt.main import custom_optimize
-    from metaopt.invoker.pluggable import PluggableInvoker
+    from metaopt.core.optimize.optimize import optimize
+    from metaopt.concurrent.invoker.pluggable import PluggableInvoker
 
-    from metaopt.plugins.timeout import TimeoutPlugin
-    from metaopt.plugins.print import PrintPlugin
+    from metaopt.plugin.timeout import TimeoutPlugin
+    from metaopt.plugin.print.status import StatusPrintPlugin
 
     invoker = PluggableInvoker(CustomInvoker(),
                                plugins=[PrintPlugin(), TimeoutPlugin(2)])
@@ -382,14 +388,14 @@ used.
 
 The following plugins are available in MetaOpt.
 
-.. autoclass:: metaopt.plugins.timeout.TimeoutPlugin
+.. autoclass:: metaopt.plugin.timeout.TimeoutPlugin
 
-.. autoclass:: metaopt.plugins.print.PrintPlugin
+.. autoclass:: metaopt.plugin.print.status.StatusPrintPlugin
 
-.. autoclass:: metaopt.plugins.visualize.VisualizeLandscapePlugin
+.. autoclass:: metaopt.plugin.visualization.landscape.VisualizeLandscapePlugin
    :members: show_image_plot, show_surface_plot
 
-.. autoclass:: metaopt.plugins.visualize.VisualizeBestFitnessPlugin
+.. autoclass:: metaopt.plugin.visualization.best_fitness.VisualizeBestFitnessPlugin
    :members: show_fitness_invocations_plot, show_fitness_time_plot
 
 .. For writing your own plugins, see [How to write a Plugin].

metaopt/core/paramspec/util/param.py

@@ -31,6 +31,15 @@ def some_function(a, b, c):
 
 
 def multi(other_decorator, names=[], titles=[], *vargs, **kwargs):
+    """
+    A decorator that specifies multiple parameters of the same type.
+
+    All parameters share the same attributes expect for their names and titles
+    which are specified as list of names and titles. The number of parameters
+    added is derived from the length of the former list.
+
+    """
+
     if "title" in kwargs:
         raise TitleForMultiParameterError()
 
@@ -49,9 +58,9 @@ def decorator(func):
 
 def bool(*vargs, **kwargs):
     """
-    A decorator that specifies an bool parameter for a function
+    A decorator that specifies an bool parameter for a function.
 
-    See :meth:`metaopt.core.paramspec.ParamSpec.bool` for the allowed
+    See :meth:`metaopt.core.paramspec.paramspec.ParamSpec.bool` for the allowed
     parameters.
 
     """
@@ -65,9 +74,9 @@ def decorator(func):
 
 def float(*vargs, **kwargs):
     """
-    A decorator that specifies a float parameter for a function
+    A decorator that specifies a float parameter for a function.
 
-    See :meth:`metaopt.core.paramspec.ParamSpec.float` for the allowed
+    See :meth:`metaopt.core.paramspec.paramspec.ParamSpec.float` for the allowed
     parameters.
 
     """
@@ -82,9 +91,9 @@ def decorator(func):
 
 def int(*vargs, **kwargs):
     """
-    A decorator that specifies an int parameter for a function
+    A decorator that specifies an int parameter for a function.
 
-    See :meth:`metaopt.core.paramspec.ParamSpec.int` for the allowed parameters.
+    See :meth:`metaopt.core.paramspec.paramspec.ParamSpec.int` for the allowed parameters.
 
     """
 

metaopt/optimizer/cmaes.py

@@ -48,6 +48,10 @@ class CMAESOptimizer(Optimizer):
     STEP_SIZE = 1.0
 
     def __init__(self, mu=MU, lamb=LAMBDA, global_step_size=STEP_SIZE):
+        """
+        :param mu: Number of parent arguments
+        :param lamb: Number of offspring arguments
+        """
         super(CMAESOptimizer, self).__init__()
 
         self.population = []

metaopt/optimizer/randomsearch.py

@@ -10,7 +10,13 @@
 
 
 class RandomSearchOptimizer(Optimizer):
-    """Optimizer that systematically tests parameters in a grid pattern."""
+    """
+    Optimizer that randomly tests parameters.
+
+    This optimizer should be combined with a global timeout, otherwise it will
+    run indefinitely.
+
+    """
 
     def __init__(self):
         super(RandomSearchOptimizer, self).__init__()