This page is about ``theano.function``, the interface for compiling graphs into callable objects.
The signature for this function is:
.. code-block:: python
def function(inputs, outputs, mode='FAST_RUN'):
...
You've already seen example usage in the basic tutorial... something like this:
>>> x = theano.tensor.dscalar()
>>> f = theano.function([x], 2*x)
>>> print f(4) # prints 8.0
The idea here is that we've compiled the symbolic graph (``2*x``) into a function that can be called on a number and will do some computations.
Inputs
======
The ``inputs`` argument to ``theano.function`` is a list, containing the ``Result`` instances for which values will be specified at the time of the function call. But inputs can be more than just Results.
``In`` instances let us attach properties to ``Results`` to tell function more about how to use them.
This will be assigned a value before running the function,
not computed from its owner.
name: Any type. (If autoname_input=True, defaults to result.name).
If name is a valid Python identifier, this input can be set by kwarg, and its value
can be accessed by self.<name>.
value: literal or Container
This is the default value of the Input.
update: Result instance
value (see previous) will be replaced with this expression result after each function call.
mutable: Bool (requires value)
True: permit the compiled function to modify the python object being used as the default value.
False: do not permit the compiled function to modify the python object being used as the default value.
autoname: Bool
True: if the name parameter is None and the Result has a name, it will be taken as the input's name
False: the name is the exact value passed as the name parameter (possibly None)
"""
Value: initial and default values
---------------------------------
A non-None `value` argument makes an In() instance an optional parameter. For example, in the following code we are defining an arity-2 function ``inc``.
>>> dec = function([x, In(s, update=(s-x), value=inc.container[s])], [])
>>> dec(3)
>>> print inc[s] # print 7
The functions ``inc`` and ``dec`` operate on a shared internal value for ``s``.
Theano's Module system uses this mechanism to share storage between Methods.
The container being shared doesn't have to correspond to the same Result in both functions,
but that's usually how this mechanism is used.
Input Argument Restrictions
---------------------------
- Every input list element must be (or be upgradable to) a valid ``In`` instance (see the shortcut rules below).
- The same restrictions apply as in Python function definitions: default arguments and keyword arguments have to come at the end of the list. Un-named mandatory arguments must come at the beginning of the list.
- Names have to be unique within an input list. If multiple inputs have the same name, then the function will raise an exception. [***Which exception?]
- Two ``In`` instances may not name the same Result. (You can't give the same parameter multiple times.)
If no name is specified explicitly for an In instance, then it will be taken from the Result's name.
Note that this feature can cause harmless-looking input lists to not satisfy the two conditions above.
In such cases, Inputs should be named explicitly to avoid problems such as duplicate names, and named arguments preceding unnamed ones.
This automatic naming feature can be disabled by instantiating an In instance explicitly with the ``autoname`` flag set to False.
Access to function values and containers
----------------------------------------
For each input, ``theano.function`` will create a ``Container`` if the value wasn't already a ``Contanier``.
At the time of a function call, each of these containers must be filled with a value.
Each input (but especially ones with a default value or an update expression) may have a value between calls too.
The function interface defines a way to get at both the current value associated with an input, as well as the container which will contain all future values.
The ``value`` property accesses the current values. It is both readable and writable, but
assignments (writes) may be implemented by an internal copy and/or casts.
The ``container`` property accesses the corresponding container.
This property accesses is a read-only dictionary-like interface. It is useful
for fetching the container associated with a particular input to share
containers between functions, or to have a sort of pointer to an always
up-to-date value.
(It is illegal to try to get a function to use the same container in two or
more places.)
Both ``value`` and ``container`` properties provide dictionary-like access based on three types of keys:
- ''integer keys'': you can look up a value/container by its position in the input list;
- ''name keys'': you can look up a value/container by its name;
- ''Result keys'': you can look up a value/container by the Result it corresponds to.
In addition to these access mechanisms, there is an even more convenient method
to access values by simply indexing a Function directly, as in the
examples above, by typing ``fn[<name>]``.
To show some examples of these access methods...
.. code-block:: python
a, b, c = T.scalars('xys') # set the internal names of graph nodes
