.. include:: images.rst


Installation
--------------

This page provides a guide to the installation of the cWB pipeline.

.. note::
   The easiest ways to start using cWB on your computer are:

   - **conda-forge**: cWB is available as a `conda-forge <https://anaconda.org/conda-forge/cwb>`__ package.
     It can be installed with:

     .. code-block:: bash

         conda install -c conda-forge cwb

   - **IGWN conda**: cWB is included in the `IGWN conda distribution <https://computing.docs.ligo.org/conda/>`__.

   - **Docker**: cWB can be run inside a `Docker container <https://www.docker.com/docker-community>`__.
     Instructions are reported in the FAQs `here <faq.html#running-cwb-within-a-docker-container>`__.
   

Before installing cWB, all the needed
`auxiliary libraries <software.html#auxiliary-libraries>`__ have to be already installed. 

|LVK| : cWB libraries are already pre-installed on the LIGO-Virgo clusters together with the
auxiliary libraries. In case you want to compile a specific version or make some changes to the code, you can use
the pre-installed auxiliary libraries and
go directly to `cWB install <#how-to-install-the-cwb-libraries>`__. 

.. attention::
   cWB libraries have been tested mainly on Rocky Linux and Debian Linux distributions
   (though we don't expect major problems from installing cWB on different Linux distributions).
   cWB can also be installed on Mac OS X x86_64 (with some minor modifications). OSX on ARM (Apple Silicon) is not supported.

How to install the auxiliary libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::
   This manual, from-source installation is only needed for the
   **traditional Makefile** build (see :doc:`install/cwb`). For the
   recommended **CMake** build, activate a conda environment providing the
   auxiliary libraries instead (each per-library page below also documents
   its conda-forge package) -- no manual installation is required.

First, the directories where the packages will be installed must be created:

.. code-block:: bash

    setenv HOME_LIBS "user libraries path"
    mkdir $HOME_LIBS
    cd $HOME_LIBS
    mkdir ROOT FRAMELIB HEALPix CFITSIO LAL CVODE SKYMAP WAT

#. **ROOT** is an object oriented framework for large scale data analysis
#. **HEALPix** is an acronym for Hierarchical Equal Area isoLatitude Pixelization of a sphere
#. **CFITSIO** is a library of C and Fortran subroutines for reading and writing data files in FITS (Flexible Image Transport System) data format
#. **FRAMELIB** is software (Frame Library) dedicated to the frame manipulation including file input/output
#. **LAL** is a package including various gravitational wave data analysis routines
#. **CVODE** (used by eBBH) solves initial value problems for ordinary differential equation (ODE) systems

The following table reports the list of the auxiliary libraries and their instructions:

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Auxiliary-Libraries

   install/root
   install/framelib
   install/healpix
   install/cfitsio
   install/lal
   install/cvode
   install/skymap

+-------------------------------------------------------------+------------+----------------------------+
| `ROOT <install/root.html#root-installation>`__              |  mandatory |                            |
+-------------------------------------------------------------+------------+----------------------------+
| `FRAMELIB <install/framelib.html#framelib-installation>`__  |  mandatory |                            |
+-------------------------------------------------------------+------------+----------------------------+
| `HEALPix <install/healpix.html#healpix-installation>`__     |  mandatory |                            |
+-------------------------------------------------------------+------------+----------------------------+
| `CFITSIO <install/cfitsio.html#cfitsio-installation>`__     |  mandatory | needed by HEALPix          |
+-------------------------------------------------------------+------------+----------------------------+
| `LAL <install/lal.html#lal-installation>`__                 |  optional  | needed for CBC simulation  |
+-------------------------------------------------------------+------------+----------------------------+
| `CVODE <install/cvode.html#cvode-installation>`__           |  optional  | needed by eBBH simulation  |
+-------------------------------------------------------------+------------+----------------------------+
| `SKYMAP <install/skymap.html#skymap-installation>`__        |  optional  | produce skymap-display     |
+-------------------------------------------------------------+------------+----------------------------+


How to install the cWB libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Two scenarios are considered: 

.. toctree::
   :hidden:
   :maxdepth: 1
   :caption: cWB-Libraries

   install/cwb

#. **The user wants to perform an analysis with a local copy of the cWB libraries**: 
   `Installing a local copy of the cWB libraries <install/cwb.html#installing-a-local-copy-of-the-cwb-libraries>`__.

   .. note::
      recommended for users willing to use a specific version and/or customize the libraries

#. **The user wants to perform an analysis with the libraries already installed in the LVK computing clusters** |LVK|

   .. attention::
      Pre-installed libraries could be outdated and may change without notice.
      If you need a specific version you have to install a local copy of the cWB library 

   The cWB libraries are available in the following computing
   clusters: CIT and CNAF. The pre-installed libraries can be
   used by running the cWB configuration file. The environment is set up
   `as follows <faq.html#cwb-quick-startup>`__ (assuming **bash shell**):
   
   .. code-block:: bash

             source $HOME_LIBS/GIT/cWB/library/[cit/cnaf]_watenv.sh
             cp $HOME_LIBS/GIT/cWB/library/tools/cwb/cwb.rootrc ~/.rootrc

   The $HOME_LIBS path depends on the cluster:

   .. code-block:: bash

             CIT:  /home/waveburst/SOFT
             CNAF: /opt/exp_software/virgo/virgoDev/waveburst/SOFT

   | For the **tcsh shell**, replace \*_watenv.sh with \*_watenv.csh.