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.
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.
``In`` instances let us attach properties to ``Results`` to tell function more about how to use them.
.. code-block:: python
**In(result, name=None, value=None, update=None, mutable=False)** returns an ``In`` instance:
- ``result``: a Result instance.
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>``.
Default: ``None``
- ``value``: literal or Container
This is the default value of the Input.
Default: ``None``
- ``update``: Result instance
This expression Result will replace ``value`` after each function call.
Default: ``None``
- ``mutable``: Bool (requires value)
If ``True``, permit the compiled function to modify the python object being used as the default value.
This will be assigned a value before running the function,
``True``: if ``name`` is None and the Result has a name, it will be taken
not computed from its owner.
as the input's name.
name: Any type. (If autoname_input=True, defaults to result.name).
``False``: the name is the exact value passed as the name parameter
If name is a valid Python identifier, this input can be set by kwarg, and its value
(possibly ``None``).
can be accessed by self.<name>.
Default: ???
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
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``.
A non-None `value` argument makes an In() instance an optional parameter
of the compiled function. For example, in the following code we are
>>> dec = function([x, In(s, update=(s-x), value=inc.container[s])], [])
>>> dec = function([x, In(s, update=(s-x), value=inc.container[s])], [])
>>> dec(3)
>>> dec(3)
>>> print inc[s] # print 7
[]
>>> print inc[s]
7.0
>>> inc(2)
[]
>>> print dec[s]
9.0
The functions ``inc`` and ``dec`` operate on a shared internal value for ``s``.
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.
Theano's Module system uses this mechanism to share storage between Methods.
...
@@ -110,48 +147,62 @@ but that's usually how this mechanism is used.
...
@@ -110,48 +147,62 @@ but that's usually how this mechanism is used.
Input Argument Restrictions
Input Argument Restrictions
---------------------------
---------------------------
- Every input list element must be (or be upgradable to) a valid ``In`` instance (see the shortcut rules below).
The following restrictions apply to the inputs to ``theano.function``:
- Every input list element must be a valid ``In`` instance, or must 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.
- The same restrictions apply as in Python function definitions:
default arguments and keyword arguments must 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?]
- 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.)
- Two ``In`` instances may not name the same Result. I.e. you cannot
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.
If no name is specified explicitly for an In instance, then its name
Note that this feature can cause harmless-looking input lists to not satisfy the two conditions above.
will be taken from the Result's name. Note that this feature can cause
In such cases, Inputs should be named explicitly to avoid problems such as duplicate names, and named arguments preceding unnamed ones.
harmless-looking input lists to not satisfy the two conditions above.
This automatic naming feature can be disabled by instantiating an In instance explicitly with the ``autoname`` flag set to False.
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
Access to function values and containers
----------------------------------------
----------------------------------------
For each input, ``theano.function`` will create a ``Container`` if the value wasn't already a ``Contanier``.
For each input, ``theano.function`` will create a ``Container`` if the
At the time of a function call, each of these containers must be filled with a value.
value was not already a ``Container``. At the time of a function call,
Each input (but especially ones with a default value or an update expression) may have a value between calls too.
each of these containers must be filled with a value. Each input (but
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.
especially ones with a default value or an update expression) may have a
value between calls. 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
- The ``value`` property accesses the current values. It is both readable
assignments (writes) may be implemented by an internal copy and/or casts.
and writable, but assignments (writes) may be implemented by an internal
copy and/or casts.
The ``container`` property accesses the corresponding container.
- The ``container`` property accesses the corresponding container.
This property accesses is a read-only dictionary-like interface. It is useful
This property accesses is a read-only dictionary-like interface. It is
for fetching the container associated with a particular input to share
useful for fetching the container associated with a particular input to
containers between functions, or to have a sort of pointer to an always
share containers between functions, or to have a sort of pointer to an
up-to-date value.
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:
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;
- 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;
- 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.
- 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
In addition to these access mechanisms, there is an even more convenient
to access values by simply indexing a Function directly, as in the
method to access values by indexing a Function directly by typing
examples above, by typing ``fn[<name>]``.
``fn[<name>]``, as in the examples above.
To show some examples of these access methods...
To show some examples of these access methods...
...
@@ -159,7 +210,7 @@ To show some examples of these access methods...
...
@@ -159,7 +210,7 @@ To show some examples of these access methods...
a, b, c = T.scalars('xys') # set the internal names of graph nodes
a, b, c = T.scalars('xys') # set the internal names of graph nodes
