Skip to content
Snippets Groups Projects

Docs

Merged Docs
james-clark/bayeswave:docs into master
Merged James Alexander Clark PhD requested to merge james-clark/bayeswave:docs into master
Compare
and
4 files
+ 129
− 72
Compare changes
  • Side-by-side
  • Inline
Files
4
doc/INSTALLATION.md
+ 106
− 52
@@ -5,11 +5,92 @@ There are 3 basic components to the BayesWave software package:
* BayesWavePipe workflow generation module (for writing HTCondor DAGs)
**Table of Contents**
1. [Build & Install C-executables](#installing-c-executables) (BayesWave, BayesWavePost et al)
1. [Python Postprocessing](#python-post-processing-codes) (megaplot.py, megasky.py et al)
1. [BayesWavePipe](#bayeswavepipe) (HTCondor workflow generation / make DAGs)
1. [Install everything](#install-everything)
1. [Build & Install C-executables](#installing-c-executables): BayesWave, BayesWavePost et al
1. [BayesWaveUtils](#bayeswaveutils): Plotting codes & HTCondor workflow generation / make DAGs
1. [Continuous Integration and Containerization](#continuous-integration-and-containerization)
## Install Everything
Assume bayeswave install path: `${HOME}/opt/lscsoft/bayeswave`:
```
export BAYESWAVE_REPO=${HOME}/src/lscsoft/bayeswave
export BAYESWAVE_PREFIX=${HOME}/opt/lscsoft/bayeswave
git clone git@git.ligo.org:lscsoft/bayeswave.git ${BAYESWAVE_REPO}
cd ${BAYESWAVE_REPO}
./install.sh ${BAYESWAVE_PREFIX}
```
This configures, builds and installs *all* executables and libraries (i.e.,
including python) to ${BAYESWAVE_PREFIX}. Upon successful installation, you
should see a message like:
```
*****************************************************************************
DONE: BayesWave built and installed to:
/home/albert.einstein/opt/lscsoft/bayeswave
To use:
source /home/albert.einstein/opt/lscsoft/bayeswave/etc/bayeswave-user-env.sh
*****************************************************************************
```
Source that file per the instructions and your environment will be ready to go.
The directory tree of your bayeswave installation looks something like:
```
├── bin
│ ├── BayesWave
│ ├── BayesWaveCleanFrame
│ ├── bayeswave_pipe
│ ├── BayesWavePost
│ ├── BayesWaveToLALPSD
│ ├── megaplot.py
│ └── megasky.py
├── etc
│ └── bayeswave-user-env.sh
└── lib
├── libbayeswave.a
├── libbayeswave.la
├── libbayeswave.so -> libbayeswave.so.0.0.0
├── libbayeswave.so.0 -> libbayeswave.so.0.0.0
├── libbayeswave.so.0.0.0
└── python2.7
└── site-packages
├── bayeswave_pipe
│ ├── bayeswave_pipe_utils.py
│ ├── bayeswave_pipe_utils.pyc
│ ├── __init__.py
│ └── __init__.pyc
├── bayeswave_pipe_examples
│ ├── LDG-GW150914
│ │ ├── LDG-GW150914.ini
│ │ └── makework-LDG-GW150914.sh
│ ├── LDG-GW150914-singularity
│ │ ├── LDG-GW150914-singularity.ini
│ │ └── makework-LDG-GW150914-singularity.sh
│ └── OSG-GW150914-singularity
│ ├── makework-OSG-GW150914-singularity.sh
│ ├── OSG-GW150914-singularity.ini
│ ├── status.sh
│ └── times.txt
├── bayeswave_plot
│ ├── find_trig.py
│ ├── find_trig.pyc
│ ├── __init__.py
│ ├── __init__.pyc
│ ├── readbwb.py
│ └── readbwb.pyc
├── bayeswave_plot_data
│ ├── BWBweb.css
│ ├── navigate.js
│ └── secure_ajax.js
└── BayesWaveUtils-0.1dev-py2.7.egg-info
```
The following notes may be useful for developers who wish to skip configuration
stages and unncessarily rebuilding/reinstalling unchanged components. Be aware,
however, that you may want to clean the `src` directory of build products if
you're changing C code.
## Installing C Executables
**Requirements**
@@ -21,25 +102,12 @@ There are 3 basic components to the BayesWave software package:
BayesWave is built using an autoreconf script which automatically configures
and builds a Makefile. There are two basic ways to build bayeswave executables:
1. Use the helper script `install.sh` (easy)
1. Use the helper script `install.sh` (easy, see above)
1. Execute build commands manually (harder)
### Using `install.sh` (easy)
The `install.sh` script takes a single input argument: the target directory to
install bayeswave to. Let `BAYESWAVE_SRC` be the top-level of the source
repository. Then to install to somewhere like `${HOME}/opt/bayeswave`:
```
cd ${BAYESWAVE_SRC}
export BAYESWAVE_PREFIX=${HOME}/opt/bayeswave
./install.sh ${BAYESWAVE_PREFIX}
```
will compile and link all required libraries and executables and places them in
`~/opt/bayeswave`.
### Manual Build (harder)
This procedure follows that of lalsuite. Again, assume the repository has been
### Manual Build
This procedure is similar to lalsuite. Again, assume the repository has been
cloned to `BAYESWAVE_SRC`.
First, generate the configuration files:
@@ -60,7 +128,12 @@ make
make install
```
## Python Post-processing Codes
This will install the non-python executables and libraries in the `bin` and
`lib` directories of your `BAYESWAVE_PREFIX` as above. You will then need to
set your environment accordingly. Note that there is an environment script
`BAYESWAVE_SRC/etc/bayeswave-user-env.sh` to help with this step.
## BayesWaveUtils
**Requirements**
* acor: a python port of a fast autocorrelation routine is required by
@@ -68,48 +141,29 @@ make install
installed manually. Details can be found at
[PyPi](https://pypi.org/project/acor/). The quick and dirty solution is
simply: `pip install acor --user`
The plotting and webpage generation does not currently have an installation
procedure and scripts/modules are accessed directly from the source repository.
Simply set your `PATH` and `PYTHONPATH` to contain the appropriate
`postprocess` and `utils` directories.
Assuming the `postprocess` and `utils` directories can be found at the location
pointed to by `BAYESWAVE_PREFIX`, set the following environment:
```
export PATH=${BAYESWAVE_PREFIX}/bin:${PATH}
export PATH=${BAYESWAVE_PREFIX}/postprocess:${PATH}
export PATH=${BAYESWAVE_PREFIX}/postprocess/dist:${PATH}
export PATH=${BAYESWAVE_PREFIX}/postprocess/skymap:${PATH}
export PATH=${BAYESWAVE_PREFIX}/postprocess/skymap/dist:${PATH}
export PYTHONPATH=${BAYESWAVE_PREFIX}/postprocess:${PYTHONPATH}
export PYTHONPATH=${BAYESWAVE_PREFIX}/postprocess/skymap:${PYTHONPATH}
export PYTHONPATH=${BAYESWAVE_PREFIX}/utils:${PYTHONPATH}
```
`BAYESWAVE_SRC/etc/bayeswave-user-env.sh` is a helper script for this step.
## BayesWavePipe
**Requirements**
* Swig-wrapped LALSuite: provides an easy interface for reading `sim-inspiral`
tables from XML
* Glue: provides tools for segment generation and HTCondor workflows management.
* `gw_data_find`: The script makes an external call to `gw_data_find` to
create frame cache files.
The pipeline module uses a standard python setup.py script. Starting from a
repository cloned to `BAYESWAVE_SRC`, we install to `BAYESWAVEPIPE_PREFIX` like:
```
cd ${BAYESWAVE_SRC}/BayesWavePipe
python setup.py install --prefix ${BAYESWAVEPIPE_PREFIX}
```
BayesWaveUtils consists of two packages and some supplementary data:
* bayeswave_plot: plotting utilities, skymaps etc
* bayeswave_plot_data: auxillary files for webpages (javascript, css, etc)
* bayeswave_pipe: HTCondor workflow generator
* bayeswave_pipe_examples: example configuration files for bayeswave_pipe
To install to your `${HOME}/.local` (**recommended**):
To install BayesWaveUtils to e.g., BAYESWAVE_PREFIX, enter the BayesWaveUtils
directory and:
```
python setup.py install --user
python setup.py install --prefix ${BAYESWAVE_PREFIX}
```
This will install the executable scripts, modules and data directories as
described in [Install everything](#install-everything). You will then need to
set your environment accordingly. Note that there is an environment script
`BAYESWAVE_SRC/etc/bayeswave-user-env.sh` to help with this step.
# Continuous Integration and Containerization
GitLab provides integrated continuous integration (CI) tools which can be used