function - defines theano.function

Guide

This module provides 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:

  1. >>> import theano
  2. >>> x = theano.tensor.dscalar()
  3. >>> f = theano.function([x], 2*x)
  4. >>> f(4)
  5. array(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 asIn, Out, mode, updates, and givens. These are coveredin the tutorial examples and tutorial on modes.

Reference

  • class theano.compile.function.In[source]

  • A class for attaching information to function inputs.

    • variable[source]

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

    • name[source]

    • A string to identify an argument for this parameter in keyword arguments.

    • value[source]

    • The default value to use at call-time (can also be a Container wherethe function will find a value at call-time.)

    • update[source]

    • An expression which indicates updates to the Value after each function call.

    • mutable[source]

    • True means the compiled-function is allowed to modify thisargument. False means it is not allowed.

    • borrow[source]

    • 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.

    • strict[source]

    • If False, a function argument may be copied or cast to match the typerequired by the parameter variable. If True, a function argumentmust exactly match the type required by variable.

    • allow_downcast[source]

    • True indicates that the value you pass for this input can be silently downcasted to fit the right type, which may lose precision. (Only applies when strict is False.)

    • autoname[source]

    • True means that the name is set to variable.name.

    • implicit[source]

    • True means that the input is implicit in the sense that the user is not allowed to provide a value for it. Requires ‘value’ to be set.False means that the user can provide a value for this input.

    • init(self, variable, name=None, value=None, update=None, mutable=None, strict=False, allow_downcast=None, autoname=True, implicit=None, borrow=None, shared=False)[source]

    • Initialize attributes from arguments.
  • class theano.compile.function.Out[source]

  • A class for attaching information to function outputs

    • variable[source]

    • A variable in an expression graph to use as a compiled-functionoutput

    • borrow[source]

    • 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.

    • init(variable, borrow=False)[source]

    • Initialize attributes from arguments.
  • theano.compile.function.function(inputs, outputs, mode=None, updates=None, givens=None, no_default_updates=False, accept_inplace=False, name=None, rebuild_strict=True, allow_input_downcast=None, profile=None, on_unused_input='raise')[source]
  • Return a callable object that will calculate outputs from inputs.

Parameters:

  • params (list of either Variable or In instances, but not sharedvariables.) – the returned Function instance will haveparameters for these variables.
  • outputs (list of Variables or Out instances) – expressions to compute.
  • mode (None, string or Mode instance.) – compilation mode
  • updates (iterable over pairs (sharedvariable, newexpression)List, tuple or __dict.) – expressions for new SharedVariable values
  • givens (iterable over pairs (Var1, Var2) of Variables.List, tuple or dict. The Var1and Var2 in each pair must have the same Type.) – specific substitutions to make in thecomputation graph (Var2 replaces Var1).
  • no_default_updates (either bool or list of Variables) – if True, do not perform any automatic update on Variables.If False (default), perform them all.Else, perform automatic updates on all Variables that areneither in updates nor in no_default_updates.
  • name – an optional name for this function.The profile mode will print the time spent in this function.
  • rebuild_strict – True (Default) is the safer and bettertested setting, in which case givens must substitute newvariables with the same Type as the variables they replace.False is a you-better-know-what-you-are-doing setting, thatpermits givens to replace variables with new variables ofany Type. The consequence of changing a Type is that allresults depending on that variable may have a different Typetoo (the graph is rebuilt from inputs to outputs). If one ofthe new types does not make sense for one of the Ops in thegraph, an Exception will be raised.
  • allow_input_downcast (Boolean or None) – True means that the values passed asinputs when calling the function can be silently downcasted tofit the dtype of the corresponding Variable, which may loseprecision. False means that it will only be cast to a moregeneral, or precise, type. None (default) is almost likeFalse, but allows downcasting of Python float scalars tofloatX.
  • profile (None, True, or ProfileStats instance) – accumulate profiling information into a givenProfileStats instance. If argument is True then a newProfileStats instance will be used. This profiling objectwill be available via self.profile.
  • on_unused_input – What to do if a variable in the ‘inputs’list is not used in the graph. Possible values are ‘raise’,‘warn’, and ‘ignore’.Return type: Functioninstance 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 In instances.In instances also have a variable, but they attach some extrainformation about how call-time arguments corresponding to that variableshould be used. Similarly, Out instances can attach informationabout how output variables should be returned.

The default is typically ‘FAST_RUN’ but this can be changed intheano.config. The modeargument controls the sort of optimizations that will be applied to thegraph, and the way the optimized graph will be evaluated.

After each function evaluation, the updates mechanism can replace thevalue of any SharedVariable [implicit] inputs with new values computedfrom the expressions in the updates list. An exception will be raisedif you give two update expressions for the same SharedVariable input (thatdoesn’t make sense).

If a SharedVariable is not given an update expression, but has adefault_update member containing an expression, this expressionwill be used as the update expression for this variable. Passingno_default_updates=True to function disables this behaviorentirely, passing no_default_updates=[sharedvar1, sharedvar2]disables it for the mentioned variables.

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

  • theano.compile.function.functiondump(_filename, inputs, outputs=None, mode=None, updates=None, givens=None, no_default_updates=False, accept_inplace=False, name=None, rebuild_strict=True, allow_input_downcast=None, profile=None, on_unused_input=None, extra_tag_to_remove=None)[source]
  • This is helpful to make a reproducible case for problems during Theanocompilation.

Ex:

replace theano.function(…) bytheano.function_dump(‘filename.pkl’, …).

If you see this, you were probably asked to use this function tohelp debug a particular case during the compilation of a Theanofunction. function_dump allows you to easily reproduce yourcompilation without generating any code. It pickles all the objects andparameters needed to reproduce a call to theano.function(). Thisincludes shared variables and their values. If you do not wantthat, you can choose to replace shared variables values with zeros bycalling setvalue(…) on them before calling _function_dump.

To load such a dump and do the compilation:

  1. >>> from six.moves import cPickle
  2. >>> import theano
  3. >>> d = cPickle.load(open("func_dump.bin", "rb"))  
  4. >>> f = theano.function(**d)

Note:The parameter extra_tag_to_remove is passed to the StripPickler used.To pickle graph made by Blocks, it must be:[‘annotations’, ‘replacement_of’, ‘aggregation_scheme’, ‘roles’]

  • class theano.compile.functionmodule.Function(_fn, input_storage, output_storage, indices, outputs, defaults, unpack_single, return_none, output_keys, maker, name=None)[source]
  • Type of the functions returned by theano.function ortheano.FunctionMaker.create.

Function is the callable object that does computation. It has the storageof inputs and outputs, performs the packing and unpacking of inputs andreturn values. It implements the square-bracket indexing so that you canlook up the value of a symbolic node.

Functions are copyable via {{{fn.copy()}}} and {{{copy.copy(fn)}}}.When a function is copied, this instance is duplicated. Contrast withself.maker (instance of FunctionMaker) that is shared between copies.The meaning of copying a function is that the containers and their currentvalues will all be duplicated. This requires that mutable inputs becopied, whereas immutable inputs may be shared between copies.

A Function instance is hashable, on the basis of its memoryaddress (its id).

A Function instance is only equal to itself.

A Function instance may be serialized using the pickle orcPickle modules. This will save all default inputs, the graph,and WRITEME to the pickle file.

A Function instance have a trust_input field that default toFalse. When True, we don’t do extra check of the input to givebetter error message. In some case, python code will still returnthe good results if you pass a python or numpy scalar instead of anumpy tensor. C code should raise an error if you pass an objectof the wrong type.

Parameters:

  1. - **args** (_list_) – List of inputs to the function. All inputs are required, even whensome of them are not necessary to calculate requested subset ofoutputs.
  2. - **kwargs** (_dict_) –

The function inputs can be passed as keyword argument. For this, usethe name of the input or the input instance as the key.

Keyword argument outputsubset is a list of either indices of thefunction’s outputs or the keys belonging to the _output_keys dictand represent outputs that are requested to be calculated. Regardlessof the presence of output_subset, the updates are always calculatedand processed. To disable the updates, you should use the copymethod with delete_updates=True. Returns: List of outputs on indices/keys from output_subset or all of them,if output_subset is not passed. Return type: list

  • copy(share_memory=False, swap=None, delete_updates=False, name=None, profile=None)[source]
  • Copy this function. Copied function will have separated maker andfgraph with original function. User can choose whether to separatestorage by changing the share_memory arguments.

Parameters:

  1. - **share_memory** (_boolean_) – When True, two function share intermediate storages(storages except input andoutput storages). Otherwise two functions will only share partialstorages and same maker. If two functions share memory andallow_gc=False, this will increase executing speed and save memory.
  2. - **swap** (_dict_) – Dictionary that map old SharedVariables to newSharedVariables. Default is None.NOTE: The shared variable swap in only done in the new returnedfunction, not in the user graph.
  3. - **delete_updates** (_boolean_) – If True, Copied function will not have updates.
  4. - **name** (_string_) – If provided, will be the name of the newFunction. Otherwise, it will be old + ” copy”
  5. - **profile** – as theano.function profile parameterReturns:

Copied theano.Function Return type: theano.Function

  • free()[source]
  • When allow_gc = False, clear the Variables in storage_map