.. _installation:

Requirements & Installation
===========================

.. note::

   This is entirely optional, but you may wish to sign up to the mailing list ``stpsf-users@maillist.stsci.edu``. This is a very low-traffic moderated announce-only list, to which we will periodically post announcements of updates to this software.

   To subscribe, visit  the `maillist.stsci.edu server <https://maillist.stsci.edu/scripts/wa.exe?SUBED1=STPSF-users&A=1>`_


.. NOTE: installation with conda is unavailable as of v1.1.0. uncomment and edit the following section once it's back.
  .. _install_with_conda:

  Recommended: Installing with conda
  ----------------------------------

  If you already use ``conda``, but do not want to install the full suite of STScI software, you can simply add the AstroConda *channel* and install STPSF as follows (creating a new environment named ``stpsf-env``)::

    $ conda config --add channels http://ssb.stsci.edu/astroconda
    $ conda create -n stpsf-env stpsf
    $ conda activate stpsf-env

  Upgrading to the latest version is done with ``conda update -n stpsf-env --all``.

  .. warning::

     You *must* install STPSF into a specific environment (e.g. ``stpsf-env``); our conda package will not work if installed into the default "root" environment.

.. _install_pip:

Installing with pip
-------------------

STPSF and its underlying optical library POPPY may be installed from the `Python Package Index <http://pypi.python.org/pypi>`_ in the usual manner for Python packages. ::

    $ pip install --upgrade stpsf
    [... progress report ...]

    Successfully installed stpsf


.. _synphot_install:

Installing or updating synphot
--------------------------------

Stsynphot is an optional dependency, but is highly recommended. Its installation instructions can be found in `the synphot docs <https://synphot.readthedocs.io/en/latest/#installation-and-setup>`_ or `a discussion in the POPPY docs <http://poppy-optics.readthedocs.io/en/stable/installation.html#installing-or-updating-synphot>`_.

.. _data_install:

Installing the Required Data Files
----------------------------------

.. note::
  The necessary data files will be installed automatically in a default path, ``$HOME/data/stpsf-data``, and there is no user action required unless you want to install them somewhere else.

Files containing such information as the JWST pupil shape, instrument throughputs, and aperture positions are distributed separately from STPSF. These sum to about 100 MB in size.

STPSF will now **automatically download and install these files** the first time it is run.  By default these will be downloaded and installed into a folder ``$HOME/data/stpsf-data``  within the user's home directory. This directory will be created automatically if it doesn't exist already. If this path is acceptable to you, then no further action is needed on your part, and it'll all work automatically.

*If you would like to place the data files at some other location*,  you can manually install the data files yourself.

1. Download the following file:  `stpsf-data-LATEST.tar.gz <https://stsci.box.com/shared/static/kqfolg2bfzqc4mjkgmujo06d3iaymahv.gz>`_  [approx. 175 MB]
2. Untar ``stpsf-data-LATEST.tar.gz`` into a directory of your choosing.
3. Set the environment variable ``STPSF_PATH`` to point to that directory. e.g. ::

    export STPSF_PATH=$HOME/data/stpsf-data

for bash. (You will probably want to add this to your ``.bashrc``, or equivalent for the shell of your choice.)

You should now be able to successfully ``import stpsf`` in a Python session.

.. warning::

   If you have previously installed the data files for an earlier version of STPSF, and then update to a newer version, the
   software may prompt you that you must download and install a new updated version of the data files.

.. Note::

   **For STScI Users Only:** Users at STScI may access the required data files from the Central Storage network. Set the following environment variables in your ``bash`` shell. (You will probably want to add this to your ``.bashrc``.) ::

      export STPSF_PATH="/grp/stpsf/stpsf-data"
      export PYSYN_CDBS="/grp/hst/cdbs"

Software Requirements
---------------------

See `the requirements.txt specification file <https://github.com/spacetelescope/stpsf/blob/develop/requirements.txt>`_ for the required package dependencies.

**Required Python version**: STPSF 1.1 and above require Python 3.10 or higher.

The major dependencies are the standard `NumPy, SciPy <http://www.scipy.org/scipylib/download.html>`_, `matplotlib <http://matplotlib.org>`_ stack, and `Astropy <http://astropy.org>`_.

**Recommended Python packages**:

* `synphot <https://synphot.readthedocs.io/>`_ enables the simulation
  of PSFs with proper spectral response to realistic source spectra.  Without
  this, PSF fidelity is reduced. See above for :ref:`installation instructions
  for synphot <synphot_install>`.  Stsynphot is recommended for most users.

**Optional Python packages**:

Some calculations with POPPY can benefit from the optional packages `psutil <https://pypi.python.org/pypi/psutil>`_ and `pyFFTW <https://pypi.python.org/pypi/pyFFTW>`_, but these are not needed in general. See `the POPPY installation docs <http://poppy-optics.readthedocs.io/en/stable/installation.html>`_ for more details.
These optional packages are only worth adding for speed improvements if you are spending substantial time running calculations.

Additional packages are needed for the optional use of GPUs to accelerate calculations. See the POPPY documentation.

.. _install_dev_version:

Installing a pre-release version or contributing to STPSF development
-----------------------------------------------------------------------

The `STPSF source code repository <https://github.com/spacetelescope/stpsf>`_ is hosted at GitHub, as is the repository for `POPPY <https://github.com/spacetelescope/poppy>`_. Users may clone or fork in the usual manner. Pull requests with code enhancements welcomed.

To install the current development version of STPSF, you can use ``pip`` to install directly from a ``git`` repository. To install STPSF and POPPY from ``git``, uninstall any existing copies of STPSF and POPPY, then invoke pip as follows::

    $ pip install -e git+https://github.com/spacetelescope/poppy.git#egg=poppy \
       -e git+https://github.com/spacetelescope/stpsf.git#egg=stpsf

This will create directories ``./src/poppy`` and ``./src/stpsf`` in your current directory containing the cloned repository. If you have commit access to the repository, you may want to clone via ssh with a URL like ``git+ssh://git@github.com:spacetelescope/stpsf.git``. Documentation of the available options for installing directly from Git can be found in the `pip documentation <http://pip.readthedocs.org/en/latest/reference/pip_install.html#git>`_.

Remember to :ref:`install the required data files <data_install>`, if you have not already installed them.

.. _specific_versions:

Using Specific Data Versions
--------------------------------

If you need a specific version of the STPSF data you can download it directly

| Full Versions:
| `stpsf-data-2.1.0.tar.gz <https://stsci.box.com/shared/static/ybp9cupdgxicsn3yj7p9ru9ivuyzcyfw.gz>`_
| `stpsf-data-2.0.0.tar.gz <https://stsci.box.com/shared/static/i3ui9gfypnhmu5ocec47ooci2ehwf9xf.gz>`_


| Min Versions:
| `minimal-stpsf-data-2.1.0.tar.gz <https://stsci.box.com/shared/static/z4wt613tg9txgfo5gc4qkvco1jzg74xe.gz>`_
| `minimal-stpsf-data-2.0.0.tar.gz <https://stsci.box.com/shared/static/4f0jrt20l1tagsmz9s3juxfacu4kgigm.gz>`_