Table Of Contents

Previous topic

Tutorials

Next topic

Getting started with ctools

Getting started with gammalib

“GammaLib is a self-contained, instrument independent, open source, multi-platform C++ library that implements all code required for high-level science analysis of astronomical gamma-ray data. GammaLib is also wrapped into a Python module.”

—Jürgen Knödlseder (GammaLib lead; on the GammaLib webpage)

GammaLib has a lot of great functionality, but very little documentation to get started.

This is a tutorial-style 10 minute introduction to gammalib to get you started.

Setup

Please follow the installation instructions or if you are adventurous get the latest and greatest version from github and install gammalib, then init the $GAMMALIB/gammalib-init.sh file. To check that your setup is OK use these commands:

$ pkg-config --modversion gammalib
0.8
$ python -c 'import gammalib'

Note

If pkg-config or Python can’t find gammalib for some reason, the following commands might help you figure out why:

echo $GAMMALIB
echo $PATH
echo $LD_LIBRARY_PATH  ( sometimes called $DYLD_LIBRARY_PATH on Mac )
echo $PYTHONPATH
which python

Warning

This tutorial is supposed to work with the latest version, i.e. the devel branch from the git repository at https://github.com/gammalib/gammalib . Compared to the latest released version gammalib 0.7 there have been a few small API changes, e.g. it’s now GModelSpectralPlaw(double norm, double index, GEnergy pivot) instead of GModelSpectralPlaw(double norm, double index, double pivot) (the type of the third parameter changed), so trying to run the examples with gammalib 0.7 will give an error.

As mentioned above, you can use GammaLib from C++ or from Python. We’ll start with Python.

First Python example

Without further ado ... make_crab_model.py shows how you code GammaLib in Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
"""Create a Crab source model, print it to screen and save it in XML format"""

# Import the gammalib Python package 
import gammalib

# Create the spatial part of the Crab source model
ra, dec = 83.6331, 22.0145
direction = gammalib.GSkyDir()
direction.radec_deg(ra, dec)
spatial_model = gammalib.GModelSpatialPointSource(direction)

# Create the spectral part of the Crab source model
# HEGRA publication : 2004ApJ...614..897A
norm, index = 2.83e-11, -2.62
pivot_energy = gammalib.GEnergy(1, 'TeV')
spectral_model = gammalib.GModelSpectralPlaw(norm, index, pivot_energy)

# Create complete model and print it to the console
model = gammalib.GModelSky(spatial_model, spectral_model)
print(model)

# To store the model in an XML file we need to put it in a models container
models = gammalib.GModels()
models.append(model)
models.save('crab.xml')

Hopefully the code is pretty much self-explanatory ... we import the gammalib package and then use it by constructing GSkyDir, GModelSpatialPointSource, GEnergy GModelSpectralPlaw, GModelSky and GModels objects and calling methods on them. Note that we simply pass Python float, int and string parameters and in the background these are automatically converted to C++ parameters and the corresponding Gammalib C++ code is executed. Even calling print() on a gammalib.GModelSky object works.

To execute the script, run this in the shell:

$ python make_crab_model.py

or if you like working in the IPython shell:

$ ipython
...
In [1]: %run make_crab_model.py

The script will create the gammalib.GModelSky object and print it to the console:

=== GModelSky ===
 Name ......................: 
 Instruments ...............: all
 Instrument scale factors ..: unity
 Observation identifiers ...: all
 Model type ................: PointSource
 Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
 Number of parameters ......: 6
 Number of spatial par's ...: 2
  RA .......................: 83.6331 deg (fixed,scale=1)
  DEC ......................: 22.0145 deg (fixed,scale=1)
 Number of spectral par's ..: 3
  Prefactor ................: 2.83e-11 +/- 0 [0,infty[ ph/cm2/s/MeV (free,scale=2.83e-11,gradient)
  Index ....................: -2.62 +/- 0 [10,-10]  (free,scale=-2.62,gradient)
  PivotEnergy ..............: 1e+06 MeV (fixed,scale=1e+06,gradient)
 Number of temporal par's ..: 1
  Constant .................: 1 (relative value) (fixed,scale=1,gradient)

and write the following crab.xml model description to file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<source_library title="source library">
  <source name="" type="PointSource">
    <spectrum type="PowerLaw">
      <parameter name="Prefactor" value="1" error="0" scale="2.83e-11" min="0" free="1" />
      <parameter name="Index" value="1" error="-0" scale="-2.62" min="-3.81679" max="3.81679" free="1" />
      <parameter name="Scale" value="1" scale="1e+06" free="0" />
    </spectrum>
    <spatialModel type="SkyDirFunction">
      <parameter name="RA" value="83.6331" scale="1" free="0" />
      <parameter name="DEC" value="22.0145" scale="1" free="0" />
    </spatialModel>
  </source>
</source_library>

Pretty nice ... you could give this model to a friend and she’d be able to use it like this:

$ ipython
...
In [1]: import gammalib
In [2]: models = gammalib.GModels('crab.xml')
In [3]: print models

First C++ example

Here’s the C++ version make_crab_model.cpp of the make_crab_model.py script shown above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Create a Crab source model, print it to screen and save it in XML format
#include <iostream>
#include <GammaLib.hpp>

int main(void) {
  // Create the spatial part of the Crab source model
  double ra = 83.6331, dec = 22.0145;
  GSkyDir direction;
  direction.radec_deg(ra, dec);
  GModelSpatialPointSource spatial_model(direction);

  // Create the spectral part of the Crab source model
  // HEGRA publication : 2004ApJ...614..897A
  double norm = 2.83e-11, index = -2.62;
  GEnergy pivot_energy(1, "TeV");
  GModelSpectralPlaw spectral_model(norm, index, pivot_energy);

  // Create complete model and print it to the console
  GModelSky model(spatial_model, spectral_model);
  std::cout << model << std::endl;

  // To store the model in an XML file we need to put it in a models container
  GModels models;
  models.append(model);
  models.save("crab.xml");
  return 0;
}

This is almost a 1:1 translation of the Python script, just the syntax is a bit different.

To compile and link this C++ source file into an executable, use this command:

c++ -o make_crab_model make_crab_model.cpp -I$GAMMALIB/include/gammalib -L$GAMMALIB/lib -lgamma

If you have a more complicated program consisting of multiple source files, or if you don’t want to remember this command, you can use the following Makefile as a starting point:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# Example Makefile for compiling and linking a C++ GammaLib program

# Put the name of the C++ file with the main() function here:
PROGRAM = make_crab_model
# List additional source files here:
SOURCES = make_crab_model.cpp

# You probably don't have to change the rest of this Makefile
CFLAGS = -I$(GAMMALIB)/include/gammalib
LDFLAGS = -L$(GAMMALIB)/lib -lgamma

%o: *.cpp
	$(CXX) -c -o $@ $< $(CFLAGS)

$(PROGRAM): $(SOURCES)
	$(CXX) -o $@ $^ $(CFLAGS) $(LDFLAGS)

clean:
	rm -f $(PROGRAM)

Now you only have to say make to create the make_crab_model executable:

$ make
c++ -o make_crab_model make_crab_model.cpp -I/usr/local/gamma/include/gammalib -L/usr/local/gamma/lib -lgamma

To execute the program:

$ ./make_crab_model

Warning

Using a different compiler in the gammalib build and in in your program build can result in weird linker errors. E.g. on the Mac the default compiler is clang and not gcc, so you should call clang++ instead of g++. On most systems c++ will call the default compiler and this will match the one that was used to build GammaLib. If you are having problems, try this:

$ which c++
$ c++ --version

To explicitly choose a C++ compiler with the Makefile you can specify it via the CXX environment variable:

$ CXX=clang++ make

Warning

Usually the pkg-config tool is used like this:

$ c++ -o make_crab_model make_crab_model.cpp `pkg-config --cflags --libs gammalib`

which should work everywhere and automatically create the correct compiler and linker flags. In gammalib this is currently broken though ... see issue 826 in the gammalib bug tracker.

Exploring the GammaLib API

So now you know how to run GammaLib from Python and C++. What is left is to learn the GammaLib API (application programming interface), i.e. the classes and functions that you can use to implement programs for gamma-ray data analysis. This section gives some hints to get you started.

The first thing you should realize is that GammaLib is large ... there are about 100,000 lines of C++ code and another 100,000 lines of comments in the C++ header .hpp and source .cpp files as you can see on Ohloh.

TODO

Second example: Creating a shell image

TODO

What next?

In the next tutorial, we will learn how to use the ctools.

If you want to learn more about GammaLib, check out the official tutorials / examples / tests:

TODO: link to github or Doxygen example files. TODO: convert examples to tutorials by integrating them into these docs ... specifically the simulated Galactic plane survey would be a great example.