Francois Brun / ctools

Browse Code »

Commit 3f06c0228f49d771acd19410c8c5b04f10429d49

Authored by knodlseder 2011-10-03 20:14:03 +0000

1 parent 29c48a18

initial version

Inline Side-by-side

Showing 2 changed files with 426 additions and 0 deletions

doc/um/latex/ctatools-manual.tex 0 → 100644

View file @3f06c02

	1	+%----------------------------------------------------------------------------
	2	+% ctatools User Manual
	3	+%
	4	+% Version: 0.1
	5	+% Last modification: 12 August 2011
	6	+%----------------------------------------------------------------------------
	7	+
	8	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	9	+%
	10	+% There are at least 5 sections required, depending on the audience:
	11	+% 1. Functional description (description of services provided) - for system evaluators
	12	+% 2. Installation document (how to install the system) - for system administrators
	13	+% 3. Introductory material (getting started with the system) - for novice users
	14	+% 4. Reference manual (details of all system facilities) - for experienced users
	15	+% 5. System administration guide (how to operate and maintain the system) - for system administators
	16	+%
	17	+% Design the document structure so that the different parts are as independent as possible.
	18	+%
	19	+% Required document components:
	20	+% Identification data - Data such as a title and identifier that uniquely identifies the document.
	21	+% Table of contents - Chapter/section names and page numbers.
	22	+% List of illustrations - Figure numbers and titles
	23	+% Introduction - Defines the purpose of the document and a brief summary of the contents
	24	+% Information for use of the documentation - Suggestions for different readers on how to use the documentation effectively.
	25	+% Concept of operations - An explanation of the conceptual background to the use of the software.
	26	+% Procedures - Directions on how to use the software to complete the tasks that it is designed to support.
	27	+% Information on software commands - A description of each of the commands supported by the software.
	28	+% Error messages and problem resolution - A description of the errors that can be reported and how to recover from these errors.
	29	+% Glossary - Definitions of specialized terms used.
	30	+% Related information sources - References or links to other documents that provide additional information
	31	+% Navigational features - Features that allow readers to find their current location and move around the document.
	32	+% Index - A list of key terms and the pages where these terms are referenced.
	33	+% Search capability - In electronic documentation, a way of finding specific terms in the document.
	34	+%
	35	+% Writing style:
	36	+% - Use active rather than passive tenses ("You should see a flashing cursor at the top left")
	37	+% - Use grammatically correct constructs and correct spelling
	38	+% - Do not use long sentences which present several different facts
	39	+% - Keep paragraphs short (less than 7 sentences)
	40	+% - Don't be verbose. Quality is more important than quantity.
	41	+% - Be precise and define the terms you use
	42	+% - If a description is complex, repeat yourself
	43	+% - Make use of headings and sub-headings
	44	+% - Itemize facts wherever possible
	45	+% - Do not refer to information by reference number alone ("In section 1.3, which describes the ...")
	46	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	47	+
	48	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	49	+% Definitions for manual package
	50	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	51	+\newcommand{\task}{\mbox{ctatools}}
	52	+\newcommand{\this}{\mbox{\tt \task}}
	53	+\newcommand{\gammalib}{\mbox{\tt gammalib}}
	54	+\newcommand{\cfitsio}{\mbox{\tt cfitsio}}
	55	+\newcommand{\ctools}{\mbox{\tt ctools}}
	56	+\newcommand{\cscripts}{\mbox{\tt cscripts}}
	57	+\newcommand{\version}{\mbox{0.1}}
	58	+\newcommand{\calendar}{\mbox{12 August 2011}}
	59	+
	60	+
	61	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	62	+% Document definition
	63	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	64	+\documentclass{article}[12pt,a4]
	65	+\usepackage{epsfig}
	66	+\usepackage{manual}
	67	+\usepackage{makeidx}
	68	+\usepackage{hyperref}
	69	+\makeindex
	70	+
	71	+
	72	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	73	+% Begin of document body
	74	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	75	+\begin{document}
	76	+\frontpage
	77	+
	78	+
	79	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	80	+% Introduction (for system evaluators)
	81	+%
	82	+% Provides the functional description of the system. It outlines the system requirements and briefly
	83	+% describes the services provided. This section should provide an overview of the system. Users
	84	+% should be able to read this section and decide if the system is what they need.
	85	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	86	+\section{Introduction}
	87	+
	88	+\this\ is a highly modular collection of utilities for processing and analysing CTA reconstructed
	89	+event data in the FITS\index{FITS} (Flexible Image Transport System) data format.
	90	+Each utility presents itself as a FTOOL\index{FTOOLS}
	91	+(see \url{http://heasarc.gsfc.nasa.gov/ftools/}) and performs a single simple task such as event binning,
	92	+event selection or model fitting.
	93	+Individual utilities can easily be chained together in scripts to achieve more complex operations,
	94	+either by using the command line interface, or by using the Python\index{Python}
	95	+scripting language.
	96	+The \this\ user interface is controlled by standard IRAF-style parameter files.
	97	+\index{IRAF parameter file}
	98	+Software is written in C++ to provide portability across most computer systems.
	99	+The data format dependencies between hardware platforms are isolated through the
	100	+\cfitsio\index{\cfitsio} library package from HEASARC\index{HEASARC}
	101	+(\url{http://heasarc.gsfc.nasa.gov/fitsio/}).
	102	+
	103	+This document describes the use of the \this\ software.
	104	+
	105	+
	106	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	107	+% Installation (for system administrators)
	108	+%
	109	+% Should provide details of how to install the system in a particular environment. It should contain a
	110	+% description of the files making up the system and the minimal hardware configuration required.
	111	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	112	+\section{Getting the \this}
	113	+
	114	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	115	+\subsection{Before you start}
	116	+
	117	+The procedure for building and installing \this\ is modeled on GNU software distributions.
	118	+You will need the following to build the software:
	119	+\begin{itemize}
	120	+\item Up to {\bf TBD} free disk space.
	121	+\item ANSI C++ compiler. \this\ builds well using GNU g++.
	122	+\item make
	123	+\item \gammalib\ (see Section \ref{sec:gammalib} which provides requirements and installation
	124	+instructions for \gammalib).
	125	+\item Python, including the Python developer package that includes the {\tt Python.h} header
	126	+files. Although \this\ compiles without Python and/or the Python developer package installed,
	127	+compiling with Python support is highly recommended to enable dynamic scripting of \ctools\
	128	+and developing and using of \cscripts.
	129	+\end{itemize}
	130	+No system administrator privileges are needed to install \this.
	131	+
	132	+
	133	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	134	+\subsection{Installing \gammalib}
	135	+\label{sec:gammalib}
	136	+
	137	+\this\ is built on top of \gammalib, hence \gammalib\ needs to be built, installed and configured
	138	+before \this\ can be installed.
	139	+In case that \this\ is already installed on your system you may skip reading this section
	140	+and continue with Section \ref{sec:ctatools} that explains how to install \this.
	141	+
	142	+You will need the following to build the \gammalib:
	143	+\begin{itemize}
	144	+\item Up to {\bf TBD} free disk space.
	145	+\item ANSI C++ compiler. \this\ builds well using GNU g++.
	146	+\item make
	147	+\item \cfitsio
	148	+\item Python, including the Python developer package that includes the {\tt Python.h} header
	149	+files. Although \this\ compiles without Python and/or the Python developer package installed,
	150	+compiling with Python support is highly recommended to enable dynamic scripting of \ctools\
	151	+and developing and using of \cscripts.
	152	+\end{itemize}
	153	+
	154	+Furthermore it is recommended to have {\tt readline} and {\tt ncurses} installed (including the
	155	+developer packages)
	156	+
	157	+
	158	+first.
	159	+If GammaLib is already installed on your system you may skip this section.
	160	+
	161	+Requires:
	162	+cfitsio
	163	+readline
	164	+ncurses
	165	+Python
	166	+
	167	+Step by step instruction:
	168	+download,
	169	+unpack,
	170	+configure,
	171	+make,
	172	+make check,
	173	+sudo make install,
	174	+configuration of environment.
	175	+
	176	+
	177	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	178	+\subsection{Installing \this}
	179	+\label{sec:ctatools}
	180	+
	181	+Step by step instruction:
	182	+download,
	183	+unpack,
	184	+configure,
	185	+make,
	186	+make check,
	187	+sudo make install,
	188	+configuration of environment.
	189	+
	190	+
	191	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	192	+\subsection{Testing \this}
	193	+
	194	+
	195	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	196	+% Getting started (for novice users)
	197	+%
	198	+% Present an informal introduction to the system, describing its 'normal' usage. It should describe how
	199	+% to get started and how end-users might make use of the common system facilities. The section
	200	+% should be liberally illustrated with examples. Inevitably, beginners will make mistakes. Easily
	201	+% discovered information on how to recover from these mistakes and restart useful work should be
	202	+% an integral part of this section.
	203	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	204	+\section{Getting started}
	205	+
	206	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	207	+\subsection{A quick \this\ tutorial}
	208	+
	209	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	210	+\subsection{Models available in \this}
	211	+
	212	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	213	+\subsection{Using \this\ from Python}
	214	+
	215	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	216	+\subsection{Frequently asked questions}
	217	+
	218	+
	219	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	220	+% Deeper information (for experienced users)
	221	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	222	+\section{Enhancing \this}
	223	+
	224	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	225	+\subsection{Building your own cscripts}
	226	+
	227	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	228	+\subsection{Building your own ctools}
	229	+
	230	+
	231	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	232	+% ctatools reference manual (for experienced users)
	233	+%
	234	+% This section should decribe the system facilities and their usage, should provide a complete listing
	235	+% of error messages and should describe how to recover from them. It should be complete. Formal
	236	+% descriptive techniques may be used. Completeness is more important that readability.
	237	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	238	+\section{\this\ reference manual}
	239	+
	240	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	241	+\subsection{{\tt ctselect}}
	242	+
	243	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	244	+\subsection{{\tt ctbin}}
	245	+
	246	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	247	+\subsection{{\tt ctlike}}
	248	+
	249	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	250	+\subsection{{\tt ctobssim}}
	251	+
	252	+
	253	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	254	+% Behind the scenes
	255	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	256	+\section{Behind the scenes}
	257	+
	258	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	259	+\subsection{CTA data structure}
	260	+
	261	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	262	+\subsection{Instrument response functions}
	263	+
	264	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	265	+\subsection{Maximum likelihood fitting}
	266	+
	267	+
	268	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	269	+% Glossary
	270	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	271	+\section{Glossary}
	272	+\begin{itemize}
	273	+\item[] {\bf \cfitsio}\break
	274	+ Library of C and Fortran subroutines for reading and writing data files in FITS data format\break
	275	+ (\url{http://heasarc.gsfc.nasa.gov/fitsio/}).
	276	+\item[] {\bf FITS\label{gloss:fits}}\break
	277	+ Flexible Image Transport System (\url{http://fits.gsfc.nasa.gov/}).
	278	+\item[] {\bf FTOOLS}\break
	279	+ Collection of utility programs to create, examine, or modify data files in the FITS data format\break
	280	+ (\url{http://heasarc.gsfc.nasa.gov/ftools/}).
	281	+\item[] {\bf GNU}\break
	282	+ A free Unix-like operating system (\url{http://www.gnu.org/}).
	283	+\item[] {\bf HEASARC}\break
	284	+ High Energy Astrophysics Science Archive Research Center (\url{http://heasarc.gsfc.nasa.gov/}).
	285	+\item[] {\bf Python}\break
	286	+ Dynamic programming language that is used in a wide variety of application domains\break
	287	+ (\url{http://www.python.org/}).
	288	+\end{itemize}
	289	+
	290	+
	291	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	292	+% Index
	293	+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	294	+\section{Index}
	295	+\printindex
	296	+
	297	+\end{document}
...	...

doc/um/latex/manual.sty 0 → 100644

View file @3f06c02

	1	+%%
	2	+%% "manual.sty" provides definitions for the ctatools User Manual
	3	+%%
	4	+%% Copyright (C) 2011 Jurgen Knodlseder
	5	+%%
	6	+\NeedsTeXFormat{LaTeX2e}
	7	+\ProvidesPackage{manual}[2011/08/12 v1.0 ctatools User Manual]
	8	+
	9	+%
	10	+% The page dimensions
	11	+%
	12	+%\setlength\paperheight{9.25in}
	13	+%\setlength\paperwidth{7.375in}
	14	+\setlength\parindent{0cm}
	15	+\setlength\parskip{0.2cm}
	16	+\setlength\linewidth{13.2cm}
	17	+\setlength\headheight{1.5cm}
	18	+\setlength\textwidth{16.3cm}
	19	+\setlength\textheight{22.5cm}
	20	+\setlength\oddsidemargin{0cm}
	21	+\setlength\topmargin{-1.7cm}
	22	+%\setlength\parindent{2em}
	23	+%\setlength\headheight{8pt}
	24	+\setlength\headsep{19pt}
	25	+\setlength\footskip{24pt}
	26	+%\setlength\textwidth{345pt}
	27	+%\setlength\textheight{46pc}
	28	+\setlength\evensidemargin{1.6804in}
	29	+%\setlength\oddsidemargin{1.5139in}
	30	+%\setlength\topmargin{.625in}
	31	+
	32	+%
	33	+% Page style
	34	+%
	35	+\pagestyle{myheadings}
	36	+\markboth{\task\ User Manual}
	37	+ {\task\ User Manual}
	38	+
	39	+%\renewcommand{\subsection}{\@startsection{subsection}{3}{-4pc}{-16pt}{6pt}{%
	40	+% \rightmark{Introduction}}}
	41	+
	42	+%
	43	+% Define front-page command
	44	+%
	45	+\newcommand{\frontpage}{%
	46	+\begin{center}
	47	+\framebox[16cm]{
	48	+\begin{minipage}[c]{16cm}
	49	+\vspace*{6.5cm}
	50	+\begin{center}
	51	+
	52	+% Software component
	53	+\framebox{
	54	+ \framebox{
	55	+ \parbox{10cm}{
	56	+ \vspace{5mm} \centerline{
	57	+ \vspace{5mm} \Huge \bf
	58	+ \task
	59	+ }
	60	+ }
	61	+ }
	62	+}
	63	+
	64	+% User Manual
	65	+\vspace{10mm}
	66	+{\Huge \bf User Manual}
	67	+\\[10mm]
	68	+
	69	+% Version, Date
	70	+{\normalsize \bf Version \version\\ \calendar}
	71	+\\[10mm]
	72	+
	73	+% Author
	74	+\rm
	75	+J\"urgen Kn\"odlseder\\
	76	+Institut de Recherche en Astrophysique et Plan\'etologie (IRAP)\\
	77	+knodlseder@cesr.fr\\
	78	+http://www.irap.omp.eu/
	79	+
	80	+\vfill
	81	+\end{center}
	82	+\vspace*{6.5cm}
	83	+\end{minipage}
	84	+}
	85	+\end{center}
	86	+
	87	+\thispagestyle{empty}
	88	+\pagenumbering{roman}
	89	+\newpage
	90	+%\begin{center}
	91	+%\parbox{15cm}{
	92	+%\vspace{200mm}
	93	+%\centerline{Note to the user}
	94	+%\vspace{3mm}
	95	+%This software has been written to analyse gamma-ray data.
	96	+%Particular care has been taken in making the software user friendly
	97	+%and well documented.
	98	+%If you appreciated this effort, and if this software and User Manual
	99	+%were useful for your scientific work, the author would appreciate a
	100	+%corresponding acknowledgment in your published work.
	101	+%}
	102	+%\end{center}
	103	+\begin{center}
	104	+\parbox{15cm}{
	105	+\vspace{200mm}
	106	+\centerline{This page has been intentionally left blank.}
	107	+}
	108	+\end{center}
	109	+
	110	+\newpage
	111	+\tableofcontents
	112	+\newpage
	113	+\pagenumbering{arabic}
	114	+}
	115	+
	116	+
	117	+%
	118	+% Further commands
	119	+%
	120	+%\newcommand{\icd}[1]{\item[{\tt #1}] }
	121	+\newcommand{\icd}[1]{\item{\tt #1} }
	122	+\newcommand{\cur}[1]{%
	123	+\icd{#1} specifies the current ISDC status when the function is entered.
	124	+ If {\tt status != ISDC\_OK} the function does nothing and
	125	+ returns the input status as return code.
	126	+}
	127	+\endinput
	128	+%%
	129	+%% End of file `manual.sty'.
...	...