Merge pull request #3890 from mohammadpz/remove_param_class

doc/library/compile/function.txt

@@ -27,30 +27,13 @@ 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 as
-:class:`Param`, ``mode``, ``updates``, and ``givens``.  These are covered
+:class:`In`, :class:`Out`, ``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
+.. class:: In
 
     A class for attaching information to function inputs.
 
@@ -58,36 +41,74 @@ Reference
 
         A variable in an expression graph to use as a compiled-function parameter
 
-    .. attribute:: default
+    .. attribute:: name
+
+        A string to identify an argument for this parameter in keyword arguments.
+
+    .. attribute:: value
 
         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
+    .. attribute:: update
 
-        A string to identify an argument for this parameter in keyword arguments.
+        An expression which indicates updates to the Value after each function call.
 
     .. attribute:: mutable
 
         ``True`` means the compiled-function is allowed to modify this
         argument. ``False`` means it is not allowed.
 
+    .. 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.
+
     .. 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)
+    .. attribute:: allow_downcast
+
+        ``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``.)
+
+    .. attribute:: autoname
+
+        ``True`` means that the `name` is set to variable.name.
+
+    .. attribute:: implicit
+
+        ``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.
+
+    .. method:: __init__(self, variable, name=None, value=None, update=None, mutable=None, strict=False, allow_downcast=None, autoname=True, implicit=None, borrow=None, shared=False)
+
+        Initialize attributes from arguments.
+
+.. class:: Out
+
+    A class for attaching information to function outputs
 
-        Initialize object attributes.
+    .. 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.
 
 
 .. 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')
 
     Return a :class:`callable object <theano.compile.function_module.Function>` that will calculate `outputs` from `inputs`.
 
-    :type params: list of either Variable or Param instances, but not shared
+    :type params: list of either Variable or In instances, but not shared
         variables.
 
     :param params: the returned :class:`Function` instance will have
@@ -159,8 +180,8 @@ Reference
       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
+    Inputs can be given as variables or In instances.
+    :class:`In` 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.

doc/library/index.txt

@@ -47,9 +47,9 @@ There are also some top-level imports that you might find more convenient:
     
     Alias for :func:`theano.compile.sharedvalue.shared`
 
-.. class:: Param
+.. class:: In
 
-    Alias for :class:`function.Param`
+    Alias for :class:`function.In`
 
 .. function:: dot(x, y)
 

doc/proposals/pfunc.txt

@@ -18,8 +18,6 @@ The strategy is to
 - introduce a new kind of ``Variable`` (``SharedVariable``) that has a container
   associated with it, and can allow multiple functions to share a value.
 
-- introduce a class called ``Param`` to serve a role similar to that of ``In``,
-
 - introduce a friendlier version of function (tentative name ``pfunc``),
 
 The following code gives a very quick idea of what is being proposed:
@@ -30,7 +28,7 @@ The following code gives a very quick idea of what is being proposed:
     b = shared(1) #NEW: create a shared variable
 
     f1 = pfunc([a], a+b)
-    f2 = pfunc([Param(a, default=44)], a + b, updates={b: b + 1})
+    f2 = pfunc([In(a, value=44)], a + b, updates={b: b + 1})
 
     b.value # -> 1
 
@@ -140,10 +138,10 @@ prone to easy mistakes (e.g. accidentally overwriting the content of a shared
 variable).
 
 
-Param and pfunc
-===============
+pfunc
+=====
 
-The examples above give the general flavour of what pfunc and Param are for.
+The examples above give the general flavour of what pfunc is for.
 Their signatures are below.
 Corner cases and exotic examples can be found in the tests.
 
@@ -152,7 +150,7 @@ Corner cases and exotic examples can be found in the tests.
     def pfunc(params, outputs, mode=None, givens=None, updates=None)
         """Function-constructor for graphs with shared variables.
 
-        :type params: list of either Variable or Param instances.
+        :type params: list of either Variable or In instances.
         :param params: function parameters, these are not allowed to be shared
         variables
 
@@ -171,27 +169,6 @@ Corner cases and exotic examples can be found in the tests.
         """
         ...
 
-.. code-block:: python
-
-    class Param(object):
-        def __init__(self, variable, default=None, mutable=False, strict=False):
-            """
-            :param variable: A node in an expression graph to set with each function call.
-
-            :param default: The default value to use at call-time (can also be a Container where
-            the function will find a value at call-time.)
-
-            :param name: A string to identify this parameter from function kwargs.
-
-            :param mutable: True -> function is allowed to modify this argument.
-
-            :param strict: False -> function arguments may be copied or cast to match the
-            type required by the parameter `variable`.  True -> function arguments must exactly match the type
-            required by `variable`.
-
-            :param implicit: see help(theano.io.In)
-
-            """
 
 Note that if some update value is not a variable, it will be cast into
 a ``SharedVariable`` using the ``shared`` function. This ensures it is

doc/tutorial/examples.txt

@@ -112,19 +112,19 @@ one. You can do it like this:
 .. If you modify this code, also change :
 .. theano/tests/test_tutorial.py:T_examples.test_examples_6
 
->>> from theano import Param
+>>> from theano import In
 >>> from theano import function
 >>> x, y = T.dscalars('x', 'y')
 >>> z = x + y
->>> f = function([x, Param(y, default=1)], z)
+>>> f = function([x, In(y, default=1)], z)
 >>> f(33)
 array(34.0)
 >>> f(33, 2)
 array(35.0)
 
-This makes use of the :ref:`Param <function_inputs>` class which allows
+This makes use of the :ref:`In <function_inputs>` class which allows
 you to specify properties of your function's parameters with greater detail. Here we
-give a default value of 1 for *y* by creating a ``Param`` instance with
+give a default value of 1 for *y* by creating a ``In`` instance with
 its ``default`` field set to 1.
 
 Inputs with default values must follow inputs without default
@@ -137,7 +137,7 @@ be set positionally or by name, as in standard Python:
 
 >>> x, y, w = T.dscalars('x', 'y', 'w')
 >>> z = (x + y) * w
->>> f = function([x, Param(y, default=1), Param(w, default=2, name='w_by_name')], z)
+>>> f = function([x, In(y, default=1), In(w, default=2, name='w_by_name')], z)
 >>> f(33)
 array(68.0)
 >>> f(33, 2)
@@ -150,11 +150,11 @@ array(34.0)
 array(33.0)
 
 .. note::
-   ``Param`` does not know the name of the local variables *y* and *w*
+   ``In`` does not know the name of the local variables *y* and *w*
    that are passed as arguments.  The symbolic variable objects have name
    attributes (set by ``dscalars`` in the example above) and *these* are the
    names of the keyword parameters in the functions that we build.  This is
-   the mechanism at work in ``Param(y, default=1)``.  In the case of ``Param(w,
+   the mechanism at work in ``In(y, default=1)``.  In the case of ``In(w,
    default=2, name='w_by_name')``. We override the symbolic variable's name
    attribute with a name to be used for this function.
 

theano/__init__.py

@@ -67,7 +67,7 @@ from theano.compile import (
     predefined_modes, predefined_linkers, predefined_optimizers,
     FunctionMaker, function, function_dump, OpFromGraph,
     ProfileMode, ProfileStats,
-    Param, shared, as_op)
+    shared, as_op)
 
 from theano.misc.safe_asarray import _asarray
 

theano/compile/__init__.py

@@ -22,7 +22,7 @@ from theano.compile.profilemode import ProfileMode
 
 from theano.compile.sharedvalue import (shared, shared_constructor,
                                         SharedVariable)
-from theano.compile.pfunc import pfunc, Param, rebuild_collect_shared
+from theano.compile.pfunc import pfunc, rebuild_collect_shared
 
 from theano.compile.builders import *
 

theano/compile/function.py

@@ -79,7 +79,7 @@ def function(inputs, outputs=None, mode=None, updates=None, givens=None,
 
     Parameters
     ----------
-    inputs : list of either Variable or Param instances.
+    inputs : list of either Variable or In instances.
         Function parameters, these are not allowed to be shared variables.
     outputs : list or dict of Variables or Out instances.
         If it is a dict, the keys must be strings. Expressions to compute.

theano/compile/pfunc.py

@@ -261,71 +261,6 @@ def rebuild_collect_shared(outputs,
             [clone_d, update_d, update_expr, shared_inputs])
 
 
-class Param(object):
-    """
-
-    Parameters
-    ----------
-    variable
-        A variable in an expression graph to use as a compiled-function
-        parameter.
-    default
-        The default value to use at call-time (can also be a Container where
-        the function will find a value at call-time).
-    name : str
-        A string to identify this parameter from function kwargs.
-    mutable : bool
-        True : function is allowed to modify this argument.
-    borrow
-        Whether the function is allowed to alias some output to this input.
-        Using None (default) means we re-use the same value as the `mutable`
-        flag. False: do not permit any output to be aliased to the input.
-    strict : bool
-        False : function arguments may be copied or cast to match the type
-        required by the parameter `variable`.
-        True : function arguments must exactly match the type required by
-        `variable`.
-    allow_downcast : bool or None
-        Only applies if `strict` is False.
-        True : allow assigned value to lose precision when cast during
-        assignment.
-        False : never allow precision loss.
-        None : only allow downcasting of a Python float to a scalar floatX.
-    implicit
-        See help(theano.io.In)
-
-    """
-
-    def __init__(self, variable, default=None, name=None, mutable=False,
-                 strict=False, allow_downcast=None, implicit=None,
-                 borrow=None):
-        self.variable = variable
-        self.default = default
-        self.name = name
-        self.mutable = mutable
-
-        if borrow is None:
-            self.borrow = self.mutable
-        else:
-            self.borrow = borrow
-
-        # mutable implies the output can be both aliased to the input and that
-        # the input can be destroyed. borrow simply implies the output can be
-        # aliased to the input. Thus mutable=True should require borrow=True.
-        if self.mutable and not self.borrow:
-            raise AssertionError(
-                "Symbolic input for variable %s (name=%s) has "
-                "flags mutable=True, borrow=False. This combination is "
-                "incompatible since mutable=True implies that the "
-                "input variable may be both aliased (borrow=True) and "
-                "overwritten.",
-                variable, name)
-
-        self.strict = strict
-        self.allow_downcast = allow_downcast
-        self.implicit = implicit
-
-
 def pfunc(params, outputs=None, mode=None, updates=None, givens=None,
           no_default_updates=False, accept_inplace=False, name=None,
           rebuild_strict=True, allow_input_downcast=None,
@@ -335,7 +270,7 @@ def pfunc(params, outputs=None, mode=None, updates=None, givens=None,
 
     Parameters
     ----------
-    params : list of either Variable or Param instances
+    params : list of either Variable or In instances
         Function parameters, these are not allowed to be shared variables.
     outputs : list of Variables or Out instances
         Expressions to compute.
@@ -531,16 +466,6 @@ def _pfunc_param_to_in(param, strict=False, allow_downcast=None):
         raise TypeError('Constants not allowed in param list', param)
     if isinstance(param, Variable):  # N.B. includes SharedVariable
         return In(variable=param, strict=strict, allow_downcast=allow_downcast)
-    elif isinstance(param, Param):
-        return In(
-            variable=param.variable,
-            name=param.name,
-            value=param.default,
-            mutable=param.mutable,
-            strict=param.strict,
-            borrow=param.borrow,
-            allow_downcast=param.allow_downcast,
-            implicit=param.implicit)
     elif isinstance(param, In):
         return param
     raise TypeError('Unknown parameter type: %s' % type(param))

theano/compile/tests/test_pfunc.py

@@ -7,6 +7,7 @@ import theano
 from theano.tensor import dmatrix, iscalar, lscalar, dmatrices
 from theano import tensor
 
+from theano.compile import In
 from theano.compile.sharedvalue import *
 from theano.compile.pfunc import *
 
@@ -25,7 +26,7 @@ class Test_pfunc(unittest.TestCase):
         a = lscalar()
         b = shared(1)
         f1 = pfunc([a], (a + b))
-        f2 = pfunc([Param(a, default=44)], a + b, updates={b: b + 1})
+        f2 = pfunc([In(a, value=44)], a + b, updates={b: b + 1})
         self.assertTrue(b.get_value() == 1)
         self.assertTrue(f1(3) == 4)
         self.assertTrue(f2(3) == 4)
@@ -112,13 +113,13 @@ class Test_pfunc(unittest.TestCase):
         b = shared(7)
         out = a + b
 
-        f = pfunc([Param(a, strict=False)], [out])
+        f = pfunc([In(a, strict=False)], [out])
         # works, rand generates float64 by default
         f(numpy.random.rand(8))
         # works, casting is allowed
         f(numpy.array([1, 2, 3, 4], dtype='int32'))
 
-        f = pfunc([Param(a, strict=True)], [out])
+        f = pfunc([In(a, strict=True)], [out])
         try:
             # fails, f expects float64
             f(numpy.array([1, 2, 3, 4], dtype='int32'))
@@ -130,14 +131,14 @@ class Test_pfunc(unittest.TestCase):
         a_out = a * 2  # assuming the op which makes this "in place" triggers
 
         # using mutable=True will let fip change the value in aval
-        fip = pfunc([Param(a, mutable=True)], [a_out], mode='FAST_RUN')
+        fip = pfunc([In(a, mutable=True)], [a_out], mode='FAST_RUN')
         aval = numpy.random.rand(10)
         aval2 = aval.copy()
         assert numpy.all(fip(aval) == (aval2 * 2))
         assert not numpy.all(aval == aval2)
 
         # using mutable=False should leave the input untouched
-        f = pfunc([Param(a, mutable=False)], [a_out], mode='FAST_RUN')
+        f = pfunc([In(a, mutable=False)], [a_out], mode='FAST_RUN')
         aval = numpy.random.rand(10)
         aval2 = aval.copy()
         assert numpy.all(f(aval) == (aval2 * 2))
@@ -182,9 +183,9 @@ class Test_pfunc(unittest.TestCase):
         a = tensor.wvector('a')  # int16
         b = tensor.bvector('b')  # int8
         c = tensor.bscalar('c')  # int8
-        f = pfunc([Param(a, allow_downcast=True),
-                   Param(b, allow_downcast=False),
-                   Param(c, allow_downcast=None)],
+        f = pfunc([In(a, allow_downcast=True),
+                   In(b, allow_downcast=False),
+                   In(c, allow_downcast=None)],
                   (a + b + c))
 
         # Both values are in range. Since they're not ndarrays (but lists),
@@ -211,9 +212,9 @@ class Test_pfunc(unittest.TestCase):
         b = tensor.fscalar('b')
         c = tensor.fscalar('c')
 
-        f = pfunc([Param(a, allow_downcast=True),
-                   Param(b, allow_downcast=False),
-                   Param(c, allow_downcast=None)],
+        f = pfunc([In(a, allow_downcast=True),
+                   In(b, allow_downcast=False),
+                   In(c, allow_downcast=None)],
                   (a + b + c))
 
         # If the values can be accurately represented, everything is OK
@@ -236,9 +237,9 @@ class Test_pfunc(unittest.TestCase):
         b = tensor.fvector('b')
         c = tensor.fvector('c')
 
-        f = pfunc([Param(a, allow_downcast=True),
-                   Param(b, allow_downcast=False),
-                   Param(c, allow_downcast=None)],
+        f = pfunc([In(a, allow_downcast=True),
+                   In(b, allow_downcast=False),
+                   In(c, allow_downcast=None)],
                   (a + b + c))
 
         # If the values can be accurately represented, everything is OK

theano/scan_module/scan_op.py

@@ -67,7 +67,7 @@ from six.moves import xrange
 
 import theano
 from theano.compat import exc_message
-from theano.compile import function, In, Param, Out
+from theano.compile import function, In, Out
 from theano.compile.mode import AddFeatureOptimizer
 from theano import compile, config, gradient, gof, tensor
 from theano.gof import PureOp, Apply
@@ -839,7 +839,7 @@ class Scan(PureOp):
             # tap as not being preallocated
             self.mitmots_preallocated = [False] * self.n_mit_mot_outs
 
-            wrapped_inputs = [Param(x, borrow=True) for x in
+            wrapped_inputs = [In(x, borrow=True) for x in
                               self.inputs]
             wrapped_outputs = [Out(x, borrow=False) for x in
                                self.outputs[:slices]]

theano/scan_module/tests/test_scan.py

@@ -897,9 +897,9 @@ class T_Scan(unittest.TestCase):
         u0 = theano.tensor.vector('u0')
         u1 = theano.tensor.vector('u1')
         u2 = theano.tensor.vector('u2')
-        mu0 = theano.Param(u0, mutable=False)
-        mu1 = theano.Param(u1, mutable=True)
-        mu2 = theano.Param(u2, mutable=True)
+        mu0 = theano.In(u0, mutable=False)
+        mu1 = theano.In(u1, mutable=True)
+        mu2 = theano.In(u2, mutable=True)
         x0 = theano.tensor.scalar('x0')
         x1 = theano.tensor.scalar('y0')
         W_in = theano.shared(vW_in, 'Win')
@@ -961,9 +961,9 @@ class T_Scan(unittest.TestCase):
         u0 = theano.tensor.vector('u0')
         u1 = theano.tensor.vector('u1')
         u2 = theano.tensor.vector('u2')
-        mu0 = theano.Param(u0, mutable=True)
-        mu1 = theano.Param(u1, mutable=True)
-        mu2 = theano.Param(u2, mutable=True)
+        mu0 = theano.In(u0, mutable=True)
+        mu1 = theano.In(u1, mutable=True)
+        mu2 = theano.In(u2, mutable=True)
         x0 = theano.tensor.scalar('x0')
         x1 = theano.tensor.scalar('y0')
         W_in = theano.shared(vW_in, 'Win')

theano/tensor/opt.py

@@ -886,7 +886,7 @@ class ShapeFeature(object):
     just for the ConvOp.  All that's necessary to do shape
     inference is 1) to mark shared inputs as having a particular
     shape, either via a .tag or some similar hacking; and 2) to
-    add an optional Param() argument to promise that inputs will
+    add an optional In() argument to promise that inputs will
     have a certain shape (or even to have certain shapes in
     certain dimensions). We can't automatically infer the shape of
     shared variables as they can change of shape during the

theano/tensor/tests/test_blas.py

@@ -12,7 +12,7 @@ from six.moves import xrange
 
 import theano
 import theano.tensor as T
-from theano import tensor, Param, shared, config
+from theano import tensor, In, shared, config
 from theano.compat import exc_message
 from theano.printing import pp
 from theano.tensor.blas import (_dot22, _dot22scalar, res_is_a, _as_scalar,
@@ -457,7 +457,7 @@ def just_gemm(i, o, ishapes=[(4, 3), (3, 5), (4, 5), (), ()],
               max_graphlen=0, expected_nb_gemm=1):
     try:
         f = inplace_func(
-                [Param(ii, mutable=True, allow_downcast=True) for ii in i],
+                [In(ii, mutable=True, allow_downcast=True) for ii in i],
                 o,
                 mode='FAST_RUN',
                 on_unused_input='ignore')
@@ -543,7 +543,7 @@ def test_gemm_opt_double_gemm():
     o = [(a * T.dot(X, Y)
         + gemm_inplace(Z, b, S.T, R.T, T.constant(1.0).astype(config.floatX)))]
     try:
-        f = inplace_func([Param(ii, mutable=True) for ii in i], o,
+        f = inplace_func([In(ii, mutable=True) for ii in i], o,
                 mode='FAST_RUN', on_unused_input='ignore')
         for node in f.maker.fgraph.apply_nodes:
             if isinstance(node.op, T.Dot):