Promise
-------

Computing the whole-model cross-entropy requires either a lot of patience, or distributed computation.
For distributed programming, this toolkit has a Python implementaton of `promises <http://en.wikipedia.org/wiki/Promise_(programming)>`_\ .
A promise is essentially a function that can be evaluated ("fulfilled").
It may depend on other promises.
This implicitly implies a tree of expressions that constitute the computation.

The term "function" is taken in the functional programming sense.
A promise can declare what it needs as inputs, and it has a return value.
It should not have any side effects, and each time it is evaluated with the same inputs, this must the same return value.
These restrictions make it possible for a framework for distributed programming to be robust to failing nodes.
The framework, not the promises, takes care of the loading results from and writing results to disk.
This makes it possible to evaluate a promise on two machines at the same time, for example if one machine turns out to be slow, or if a job fails.
Restricting functions to have no side effects therefore makes it possible for the framework to be inherently robust.

Interacting with the Promise framework involves setting up a structured promise (an expression tree, with promises that depend on other promises) in ``main_promise.py``.
It puts the main promise in the variable ``mainPromise``.
To evaluate the promise, ``./dashboard.py`` starts a Python shell with the commands ``status()``, ``run()``, ``submit()``.
``run()`` is useful in case of unlimited patience.
``submit()`` requires the Sun Grid Engine.

The results of promises are written to disk in a separate directory for each sub-promise.
To allow constant-time identification and lookup, promises use hashing with :class:`consistentHash <tools.consistent_hash.consistentHash>`\ .
The current implementation does not deal with hash collisions except by throwing an exception.
It is therefore currently necessary to ensure that hash collisions do not occur.

Promises
^^^^^^^^

Promises must be subclasses of :class:`Promise <promise.promise.Promise>`\ .
It is possible to write one's own subclasses, or to pass functions and values into
:class:`ValuePromise <promise.promise.ValuePromise>`\ ,
:class:`FunctionPromise <promise.promise.FunctionPromise>`\ , or
:class:`BoundFunctionPromise <promise.promise.BoundFunctionPromise>`\ .
All functions and values that are passed in to promises need to have a consistent hash defined with :class:`consistentHash <tools.consistent_hash.consistentHash>`\ .

..  autoclass:: promise.promise.Promise
    :members: 

..  autoclass:: promise.promise.ValuePromise
    :members: 

..  autoclass:: promise.promise.FunctionPromise
    :members: 

..  autoclass:: promise.promise.BoundFunctionPromise
    :members: 

..  autoclass:: promise.promise.PromiseProxy
    :members: 

Fulfilling promises
^^^^^^^^^^^^^^^^^^^

It is possible to cache results of computation in memory, or on disk.

..  autoclass:: promise.fulfill.MemoFulfill
    :members:

..  autoclass:: promise.fulfill_disk.FulfillDisk
    :members: