F311 Installation
=================

.. note:: As of July 2023, we recommend using Anaconda/Miniconda and Python 3.11

Setting up Anaconda virtual environment
--------------------------------------------

A virtual environment is an isolated Python installation, which can be activated/deactivated at will, and does not
interfere in the rest of your system.

First you will need to have Anaconda or Miniconda installed. If you are in doubt about this, just install **Miniconda**.

Once Anaconda/Miniconda is installed, create a new virtual environment called **astroenv** (or any name you like):

.. code:: shell

   conda create --name astroenv python=3.11

Activate this new virtual environment:

.. code:: shell

   source activate astroenv

Now, install PyQt5 manually using the following:

.. code:: shell

   conda install pyqt

.. note:: **(about PyQt5)** The correct installation of PyQt5 can be challenging depending on one's system.
          The above solution was found to work in July 2023. It is important to use ``conda`` (**not** ``pip``) for the
          installation of PyQt5.

Now install package ``f311``:

.. code:: shell

   pip install f311

To activate the environment:

.. code:: shell

   source activate astroenv

To deactivate the environment:

.. code:: shell

   source deactivate

Installing F311 in Developer Mode
---------------------------------

.. note:: Install F311 in developer mode only if you want to make changes to the source code.

First, set up Anaconda/Miniconda and install PyQt5 as described above.

Then, clone the F311 GitHub repository:

.. code:: shell

   git clone ssh://git@github.com/trevisanj/f311.git

or

.. code:: shell

   git clone http://github.com/trevisanj/f311

Finally, install F311 in **developer mode**:

.. code:: shell

   cd f311
   python setup.py develop

Upgrading package ``f311``
--------------------------

If package ``f311`` is already installed, but you need to install a new version, please follow these instructions.

Upgrading in the majority of cases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Package ``f311`` can be upgraded to a new version by typing::

    pip install f311 --upgrade


Upgrading F311 in developer mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enter the `f311` repository (directory) cloned from Github, then type::

    git pull
    python setup.py develop


Package dependencies
--------------------

``f311`` package dependencies are listed below. This list is provided only for reference, as **most of these
packages should be automatically installed** during the installation process (except for ``pyqt``).

- numpy
- scipy
- matplotlib
- astropy
- configobj
- bs4
- lxml
- robobrowser
- requests
- tabulate
- rows
- pyqt
- a99

Troubleshooting installation
----------------------------

This section shows some possible errors and their solutions.

PtQt5
~~~~~

If you have PyQt5-related errors such as the following::

    ImportError: [...]/QtGui.abi3.so: undefined symbol: _ZdaPvm, version Qt_5

be sure to follow the above instructions to install PyQt5.

MatPlotLib and PyQt5
~~~~~~~~~~~~~~~~~~~~

.. code:: shell

   ValueError: Unrecognized backend string "qt5agg": valid strings are ['GTKAgg', 'template', 'pdf',
   'GTK3Agg', 'cairo', 'TkAgg', 'pgf', 'MacOSX', 'GTK', 'WX', 'GTKCairo', 'Qt4Agg', 'svg', 'agg',
   'ps', 'emf', 'WebAgg', 'gdk', 'WXAgg', 'CocoaAgg', 'GTK3Cairo']

**Solution**: upgrade Matplotlib to version 1.4 or later

Problems with package bs4
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: shell

  bs4.FeatureNotFound: Couldn't find a tree builder with the features you requested: lxml. Do you need to install a parser library?

**Solution**: install package "lxml"::

    pip install lxml

Other problems
~~~~~~~~~~~~~~
If you have other installation problems or have a suggestion, please open an issue at the project
site on `GitHub <http://github.com/trevisanj/f311>`_.