LICENSE, README files + rudimentary install instructions

LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2013, Alborz Geramifard, Robert H. Klein, Christoph Dann, William Dabney and Jonathan P. How
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, 
+this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, 
+this list of conditions and the following disclaimer in the documentation 
+and/or other materials provided with the distribution.
+
+Neither the name of ACL nor the names of its contributors may be used to 
+endorse or promote products derived from this software without specific 
+prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+POSSIBILITY OF SUCH DAMAGE.

README.rst

@@ -0,0 +1,20 @@
+.. -*- mode: rst -*-
+
+RLPy -- Reinforment Learning Framework
+======================================
+
+RLPy is a framework to conduct sequential decision making experiments. The
+current focus of this project lies on value-function-based reinforcement
+learning. The project is distributed under the 3-Clause BSD License.
+
+Important Links
+===============
+
+- Official source code repository: http://bitbucket.org/rlpy/rlpy
+- Documentation and Homepage: http://acl.mit.edu/RLPy
+- Issue Tracker: http://bitbucket.org/rlpy/rlpy/issues
+
+Installation
+============
+
+For installation instructions see http://acl.mit.edu/RLPy/install.html

doc/index.rst

@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 2
 
    big_picture
+   install
    tutorial
    faq
    api/index

doc/install.rst

@@ -1,199 +1,88 @@
-// \file install.txt
-/*! 
-  \page install.txt Installation
-  \anchor the_install_page
-  \section Download Download
-Download RLPy <a href="http://acl.mit.edu/RLPy/RLPy.zip">Here</a> \n
-\n
-Please direct any questions or bug reports to\n
-rlpy[at]mit[dot]edu\n
-
-  \section Citations Citations
-Alborz Geramifard and Robert H Klein and Jonathan P How, RLPy: The Reinforcement Learning Library for Education and Research, 2013. http://acl.mit.edu/RLPy, April, 2013 
-\n
-\n
-<B> Bibtex </B>\n
-\@ONLINE{RLPy, \n
-author = {Alborz Geramifard and Robert H Klein and Jonathan P How}, \n
-title = {{RLPy: The Reinforcement Learning Library for Education and Research}}, \n
-month = April, \n
-year = {2013}, \n
-howpublished = {\\url{http://acl.mit.edu/RLPy}}, \n
-} \n
-  \section Prerequisites Prerequisites
-The only requirements to run and contribute to RLPy are
-a working Python 2.7 environment and the required package dependencies,
-which can be installed automatically by the provided scripts.\n
-Detailed installation instructions are shown below.\n
-Installation FAQ available at bottom, general FAQ available on the FAQ page
-or in the file FAQ.txt located in the RLPy folder.\n
-\n
-Recommended Operating Systems:\n
-a) <B>Windows 32-bit</B>\n
-b) <B>Ubuntu Linux 32/64-bit</B>\n
-c) <B>Mac OSX</B> \n
-\n
-
-If your setup does not match those recommended above
-you must download the packages manually, described in manual_install.txt.\n
-\n
-\n
-    \section installation INSTALLATION: As easy as 1,2,3 (+4 to run)
-===============================================================\n
-===============================================================\n
-1. Python 2.7\n
-\n
-Check to see if python is already installed by opening a terminal in any
-OS and typing:\n
-> python --version\n
-\n
-If you do not see the output "Python 2.7.3", download and install python,
-for example, from ( http://www.python.org/getit/ )\n
-\n
-===============================================================\n
-===============================================================\n
-2. An IDE capable of development in Python\n
-\n
-Install a development environment of choice with Python support.\n
-We recommend Eclipse Classic.  Note that eclipse requires the Java SDK.\n
-To obtain Eclipse, download and follow the instructions:\n
-i) Download+Install Eclipse Classic ( http://www.eclipse.org/downloads/ )\n
-ii) Install Pydev for Eclipse ( http://pydev.org/manual_101_install.html )\n
-\n
-See FAQ if eclipse fails to run.\n
-\n
-===============================================================\n
-===============================================================\n
-2.5. pip\n
-a) Windows 32/64-bit\n
-Install per instructions here:
-http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows\n
-\n
-b) Ubuntu Linux - automated in script\n
-c) Mac OSX - automated in script\n
-\n
-===============================================================\n
-===============================================================\n
-3. Run the dependency installer script\n
-\n
-FIRST ensure the RLPy directory is located in the workspace folder of your
-IDE, or whatever final location you intend it to be.\n
-THEN Run the installer script for your operating system: (on windows, first extract
-the zip file Win32_files.zip into the Install folder)\n
-\n
-a) <B>Windows 32-bit</B>\n
-a.i) Open a command prompt window with administrative privileges:\n
-	Windows 8: 		 WindowsKey-X, select "Command Prompt Admin"\n
-	Windows 7,Vista: type 'cmd' in the start menu, right click and open with admin privileges\n
-	Windows XP:      Start-->Run cmd.exe\n
-a.ii) Navigate to the Install directory and run the .bat script.\n
-\n
-\n
-\n
-b) <B>Ubuntu</B> - Open a terminal window, navigate to the Installation folder,
-and enter 'chmod u+x ubuntu_setup.sh'\n
-Then run the provided script with ./ubuntu_setup.sh\n
-\n
-\n
-\n
-c) <B> Mac OSX </B> \n
-c.i) The Command Line Tools (CLT) and/or XCode are required to use the script.
-If you are unsure of your setup, type " xcode-select --version " at a terminal.\n
-If you don't see a valid version number appear, follow the instructions here to
-setup your environment: ( http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac/ )\n
-\n
-c.ii) Open a terminal window, navigate to the Installation folder,
-and enter 'chmod u+x OSX_setup.sh'\n
-Then run the provided script with ./OSX_setup.sh\n
-\n
-\n
-
-===============================================================\n
-===============================================================\n
-Installation of RLPy is now complete!\n
-\n
-4. Now open the framework in your IDE of choice.\n
-\n
-If using Eclipse:\n
-i) Go to file -> switch workspace -> other\n
-And navigate to the folder containing RLPy (NOT the RLPy folder itself.)\n
-\n
-ii) Go to file -> import -> general -> existing projects into workspace
-And select 'Browse.'  Navigate into the RLPy directory and select 'Next.'\n
-You should now see the RLPy directory structure in the left pane.\n
-\n
-===============================================================\n
-===============================================================\n
-\n
-That's it!\n
-\n
-Now take a look at the \ref First_Run Getting Started Tutorial page,
-and (as part of the tutorial) test the installation by running IshouldRun.py.\n
-Finally, start experimenting with RLPy yourself!\n
-\n
-If you encountered errors in the installation, see the FAQ section at bottom\n
-(and an extended FAQ located in the FAQ.txt file).\n
-\n
-\n
-\n
-
-\section install_faq Insallation FAQ: Error/Solutions
-U = Ubuntu, W = Windows, X = OSX\n
-===============================================================\n
-If you are having trouble installing on OSX, see the following:\n
-http://www.thisisthegreenroom.com/2011/installing-python-numpy-scipy-matplotlib-and-ipython-on-lion/#numpy\n
-\n
-===============================================================\n
-E: Generic messages about missing environmental variables\n
-S1: Ensure that the environment variable 'RL_PYTHON_ROOT' is set on your OS for
-whatever environment you are running RLPy in (e.g. it might be set in a terminal
-window but not in general).\n
-This should have been configured by the installer script; if your RLPy
-directory has moved since then, merely re-run the installer script and
-restart your computer.\n
-S2: If the installer script fails to solve the problem, the easiest solution is
-to add the RL_PYTHON_ROOT variable to your IDE directly.
-In eclipse, go to window->preferences->pydev->interpreter Pydev->environment.
-There, add a variable called RL_PYTHON_ROOT and set its value to be the path to
-your RLPy directory.\n
-===============================================================\n
-E: Generic messages about missing functions or 'module does not contain function xxx'\n
-S: Ensure you have the latest version of scipy (0.11 as of this writing):\n
-import scipy\n
-scipy.version.version\n
-S-U: if you don't have the correct version, run the following commands\n
-sudo apt-get install libatlas-base-dev gfortran python-pip\n
-sudo pip install scipy --upgrade\n
-===============================================================\n
-E: ImportError: numpy.core.multiarray failed to import\n
-S1: Dont import pylab directly. Use Matplotlib.pylab\n
-S2: sudo easy_install -U numpy\n
-===============================================================\n
-E: In eclipse sty is out of synch with the file system\n
-S: Refresh (F5)\n
-===============================================================\n
-E: In Windows: Python does not appear to be installed (Eclipse
-fails to locate python, or running 'python' in a command prompt gives
-'python' is not recognized as an internal or external command, operable
-program or batch file."\n
-S-W: Set the path variables for python as described in: ( http://docs.python.org/2/faq/windows.html )\n
-===============================================================\n
-
-  \section Copyright Copyright (BSD License)
-
-\verbatim
-Copyright (c) 2013, Alborz Geramifard, Robert H. Klein, and Jonathan P. How
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-Neither the name of ACL nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-\endverbatim
-
-*/
+.. _install:
+
+************
+Installation
+************
+
+Download
+========
+
+Stable Version
+--------------
+You can download the latest stable version of RLPy from http://acl.mit.edu/RLPy.
+Extract the package in your desired location.
+
+Development Version
+-------------------
+The development is maintained bitbucket at https://bitbucket.org/rlpy/rlpy.
+The git-repository with the latest development version can be cloned via::
+
+    git clone git://bitbucket.org/rlpy/rlpy.git RLPy
+
+This will give you a copy of the repository in the directory `RLPy`. You might
+want to change the location as you wish.
+
+Dependencies
+============
+
+RLPy requires the following packages besides Python:
+
+Graphviz
+    (optional) For creating the graphical ouput of the code profiling tool.
+GCC >= 4.6
+    For compiling some C++ extensions which use the C++11 standard.
+
+
+In addition, RLPy requires Python 2.7 to run. We do not support Python 3 at the
+moment since most scientific libraries still require Python 2.
+The following Python packages need to be available:
+
+- Numpy >= 1.7
+- Scipy
+- Matplotlib >= 1.2
+- Networkx
+- PyTk
+- scikit-learn
+- Cython
+
+
+Ubuntu / Debian
+---------------
+Install the non-python dependencies with::
+
+    sudo apt-get install graphviz tk blt tcl gcc
+
+To install the Python packages we recommend using Anaconda as described in
+:ref:`the following section <anaconda>` . This will ensure you have the latest versions of
+each package.
+**Alternatively** you can install the python packages via apt. Note however that
+these packages will usually be older.
+You can install them by executing::
+
+    sudo apt-get install python-dev python-setuptools python-sklearn python-numpy python-scipy python-matplotlib python-networkx graphviz python-pip tcl-dev tk-dev python-tk cython
+
+
+.. _anaconda:
+
+Anaconda
+--------
+
+We recommend using 
+the `Anaconda Python distribution <https://store.continuum.io/cshop/anaconda/>`_. This software package comes with a current version of Python
+and many libraries necessary for scientific computing. It simplifies installing
+and updating Python libraries significantly on Windows, MacOS and Linux.
+Please follow the original `installation instructions
+<http://docs.continuum.io/anaconda/install.html>`_ of Anaconda.
+
+After installing Anaconda, install the dependencies of RLPy by executing::
+
+    conda install numpy scipy matplotlib networkx tk scikit-learn cython
+
+Build Extensions of RLPy
+------------------------
+
+Build the C++ / Cython extensions of RLPy by executing in your RLPy directory::
+
+    python setup.py build_ext --inplace
+
+