Updated 11 months ago by Knödlseder Jürgen

GammaLib directory structure¶

This page explains the directory structure of GammaLib. Note that this description applies to the directory that is obtained by cloning the Git repository. For a source code release, Python wrapper files will be present, and also some documentation will be shipped in pdf format. The directory structure of a source code release will thus differ in details.

The directory structure is shown here as it would appear using the ls -la command on a Linux machine. Note that file sizes may differ for your actual copy of the source code as the software evolves.

GammaLib directory¶

The gammalib directory after cloning from the GammaLib Git repository will have the following content:

drwxr-xr-x   13 jurgen  staff    442 12 oct 21:35 .git            <= Git information
-rw-r--r--    1 jurgen  staff    218 12 oct 21:35 AUTHORS
-rw-r--r--    1 jurgen  staff  35146 12 oct 21:35 COPYING
-rw-r--r--    1 jurgen  staff   6358 12 oct 21:35 ChangeLog
-rw-r--r--    1 jurgen  staff  11397 12 oct 21:35 INSTALL
-rw-r--r--    1 jurgen  staff   6139 12 oct 21:35 Makefile.am     <- automake input file
-rw-r--r--    1 jurgen  staff   2770 12 oct 21:35 NEWS
-rw-r--r--    1 jurgen  staff  11606 12 oct 21:35 README
-rwxr-xr-x    1 jurgen  staff    228 12 oct 21:35 autogen.sh      <- autotools generation script
-rw-r--r--    1 jurgen  staff  52654 12 oct 21:35 configure.ac    <- autoconf input file
drwxr-xr-x    9 jurgen  staff    306 12 oct 21:35 dev             <= code development utilities
drwxr-xr-x    8 jurgen  staff    272 12 oct 21:35 doc             <= GammaLib documentation
drwxr-xr-x    3 jurgen  staff    102 12 oct 21:35 examples        <= GammaLib usage examples
-rw-r--r--    1 jurgen  staff    397 12 oct 21:35 gammalib.pc.in  <- pkgconfig input file
drwxr-xr-x  129 jurgen  staff   4386 12 oct 21:35 include         <= include files for instrument independent code
drwxr-xr-x    6 jurgen  staff    204 12 oct 21:35 inst            <= instrument dependent code
drwxr-xr-x   12 jurgen  staff    408 12 oct 21:35 m4              <= autoconf macros
drwxr-xr-x  128 jurgen  staff   4352 12 oct 21:35 pyext           <= Python binding definition files (for swig)
drwxr-xr-x   18 jurgen  staff    612 12 oct 21:35 src             <= instrument independent code
drwxr-xr-x   52 jurgen  staff   1768 12 oct 21:35 test            <= code for unit testing
-rwxr-xr-x    1 jurgen  staff   1418 12 oct 21:35 testall.sh      <- extended test script

GammaLib uses autotools for configuration (see below). There are two central input files that will be used by autotools: Makefile.am will be used to generate Makefile, which is the script invoked by the make command. configure.ac will be used to generate configure, which is the script that is called for configuration of the software prior to compilation.

GammaLib supports the pkg-config helper system. The file gammalib.pc.in will be used to generate gammalib.pc using the autotools.

In the following, the subdirectories of the gammalib directory are described.

dev¶

The dev directory contains are couple of scripts and files that are useful for GammaLib development and GammaLib release. Most developers will not need to use one of these scripts. Below the content of the dev directory:

-rw-r--r--  1 jurgen  staff    925 12 oct 21:35 license_new.txt      <- New license text (used by replace_license.py)
-rw-r--r--  1 jurgen  staff    308 12 oct 21:35 license_old.txt      <- Old license text (used by replace_license.py)
-rwxr-xr-x  1 jurgen  staff   5122 12 oct 21:35 macosx_package.sh    <- Create a GammaLib / ctools binary for packaging
-rwxr-xr-x  1 jurgen  staff  13654 12 oct 21:35 macosx_testconf.sh   <- Tests GammaLib under various Mac OS X configurations
-rwxr-xr-x  1 jurgen  staff  12016 12 oct 21:35 macosx_testpkg.sh    <- Tests GammaLib / ctools Mac OS X package prior to release
-rwxr-xr-x  1 jurgen  staff   2997 12 oct 21:35 release_gammalib.sh  <- Create a GammaLib release
-rwxr-xr-x  1 jurgen  staff   2586 12 oct 21:35 replace_license.py   <- Replace license text in all source and include files

doc¶

The doc directory contains the GammaLib documentation. Here the content of the directory:

-rw-r--r--   1 jurgen  staff  57183 12 oct 21:35 Doxyfile  <- Configuration file for generation of Doxygen documentation
drwxr-xr-x   8 jurgen  staff    272 12 oct 21:35 dev       <= Development documentation
drwxr-xr-x  14 jurgen  staff    476 12 oct 21:35 html      <= Web documentation
drwxr-xr-x   3 jurgen  staff    102 12 oct 21:35 um        <= User Manual

GammaLib uses Doxygen to generate the reference documentation. The file Doxyfile contains the Doxygen configuration that is applied for this generation.

The dev directory contains all documentation that is relevant for code development. It contains a number of subdirectories, one for each development document (except of the tn directory which contains all technical notes of the project). Here the actual content of dev:

drwxr-xr-x  4 jurgen  staff  136 12 oct 21:35 coding  <= Coding and Design Conventions
drwxr-xr-x  7 jurgen  staff  238 12 oct 21:35 inst    <= Instrument specific interface
drwxr-xr-x  5 jurgen  staff  170 12 oct 21:35 maths   <= Mathematical Implementation
drwxr-xr-x  6 jurgen  staff  204 12 oct 21:35 sdd     <= Software Design Description
drwxr-xr-x  4 jurgen  staff  136 12 oct 21:35 srs     <= Software Requirement Specification
drwxr-xr-x  4 jurgen  staff  136 12 oct 21:35 tn      <= Technical Notes

The html directory contains all Web documentation of GammaLib. The Web documentation is published at the following sourceforge site: http://gammalib.sourceforge.net/

The um directory contains the User Manual for GammaLib.

Note that much of the documentation is not up to date. The only document that can be considered reasonably complete are the "Coding and Design Conventions".

examples¶

This directory contains example code that illustrates the usage of GammaLib. So far, only a single example named readmodel exists. To compile this example, step into the examples/readmodel directory and type

$ make

Note that GammaLib needs to be installed prior to compilation. Also, the Makefile assumes that GammaLib has been installed in the path /usr/local/gamma. If GammaLib is installed in a different location, please adjust the Makefile.

include¶

The include directory contains all instrument independent header files for GammaLib. The directory is flat, i.e. no structuration into modules exists.

To add a new class to GammaLib, simply add a header file to this directory. Add the name of the header file also to the Makefile.am script, and add a

#include "GClass.hpp" 

directive to GammaLib.hpp to include the new header in the GammaLib master header file (in this example we supposed that the new header file is named GClass.hpp).

inst¶

This directory contains the instrument specific source code. There is one directory per instrument. The Makefile.am gathers information for all subdirectories, and it is one of the files that needs to be adapted when a new instrument should be added.

A typical instrument specific directory has the following structure (here the example of cta):

-rw-r--r--   1 jurgen  staff  2732 12 oct 21:35 Makefile.am  <- automake input file
drwxr-xr-x  15 jurgen  staff   510 12 oct 21:35 caldb        <= calibration data
drwxr-xr-x  21 jurgen  staff   714 12 oct 21:35 include      <= include files
drwxr-xr-x  20 jurgen  staff   680 12 oct 21:35 pyext        <= Python binding definition files (for swig)
drwxr-xr-x  24 jurgen  staff   816 12 oct 21:35 src          <= source code
drwxr-xr-x  18 jurgen  staff   612 12 oct 21:35 test         <= code for unit testing

The Makefile.am is the input file that will be used by automake to generate a Makefile. This file needs to be modified if code is added to the interface.

The structure of the caldb directory depends strongly on the instrument. The data contained in this directory will be used for unit testing, and will be installed together with the software.

The include directory is a flat directory, containing all header files for the instrument dependent code. It's structure is similar to the include directory of the instrument independent code. Instead of the GammaLib.hpp file (which gathers all headers for the instrument independent code), a file gathering all headers for the instrument dependent code will exist (for CTA this file is named GCTALib.hpp).

The pyext directory is a flat directory, containing all interface files that will be processed by swig to create the Python wrapper files. There is one interface file for each class. All interface files a gathered in a summary file (for CTA this file is named cta.i). If a class interface should be added it is sufficient to add the respective file to the summary file.

The src directory is a flat directory, containing all source code.

The test directory contains all code and data needed for unit testing. In addition, it may contain an (arbitrary) number of test scripts and programs that are useful for testing the functionalities of the instrument specific interface. Here the example for the cta interface:

-rw-r--r--   1 jurgen  staff    982 12 oct 21:35 README
drwxr-xr-x  14 jurgen  staff    476 12 oct 21:35 data
-rwxr-xr-x   1 jurgen  staff   2338 12 oct 21:35 example_binned_ml_fit.py
-rwxr-xr-x   1 jurgen  staff   1672 12 oct 21:35 example_make_model.py
-rwxr-xr-x   1 jurgen  staff   3889 12 oct 21:35 example_sim_photons.py
-rw-r--r--   1 jurgen  staff  20474 12 oct 21:35 test_CTA.cpp
-rw-r--r--   1 jurgen  staff   3868 12 oct 21:35 test_CTA.hpp
-rwxr-xr-x   1 jurgen  staff   1578 12 oct 21:35 test_CTA.py
-rwxr-xr-x   1 jurgen  staff   1998 12 oct 21:35 test_gauss.py
-rwxr-xr-x   1 jurgen  staff   5056 12 oct 21:35 test_irf_offset.py
-rwxr-xr-x   1 jurgen  staff   1561 12 oct 21:35 test_irf_trafo.py
-rwxr-xr-x   1 jurgen  staff   6408 12 oct 21:35 test_model.py
-rwxr-xr-x   1 jurgen  staff   3388 12 oct 21:35 test_npred_computation.py
-rwxr-xr-x   1 jurgen  staff   3492 12 oct 21:35 test_npred_intergation.py
-rwxr-xr-x   1 jurgen  staff   2393 12 oct 21:35 test_radial_acceptance.py
-rwxr-xr-x   1 jurgen  staff   1944 12 oct 21:35 test_response_table.py

The README file contains more information about the various test files that exist in this directory. The data directory contains data needed for unit testing. The files test_CTA.cpp and test_CTA.hpp are used for unit testing of the C++ code, the file test_CTA.py is used for unit testing of the Python interface.

m4¶

This directory contains autoconf macros. Some of the macros are actually used by the configure script during testing of the system configuration, other macros are still there for legacy.

In case you need to add a test to the configure script that makes use of a non-standard macro, please add the macro to this folder to make sure that it will be available during the configuration step.

pyext¶

The pyext directory contains all interface files that will be processed by swig to create the Python wrapper files. There is one interface file for each class. All these files are directly located in the pyext directory.

The Python interface is organized into modules, mainly to reduce the size of the Python wrapper code. The definitions of the modules are found in the gammalib subdirectory, which has the following content:

-rw-r--r--  1 jurgen  staff  2194 12 oct 21:35 app.i
-rw-r--r--  1 jurgen  staff  3024 12 oct 21:35 fits.i
-rw-r--r--  1 jurgen  staff  2234 12 oct 21:35 linalg.i
-rw-r--r--  1 jurgen  staff  3101 12 oct 21:35 model.i
-rw-r--r--  1 jurgen  staff  2209 12 oct 21:35 numerics.i
-rw-r--r--  1 jurgen  staff  2543 12 oct 21:35 obs.i
-rw-r--r--  1 jurgen  staff  2225 12 oct 21:35 opt.i
-rw-r--r--  1 jurgen  staff  2348 12 oct 21:35 sky.i
-rw-r--r--  1 jurgen  staff  2070 12 oct 21:35 support.i
-rw-r--r--  1 jurgen  staff  2186 12 oct 21:35 test.i
-rw-r--r--  1 jurgen  staff  2298 12 oct 21:35 xml.i

Each of these files is a summary file for one module. By means of %include directives, each summary file includes the interface files that should be gathered into the module. If a new class should be added to a module you have to add an %include directive to the respective module. Please make sure that a given interface file is not included in several modules.

The pyext directory contains a Makefile.am that defines how the modules will be built. The files needs to be modified when a new module (or a new instrument) should be added. If a new class is added to an existing module, no modification is required.

The directory also contains a file setup.py.in that is used for building and installing the Python wrappers. This file will be converted into a file setup.py by the configuration step. The files needs to be modified when a new module (or a new instrument) should be added. If a new class is added to an existing module, no modification is required.

src¶

The src directory is where all instrument independent source code lives. The directory has the following content:

-rw-r--r--   1 jurgen  staff  2074 12 oct 21:35 Makefile.am
drwxr-xr-x   8 jurgen  staff   272 12 oct 21:35 app
drwxr-xr-x  36 jurgen  staff  1224 12 oct 21:35 fits
-rwxr-xr-x   1 jurgen  staff   814 12 oct 21:35 gammalib-init.csh
-rwxr-xr-x   1 jurgen  staff   793 12 oct 21:35 gammalib-init.sh
-rw-r--r--   1 jurgen  staff  5636 12 oct 21:35 gammalib-setup.in
drwxr-xr-x  13 jurgen  staff   442 12 oct 21:35 linalg
drwxr-xr-x  35 jurgen  staff  1190 12 oct 21:35 model
drwxr-xr-x   8 jurgen  staff   272 12 oct 21:35 numerics
drwxr-xr-x  25 jurgen  staff   850 12 oct 21:35 obs
drwxr-xr-x   7 jurgen  staff   238 12 oct 21:35 opt
drwxr-xr-x  15 jurgen  staff   510 12 oct 21:35 sky
drwxr-xr-x   8 jurgen  staff   272 12 oct 21:35 support
drwxr-xr-x   4 jurgen  staff   136 12 oct 21:35 template
drwxr-xr-x   7 jurgen  staff   238 12 oct 21:35 test
drwxr-xr-x  12 jurgen  staff   408 12 oct 21:35 xml

Each subdirectory presents a specific module. As example, the content of the app subdirectory is

-rw-r--r--  1 jurgen  staff  20078 12 oct 21:35 GApplication.cpp
-rw-r--r--  1 jurgen  staff   8383 12 oct 21:35 GException_app.cpp
-rw-r--r--  1 jurgen  staff  26817 12 oct 21:35 GLog.cpp
-rw-r--r--  1 jurgen  staff  32253 12 oct 21:35 GPar.cpp
-rw-r--r--  1 jurgen  staff  39490 12 oct 21:35 GPars.cpp
-rw-r--r--  1 jurgen  staff    499 12 oct 21:35 Makefile.am

These directories contain the code for all GammaLib classes. Typically, there is one file per class. The Makefile.am in these subdirectories gather the names of all files that need be compiled. If a new file is added to the subdirectory, Makefile.am needs to be updated.

Often, the subdirectories contain a file named GException_xxx.cpp, where xxx is the name of the module. This file implements the exception classes that are relevant for this module. The definition of these exception classes are found in the file GException.hpp, situated in the gammalib/include directory.

The src directory also contains a Makefile.am which gathers informations about all modules and instrument interfaces that are present. If a module is added ot if a new instrument interface is added, this file needs to be modified.

Finally, the src directory contains the scripts gammalib-init.csh, gammalib-init.sh, and gammalib-setup.in. These scripts will be installed in the bin directory of the GammaLib installation, and will serve to configure the GammaLib environment. If modifications to the environment are required, the file gammalib-setup.in should be changed.

test¶

The test directory contains all code and data that are needed for unit testing. In addition, it may contain any kind of script that is useful for testing some functionalities of GammaLib. Here is a selected list of files or folders that are present in the directory:

-rw-r--r--   1 jurgen  staff   5513 12 oct 21:35 Makefile.am            <- automake input file
-rw-r--r--   1 jurgen  staff    755 12 oct 21:35 README
drwxr-xr-x   7 jurgen  staff    238 12 oct 21:35 data                   <= test data directory
drwxr-xr-x   3 jurgen  staff    102 12 oct 21:35 reports                <= test reports directory
-rw-r--r--   1 jurgen  staff   4960 12 oct 21:35 test_GApplication.cpp  <- source code for C++ module test
-rw-r--r--   1 jurgen  staff   2454 12 oct 21:35 test_GApplication.hpp  <- header file for C++ module test
-rwxr-xr-x   1 jurgen  staff   4115 12 oct 21:35 test_GApplication.py   <- script for Python module test
drwxr-xr-x  13 jurgen  staff    442 12 oct 21:35 testinst               <= Instrument for testing of instrument interface

The Makefile.am file is the input file from which automake will generate a Makefile. This Makefile will be executed when make check is invoked. If a new module or a new instrument is added, this file needs to be modified.

For each module there is a C++ source code file, a C++ header file and a Python script. These files will be used during make check to perform the C++ and Python unit tests for a given module.

The testinst directory implements a test instrument that is used to test the instrument interface. The test instrument is realized by header files only, hence no compilation is performed. To include the test instrument in any unit test, the testinst/GTestLib.hpp file needs to be included in the test. See test_GObservation.cpp for an example.