Commit 509bf12b authored by karpov-sv's avatar karpov-sv
Browse files

Installation documentation is in ReST now

parent d9324daf
......@@ -40,6 +40,7 @@ extensions = [
"sphinx.ext.intersphinx",
"sphinx.ext.autosectionlabel",
"sphinx.ext.viewcode",
"sphinx-prompt",
]
mathjax_config = {
......
# Installation
Installation
============
*STDpipe* is available at [https://github.com/karpov-sv/stdpipe](https://github.com/karpov-sv/stdpipe) and is mirrored at [https://gitlab.in2p3.fr/icare/stdpipe](https://gitlab.in2p3.fr/icare/stdpipe)
*STDpipe* is available at https://github.com/karpov-sv/stdpipe and is mirrored at https://gitlab.in2p3.fr/icare/stdpipe.
In order to use it, you will need a working Python (>=3.6) installation, as well as a number of additional Python libraries and external packages. Below you will find some basic instructions how to set it up (using Anaconda environment as an example, but you may use any other as well) if you do not have it already.
## Preparing the environment (optional)
Preparing the environment (optional)
------------------------------------
The steps highlighted below are primarily for Linux and MacOS systems.
Windows users are advised to use WSL (preferrably Ubuntu 20.04) for smooth installation.
......@@ -14,127 +14,145 @@ Ubuntu 20.04 is available for free download on Microsoft Store.
You may safely skip these steps if you already have a working Python environment where you would like to install *STDPipe*.
Installing Anaconda
^^^^^^^^^^^^^^^^^^^
On your Linux/MacOS/WSL terminal, run the following commands to install `Anaconda <https://www.anaconda.com>`_ (replace 5.3.1 by the latest version, and adjust operating system name):
**Installing Anaconda**
.. prompt:: bash
On your Linux/MacOS/WSL terminal, run the following commands to install [Anaconda](https://www.anaconda.com) (replace 5.3.1 by the latest version, and adjust operating system name):
wget https://repo.anaconda.com/archive/Anaconda3-5.3.1-Linux-x86_64.sh
* $ wget https://repo.anaconda.com/archive/Anaconda3-5.3.1-Linux-x86_64.sh
.. prompt:: bash
* $ bash Anaconda3-5.3.1-Linux-x86_64.sh
bash Anaconda3-5.3.1-Linux-x86_64.sh
(For 32-bit installation, skip the ‘_64’ in both commands)
NOTE: If you already have Anaconda3 installed, please make sure that it is updated to the latest version (conda update --all). Also check that you do not have multiple
NOTE: If you already have Anaconda3 installed, please make sure that it is updated to the latest version (:code:`conda update --all`). Also check that you do not have multiple
versions of python installed in usr/lib/ directory as it can cause version conflicts while installing dependencies.
Now do:
* $ conda update --all
**Creating separate environment**
.. prompt:: bash
Create a new environment using this command (environment name is `stdpipe` in this case):
conda update --all
* $ conda create --name stdpipe
* $ conda activate stdpipe
NOTE: If this gives an error like:
CommandNotFoundError:
Your shell has not been properly configured to use 'conda activate', then run:
Installing basic dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* $ source ~/anaconda3/etc/profile.d/conda.sh
.. prompt:: bash
then proceed with conda activate nmma_env.
conda install numpy scipy astropy matplotlib pandas
Check python and pip version like this:
Install conda-forge dependencies
* $ python --version
* $ pip --version
.. prompt:: bash
Python 3.7 and above and Pip 21.2 and above is ideal for this installation. It is recommended to update these for your installation.
conda install -c conda-forge esutil astroscrappy
Install conda astropy dependencies
**Installing basic dependencies**
.. prompt:: bash
* $ conda install numpy scipy astropy matplotlib pandas
conda install -c astropy astroquery
Install conda-forge dependencies
* $ conda install -c conda-forge esutil astroscrappy
STDPipe installation
--------------------
Install conda astropy dependencies
Clone the STDPipe repository from GitHub at https://github.com/karpov-sv/stdpipe
* $ conda install -c astropy astroquery
.. prompt:: bash
git clone https://github.com/karpov-sv/stdpipe.git
## STDPipe installation
Change directory to the stdpipe folder:
.. prompt:: bash
Clone the STDPipe repository from GitHub at [https://github.com/karpov-sv/stdpipe](https://github.com/karpov-sv/stdpipe)
cd stdpipe
* $ git clone https://github.com/karpov-sv/stdpipe.git
Use the command below to install the rest of dependencies and the package itself in an *editable* manner so that it will be updated automatically when you update the code:
Change directory to the stdpipe folder:
.. prompt:: bash
* $ cd stdpipe
python setup.py develop
Use the commands below to install the rest of dependencies and the package itself in an *editable* manner so that it will be updated automatically when you update the code:
.. note::
* $ python setup.py develop
Alternative installation command (try it if the one above fails - they use slightly different strategies of installing the dependencies, so results may really vary!) would be
Alternative installation command (try it if the one above fails - they use slightly different strategies of installing the dependencies, so results may really vary!) would be
.. prompt:: bash
* $ pip install -e .
pip install -e .
**Keeping up to date**
Keeping up to date
^^^^^^^^^^^^^^^^^^
The command above installs the package to your Python environment in an *editable* way - it means that all changes you may make to the source tree (where you cloned the code) will immediately be reflected in the installed package, you do not need to repeat the installation.
As the code base in the repository evolves fast -- new features are being added, bugs fixed, etc -- it is a good idea to update your cloned code from the upstream often. The following command from inside stdpipe folder will do it:
* $ git pull
.. prompt:: bash
git pull
**Quick testing the installation**
Quick testing the installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run the following commands:
Run the following commands inside your python (e.g. after typing :code:`ipython`):
* $ ipython
* import stdpipe
* import stdpipe.photometry
* import stdpipe.cutouts
.. prompt:: python
import stdpipe
import stdpipe.photometry
import stdpipe.cutouts
NOTE (Okay, last one!): if everything is ok, it's the end of the installation. But in case it shows that such-and-such modules are absent, feel free to install those modules by visiting their anaconda documentation and install
those with their given commands. In case modules like photutils and statsmodels are needed, don't hesitate to do it with pip (normally it shouldn't happen), but some modules may not install correctly in case of disturbance.
This instruction file will likely cover the issues you might face during your installation. However, please open issues on GitHub if there appear to be unresolvable conflicts.
This instruction page will likely cover the issues you might face during your installation. However, please open issues on GitHub if there appear to be unresolvable conflicts.
## Installation of external packages
Installation of external packages
---------------------------------
*STDPipe* makes use of a number of (optional) external packages:
- [SExtractor](https://github.com/astromatic/sextractor)
- [SCAMP](https://github.com/astromatic/scamp)
- [PSFEx](https://github.com/astromatic/psfex)
- [SWarp](https://github.com/astromatic/swarp)
- [HOTPANTS](https://github.com/acbecker/hotpants)
- [Astrometry.Net](https://github.com/dstndstn/astrometry.net)
- `SExtractor <https://github.com/astromatic/sextractor>`__
- `SCAMP <https://github.com/astromatic/scamp>`__
- `PSFEx <https://github.com/astromatic/psfex>`__
- `SWarp <https://github.com/astromatic/swarp>`__
- `HOTPANTS <https://github.com/acbecker/hotpants>`__
- `Astrometry.Net <https://github.com/dstndstn/astrometry.net>`__
Most of them are also available in the repositories of various Linux distributions, and may be conveniently installed from there (see below).
HOTPANTS image subtraction package cannot presently (as far as I know) be installed from any package manager, and has to be compiled manually.
### Ubuntu
.. attention::
If HOTPANTS compilation fails for you on the linking stage with a number of :code:`multiple definition of` error messages - that's a `known bug <https://github.com/acbecker/hotpants/issues/5>`__ related to some recent changes in GCC compiler defaults. You may easily fix it by editing the :file:`Makefile` and adding :code:`-fcommon` switch among the others in the `COPTS` options (line `30 <https://github.com/acbecker/hotpants/blob/master/Makefile#L30>`__ at the moment of writing).
* $ sudo apt install sextractor scamp psfex swarp
Ubuntu
^^^^^^
.. prompt:: bash
sudo apt install sextractor scamp psfex swarp
Astrometry.Net may also be installed from repository, but might require additional manual configuration steps (and quite a lot of disk space for larger indices!), so install it only when you really need it, and when you really know what you are doing!
* $ sudo apt install astrometry.net
.. prompt:: bash
sudo apt install astrometry.net
Anaconda
^^^^^^^^
### Anaconda
.. prompt:: bash
* $ conda install -c conda-forge astromatic-source-extractor astromatic-scamp astromatic-psfex astromatic-swarp
conda install -c conda-forge astromatic-source-extractor astromatic-scamp astromatic-psfex astromatic-swarp
......@@ -4,6 +4,7 @@ sphinx_math_dollar
numpydoc
myst_parser
sphinxcontrib-apidoc
sphinx-prompt
extension-helpers
numpy
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment