xbob.mlp.lbfgs 0.1e

==========================
MLP L-BFGS Trainer for Bob
==========================

This example demonstrates how to extend Bob by providing a new L-BFGS-based
trainer for the multilayer perceptron (MLP) implementation of Bob.

Installation
============

First, you have to install `bob <http://www.idiap.ch/software/bob>`_ following the instructions
`there <http://www.idiap.ch/software/bob/docs/releases/last/sphinx/html/Installation.html>`_.

.. note::

If you are reading this page through our GitHub portal and not through PyPI,
note **the development tip of the package may not be stable** or become
unstable in a matter of moments.

Go to `http://pypi.python.org/pypi/xbob.mlp.lbfgs
<http://pypi.python.org/pypi/xbob.mlp.lbfgs>`_ to download the latest
stable version of this package.

There are two options you can follow to get this package installed and
operational on your computer: you can use automatic installers like `pip
<http://pypi.python.org/pypi/pip/>`_ (or `easy_install
<http://pypi.python.org/pypi/setuptools>`_) or manually download, unpack and
use `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ to create a
virtual work environment just for this package. In both cases, the two
dependences listed above will be automatically downloaded and installed.

Using an automatic installer
----------------------------

Using ``pip`` is the easiest (shell commands are marked with a ``$`` signal)::

$ pip install xbob.mlp.lbfgs

You can also do the same with ``easy_install``::

$ easy_install xbob.mlp.lbfgs

This will download and install this package plus any other required
dependencies. It will also verify if the version of Bob you have installed
is compatible.

This scheme works well with virtual environments by `virtualenv
<http://pypi.python.org/pypi/virtualenv>`_ or if you have root access to your
machine. Otherwise, we recommend you use the next option.

Using ``zc.buildout``
---------------------

Download the latest version of this package from `PyPI
<http://pypi.python.org/pypi/xbob.mlp.lbfgs>`_ and unpack it in your
working area. The installation of the toolkit itself uses `buildout
<http://www.buildout.org/>`_. You don't need to understand its inner workings
to use this package. Here is a recipe to get you started::

$ python bootstrap.py
$ ./bin/buildout

These two commands should download and install all non-installed dependencies and
get you a fully operational test and development environment.

.. note::

The python shell used in the first line of the previous command set
determines the python interpreter that will be used for all scripts developed
inside this package. Because this package makes use of `Bob
<http://idiap.github.com/bob>`_, you must make sure that the ``bootstrap.py``
script is called with the **same** interpreter used to build Bob, or
unexpected problems might occur.

If Bob is installed by the administrator of your system, it is safe to
consider it uses the default python interpreter. In this case, the above 3
command lines should work as expected. If you have Bob installed somewhere
else on a private directory, edit the file ``buildout.cfg`` **before**
running ``./bin/buildout``. Find the section named ``buildout`` and edit or
add the line ``prefixes`` to point to the directory where Bob is installed or
built. For example::

[buildout]
...
prefixes=/Users/crazyfox/work/bob/build


User Guide
==========

It is assumed you have followed the installation instructions for the package
and got this package installed.

Below, we provide an example of how to train an MLP using this trainer, from
the python universe::

>>> machine = bob.machine.MLP((n_inputs, n_hidden, n_outputs))
>>> # Initialize the machine weights/biases as wished
>>> trainer = xbob.mlp.lbfgs.Trainer(1e-6)
>>> trainer.initialize(machine)
>>> trainer.train(machine, X, labels)