changes to basic_tutorial/module.txt: removed Member, External; add second method to example

doc/basic_tutorial/module.txt

@@ -17,22 +17,26 @@ Let's use Module to re-implement :ref:`the example using state
 <functionstateexample>`.
 
 >>> m = Module()
->>> m.state = Member(T.dscalar())
->>> m.inc = External(T.dscalar())
+>>> m.state = T.dscalar()
+>>> m.inc = T.dscalar('inc')
 >>> m.new_state = m.state + m.inc
->>> m.call = Method(m.inc, m.new_state, {m.state: m.new_state})
+>>> m.add = Method(m.inc, m.new_state, {m.state: m.new_state})
+>>> m.sub = Method(m.inc, None, {m.state: m.state - m.inc})
 >>> acc = m.make(state = 0)
->>> acc.state
-array(0.0)
->>> acc.call(2)
-array(2.0)
->>> acc.state
+>>> acc.state, acc.inc
+array(0.0), None
+>>> acc.add(2)
 array(2.0)
+>>> acc.state, acc.inc
+array(2.0), None
 >>> acc.state = 39.99
->>> acc.call(0.01)
+>>> acc.add(0.01)
 array(40.0)
 >>> acc.state
 array(40.0)
+>>> acc.sub(20)
+>>> acc.state
+array(20.0)
 
 This deserves to be broken up a bit...
 
@@ -42,7 +46,7 @@ This deserves to be broken up a bit...
 Here we instantiate an empty Module.
 
 
->>> m.state = Member(T.dscalar())
+>>> m.state = T.dscalar()
 
 Then we declare a Variable for use with our Module. That Variable will
 be a :ref:`member` of the Module, which means that it will be
@@ -56,91 +60,90 @@ defined in our Module.
    be given the name 'state' automatically.
 
 
->>> m.inc = External(T.dscalar('inc'))
+>>> m.inc = T.dscalar('inc')
 
-The ``inc`` variable doesn't need to be declared as a Member because it
-will only serve as an input to the method we will define. This is why
-it is defined as an :ref:`external` variable. Do note that it is
-inconsequential if you do declare it as a Member - it is unlikely
-to cause you any problems.
+The ``inc`` variable doesn't need to be declared as a member of ``m`` because
+we only use it as a Method input.  
 
 .. note::
-
-   Both Member and External are optional. If you do the direct assignment:
-
-   >>> m.state = T.dscalar()
-
-   The default is to declare m.state as a Member. This is a sensible
-   default in most situations and can avoid clutter, so feel free to
-   omit explicit calls to Member.
+ 
+  Since we made it a member of ``m``, the ``acc`` object will have an
+  attribute called ``inc``.  This attribute will keep its default value of
+  None throughout the example.
 
 
 >>> m.new_state = m.state + m.inc
 
-This line describes how to compute the new state.
-
-.. note::
-
-   Here new_state is implicitly declared as External since it is
-   illegal to declare a Variable as a Member if it is the variable of
-   previous computations.
+This line creates a Variable corresponding to some symbolic computation.  It
+doesn't matter to Theano whether we put it inside ``m`` or not.  Feel free to
+put such results of symbolic computation wherever is most convenient.
 
 
->>> m.call = Method(m.inc, m.new_state, {m.state: m.new_state})
+>>> m.add = Method(m.inc, m.new_state, {m.state: m.new_state})
 
 Here we declare a Method. The three arguments are as follow:
 
 * **inputs**: a list of input Variables
 * **outputs**: a list of output Variables
-* **updates**: a dictionary mapping a Variable declared as a Member to a
-  Variable representing the computation of the next state of the member.
-
-If possible, you may also give the updates as keyword arguments, as
-in: ``Method(m.inc, m.new_state, state = m.new_state)``. This implies
-that m.state's name is 'state'.
-
+* **updates**: a dictionary mapping member Variables to Variables.  When we
+  call the function that this Method compiles to, it will replace (update) the
+  values associated with the member Variables.
 
 >>> acc = m.make(state = 0)
 
-This line is what does the magic. Everything in m is symbolic. Once
-the make method is called on it, an object is made which can do real
-computation and whose fields contain real values.
+This line is what does the magic (well, compilation).
+The ``m`` object contains symbolic things such as Variables and Methods. 
+Calling ``make`` on ``m`` creates an object that can do real
+computation and whose attributes contain values such as numbers and numpy
+ndarrays.
 
 The keyword arguments given to make are optional and are used to
 assign initial values to each Member. If a Member is omitted, the
 initial value is None.
 
 
->>> acc.state
-array(0.0)
+>>> acc.state, acc.inc
+array(0.0), None
 
 Since state was declared as a Member, we can access it easily using
 '.state'.
 
-
->>> acc.call(2)
+.. note::
+  
+  Members can also be accessed using a dictionary-like notation.  The syntax
+  ``acc.value[m.state]`` is equivalent to ``acc[m.state]``, and in this case,
+  ``acc.state``.  The dictionary-like syntax works for member Variables that
+  appear inside sub-modules, lists, dictionaries, and for whatever reason have
+  no name.
+
+>>> acc.add(2)
 array(2.0)
 >>> acc.state
 array(2.0)
->>> acc.call(6)
-array(8.0)
->>> acc.state
-array(8.0)
 
-When we call the ``call`` method, all the updates given to the
+When we call the ``acc.add`` method, all the updates given to the
 corresponding Method's ``updates`` field are performed. We only had
 one update which mapped ``state`` to ``new_state`` and you can see
-that it works as intended, adding the argument to the internal state
-every time.
+that it works as intended, adding the argument to the internal state.
 
 
 >>> acc.state = 39.99
+
+The state is also easy to set.  When we manually set the value of a member
+attribute like this, then subsequent calls to the methods of our module will
+use the new value.
+
 >>> acc.call(0.01)
 array(40.0)
 >>> acc.state
 array(40.0)
+>>> acc.sub(20)
+>>> acc.state
+array(20.0)
+
+Here, note that ``acc.add`` and ``acc.sub`` share access to the same ``state``
+value but update it in different ways.
 
-The state is also easy to set.
 
 
 Using Inheritance
@@ -156,12 +159,15 @@ subclass of Module:
 
        def __init__(self):
            super(Accumulator, self).__init__() # don't forget this
-           self.inc = External(T.dscalar())
-           self.state = Member(T.dscalar())
+           self.inc = T.dscalar()
+           self.state = T.dscalar()
            self.new_state = self.inc + self.state
-           self.call = Method(inputs = self.inc,
-                              outputs = self.new_state,
-                              updates = {self.state: self.new_state})
+           self.add = Method(inputs = self.inc,
+                             outputs = self.new_state,
+                             updates = {self.state: self.new_state})
+           self.sub = Method(inputs = self.inc,
+                             outputs = None,
+                             updates = {self.state: self.state - self.inc})
 
    m = Accumulator()
    acc = m.make(state = 0)
@@ -190,12 +196,15 @@ give a method called ``_instance_print_state`` to our Module.
 
        def __init__(self):
            super(Accumulator, self).__init__() # don't forget this
-           self.inc = External(T.dscalar())
-           self.state = Member(T.dscalar())
+           self.inc = T.dscalar()
+           self.state = T.dscalar()
            self.new_state = self.inc + self.state
-           self.call = Method(inputs = self.inc,
-                              outputs = self.new_state,
-                              updates = {self.state: self.new_state})
+           self.add = Method(inputs = self.inc,
+                             outputs = self.new_state,
+                             updates = {self.state: self.new_state})
+           self.sub = Method(inputs = self.inc,
+                             outputs = None,
+                             updates = {self.state: self.state - self.inc})
 
        def _instance_print_state(self, acc):
            print '%s is: %s' % (self.state, acc.state)
@@ -239,12 +248,15 @@ initialize a state with a matrix of zeros:
 
        def __init__(self):
            super(MatrixAccumulator, self).__init__() # don't forget this
-           self.inc = External(T.dscalar())
-           self.state = Member(T.dmatrix())
+           self.inc = T.dscalar()
+           self.state = T.dmatrix()
            self.new_state = self.inc + self.state
-           self.call = Method(inputs = self.inc,
-                              outputs = self.new_state,
-                              updates = {self.state: self.new_state})
+           self.add = Method(inputs = self.inc,
+                             outputs = self.new_state,
+                             updates = {self.state: self.new_state})
+           self.sub = Method(inputs = self.inc,
+                             outputs = None,
+                             updates = {self.state: self.state - self.inc})
 
        def _instance_print_state(self, acc):
            print '%s is: %s' % (self.state, acc.state)