Skip to content

Commit

Permalink
update installation
Browse files Browse the repository at this point in the history
  • Loading branch information
@grburgess
grburgess committed Aug 1, 2022
1 parent 6bd363b commit 175af25
Show file tree
Hide file tree
Showing 2 changed files with 145 additions and 46 deletions.
33 changes: 27 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,21 +34,42 @@ A framework for multi-wavelength/multi-messenger analysis for astronomy/astrophy
</div>


Astrophysical sources are observed by different instruments at different wavelengths with an unprecedented quality. Putting all these data together to form a coherent view, however, is a very difficult task. Indeed, each instrument and data type has its own ad-hoc software and handling procedure, which present steep learning curves and do not talk to each other.

The Multi-Mission Maximum Likelihood framework (3ML) provides a common high-level interface and model definition, which allows for an easy, coherent and intuitive modeling of sources using all the available data, no matter their origin. At the same time, thanks to its architecture based on plug-ins, 3ML uses under the hood the official software of each instrument, the only one certified and maintained by the collaboration which built the instrument itself. This guarantees that 3ML is always using the best possible methodology to deal with the data of each instrument.
Astrophysical sources are observed by different instruments at different
wavelengths with an unprecedented quality. Putting all these data together to
form a coherent view, however, is a very difficult task. Indeed, each instrument
and data type has its own ad-hoc software and handling procedure, which present
steep learning curves and do not talk to each other.

The Multi-Mission Maximum Likelihood framework (3ML) provides a common
high-level interface and model definition, which allows for an easy, coherent
and intuitive modeling of sources using all the available data, no matter their
origin. At the same time, thanks to its architecture based on plug-ins, 3ML uses
under the hood the official software of each instrument, the only one certified
and maintained by the collaboration which built the instrument itself. This
guarantees that 3ML is always using the best possible methodology to deal with
the data of each instrument.

<img src="https://raw.githubusercontent.com/threeML/threeML/master/docs/media/3ml_flowchart.png" alt="drawing" width="800" align="right"/>


Though **Maximum Likelihood** is in the name for historical reasons, 3ML is an interface to several **Bayesian** inference algorithms such as MCMC and nested sampling as well as likelihood optimization algorithms. Each approach to analysis can be seamlessly switched between allowing users to try different approaches quickly and without having to rewrite their model or data interfaces.
Though **Maximum Likelihood** is in the name for historical reasons, 3ML is an
interface to several **Bayesian** inference algorithms such as MCMC and nested
sampling as well as likelihood optimization algorithms. Each approach to
analysis can be seamlessly switched between allowing users to try different
approaches quickly and without having to rewrite their model or data interfaces.

Like your [XPSEC](https://heasarc.gsfc.nasa.gov/xanadu/xspec/) models? You can use them in 3ML as well as our growing selection of 1-,2- and 3-D models from our fast and customizable modeling language [astromodels](http://astromodels.readthedocs.org/en/latest/).
Like your [XPSEC](https://heasarc.gsfc.nasa.gov/xanadu/xspec/) models? You can
use them in 3ML as well as our growing selection of 1-,2- and 3-D models from
our fast and customizable modeling language
[astromodels](http://astromodels.readthedocs.org/en/latest/).


## Installation

Installing with pip or conda is easy
Installing with pip or conda is easy. However, you want to include models from
[XSPEC](https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/Models.html), the
process can get tougher and we recommend the more detailed instructions:


```bash
pip install astromodels threeml
Expand Down
158 changes: 118 additions & 40 deletions docs/md_docs/fast_execute/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,48 +15,124 @@ jupyter:

<!-- #region -->
# Installation
3ML brings together multiple instrument and fitting software packages into a common framework. Thus, installing all the pieces can be a bit of a task for the user. In order to make this a less painless process, we have packaged most of the external dependencies into conda (see below). However, if you want more control over your install, 3ML is available on PyPI via pip. If you have issues with the installs, first check that you have properly installed all the external dependencies that *you* plan on using. Are their libraries accessible on you system's standard paths? If you think that you have everything setup properly and the install does not work for you, please [submit an issue](https://github.com/threeML/threeML/issues) and we will do our best to find a solution.
3ML brings together multiple instrument and fitting software packages into a
common framework. Thus, installing all the pieces can be a bit of a task for the
user. In order to make this a less painless process, we have packaged most of
the external dependencies into conda (see below). However, if you want more
control over your install, 3ML is available on PyPI via pip. If you have issues
with the installs, first check that you have properly installed all the external
dependencies that *you* plan on using. Are their libraries accessible on you
system's standard paths? If you think that you have everything setup properly
and the install does not work for you, please [submit an
issue](https://github.com/threeML/threeML/issues) and we will do our best to
find a solution.


## XSPEC models
We allow the ability to use the models provided by [XSPEC]() natively in
3ML. However, before installing [astromodels]() or 3ML, you must already have
XSPEC installed by one of a few methods.

### HEASARC install
If you have XSPEC installed on your computer via the source code, then before
installing astromodels, make sure to `init` your HEASARC environment. Upon
installing `astromodels`, the process will attempt to find the proper libraries
on your system if it detects XSPEC and compile the proper extensions. If you
have installed your XSPEC in a non-standard directory (e.g. your home
directory), the process my not find all the libraries. You can thus export an
env variable that provides the explicit path to your XSPEC headers:

```bash

export XPEC_INC_PATH=/path/to/xspec/headers

```

As XSPEC evolves, various models have different interfaces that depend on the
version. To accommodate this, you need to set the version of XSPEC you are using
with another env variable, e.g.:

```bash

export ASTRO_XPEC_VERSION='12.12.1'

```


### xspec-modelsonly

I{f using conda, it is possible to get access to XSPEC models without having to
install HEASOFT. We thus recommend the following command to create your new
conda environment:

```bash

conda create --name threeml -c conda-forge -c xpsecmodels python=3.7 xpsec-modelsonly numpy scipy matplotlib
```

This must be done *before* installing `astromodels`.


## Conda installation

[Conda](https://conda.io/docs/) is a platform independent package manager. It allows to install 3ML (and a lot of other software) without the need
to compile anything, and in a completely separate environment from your system and your system python.
[Conda](https://conda.io/docs/) is a platform independent package manager. It
allows to install 3ML (and a lot of other software) without the need to compile
anything, and in a completely separate environment from your system and your
system python.

### If you don't know Conda

If you are not familiar with conda, install 3ML with the automatic script which will take care of everything:
If you are not familiar with conda, install 3ML with the automatic script which
will take care of everything:

1. Download the script from [here](https://raw.githubusercontent.com/threeML/threeML/master/install_3ML.sh)
2. Run the script with `bash install_3ML.sh`. If you plan to use XSPEC models use `bash install_3ML.sh --with-xspec`.
3. The script will install 3ML and then create a `threeML_init.sh` script and a `threeML_init.csh` script. Source the former if you are using Bash
(`source threeML_init.sh`) and the second one if you are using Csh/Tcsh (`source threeML_init.csh`).
1. Download the script from
[here](https://raw.githubusercontent.com/threeML/threeML/master/install_3ML.sh)
2. Run the script with `bash install_3ML.sh`. If you plan to use XSPEC models
use `bash install_3ML.sh --with-xspec`.
3. The script will install 3ML and then create a `threeML_init.sh` script and a
`threeML_init.csh` script. Source the former if you are using Bash (`source
threeML_init.sh`) and the second one if you are using Csh/Tcsh (`source
threeML_init.csh`).

### If you already know Conda

If you are familiar with Conda and you already have it installed, you can install 3ML by creating an environment with:
If you are familiar with Conda and you already have it installed, you can
install 3ML by creating an environment with (*note the exceptions above
w.r.t. to include XSPEC support*):

```bash
conda create --name threeML -c conda-forge python=3.7 numpy scipy matplotlib
```

then activating your environment and installing 3ML as:
then activating your environment:

```bash
conda activate threeML
conda install -c conda-forge -c threeml astromodels threeml

```

Finally, if you also need XSPEC models you can install them by running:
*NOTE:* Recently a third party has uploaded a version of `astromodels` to the
conda-forge channel. This version will break support for XSPEC currently if you
used the xspec-modelsonly package. It is important to set your conda channel
priority so that the threeml channel has priority over the conda-forge
channel. Please verify that the `astromodels` installed comes from our threeml
channel. We are working to resolve this hassle and we apologize to our users.



```bash
conda install -c xspecmodels xspec-modelsonly
conda install -c conda-forge -c threeml astromodels threeml

```


## pip

If you would like to install 3ML and astromodels on their own and have more control over which dependencies you would like to use. Please to the following
If you would like to install 3ML and astromodels on their own and have more
control over which dependencies you would like to use. Please to the following

1. It is highly recommended you work within a python virtual environment to keep you base python clean
1. It is highly recommended you work within a python virtual environment to keep
you base python clean
2. install astromodels

```bash
Expand All @@ -69,29 +145,34 @@ pip install astromodels
pip install threeml
```

If you need to build other dependencies such as pagmo, multinest, XSPEC, etc., it is recommended you do this **before** installing astromodels!
If you need to build other dependencies such as pagmo, multinest, XSPEC, etc.,
it is recommended you do this **before** installing astromodels!

## Docker

A docker with the complete 3ML environment and all dependencies can be installed with
A docker with the complete 3ML environment and all dependencies can be installed
with

```bash
docker pull threeml/notebook:latest
```

which will install a docker taht can be launched with
which will install a docker that can be launched with

```bash
docker run -it --rm -p 8888:8888 -v $PWD:/workdir -w /workdir threeml/notebook
```

which will launch a notebook server that can operate on the current directory. The notebooks and be accessed by typing `localhost:8888` in your browser.
which will launch a notebook server that can operate on the current
directory. The notebooks and be accessed by typing `localhost:8888` in your
browser.


## Other dependencies

You need to set up packages such as AERIE (for HAWC), or the Fermi Science Tools,
before running the script, otherwise some of the functionalities will not work.
You need to set up packages such as AERIE (for HAWC), or the Fermi Science
Tools, before running the script, otherwise some of the functionalities will not
work.

* AERIE for HAWC: make sure that this works before running the script:

Expand All @@ -103,19 +184,12 @@ before running the script, otherwise some of the functionalities will not work.
Aerie version: 2.04.00
Build type: Debug

```
If it doesn't, you need to set up the HAWC environment (refer to the appropriate
documentation)
``` If it doesn't, you need to set up the HAWC environment (refer to the
appropriate documentation)
* Fermi Science Tools for Fermi/LAT analysis: make sure that this works:
```bash
> gtirfs
...
P8R2_TRANSIENT100_V6::EDISP0
P8R2_TRANSIENT100_V6::EDISP1
...
```
If it doesn't, you need to configure and set up the Fermi Science Tools.
* Fermi Science Tools for Fermi/LAT analysis: make sure that this works: ```bash
> gtirfs ... P8R2_TRANSIENT100_V6::EDISP0 P8R2_TRANSIENT100_V6::EDISP1 ...
``` If it doesn't, you need to configure and set up the Fermi Science Tools.
* ROOT: ROOT is not required by 3ML, but it provides the Minuit2 minimizer which can
be used in 3ML. If you have ROOT, make sure that this works before running the script:
Expand All @@ -142,22 +216,26 @@ then:
> pip install git+https://github.com/threeML/astromodels.git --upgrade
```

In order to use the HAWC plugin, you will also need to install cthreeML (run this *after* setting up the HAWC environment):
In order to use the HAWC plugin, you will also need to install cthreeML (run
this *after* setting up the HAWC environment):

```bash
> pip install git+https://github.com/threeML/cthreeML.git
```

* NOTE: If you do not have permission to install packages in your current python
environment, you can still install the packages by adding the ```--user``` option at the
end of each ```pip``` command.
* NOTE: If you do not have permission to install packages in your current python
environment, you can still install the packages by adding the ```--user```
option at the end of each ```pip``` command.

### Tips for Mac users
The following paths need to be added to you DYLD_LIBRARY path if you have FORTRAN installed via these package managers:
The following paths need to be added to you DYLD_LIBRARY path if you have
FORTRAN installed via these package managers:

* Homebrew: ```DYLD_LIBRARY_PATH=/usr/local/lib/gcc/<version number>:$DYLD_LIBRARY_PATH```
* Homebrew: ```DYLD_LIBRARY_PATH=/usr/local/lib/gcc/<version
number>:$DYLD_LIBRARY_PATH```

* Fink: ```DYLD_LIBRARY_PATH=/sw/lib/gcc<version number>/lib:$DYLD_LIBRARY_PATH```
* Fink: ```DYLD_LIBRARY_PATH=/sw/lib/gcc<version
number>/lib:$DYLD_LIBRARY_PATH```

Please inform us if you have problems related to your FORTRAN distribution.

Expand Down

0 comments on commit 175af25

Please sign in to comment.