diff --git a/_sources/index.txt b/_sources/index.txt index ee713eb5..d61bce1a 100644 --- a/_sources/index.txt +++ b/_sources/index.txt @@ -4,9 +4,9 @@ :maxdepth: 1 install - beginner-tutorial - bundles - development-guidelines - appendix - release-process - releases +.. beginner-tutorial +.. bundles +.. development-guidelines +.. appendix +.. release-process +.. releases diff --git a/_sources/install.txt b/_sources/install.txt index 57fb711f..028f9295 100644 --- a/_sources/install.txt +++ b/_sources/install.txt @@ -13,7 +13,7 @@ There are two reasons for the additional complexity: In order to build the C extensions, ``pip`` needs access to the CPython header files for your Python installation. -2. Zipline depends on `numpy `_, the core library for +2. Catalyst depends on `numpy `_, the core library for numerical array computing in Python. Numpy depends on having the `LAPACK `_ linear algebra routines available. @@ -41,7 +41,15 @@ version: $ virtualenv catalyst-venv $ source ./catalyst-venv/bin/activate - $ pip install enigma-catalyst + $ pip install enigma- + +Though not required by Catalyst directly, our example algorithms use matplotlib +to visually display the results of the trading algorithms. If you wish to run +any examples or use matplotlib during development, it can be installed using: + +.. code-block:: bash + + $ pip install matplotlib GNU/Linux ~~~~~~~~~ @@ -71,8 +79,8 @@ On `Arch Linux`_, you can acquire the additional dependencies via ``pacman``: .. .. There are also AUR packages available for installing `Python 3.4 .. `_ (Arch's default python is now -.. 3.5, but Zipline only currently supports 3.4), and `ta-lib -.. `_, an optional Zipline dependency. +.. 3.5, but Catalyst only currently supports 3.4), and `ta-lib +.. `_, an optional Catalyst dependency. .. Python 2 is also installable via: .. @@ -96,12 +104,132 @@ following brew packages: $ brew install freetype pkg-config gcc openssl +OSX + virtualenv + matplotlib +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A note about using matplotlib in virtual enviroments on OSX: it may be necessary to run + +.. code-block:: bash + + echo "backend: TkAgg" > ~/.matplotlib/matplotlibrc + +in order to override the default ``macosx`` backend for your system, which may not +be accessible from inside the virtual environment. This will allow Catalyst to open +matplotlib charts from within a virtual environment, which is useful for displaying +the performance of your backtests. To learn more about matplotlib backends, please refer to the +`matplotlib backend documentation `_. + + Windows ~~~~~~~ -For windows, the easiest and best supported way to install zipline is to use +In Windows, you will need the `Microsoft Visual C++ Compiler for Python 2.7 +`_. This package +contains the compiler and the set of system headers necessary for producing +binary wheels for Python 2.7 packages. If it's not already in your system, download +it and install it before proceeding to the next step. + +For windows, the easiest and best supported way to install Catalyst is to use :ref:`Conda `. +Amazon Linux AMI +~~~~~~~~~~~~~~~~ + +The packages ``pip`` and ``setuptools`` that come shipped by default are very outdated. +Thus, you first need to run: + +.. code-block:: bash + + pip install --upgrade pip setuptools + +The default installation is also missing the C and C++ compilers, which you install by: + +.. code-block:: bash + + sudo yum install gcc gcc-c++ + +Then you should follow the regular installation instructions outlined at the beginning +of this page. + + +Troubleshooting ``pip`` Install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Issue**: + Package enigma-catalyst cannot be found + +**Solution**: + Make sure you have the most up-to-date version of pip installed, by running: + + .. code-block:: bash + + pip install --upgrade pip + + On Windows, the recommended command is: + + .. code-block:: bash + + python -m pip install --upgrade pip + +---- + +**Issue**: + Package enigma-catalyst cannot still be found, even after upgrading pip (see above), with an error similar to: + + .. code-block:: bash + + Downloading/unpacking enigma-catalyst + Could not find a version that satisfies the requirement enigma-catalyst (from versions: 0.1.dev9, 0.2.dev2, 0.1.dev4, 0.1.dev5, 0.1.dev3, 0.2.dev1, 0.1.dev8, 0.1.dev6) + Cleaning up... + No distributions matching the version for enigma-catalyst + +**Solution**: + In some systems (this error has been reported in Ubuntu), pip is configured to only find stable versions by default. Since Catalyst is in alpha version, pip cannot find a matching version that satisfies the installation requirements. The solution is to include the `--pre` flag to include pre-release and development versions: + + .. code-block:: bash + + pip install --pre enigma-catalyst + +---- + +**Issue**: + Package enigma-catalyst fails to install because of outdated setuptools + +**Solution**: + Upgrade to the most up-to-date setuptools package by running: + + .. code-block:: bash + + pip install --upgrade pip setuptools + +---- + +**Issue**: + Missing required packages + +**Solution**: + Download `requirements.txt + `_ + (click on the *Raw* button and Right click -> Save As...) and use it to + install all the required dependencies by running: + + .. code-block:: bash + + pip install -r requirements.txt + +---- + +**Issue**: + Installation fails with error: ``fatal error: Python.h: No such file or directory`` + +**Solution**: + Some systems (this issue has been reported in Ubuntu) require `python-dev` for the proper build and installation of package dependencies. The solution is to install python-dev, which is independent of the virtual environment. In Ubuntu, you would need to run: + + .. code-block:: bash + + sudo apt-get install python-dev + + .. _conda: Installing with ``conda`` @@ -118,14 +246,96 @@ without requiring the use of a second tool to acquire Catalyst's non-Python dependencies. For instructions on how to install ``conda``, see the `Conda Installation -Documentation `_ +Documentation `_. Alternatively, you +can install MiniConda, which is a smaller footprint (fewer packages and smaller +size) than its big brother Anaconda, but it still contains all the main packages +needed. To install MiniConda, you can follow these steps: -Once conda has been set up you can install Catalyst from our ``Quantopian`` -channel: +1. Download `MiniConda `_. Select Python 2.7 for + your Operating System. +2. Install MiniConda. See the `Installation Instructions `_ + if you need help. +3. Ensure the correct installation by running ``conda list`` in a Terminal window, + which should print the list of packages installed with Conda. -.. code-block:: bash +Once either Conda or MiniConda has been set up you can install Catalyst: + +1. Download the file `python2.7-environment.yml `_. +2. Open a Terminal window and enter [``cd/dir``] into the directory where you saved + the above ``python2.7-environment.yml`` file. +3. Install using this file. This step can take about 5-10 minutes to install. + + .. code-block:: bash + + conda env create -f python2.7-environment.yml + +4. Activate the environment (which you need to do every time you start a new session + to run Catalyst): + + **Linux or OSX:** + + .. code-block:: bash + + source activate catalyst + + **Windows:** + + .. code-block:: bash + + activate catalyst + +Congratulations! You now have Catalyst installed. + +Troubleshooting ``conda`` Install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the command ``conda env create -f python2.7-environment.yml`` in step 3 above failed +for any reason, you can try setting up the environment manually with the following steps: + +1. Create the environment: + + .. code-block:: bash + + conda create --name catalyst python=2.7 scipy + +2. Activate the environment: + + **Linux or OSX:** + + .. code-block:: bash + + source activate catalyst + + **Windows:** + + .. code-block:: bash + + activate catalyst + +3. Install the Catalyst inside the environment: + + .. code-block:: bash + + pip install enigma-catalyst matplotlib + +Getting Help +------------ + +If after following the instructions above, and going through the *Troubleshooting* sections, +you still experience problems installing Catalyst, you can seek additional help through the +following channels: + +- Join our `Discord community `_, and head over the #catalyst_dev + channel where many other users (as well as the project developers) hang out, and can assist + you with your particular issue. The more descriptive and the more information you can provide, + the easiest will be for others to help you out. + +- Report the problem you are experiencing on our + `GitHub repository `_ following the guidelines + provided therein. Before you do so, take a moment to browse through all `previous reported issues + `_ in the likely case + that someone else experienced that same issue before, and you get a hint on how to solve it. - conda install -c Quantopian zipline .. _`Debian-derived`: https://www.debian.org/misc/children-distros .. _`RHEL-derived`: https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux_derivatives diff --git a/appendix.html b/appendix.html index 51cf4780..7b795ca7 100644 --- a/appendix.html +++ b/appendix.html @@ -30,9 +30,7 @@ - - - + @@ -71,242 +69,24 @@ -