Merge pull request #28 from abergeron/doc_fix

doc/library/sparse/index.txt

@@ -11,20 +11,20 @@ In the tutorial section, you can find a :ref:`sparse tutorial
 The sparse submodule is not loaded when we import Theano. You must
 import ``theano.sparse`` to enable it.
 
-The sparse module provide the same functionalities as the tensor
-module. The difference lies under the cover because sparse matrices
-does not store data in a contiguous array. Note that there are no GPU
-implementations for sparse matrices implemented in Theano. The sparse
-module has been used in:
+The sparse module provides the same functionality as the tensor
+module. The difference lies under the covers because sparse matrices
+do not store data in a contiguous array. Note that there are no GPU
+implementations for sparse matrices in Theano. The sparse module has
+been used in:
 
 - NLP: Dense linear transformations of sparse vectors.
-- Audio: Filterbank in Fourier domain.
+- Audio: Filterbank in the Fourier domain.
 
 Compressed Sparse Format
 ========================
 
-This section tries to explain how information is store for the two
-sparse formats of SciPy supported by Theano. There is more formats
+This section tries to explain how information is stored for the two
+sparse formats of SciPy supported by Theano. There are more formats
 that can be used with SciPy and some documentation about them may be
 found `here
 <http://deeplearning.net/software/theano/sandbox/sparse.html>`_.
@@ -50,14 +50,14 @@ attributes: ``data``, ``indices``, ``indptr`` and ``shape``.
 CSC Matrix
 ----------
 
-In the *Compressed Sparse Column* format, ``indices`` stands for index
-inside the column vectors of the matrix and ``indptr`` tells where the
-column starts in the ``data`` and in the ``indices``
-attributes. ``indptr`` can be tought as giving the slice which must be
-applied to the other attribute in order to get each column of the
-matrix. In other words, ``slice(indptr[i], indptr[i+1])`` correspond
-to the slice needed to find the i-th column of the matrix in the
-``data`` and in the ``indices`` fields.
+In the *Compressed Sparse Column* format, ``indices`` stands for
+indexes inside the column vectors of the matrix and ``indptr`` tells
+where the column starts in the ``data`` and in the ``indices``
+attributes. ``indptr`` can be thought of as giving the slice which
+must be applied to the other attribute in order to get each column of
+the matrix. In other words, ``slice(indptr[i], indptr[i+1])``
+corresponds to the slice needed to find the i-th column of the matrix
+in the ``data`` and ``indices`` fields.
 
 The following example builds a matrix and returns its columns. It
 prints the i-th column, i.e. a list of indices in the column and their
@@ -84,18 +84,18 @@ corresponding value in the second list.
 CSR Matrix
 ----------
 
-In the *Compressed Sparse Row* format, ``indices`` stands for index
+In the *Compressed Sparse Row* format, ``indices`` stands for indexes
 inside the row vectors of the matrix and ``indptr`` tells where the
 row starts in the ``data`` and in the ``indices``
-attributes. ``indptr`` can be tought as giving the slice which must be
-applied to the other attribute in order to get each row of the
-matrix. In other words, ``slice(indptr[i], indptr[i+1])`` correspond
+attributes. ``indptr`` can be thought of as giving the slice which
+must be applied to the other attribute in order to get each row of the
+matrix. In other words, ``slice(indptr[i], indptr[i+1])`` corresponds
 to the slice needed to find the i-th row of the matrix in the ``data``
-and in the ``indices`` fields.
+and ``indices`` fields.
 
 The following example builds a matrix and returns its rows. It prints
-the i-th row, i.e. a list of indices in the row and their corresponding value
-in the second list.
+the i-th row, i.e. a list of indices in the row and their
+corresponding value in the second list.
 
 >>> data = np.asarray([7, 8, 9])
 >>> indices = np.asarray([0, 1, 2])
@@ -120,7 +120,7 @@ List of Implemented Operations
 
 - Moving from and to sparse
     - :class:`DenseFromSparse <theano.sparse.basic.DenseFromSparse>` and ``dense_from_sparse``.
-      Both grad are implemented. Structured by default.
+      Both grads are implemented. Structured by default.
     - :class:`SparseFromDense <theano.sparse.basic.SparseFromDense>` and ``csr_from_dense``, ``csc_from_dense``.
       The grad implemented is structured.
     - Theano SparseVariable object have a method ``toarray()`` that is the same as ``dense_from_sparse``.
@@ -201,16 +201,17 @@ List of Implemented Operations
         - One of the inputs must be sparse, the other sparse or dense.
         - The grad implemented is regular.
         - No C code for perform and no C code for grad.
-        - Return a dense for perform and a dense for grad.
+        - Returns a dense for perform and a dense for grad.
     - :class:`StructuredDot <theano.sparse.basic.StructuredDot>`
       and :func:`structured_dot <theano.sparse.basic.structured_dot>`.
 
         - The first input is sparse, the second can be sparse or dense.
         - The grad implemented is structured.
         - C code for perform and grad.
-        - Return for perform a sparse if both inputs are sparse and
-          dense if one of them is dense.
-        - Return a sparse grad for sparse inputs and dense grad for
+        - When not using C code, it returns a sparse output if both
+          inputs are sparse and dense one if one of the inputs is
+          dense.
+        - Returns a sparse grad for sparse inputs and dense grad for
           dense inputs.
     - :class:`TrueDot <theano.sparse.basic.TrueDot>` and
       :func:`true_dot <theano.sparse.basic.true_dot>`.
@@ -218,39 +219,38 @@ List of Implemented Operations
         - The first input is sparse, the second can be sparse or dense.
         - The grad implemented is regular.
         - No C code for perform and no C code for grad.
-        - Return a Sparse for perform.
-        - Return a Sparse for grad for sparse inputs and by default a
-          dense for dense inputs. The parameter
+        - Returns a Sparse.
+        - The gradient returns a Sparse for sparse inputs and by
+          default a dense for dense inputs. The parameter
           ``grad_preserves_dense`` can be set to False to return a
           sparse grad for dense inputs.
     - :class:`SamplingDot <theano.sparse.basic.SamplingDot>` and
       ``sampling_dot``.
 
-        - Both input must be dense.
+        - Both inputs must be dense.
         - The grad implemented is structured for `p`.
         - Sample of the dot and sample of the gradient.
         - C code for perform but not for grad.
-        - Return sparse for perform and grad.
+        - Returns sparse for perform and grad.
     - :class:`Usmm <theano.sparse.basic.Usmm>` and ``usmm``.
 
         - You *shouldn't* insert this op yourself!
-           - There is optimization that transform a
+           - There is an optimization that transform a
              :class:`Dot <theano.sparse.basic.Dot>` to ``Usmm`` when possible.
 
         - This op is the equivalent of gemm for sparse dot.
-        - There is no grad implemented for this op and this is not needed as
-          you don't insert it yourself.
+        - There is no grad implemented for this op.
         - One of the inputs must be sparse, the other sparse or dense.
-        - Return a dense for perform
+        - Returns a dense from perform.
 
 - Slice Operations
-    - sparse_variable[N, N], return a tensor scalar.
+    - sparse_variable[N, N], returns a tensor scalar.
       There is no grad implemented for this operation.
-    - sparse_variable[M:N, O:P], return a sparse matrix
+    - sparse_variable[M:N, O:P], returns a sparse matrix
       There is no grad implemented for this operation.
-    - Sparse variable don't support [M, N:O] and [M:N, O] as we don't support sparse vector
-      and returning a sparse matrix would break the numpy interface.
-      Use [M:M+1, N:O] and [M:N, O:O+1] instead.
+    - Sparse variables don't support [M, N:O] and [M:N, O] as we don't
+      support sparse vectors and returning a sparse matrix would break
+      the numpy interface.  Use [M:M+1, N:O] and [M:N, O:O+1] instead.
     - :class:`Diag <theano.sparse.basic.Diag>` and ``diag``.
       The grad implemented is regular.
 

doc/library/tensor/raw_random.txt

@@ -22,132 +22,130 @@ Reference
     :class:`theano.tensor.shared_randomstreams.RandomStreams` subclass and the
     :class:`theano.tensor.randomstreams.RandomStreams` subclass.
 
-    .. method:: binomial(self, size=(), n=1, prob=0.5, ndim=None):
+    .. method:: binomial(self, size=(), n=1, p=0.5, ndim=None):
 
-        Sample n times with probability of success prob for each trial, return the number of
-        successes.
+        Sample ``n`` times with probability of success ``p`` for each
+        trial and return the number of successes.
 
-        If the size argument is ambiguous on the number of dimensions, the first argument may be a
-        plain integer to supplement the missing information.
+        If ``size`` is ambiguous on the number of dimensions, ``ndim``
+        may be a plain integer to supplement the missing information.
 
-	This wrap numpy implementation, so it have the same behavior.
+	This wraps the numpy implementation, so it has the same
+	behavior.
 
     .. method:: uniform(self,  size=(), low=0.0, high=1.0, ndim=None):
 
-        Sample a tensor of given size whose element from a uniform distribution between low and high.
+        Sample a tensor of the given size whose elements come from a
+        uniform distribution between low and high.
 
-        If the size argument is ambiguous on the number of
-        dimensions, the first argument may be a plain integer
-        to supplement the missing information.
+        If ``size`` is ambiguous on the number of dimensions, ``ndim``
+        may be a plain integer to supplement the missing information.
 
-	This wrap numpy implementation, so it have the same bound:
-	include the low bound, but exclude the high bound.
+	This wraps the numpy implementation, so it has the same
+        bounds: [``low``, ``high``\[.
 
     .. method:: normal(self, size=(), avg=0.0, std=1.0, ndim=None):
 
-        Usage: normal(random_state, size,
-        Sample from a normal distribution centered on avg with
-        the specified standard deviation (std)
+        Sample from a normal distribution centered on ``avg`` with the
+        specified standard deviation (``std``)
 
-        If the size argument is ambiguous on the number of
-        dimensions, the first argument may be a plain integer
-        to supplement the missing information.
+        If ``size`` is ambiguous on the number of dimensions, ``ndim``
+        may be a plain integer to supplement the missing information.
 
 	This wrap numpy implementation, so it have the same behavior.
 
     .. method:: random_integers(self, size=(), low=0, high=1, ndim=None):
 
-        Usage: random_integers(random_state, size, low=0, high=1)
         Sample a random integer between low and high, both inclusive.
 
-        If the size argument is ambiguous on the number of
-        dimensions, the first argument may be a plain integer
-        to supplement the missing information.
+        If ``size`` is ambiguous on the number of dimensions, ``ndim``
+        may be a plain integer to supplement the missing information.
 
-	This is a generalization of numpy.random.random_integers to
-        the case where low and high are tensors. Otherwise it behaves the same.
+	This is a generalization of :py:func:`numpy.random.random_integers`
+        to the case where low and high are tensors. Otherwise it
+        behaves the same.
 
     .. method:: choice(self, size=(), a=2, replace=True, p=None, ndim=None, dtype='int64'):
 
-        Choose values from `a` with or without replacement. `a` can be a 1-D
-        array or a positive scalar. If `a` is a scalar, the samples are drawn
-        from the range 0,...,a-1.
+        Choose values from ``a`` with or without replacement. ``a``
+        can be a 1-D array or a positive scalar. If ``a`` is a scalar,
+        the samples are drawn from the range [0, ``a``\[.
 
-        If the size argument is ambiguous on the number of dimensions,
-        ndim may be a plain integer to supplement the missing
-        information.
+        If ``size`` is ambiguous on the number of dimensions, ``ndim``
+        may be a plain integer to supplement the missing information.
 
-	This wrap numpy implementation, so it have the same behavior.
+	This wraps the numpy implementation so it has the same behavior.
 
     .. method:: poisson(self, size=(), lam=None, ndim=None, dtype='int64'):
 
-        Usage: poisson(random_state, size, lam=5)
-
         Draw samples from a Poisson distribution.
   
-        The Poisson distribution is the limit of the Binomial distribution for large N.
+        The Poisson distribution is the limit of the Binomial
+        distribution for large N.
 
-        If the size argument is ambiguous on the number of dimensions,
-        ndim may be a plain integer to supplement the missing
-        information.
+        If ``size`` is ambiguous on the number of dimensions, ``ndim``
+        may be a plain integer to supplement the missing information.
 
-	This wrap numpy implementation, so it have the same behavior.
+	This wraps the numpy implementation so it has the same behavior.
 
     .. method:: permutation(self, size=(), n=1, ndim=None):
 
-        Returns permutations of the integers between 0 and n-1, as many times
-        as required by size. For instance, if size=(p,q), p*q permutations
-        will be generated, and the output shape will be (p,q,n), because each
-        permutation is of size n.
+        Returns permutations of the integers between 0 and ``n-1``, as
+        many times as required by ``size``. For instance, if
+        ``size=(p,q)``, ``p*q`` permutations will be generated, and
+        the output shape will be ``(p,q,n)``, because each permutation
+        is of size ``n``.
 
         Theano tries to infer the number of dimensions from the length
-        of the size argument, but you may always specify it with the
-        `ndim` parameter.
+        of ``size``, but you may always specify it with ``ndim``.
 
         .. note::
-            Note that the output will then be of dimension ndim+1.
+            The output will have ``ndim+1`` dimensions.
 
-	This is a generalization of numpy.random.permutation to
-        the generate many permutation. Otherwise it behaves the same.
+        This is a generalization of :py:func:`numpy.random.permutation` to
+        tensors. Otherwise it behaves the same.
 
     .. method:: multinomial(self, size=(), n=1, pvals=[0.5, 0.5], ndim=None):
 
-        Sample n times from a multinomial distribution defined by probabilities pvals,
-        as many times as required by size. For instance, if size=(p,q), p*q
-        samples will be drawn, and the output shape will be (p,q,len(pvals)).
-
-        Theano tries to infer the number of dimensions from the length of the size argument, but you
-        may always specify it with the `ndim` parameter.
+        Sample n times from a multinomial distribution defined by
+        probabilities ``pvals``, as many times as required by
+        ``size``. For instance, if ``size=(p,q)``, ``p*q`` samples
+        will be drawn, and the output shape will be
+        ``(p,q,len(pvals))``.
 
-	This is a generalization of numpy.random.multinomial to the
-        case where n and pvals are tensors. Otherwise it behaves the
-        same.
+        Theano tries to infer the number of dimensions from the length
+        of ``size``, but you may always specify it with ``ndim``.
 
         .. note::
-            Note that the output will then be of dimension ndim+1.
+            The output will have ``ndim+1`` dimensions.
+
+	This is a generalization of :py:func:`numpy.random.multinomial`
+        to the case where ``n`` and ``pvals`` are tensors. Otherwise
+        it behaves the same.
 
     .. method:: shuffle_row_elements(self, input):
 
         Return a variable with every row (rightmost index) shuffled.
 
-        This uses permutation random variable internally, available via the ``.permutation``
-        attribute of the return value.
-    
+        This uses a permutation random variable internally, available
+        via the ``.permutation`` attribute of the return value.
 
 .. class:: RandomStateType(gof.Type)
 
-    A `Type` for variables that will take ``numpy.random.RandomState`` values.
+    A `Type` for variables that will take ``numpy.random.RandomState``
+    values.
 
 .. function:: random_state_type(name=None)
 
-    Return a new Variable whose ``.type`` is ``random_state_variable``.
+    Return a new Variable whose ``.type`` is ``random_state_type``.
 
 .. class:: RandomFunction(gof.Op)
 
-    Op that draws random numbers from a numpy.RandomState object.  This Op is
-    parametrized to draw numbers from many possible distributions.
+    Op that draws random numbers from a numpy.RandomState object.
+    This Op is parametrized to draw numbers from many possible
+    distributions.
 
-.. function:: uniform(random_state, size=(), low=0.0, high=1.0)
+.. function:: uniform(random_state, size=None, low=0.0, high=1.0, ndim=None, dtype=None)
 
     Sample from a uniform distribution between low and high.
 
@@ -157,59 +155,62 @@ Reference
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: binomial(random_state, size=(), n=1, p=0.5)
+.. function:: binomial(random_state, size=None, n=1, p=0.5, ndim=None, dtype='int64')
 
-    Sample n times with probability of success prob for each trial,
-    return the number of successes.
+    Sample ``n`` times with probability of success ``p`` for each
+    trial and return the number of successes.
+
+    If ``size`` is ambiguous on the number of dimensions, ``ndim`` may
+    be a plain integer to supplement the missing information.
 
-    If the size argument is ambiguous on the number of
-    dimensions, the first argument may be a plain integer
-    to supplement the missing information.
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: normal(random_state, size=(), avg=0.0, std=1.0)
+.. function:: normal(random_state, size=None, avg=0.0, std=1.0, ndim=None, dtype=None)
 
-    Sample from a normal distribution centered on avg with
-    the specified standard deviation (std)
+    Sample from a normal distribution centered on ``avg`` with the
+    specified standard deviation (``std``).
 
-    If the size argument is ambiguous on the number of
-    dimensions, the first argument may be a plain integer
-    to supplement the missing information.
+    If ``size`` is ambiguous on the number of dimensions, ``ndim`` may
+    be a plain integer to supplement the missing information.
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: random_integers(random_state, size=(), low=0, high=1)
+.. function:: random_integers(random_state, size=None, low=0, high=1, ndim=None, dtype='int64')
 
-    Sample a random integer between low and high, both inclusive.
+    Sample random integers in [``low``, ``high``] to fill up ``size``.
 
-    If the size argument is ambiguous on the number of
-    dimensions, the first argument may be a plain integer
-    to supplement the missing information.
+    If ``size`` is ambiguous on the number of dimensions, ``ndim`` may
+    be a plain integer to supplement the missing information.
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: permutation(random_state, size=(), n=1)
+.. function:: permutation(random_state, size=None, n=1, ndim=None, dtype='int64')
 
-    Returns permutations of the integers between 0 and n-1, as many times
-    as required by size. For instance, if size=(p,q), p*q permutations
-    will be generated, and the output shape will be (p,q,n), because each
-    permutation is of size n.
+    Returns permutations of the integers in [0, ``n``\[, as many times
+    as required by ``size``. For instance, if ``size=(p,q)``, ``p*q``
+    permutations will be generated, and the output shape will be
+    ``(p,q,n)``, because each permutation is of size ``n``.
 
-    If the size argument is ambiguous on the number of dimensions, the first
-    argument may be a plain integer i, which should correspond to len(size).
-    Note that the output will then be of dimension i+1.
+    If ``size`` is ambiguous on the number of dimensions, ``ndim``
+    may be a plain integer, which should correspond to ``len(size)``.
+
+    .. note::
+        The output will have ``ndim+1`` dimensions.
 
     :returns: :class:`RandomVariable`, NewRandomState
 
-.. function:: multinomial(random_state, size=(), p_vals=[0.5, 0.5])
+.. function:: multinomial(random_state, size=None, p_vals=[0.5, 0.5], ndim=None, dtype='int64')
 
-    Sample from a multinomial distribution defined by probabilities pvals,
-    as many times as required by size. For instance, if size=(p,q), p*q
-    samples will be drawn, and the output shape will be (p,q,len(pvals)).
+    Sample from a multinomial distribution defined by probabilities
+    ``pvals``, as many times as required by ``size``. For instance, if
+    ``size=(p,q)``, ``p*q`` samples will be drawn, and the output
+    shape will be ``(p,q,len(pvals))``.
 
-    If the size argument is ambiguous on the number of dimensions, the first
-    argument may be a plain integer i, which should correspond to len(size).
-    Note that the output will then be of dimension i+1.
+    If ``size`` is ambiguous on the number of dimensions, ``ndim``
+    may be a plain integer, which should correspond to ``len(size)``.
+
+    .. note::
+        The output will have ``ndim+1`` dimensions.
 
     :returns: :class:`RandomVariable`, NewRandomState
 

doc/tutorial/examples.txt

@@ -5,13 +5,13 @@
 More Examples
 =============
 
-At this point it would be wise to begin familiarizing yourself 
-more systematically with Theano's fundamental objects and operations by browsing
-this section of the library: :ref:`libdoc_basic_tensor`.
+At this point it would be wise to begin familiarizing yourself more
+systematically with Theano's fundamental objects and operations by
+browsing this section of the library: :ref:`libdoc_basic_tensor`.
 
-As the tutorial unfolds, you should also gradually acquaint yourself with the other
-relevant areas of the library and with the relevant subjects of the documentation
-entrance page.
+As the tutorial unfolds, you should also gradually acquaint yourself
+with the other relevant areas of the library and with the relevant
+subjects of the documentation entrance page.
 
 
 Logistic Function
@@ -30,13 +30,13 @@ the logistic curve, which is given by:
     A plot of the logistic function, with x on the x-axis and s(x) on the
     y-axis.
 
-You want to compute the function :ref:`elementwise <libdoc_tensor_elementwise>` on matrices of
-doubles, which means that you want to apply this function to each
-individual element of the matrix.
+You want to compute the function :ref:`elementwise
+<libdoc_tensor_elementwise>` on matrices of doubles, which means that
+you want to apply this function to each individual element of the
+matrix.
 
 Well, what you do is this:
 
-
 .. If you modify this code, also change :
 .. theano/tests/test_tutorial.py:T_examples.test_examples_1
 
@@ -450,10 +450,10 @@ Other Random Distributions
 
 There are :ref:`other distributions implemented <libdoc_tensor_raw_random>`. 
 
-Other Implementation
---------------------
+Other Implementations
+---------------------
 
-Their is 2 other implementation based on :class:`CURAND <theano.sandbox.cuda.rng_curand>` and :ref:`MRG31k3p <libdoc_rng_mrg>`
+There is 2 other implementations based on :class:`CURAND <theano.sandbox.cuda.rng_curand>` and :ref:`MRG31k3p <libdoc_rng_mrg>`
 
 .. _logistic_regression:
 
@@ -461,7 +461,8 @@ Their is 2 other implementation based on :class:`CURAND <theano.sandbox.cuda.rng
 A Real Example: Logistic Regression
 ===================================
 
-The preceding elements are featured in this more realistic example.  It will be used repeatedly.  
+The preceding elements are featured in this more realistic example.
+It will be used repeatedly.
 
 .. code-block:: python
 

doc/tutorial/multi_cores.txt

@@ -5,45 +5,40 @@ Multi cores support in Theano
 BLAS operation
 ==============
 
-BLAS is an interface for some mathematics operations between vectors,
-vector and matrix and matrices (e.g. the dot product between vector/matrix
-and matrix/matrix). Many different implementations exist of that
-interface and some of them are parallel.
+BLAS is an interface for some mathematic operations between two
+vectors, a vector and a matrix or two matrices (e.g. the dot product
+between vector/matrix and matrix/matrix). Many different
+implementations of that interface exist and some of them are
+parallelized.
 
-Theano try to use that interface as frequently as possible for
-performance reason. So if Theano link to one parallel implementation,
-those operation will run in parallel in Theano.
+Theano tries to use that interface as frequently as possible for
+performance reasons. So if Theano links to a parallel implementation,
+those operations will run in parallel in Theano.
 
 The most frequent way to control the number of threads used is via the
 ``OMP_NUM_THREADS`` environment variable. Set it to the number of threads
 you want to use before starting the python process.
 
 
-Parallel element wise op with OpenMP
-====================================
+Parallel element wise ops with OpenMP
+=====================================
 
-Because element wise ops work on every tensor entry independently they can be
-easily parallelized using OpenMP.
+Because element wise ops work on every tensor entry independently they
+can be easily parallelized using OpenMP.
 
 To use OpenMP you must set the OpenMP flag in Theano configuration.
 
-You can use the flag ``openmp_elemwise_minsize`` to set the minimum tensor size
-for which the operation is parallelized because for short tensor using OpenMP
-can slow down the operation.
-
-If it is no specified the default value ``200000`` is used.
-
-For simple(fast) operation you can obtain a speed up for very long tensor
-while for more complex operation you ca obtain a good speed up also for not
-too long tensor. 
-
-There is a script ``elemwise_openmp_speedup.py`` in ``theano/misc/`` which you
-can use to choose that value for your machine.
-The script run two elemwise operation (a fast and a slow one) for a vector of
-size ``openmp_elemwise_minsize`` with and without OpenMP and show the time
-difference between the two cases.
-
-
-
+You can use the flag ``openmp_elemwise_minsize`` to set the minimum
+tensor size for which the operation is parallelized because for short
+tensors using OpenMP can slow down the operation. The default value is
+``200000``.
 
+For simple(fast) operation you can obtain a speed up with very large
+tensors while for more complex operation you can obtain a good speed
+up also for smaller tensor.
 
+There is a script ``elemwise_openmp_speedup.py`` in ``theano/misc/``
+which you can use to tune the value of ``openmp_elemwise_minsize`` for
+your machine.  The script runs two elemwise operations (a fast one and
+a slow one) for a vector of size ``openmp_elemwise_minsize`` with and
+without OpenMP and shows the time difference between the cases.

theano/sparse/basic.py

@@ -2623,9 +2623,10 @@ class TrueDot(gof.op.Op):
         self.grad_preserves_dense = grad_preserves_dense
 
     def __eq__(self, other):
-        # The grad_preserves_dense attribute don't change the
-        # execution behavior.  To have Theano merge optimizer merging
-        # them, we shouldn't compare it here.
+        # The grad_preserves_dense attribute doesn't change the
+        # execution behavior.  To let the optimizer merge nodes with
+        # different values of this attribute we shouldn't compare it
+        # here.
         return type(self) == type(other)
 
     def __hash__(self):
@@ -2714,13 +2715,13 @@ class TrueDot(gof.op.Op):
 def true_dot(x, y, grad_preserves_dense=True):
     """
     Operation for efficiently calculating the dot product when
-    one or all operands is sparse. Supported format are CSC and CSR.
+    one or all operands are sparse. Supported formats are CSC and CSR.
     The output of the operation is sparse.
 
     :param x: Sparse matrix or 2d tensor variable.
     :param y: Sparse matrix or 2d tensor variable.
-    :param grad_preserves_dense: if True and one on the input is dense,
-        make the grad dense on that input.
+    :param grad_preserves_dense: if True (default), makes the grad of
+        dense inputs dense.  Otherwise the grad is always sparse.
 
     :return: The dot product `x`.`y` in a sparse format.
 

theano/tensor/nnet/Conv3D.py

@@ -562,12 +562,12 @@ conv3D = Conv3D()
 :note: The order of dimensions does not correspond to the one in `conv2d`.
        This is for optimization.
 
-:note: The GPU implementation is very slow. You are better to use
-    :func:`conv3d2d <theano.tensor.nnet.conv3d2d.conv3d>` that is faster
-    on GPU.
+:note: The GPU implementation is very slow. You should use
+    :func:`conv3d2d <theano.tensor.nnet.conv3d2d.conv3d>` for a GPU
+    graph instead.
 
-:see: Someone made a script that show how to swap the axis between
-      both 3d convolution implementation in Theano. See the last
+:see: Someone made a script that shows how to swap the axes between
+      both 3d convolution implementations in Theano. See the last
       `attachment <https://groups.google.com/d/msg/theano-users/1S9_bZgHxVw/0cQR9a4riFUJ>`_.
 
 """

theano/tensor/nnet/conv3d2d.py

@@ -178,8 +178,8 @@ def conv3d(signals, filters,
            Another way to define signals: (batch,  time, in channel, row, column)
            Another way to define filters: (out channel,time,in channel, row, column)
 
-    :see: Someone made a script that show how to swap the axis between
-          both 3d convolution implementation in Theano. See the last
+    :see: Someone made a script that shows how to swap the axes between
+          both 3d convolution implementations in Theano. See the last
           `attachment <https://groups.google.com/d/msg/theano-users/1S9_bZgHxVw/0cQR9a4riFUJ>`_.
 
     """

theano/tensor/raw_random.py

@@ -578,10 +578,9 @@ def random_integers(random_state, size=None, low=0, high=1, ndim=None,
 def choice_helper(random_state, a, replace, p, size):
     """Helper function to draw random numbers using numpy's choice function.
 
-    This is a generalization of numpy.random.choice that coerce
-    `replace` to a bool and replace `p` to None when p is a vector of
-    0 elements.
-
+    This is a generalization of numpy.random.choice that coerces
+    `replace` to a bool and replaces `p` with None when p is a vector
+    of 0 elements.
     """
     if a.ndim > 1:
         raise ValueError('a.ndim (%i) must be 0 or 1' % a.ndim)
@@ -660,8 +659,8 @@ def permutation_helper(random_state, n, shape):
     If you wish to perform a permutation of the elements of an existing vector,
     see shuffle_row_elements.
 
-    This is a generalization of numpy.random.permutation to
-    the generate many permutation. Otherwise it behave the same.
+    This is a generalization of numpy.random.permutation to tensors.
+    Otherwise it behaves the same.
     """
     # n should be a 0-dimension array
     assert n.shape == ()
@@ -863,7 +862,7 @@ class RandomStreamsBase(object):
     def binomial(self, size=None, n=1, p=0.5, ndim=None, dtype='int64',
                  prob=None):
         """
-        Sample n times with probability of success prob for each trial,
+        Sample n times with probability of success p for each trial and
         return the number of successes.
 
         If the size argument is ambiguous on the number of dimensions,