Split Josh's documentation between aliasing.txt and…

doc/tutorial/aliasing.txt

@@ -182,29 +182,29 @@ This pattern works regardless of the compute device, and when the compute device
 makes it possible to expose Theano's internal variables without a copy, then it
 goes as fast as an in-place update.
 
-Prior to Theano 0.3.1, set_value did not work in-place on the GPU. This meant that sometimes,
-GPU memory for the new value would be allocated before the old memory was released. If you're
-running near the limits of GPU memory, this could cause you to run out of GPU memory.
-
-Beginning with Theano 0.3.1, set_value will work in-place on the GPU, if the following conditions
-are met:
-
-* The destination on the GPU must be c_contiguous.
-* The old value must have the same dtype as the new value (which is a given for now,
-  since only float32 is supported).
-* The old and new value must have the same shape.
-* The old value is being completely replaced by the new value (not partially modified,
-  e.g. by replacing some subtensor of it).
-* You change the value of the shared variable via set_value, not via the .value
-  accessors. You should not use the .value accessors anyway, since they will soon be
-  deprecated and removed.
-
-Fortunately, these conditions are usually straightforwardly met without any additional effort.
-If you are going to swap several chunks of data in and out of a shared variable repeatedly,
-it is worth padding your source data to make sure that every chunk is the same size.
-
-It is also worth mentioning that, for efficient transfer to the GPU, theano will make the new data
-c_contiguous. This could mean making a copy of the data on the host.
+
+When shared variables are allocated on the GPU, the transfers to and from GPU device memory can
+be costly.  Here are a few tips to ensure fast and efficient use of GPU memory and bandwidth:
+
+* Prior to Theano 0.3.1, set_value did not work in-place on the GPU. This meant that sometimes,
+  GPU memory for the new value would be allocated before the old memory was released. If you're
+  running near the limits of GPU memory, this could cause you to run out of GPU memory
+  unnecessarily.  *Solution*: update to a newer version of Theano.
+
+* If you are going to swap several chunks of data in and out of a shared variable repeatedly,
+  you will want to reuse the memory that you allocated the first time if possible - it is both
+  faster and more memory efficient.
+  *Solution*: upgrade to a recent version of Theano (>0.3.0) and consider padding your source
+  data to make sure that every chunk is the same size.
+
+* It is also worth mentioning that, current GPU copying routines support only contiguous memory.
+  So Theano must make the ``value`` you provide ``c_contiguous`` prior to copying it.
+  This can require an extra copy of the data on the host.  *Solution*: make sure that the value
+  you assign to a CudaNdarraySharedVariable is *already*  ``c_contiguous``.
+
+(Further remarks on the current implementation of the GPU version of set_value() can be found
+here: :ref:`libdoc_cuda_var`)
+
 
 Retrieving and assigning via the .value property
 ------------------------------------------------

theano/sandbox/cuda/var.py

@@ -82,6 +82,34 @@ class CudaNdarraySharedVariable(SharedVariable, _operators):
             return numpy.asarray(self.container.value)
 
     def set_value(self, value, borrow=False):
+        """
+        Assign `value` to the GPU-allocated array.
+
+        :param borrow: ``True`` permits reusing `value` itself, ``False`` requires that this function
+                       copies `value` into internal storage.
+
+        :note:
+
+            Prior to Theano 0.3.1, set_value did not work in-place on the GPU. This meant that sometimes,
+            GPU memory for the new value would be allocated before the old memory was released. If you're
+            running near the limits of GPU memory, this could cause you to run out of GPU memory.
+
+            Beginning with Theano 0.3.1, set_value will work in-place on the GPU, if the following conditions
+            are met:
+
+            * The destination on the GPU must be c_contiguous.
+            * The old value must have the same dtype as the new value (which is a given for now,
+              since only float32 is supported).
+            * The old and new value must have the same shape.
+            * The old value is being completely replaced by the new value (not partially modified,
+              e.g. by replacing some subtensor of it).
+            * You change the value of the shared variable via set_value, not via the .value
+              accessors. You should not use the .value accessors anyway, since they will soon be
+              deprecated and removed.
+            
+            It is also worth mentioning that, for efficient transfer to the GPU, Theano will make the new data
+            ``c_contiguous``. This can require an extra copy of the data on the host.
+        """
         if not borrow:
             #TODO: check for cuda_ndarray type
             if not isinstance(value, numpy.ndarray):