
.. _usingfunction:

===========================================
:mod:`function` - defines theano.function
===========================================

.. module:: function
   :platform: Unix, Windows
   :synopsis: defines theano.function and related classes
.. moduleauthor:: LISA

Guide
=====

This module provides :func:`function`, commonly accessed as `theano.function`,
the interface for compiling graphs into callable objects.

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.

The behaviour of function can be controlled in several ways, such as
:class:`Param`, ``mode``, ``updates``, and ``givens``.  These are covered
in the :ref:`tutorial examples <basictutexamples>` and :ref:`tutorial on modes <using_modes>`.

Reference
=========

.. class:: Out

    A class for attaching information to function outputs

    .. attribute:: variable

        A variable in an expression graph to use as a compiled-function
        output

    .. attribute:: borrow

        ``True`` indicates that a reference to internal storage may be returned, and that the caller is aware that subsequent function evaluations might overwrite this memory.

    .. method:: __init__(variable, borrow=False)

        Initialize attributes from arguments. 

.. class:: Param

    A class for attaching information to function inputs.

    .. attribute:: variable

        A variable in an expression graph to use as a compiled-function parameter

    .. attribute:: default
    
        The default value to use at call-time (can also be a Container where
        the function will find a value at call-time.)

    .. attribute:: name 
    
        A string to identify an argument for this parameter in keyword arguments.

    .. attribute:: mutable
    
        ``True`` means the compiled-function is allowed to modify this
        argument. ``False`` means it is not allowed.

    .. attribute:: strict
    
      If ``False``, a function argument may be copied or cast to match the type
      required by the parameter `variable`.  If ``True``, a function argument
      must exactly match the type required by `variable`.

    .. method:: __init__(self, variable, default=None, name=None, mutable=False, strict=False)

        Initialize object attributes.


.. function:: function(inputs, outputs, mode=None, updates=[], givens=[], accept_inplace=False, name=None)

    Return a callable object that will calculate `outputs` from `inputs`.

    :type params: list of either Variable or Param instances, but not shared
        variables.

    :param params: the returned :class:`Function` instance will have
      parameters for these variables.

    :type outputs: list of Variables or Out instances

    :param outputs: expressions to compute.

    :type mode: None, string or :class:`Mode` instance.

    :param mode: compilation mode

    :type updates: iterable over pairs (shared_variable, new_expression).
       List, tuple or dict.

    :param updates: expressions for new :class:`SharedVariable` values

    :type givens: iterable over pairs (Var1, Var2) of Variables.
       List, tuple or dict.  The Var1
       and Var2 in each pair must have the same Type.

    :param givens: specific substitutions to make in the
      computation graph (Var2 replaces Var1).

    :type no_default_updates: either bool or list of Variables
    :param no_default_updates:
        if True, do not perform any automatic update on Variables.
        If False (default), perform them all.
        Else, perform automatic updates on all Variables that are
        neither in ``updates`` nor in ``no_default_updates``.

    :param name: an optional name for this function.
      The profile mode will print the time spent in this function.

    :rtype: Function instance

    :returns: a callable object that will compute the outputs (given the inputs)
      and update the implicit function arguments according to the `updates`.


    Inputs can be given as variables or Param instances.
    :class:`Param` instances also have a variable, but they attach some extra
    information about how call-time arguments corresponding to that variable
    should be used.  Similarly, :class:`Out` instances can attach information
    about how output variables should be returned.

    The default is typically 'FAST_RUN' but this can be changed in
    :doc:`theano.config <../config>`.  The mode
    argument controls the sort of optimizations that will be applied to the
    graph, and the way the optimized graph will be evaluated.

    After each function evaluation, the `updates` mechanism can replace the
    value of any SharedVariable [implicit] inputs with new values computed
    from the expressions in the `updates` list.  An exception will be raised
    if you give two update expressions for the same SharedVariable input (that
    doesn't make sense).

    If a SharedVariable is not given an update expression, but has a
    ``default_update`` member containing an expression, this expression
    will be used as the update expression for this variable.  Passing
    ``no_default_updates=True`` to ``function`` disables this behavior
    entirely, passing ``no_default_updates=[sharedvar1, sharedvar2]``
    disables it for the mentioned variables.

    Regarding givens: Be careful to make sure that these substitutions are
    independent, because behaviour when Var1 of one pair appears in the graph leading
    to Var2 in another expression is undefined (e.g. with ``{a: x, b: a + 1}``).
    Replacements specified with
    givens are different from optimizations in that Var2 is not expected to be
    equivalent to Var1.
