Installing a local copy of the cWB libraries

Important

For the recommended CMake build (see below), the auxiliary libraries are provided by an activated conda environment – no manual library installation is needed.

For the traditional Makefile build, it is necessary to first install the auxiliary libraries manually; $HOME_LIB is the environment variable pointing to the auxiliary libraries path.

The cWB pipeline is implemented in the cWB library which contains the algorithms and the pipeline infrastructure. The pipeline uses the cWB config which contains the configurations files and the search procedures.

The following table reports the list of of steps to be executed to install the cWB pipeline:

1 - cWB config installation	the configurations-files and search-procedures
2 - cWB library installation	the algorithm-library and pipeline-infrastructure
3 - cWB www files setting	html, javascripts and images used by CEDs & reports
4 - cWB test installation	quick tests to check the cWB installation

1 - cWB config installation

What is: configuration files used by the cWB pipeline to perform the analysis

Note

We provide two git repositories:

https://gitlab.com/gwburst/public/config_o3.git

The public config_o3 repository contains the configuration files and the search procedures used for the production and post-production analysis of the O1, O2 and O3 observing runs, using the DATA released in the Gravitational Wave Open Science Center ( GWOSC ).
git.ligo.org:cWB/2g/config_o4.git

The current, O4 configuration used within the LVK collaboration. This repository is not yet publicly released (unlike config_o3, which covers O1-O3); until it is, LVK members should use it directly from git.ligo.org, and public users should refer to config_o3 above.

Installation:

Download cWB config from GIT Repository

The suggested local directory is $HOME/git/cWB/config_o3 (this is also the path expected by the IGWN-conda setup script, see the library README):
cd $HOME/git/cWB
git clone https://gitlab.com/gwburst/public/config_o3.git
cd config_o3
git lfs install --skip-smudge
git lfs pull -I XTALKS/wdmXTalk

# then, to use O3a run do:
make DATA=GWOSC O3=O3a
# or for O3b run:
make DATA=GWOSC O3=O3b
By default the downloaded repository is the last available version; to use a specific tagged version instead:
git tag                    # list the available tags
git checkout -b TAG TAG    # then select a suitable tag
LVK members with access to the restricted data (frame lists, data quality and xml files) can additionally pull the LVC branch inside the config_o3 checkout:
cd config_o3
git clone -b LVC git@git.ligo.org:cWB/config_o3.git LVC
cd LVC
git lfs install --skip-smudge

# lastly, from config_o3, create the symbolic links to the LVK data:
make DATA=LVC O3=O3a    # or O3=O3b

At CIT the tagged versions are available in the following directory:: /home/waveburst/SOFT/cWB/tags/config

2 - cWB library installation

What is: gravitational wave burst analysis software: algorithm library and pipeline infrastructure

Note

We provide two git repositories:

Both track the same release history (see the changelog); the LVK repository additionally carries LVK-only developments. The current release is documented in the changelog; a suggested tag is cWB-6.4.8.0.

Installation:

Two build systems are supported: the recommended CMake build (used by CI), and the traditional Makefile build, kept for backward compatibility.

CMake (recommended)

Activate a conda environment providing the auxiliary libraries. See the library README for the supported ROOT versions and known-good package combinations; the relevant conda-forge packages are root_base, healpix_cxx, cfitsio, libframel and, optionally, liblal liblalburst liblalmetaio liblalsimulation for LAL support:
```
conda activate your_cwb_env
```

Clone the repository:

cd $HOME/git/cWB
git clone https://gitlab.com/gwburst/public/library.git   # or the LVK repository
cd library

To use a specific tagged version instead of the latest commit:

git tag                    # list the available tags
git checkout -b TAG TAG    # e.g. cWB-6.4.8.0

Build and install, using the build.sh script. By default this installs under tools/install; passing an argument installs under tools/install_<argument> instead, which is convenient to keep several builds side by side:
```
bash build.sh            # -> tools/install
bash build.sh mybuild    # -> tools/install_mybuild
```
Extra CMake options can be passed via the CMAKE_ARGS environment variable, for example to build with up to 8 detectors instead of the default 4:
```
CMAKE_ARGS="-DXIFO=8" bash build.sh
```

Activate the installed environment:

source tools/install/etc/cwb/cwb-activate.sh   # (or tools/install_<argument>/etc/cwb/cwb-activate.sh)

Set the cross-talk catalog location, e.g.:

export CWB_CONFIG="$HOME/git/cWB/config_o3"
export HOME_WAT_FILTERS="${CWB_CONFIG}/XTALKS"

Traditional Makefile (legacy)

This is the historical, tcsh-based build. It requires the auxiliary libraries (ROOT, HEALPix, CFITSIO, FRAMELIB, and optionally LAL/CVODE) to be built and installed manually, see the auxiliary libraries section.

Setting the cWB environmental variables (The cWB init script)

- Copy the default init root file into the $HOME directory

    cp $HOME/git/cWB/library/tools/cwb/cwb.rootrc ~/.rootrc

- Create a directory used by cWB to display from WEB the CEDs and reports produced
  by the cWB analysis.

    Example for CIT user do :

      mkdir ~/public_html/reports

    reports can be browse at (user must be substituted with the user name):
    https://ldas-jobs.ligo.caltech.edu/~user/reports/

- Go into the cloned git library directory and select one of the following
  watenv init scripts suitable for your environment (sh,csh=bash,tcsh):

    - cit_watenv.(sh,csh)         -> default for CIT cluster
    - cnaf_watenv.(sh,csh)        -> default for CNAF cluster
    - atlas_watenv.(sh,csh)       -> default for ATLAS cluster
    - cascina_watenv.(sh,csh)     -> default for CASCINA cluster
    - gatech_watenv.(sh,csh)      -> default for GEORGIA-TECH cluster
    - virtualbox_watenv.(sh,csh)  -> default for VIRTUALBOX machine

- Copy the selected watenv init script:

    cp cit_watenv.(sh,csh) user_watenv.(sh,csh)

- Edit and change the environmental parameters according to the paths where the
  auxiliary libraries and config files have been installed.

    setenv HOME_LIBS "/home/waveburst/SOFT/"   # default location at CIT cluster
    setenv CWB_CONFIG "$HOME/git/cWB/config_o3"   # Location of cWB config

- Execute the init script

    source user_watenv.(sh,csh)

Compile library

- Go into the cloned git library directory execute your cWB init script:

    source user_watenv.(sh,csh)

- Compile cWB with the default settings (up to 4 detectors)

    make

- Install cWB libraries to the default directory ($HOME/git/cWB/library/tools/install)

    make install    # only install
    make winstall   # compile + install

  with this option only the compiled shared library files
  are copied to the destination directory

- It is possible to install cWB libraries into a specific directory:

    make install ODIR=your_specific_dir

  with this option all the library files and the compiled shared library files
  are copied to the destination directory (but the .git infos are excluded)

Compile cWB with specific options (the instructions refere to tcsh shell, for bash shell see for example $HOME/git/cWB/cit_watenv.sh):

- To compile cWB with up to 8 detectors capability

    make XIFO=8

- To compile cWB with/without LAL (default : enabled) set

    # disable

      unsetenv _USE_LAL          # disable LAL in cWB

    # enable

    setenv _USE_LAL      1     # enable LAL in cWB
    setenv HOME_LAL            "${HOME_LIBS}/LAL/lalsuite/master"
    setenv LAL_INC             "${HOME_LAL}/include"
    setenv LALINSPINJ_EXEC     "${HOME_LAL}/bin/lalapps_inspinj"

- To compile cWB with/without HEALPix (default : enabled) set

    # disable

    unsetenv _USE_HEALPIX      # disable HEALPix in cWB

    # enable

    setenv _USE_HEALPIX 1      # enable HEALPix in cWB
    setenv HOME_HEALPIX        "${HOME_LIBS}/HEALPix/Healpix_3.40"
    setenv HOME_CFITSIO        "${HOME_LIBS}/CFITSIO/cfitsio-3.45"

- To compile cWB with eBBH (default : enabled) set

    # disable

    unsetenv _USE_EBBH          # disable EBBH in cWB

    # enable

    setenv _USE_EBBH 1          # enable EBBH in CWB
    setenv HOME_CVODE            "${HOME_LIBS}/CVODE/sundials-2.7.0/dist"

Important

The cWB init script must located in the main cWB library directory, if the installation has been done in the non default directory then the destination directory must be used.

To check the cWB environmental variables use the command: cwb_watenv

3 - cWB WWW setup

cWB needs html files, javascripts and images to display the CEDs & reports from WEB. All such stuff must be located into a directory visible from WEB.

Note

For CIT cluster we suggest to use the pre-installed directory in the waveburst account:

/home/waveburst/public_html/waveburst/WWW/ced

which is the default path defined in the CIT init script file cwb_watenv.(sh.csh):

setenv HOME_CED_PATH “/home/waveburst/public_html/waveburst/WWW/ced”

To setup a local WWW directory use the script $CWB_SCRIPTS/cwb_create_www.sh. It is implemented for CIT user and VirtualBox Machine but it can be easily adapted others cases. To execute the script do:

1) activate the cWB environment (cwb-activate.sh for CMake, or the
   watenv init script for the traditional Makefile build)

2) cd <cWB library checkout directory>/tools/cwb/www   # $HOME_WAT for a traditional install

   make

3) $CWB_SCRIPTS/cwb_create_www.sh

In CIT cluster it creates the directory: $HOME/public_html/waveburst/WWW

4 - Test cWB installation

Note

The easiest way to check cWB has been installed correctly is to process with cWB the GWTC-1 public data released in GWOSC.

The analysis of GWTC-1 Catalog events can be easily performed with a dedicated cWB command: cwb_gwosc.

The command line to execute the full analysis of GW150914 event is:

cwb_gwosc GW=GW150914 all

The output of the previous command is the Coherent Event Display ( CED ) of the GW150914 event. See the CEDs of the GWTC-1 Catalog