Francois Brun / ctools

%---------------------------------------------------------------------------- 
%                             ctools User Manual
%
% Version: 0.1
% Last modification: 6 October 2011
%----------------------------------------------------------------------------

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% There are at least 5 sections required, depending on the audience:
% 1. Functional description (description of services provided) - for system evaluators
% 2. Installation document (how to install the system) - for system administrators
% 3. Introductory material (getting started with the system) - for novice users
% 4. Reference manual (details of all system facilities) - for experienced users
% 5. System administration guide (how to operate and maintain the system) - for system administators
%
% Design the document structure so that the different parts are as independent as possible.
%
% Required document components:
% Identification data - Data such as a title and identifier that uniquely identifies the document.
% Table of contents - Chapter/section names and page numbers.
% List of illustrations - Figure numbers and titles
% Introduction - Defines the purpose of the document and a brief summary of the contents
% Information for use of the documentation - Suggestions for different readers on how to use the documentation effectively.
% Concept of operations - An explanation of the conceptual background to the use of the software.
% Procedures - Directions on how to use the software to complete the tasks that it is designed to support.
% Information on software commands - A description of each of the commands supported by the software.
% Error messages and problem resolution - A description of the errors that can be reported and how to recover from these errors.
% Glossary - Definitions of specialized terms used.
% Related information sources - References or links to other documents that provide additional information
% Navigational features - Features that allow readers to find their current location and move around the document.
% Index - A list of key terms and the pages where these terms are referenced.
% Search capability - In electronic documentation, a way of finding specific terms in the document.
%
% Writing style:
% - Use active rather than passive tenses ("You should see a flashing cursor at the top left")
% - Use grammatically correct constructs and correct spelling
% - Do not use long sentences which present several different facts
% - Keep paragraphs short (less than 7 sentences)
% - Don't be verbose. Quality is more important than quantity.
% - Be precise and define the terms you use
% - If a description is complex, repeat yourself
% - Make use of headings and sub-headings
% - Itemize facts wherever possible
% - Do not refer to information by reference number alone ("In section 1.3, which describes the ...")
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Definitions for manual package
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\task}{\mbox{ctools}}
\newcommand{\this}{\mbox{\tt \task}}
\newcommand{\gammalib}{\mbox{\tt gammalib}}
\newcommand{\cfitsio}{\mbox{\tt cfitsio}}
\newcommand{\ctools}{\mbox{\tt ctools}}
\newcommand{\cscripts}{\mbox{\tt cscripts}}
\newcommand{\version}{\mbox{0.1}}
\newcommand{\calendar}{\mbox{6 October 2011}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Document definition
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass{article}[12pt,a4]
\usepackage{epsfig}
\usepackage{manual}
\usepackage{makeidx}
\usepackage{hyperref}
\makeindex


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Begin of document body
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\frontpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Introduction (for system evaluators)
%
% Provides the functional description of the system. It outlines the system requirements and briefly
% describes the services provided. This section should provide an overview of the system. Users
% should be able to read this section and decide if the system is what they need.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

\this\ is a highly modular collection of utilities for processing and analysing CTA reconstructed
event data in the FITS\index{FITS} (Flexible Image Transport System) data format.
Each utility presents itself as a FTOOL\index{FTOOLS} 
(see \url{http://heasarc.gsfc.nasa.gov/ftools/}) and performs a single simple task such as event binning, 
event selection or model fitting.
Individual utilities can easily be chained together in scripts to achieve more complex operations,
either by using the command line interface, or by using the Python\index{Python} 
scripting language.
The \this\ user interface is controlled by standard IRAF-style parameter files.
\index{IRAF parameter file}
Software is written in C++ to provide portability across most computer systems. 
The data format dependencies between hardware platforms are isolated through the 
\cfitsio\index{\cfitsio} library package from HEASARC\index{HEASARC} 
(\url{http://heasarc.gsfc.nasa.gov/fitsio/}).

This document describes the use of the \this\ software. 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Installation (for system administrators)
%
% Should provide details of how to install the system in a particular environment. It should contain a
% description of the files making up the system and the minimal hardware configuration required.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Getting the \this}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Before you start}

The procedure for building and installing \this\ is modeled on GNU software distributions.
You will need the following to build the software:
\begin{itemize}
\item Up to {\bf TBD} free disk space.
\item ANSI C++ compiler. \this\ builds well using GNU g++.
\item make
\item \gammalib\ (see Section \ref{sec:gammalib} which provides requirements and installation 
instructions for \gammalib).
\item Python, including the Python developer package that includes the {\tt Python.h} header
files. Although \this\ compiles without Python and/or the Python developer package installed,
compiling with Python support is highly recommended to enable dynamic scripting of \ctools\
and developing and using of \cscripts. 
\end{itemize}
No system administrator privileges are needed to install \this.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installing \gammalib}
\label{sec:gammalib}

\this\ is built on top of \gammalib, hence \gammalib\ needs to be built, installed and configured
before \this\ can be installed.
In case that \this\ is already installed on your system you may skip reading this section
and continue with Section \ref{sec:ctools} that explains how to install \this.

You will need the following to build the \gammalib:
\begin{itemize}
\item Up to {\bf TBD} free disk space.
\item ANSI C++ compiler. \this\ builds well using GNU g++.
\item make
\item \cfitsio
\item Python, including the Python developer package that includes the {\tt Python.h} header
files. Although \this\ compiles without Python and/or the Python developer package installed,
compiling with Python support is highly recommended to enable dynamic scripting of \ctools\
and developing and using of \cscripts. 
\end{itemize}

Furthermore it is recommended to have {\tt readline} and {\tt ncurses} installed (including the
developer packages)


first.
If GammaLib is already installed on your system you may skip this section.

Requires:
cfitsio
readline
ncurses
Python

Step by step instruction:
download,
unpack,
configure,
make,
make check,
sudo make install,
configuration of environment.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installing \this}
\label{sec:ctools}

Step by step instruction:
download,
unpack,
configure,
make,
make check,
sudo make install,
configuration of environment.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Testing \this}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Getting started (for novice users)
%
% Present an informal introduction to the system, describing its 'normal' usage. It should describe how
% to get started and how end-users might make use of the common system facilities. The section
% should be liberally illustrated with examples. Inevitably, beginners will make mistakes. Easily
% discovered information on how to recover from these mistakes and restart useful work should be
% an integral part of this section.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Getting started}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{A quick \this\ tutorial}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Models available in \this}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Using \this\ from Python}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Frequently asked questions}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Deeper information (for experienced users)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Enhancing \this}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Building your own cscripts}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Building your own ctools}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% ctools reference manual (for experienced users)
%
% This section should decribe the system facilities and their usage, should provide a complete listing
% of error messages and should describe how to recover from them. It should be complete. Formal
% descriptive techniques may be used. Completeness is more important that readability.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\this\ reference manual}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{{\tt ctselect}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{{\tt ctbin}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{{\tt ctlike}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{{\tt ctobssim}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Behind the scenes
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Behind the scenes}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{CTA data structure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Instrument response functions}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Maximum likelihood fitting}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Glossary
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Glossary}
\begin{itemize}
\item[] {\bf \cfitsio}\break
  Library of C and Fortran subroutines for reading and writing data files in FITS data format\break
  (\url{http://heasarc.gsfc.nasa.gov/fitsio/}).
\item[] {\bf FITS\label{gloss:fits}}\break
  Flexible Image Transport System (\url{http://fits.gsfc.nasa.gov/}).
\item[] {\bf FTOOLS}\break
  Collection of utility programs to create, examine, or modify data files in the FITS data format\break
  (\url{http://heasarc.gsfc.nasa.gov/ftools/}).
\item[] {\bf GNU}\break
  A free Unix-like operating system (\url{http://www.gnu.org/}).
\item[] {\bf HEASARC}\break
  High Energy Astrophysics Science Archive Research Center (\url{http://heasarc.gsfc.nasa.gov/}).
\item[] {\bf Python}\break
  Dynamic programming language that is used in a wide variety of application domains\break
  (\url{http://www.python.org/}).
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Index
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Index}
\printindex

\end{document}