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.
.. 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,
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)
"""
Default: ``False``
- ``autoname``: Bool
``True``: if ``name`` 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``).
Default: ???
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(3)
>>> print inc[s] # print 7
>>> dec(3)
[]
>>> 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``.
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.
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.
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.
If no name is specified explicitly for an In instance, then its name
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.
For each input, ``theano.function`` will create a ``Container`` if the
value was not already a ``Container``. 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. 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 ``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.)
- 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.
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.
- 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>]``.
In addition to these access mechanisms, there is an even more convenient
method to access values by indexing a Function directly by typing
``fn[<name>]``, as in the examples above.
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
