Merge pull request #14 from dwf/install_fixes

doc/install.txt

@@ -79,9 +79,10 @@ Linux
 CentOS 6
 ~~~~~~~~
 
-:ref:`install_centos6` on how to install Theano on CentOS 6
-made by us. It cover how to install Theano on the CPU with the
-distribution packages atlas, a free fast implementation of Blas.
+:ref:`install_centos6` provides instructions on how to install Theano on CentOS
+6, written by the Theano developers. It covers how to install Theano (for
+CPU-based computation only) with the distribution-packaged ATLAS, a free fast
+implementation of BLAS.
 
 .. Cent OS 6
 
@@ -178,8 +179,8 @@ The following command will update Theano and Numpy/Scipy (warning bellow):
 
 If you installed numpy/scipy with yum/apt-get, updating numpy/scipy
 this way is not always a good idea. This can make Theano crash due to
-problem with Blas (We will try to fix them). But, this can also result
-in slower version of Theano and Numpy. To fix the crash, you can
+problem with BLAS (We will try to fix them). But, this can also result
+in slower version of Theano and NumPy. To fix the crash, you can
 delete Theano cache like this:
 
 .. code-block:: bash

doc/install_centos6.txt

@@ -2,99 +2,99 @@
 .. _install_centos6:
 
 
-Easy Installation of Theano optimized on CentOS 6
-=================================================
+Easy Installation of an optimized Theano on CentOS 6
+====================================================
 
 .. note::
 
-    It is possible to have a faster installation of Theano. But this
-    make the installation more complicated or request that you buy
-    software. So this is a simple installation instruction that give a
-    relatively well optimized version that use only free
-    software. With more work or with money, you can have a faster
-    installation.
-    
-    The differences between those faster version are related to blas
-    libraries.
+    It is possible to have a faster installation of Theano than the one these
+    instructions will provide, but this will make the installation more
+    complicated and/or may require that you buy software. This is a simple set
+    of installation instructions that will leave you with a relatively
+    well-optimized version that uses only free software. With more work or by
+    investing money (i.e. buying a license to a proprietary BLAS
+    implementation), it is possible to gain further performance.
 
 .. note::
 
-    This procedure make Theano use only 1 thread for all blas
-    function. See note 1 about faster version. The other blas
-    libraries can work in parallel.
+    These instructions will result in Theano using only 1 thread for all BLAS
+    function calls. See the note above; other BLAS implementations can employ
+    multithreading to speed up computation.
 
 .. note::
 
-   If you are under a proxy, you must do some extra configuration step
-   bedofore staring the installation. You must set the environment
-   variable ``http_proxy`` to the proxy like this under bash:
+   If you are behind a proxy, you must do some extra configuration steps
+   before starting the installation. You must set the environment
+   variable ``http_proxy`` to the proxy address. Using bash this is
+   accomplished with the command
    ``export http_proxy="http://user:pass@my.site:port/"``
-   You can also give the ``--proxy=[user:pass@]url:port`` parameter
-   to pip. [user:pass@] is optional.
+   You can also provide the ``--proxy=[user:pass@]url:port`` parameter
+   to pip. The ``[user:pass@]`` portion is optional.
 
 .. note::
 
-   We use pip for 2 reasons. First to allow "import module;
-   module.test()" to work correctly. Second, the installation of numpy
-   1.6 or 1.6.1 with easy_intall raise an import error at the end of
+   We use ``pip`` for 2 reasons. First, it allows "``import module;
+   module.test()``" to work correctly. Second, the installation of NumPy
+   1.6 or 1.6.1 with ``easy_install`` raises an ImportError at the end of
    the installation. To my knowledge we can ignore this error, but
-   this is not completly safe. easy_install with numpy 1.5.1 don't
-   have this error.
+   this is not completely safe. ``easy_install`` with NumPy 1.5.1 does not
+   raise this error.
 
 
 
-Installation step
-~~~~~~~~~~~~~~~~~
+Installation steps
+~~~~~~~~~~~~~~~~~~
 
- 1) sudo yum install python-devel python-nose python-setuptools gcc
-    gcc-gfortran gcc-c++ blas-devel lapack-devel atlas-devel
- 2) sudo easy_install pip
- 3) sudo pip install numpy==1.6.1
- 4) sudo pip install scipy==0.10.1
- 5) sudo pip install Theano
+ 1) ``sudo yum install python-devel python-nose python-setuptools gcc
+    gcc-gfortran gcc-c++ blas-devel lapack-devel atlas-devel``
+ 2) ``sudo easy_install pip``
+ 3) ``sudo pip install numpy==1.6.1``
+ 4) ``sudo pip install scipy==0.10.1``
+ 5) ``sudo pip install Theano``
 
 
-Tests newly installed package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Test the newly installed packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
- 1) Numpy (~30s): python -c "import numpy;numpy.test()"
- 2) Scipy (~1m): python -c "import scipy;scipy.test()"
- 3) Theano (~30m): python -c "import theano;theano.test()"
+ 1) NumPy (~30s): ``python -c "import numpy; numpy.test()"``
+ 2) SciPy (~1m): ``python -c "import scipy; scipy.test()"``
+ 3) Theano (~30m): ``python -c "import theano; theano.test()"``
 
 
-Speed test Theano/Blas
+Speed test Theano/BLAS
 ~~~~~~~~~~~~~~~~~~~~~~
 
-It is recommended to test the Theano/Blas integration. There is many
-version of Blas that exist and there can be up to 10x speed
-difference.  Also, having Theano link directly to blas instead of
-using numpy/scipy as an intermediate lower the overhead. This is
-important for blas call to ger, gemv and small gemm (automaticaled
-when needed when you use dot()). To run Theano/Blas speed test:
+It is recommended to test your Theano/BLAS integration. There are many versions
+of BLAS that exist and there can be up to 10x speed difference between them.
+Also, having Theano link directly against BLAS instead of using NumPy/SciPy as
+an intermediate layer reduces the computational overhead. This is
+important for BLAS calls to ``ger``, ``gemv`` and small ``gemm`` operations
+(automatically called when needed when you use ``dot()``). To run the
+Theano/BLAS speed test:
 
 .. code-block:: bash
 
     python /usr/lib/python2.*/site-packages/theano/misc/check_blas.py
 
-This will print a table with with different version of blas/number of
-thread on multiple CPUs and GPUs. It will also print some Theano/numpy
-configuration. Thenit will print the run time for your
-installation. Try to find a CPU close to yours and check if the
-timming is not too far.
+This will print a table with different versions of BLAS/numbers of
+threads on multiple CPUs and GPUs. It will also print some Theano/NumPy
+configuration information. Then, it will print the running time of the same
+benchmarks for your installation. Try to find a CPU similar to yours in
+the table, and check that the single-threaded timings are roughly the same.
 
 
 Updating Theano
 ~~~~~~~~~~~~~~~
 
-If you followed this instruction installation, you can execute this to
-update only Theano:
+If you followed these installation instructions, you can execute this command
+to update only Theano:
 
 .. code-block:: bash
 
     sudo pip install --upgrade --no-deps theano
 
 
-If you want to also update numpy/scipy, you can run this:
+If you want to also update NumPy/SciPy, you can run this:
 
 .. code-block:: bash