diff --git a/doc/um/latex/ctatools-manual.tex b/doc/um/latex/ctatools-manual.tex new file mode 100644 index 0000000..4bcf25d --- /dev/null +++ b/doc/um/latex/ctatools-manual.tex @@ -0,0 +1,297 @@ +%---------------------------------------------------------------------------- +% ctatools User Manual +% +% Version: 0.1 +% Last modification: 12 August 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{ctatools}} +\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{12 August 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:ctatools} 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:ctatools} + +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} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% ctatools 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} diff --git a/doc/um/latex/manual.sty b/doc/um/latex/manual.sty new file mode 100644 index 0000000..3940fd5 --- /dev/null +++ b/doc/um/latex/manual.sty @@ -0,0 +1,129 @@ +%% +%% "manual.sty" provides definitions for the ctatools User Manual +%% +%% Copyright (C) 2011 Jurgen Knodlseder +%% +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{manual}[2011/08/12 v1.0 ctatools User Manual] + +% +% The page dimensions +% +%\setlength\paperheight{9.25in} +%\setlength\paperwidth{7.375in} +\setlength\parindent{0cm} +\setlength\parskip{0.2cm} +\setlength\linewidth{13.2cm} +\setlength\headheight{1.5cm} +\setlength\textwidth{16.3cm} +\setlength\textheight{22.5cm} +\setlength\oddsidemargin{0cm} +\setlength\topmargin{-1.7cm} +%\setlength\parindent{2em} +%\setlength\headheight{8pt} +\setlength\headsep{19pt} +\setlength\footskip{24pt} +%\setlength\textwidth{345pt} +%\setlength\textheight{46pc} +\setlength\evensidemargin{1.6804in} +%\setlength\oddsidemargin{1.5139in} +%\setlength\topmargin{.625in} + +% +% Page style +% +\pagestyle{myheadings} +\markboth{\task\ User Manual} + {\task\ User Manual} + +%\renewcommand{\subsection}{\@startsection{subsection}{3}{-4pc}{-16pt}{6pt}{% +% \rightmark{Introduction}}} + +% +% Define front-page command +% +\newcommand{\frontpage}{% +\begin{center} +\framebox[16cm]{ +\begin{minipage}[c]{16cm} +\vspace*{6.5cm} +\begin{center} + +% Software component +\framebox{ + \framebox{ + \parbox{10cm}{ + \vspace{5mm} \centerline{ + \vspace{5mm} \Huge \bf + \task + } + } + } +} + +% User Manual +\vspace{10mm} +{\Huge \bf User Manual} +\\[10mm] + +% Version, Date +{\normalsize \bf Version \version\\ \calendar} +\\[10mm] + +% Author +\rm +J\"urgen Kn\"odlseder\\ +Institut de Recherche en Astrophysique et Plan\'etologie (IRAP)\\ +knodlseder@cesr.fr\\ +http://www.irap.omp.eu/ + +\vfill +\end{center} +\vspace*{6.5cm} +\end{minipage} +} +\end{center} + +\thispagestyle{empty} +\pagenumbering{roman} +\newpage +%\begin{center} +%\parbox{15cm}{ +%\vspace{200mm} +%\centerline{Note to the user} +%\vspace{3mm} +%This software has been written to analyse gamma-ray data. +%Particular care has been taken in making the software user friendly +%and well documented. +%If you appreciated this effort, and if this software and User Manual +%were useful for your scientific work, the author would appreciate a +%corresponding acknowledgment in your published work. +%} +%\end{center} +\begin{center} +\parbox{15cm}{ +\vspace{200mm} +\centerline{This page has been intentionally left blank.} +} +\end{center} + +\newpage +\tableofcontents +\newpage +\pagenumbering{arabic} +} + + +% +% Further commands +% +%\newcommand{\icd}[1]{\item[{\tt #1}] } +\newcommand{\icd}[1]{\item{\tt #1} } +\newcommand{\cur}[1]{% +\icd{#1} specifies the current ISDC status when the function is entered. + If {\tt status != ISDC\_OK} the function does nothing and + returns the input status as return code. +} +\endinput +%% +%% End of file `manual.sty'.