source: tags/release-1.1/docs/app-install.tex @ 1323

% -----------------------------------------------------------------------
% app-install.tex: Section about how to download, install and run
%                  Duchamp. 
% -----------------------------------------------------------------------
% Copyright (C) 2006, Matthew Whiting, ATNF
%
% This program is free software; you can redistribute it and/or modify it
% under the terms of the GNU General Public License as published by the
% Free Software Foundation; either version 2 of the License, or (at your
% option) any later version.
%
% Duchamp is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
% for more details.
%
% You should have received a copy of the GNU General Public License
% along with Duchamp; if not, write to the Free Software Foundation,
% Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
%
% Correspondence concerning Duchamp may be directed to:
%    Internet email: Matthew.Whiting [at] atnf.csiro.au
%    Postal address: Dr. Matthew Whiting
%                    Australia Telescope National Facility, CSIRO
%                    PO Box 76
%                    Epping NSW 1710
%                    AUSTRALIA
% -----------------------------------------------------------------------
\secA{Obtaining and installing \duchamp}
\label{app-install}

\secB{Installing}
The \duchamp web page can be found at the following location:\\
\href{http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}%
{http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}\\
Here you can find a gzipped tar archive of the source code that can be
downloaded and extracted, as well as this User's Guide in postscript
and hyperlinked PDF formats.

To build \duchamp, you will need three main external libraries:
\textsc{pgplot}, \textsc{cfitsio} (this needs to be version 2.5 or
greater -- version 3+ is better) and \textsc{wcslib}. If these are not
present on your system, you can download them from the following
locations:
\begin{itemize}
\item \textsc{pgplot}:
\href{http://www.astro.caltech.edu/~tjp/pgplot/}%
{\footnotesize http://www.astro.caltech.edu/~tjp/pgplot/}
\item \textsc{cfitsio}:
\href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}%
{\footnotesize http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}
\item \textsc{wcslib}:
\href{http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}%
{\footnotesize http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}
\end{itemize}

\duchamp can be built on Unix/Linux systems by typing (assuming that
the prompt your terminal provides is a \texttt{> } -- don't type this
character!):
\begin{quote}
{\footnotesize
\texttt{%
> ./configure\\
> make\\
> make clean (optional -- to remove the object files)}
}
\end{quote}

Run in this manner, \texttt{configure} should find all the necessary
libraries, but if some libraries have been installed in non-standard
locations, it may fail. In this case, you can specify additional
directories to look in by giving extra command-line arguments. There
are separate options for library files (eg. libcpgplot.a) and header
files (eg. cpgplot.h).

For example, suppose \textsc{wcslib} had been locally installed in the
directory \texttt{/home/mduchamp/wcslib}. There will then be two
libraries created that are likely to be in the following
subdirectories: \texttt{C/} and \texttt{pgsbox/}. Each subdirectory
needs to be searched for library and header files, so one could build
Duchamp by typing:
\begin{quote}
{\footnotesize
\texttt{%
>  ./configure $\backslash$ \\ 
LIBDIRS="/home/mduchamp/wcslib/C /home/mduchamp/wcslib/pgsbox" 
$\backslash$\\
INCDIRS="/home/mduchamp/wcslib/C /home/mduchamp/wcslib/pgsbox"}
}
\end{quote}
And then just run make in the usual fashion:
\begin{quote}
{\footnotesize
\texttt{> make}
}
\end{quote}

This will produce the executable \texttt{Duchamp}. You can verify that
it is running correctly by running the verification shell script:
\begin{quote}
{\footnotesize
\texttt{> VerifyDuchamp.sh}
}
\end{quote}
This will use a dummy FITS image in the \texttt{verification/}
directory -- this image has some Gaussian random noise, with five
Gaussian sources present, plus a dummy WCS. The script runs
Duchamp on this image with four different sets of inputs, and
compares to known results, looking for differences and reporting
any. There should be none reported if everything is working correctly.

\secB{Running \duchamp}
You can then run \duchamp on your own data. This can be done in one
of two ways. The first is:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -f [FITS file]}
}
\end{quote}
where \texttt{[FITS file]} is the file you wish to search. This method
simply uses the default values of all parameters.

The second method allows some determination of the parameter values by
the user. Type:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -p [parameter file]}
}
\end{quote}
where \texttt{[parameterFile]} is a file with the input parameters,
including the name of the cube you want to search. There are two
example input files included with the distribution. The smaller one,
\texttt{InputExample}, shows the typical parameters one might want to
set. The large one, \texttt{InputComplete}, lists all possible
parameters that can be entered, and a brief description of them. To
get going quickly, just replace the \texttt{"your-file-here"} in the
\texttt{InputExample} file with your image name, and type
\begin{quote}
{\footnotesize
\texttt{> Duchamp -p InputExample}
}
\end{quote}

To disable the use of X-window plotting (in displaying the map of
detections), one can either set the parameter \texttt{flagXOutput =
false} or use the \texttt{-x} command-line option:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -x -p [parameter file]}
}, or\\
{\footnotesize
\texttt{> Duchamp -x -f [FITS file]}
}
\end{quote}

The following appendices provide details on the individual parameters,
and show examples of the output files that \duchamp produces.

\secB{Feedback}
It may happen that you discover bugs or problems with \duchamp, or you
have suggestions for improvements or additional features to be
included in future releases. You can submit a ``ticket'' (a trackable
bug report) at the \duchamp Trac wiki at the following location:\\
\href{http://sourcecode.atnf.csiro.au/cgi-bin/trac\_duchamp.cgi/newticket}%
{\footnotesize 
http://sourcecode.atnf.csiro.au/cgi-bin/trac\_duchamp.cgi/newticket}
\\(there is a link to this page from the Duchamp website).

There is also an email exploder, duchamp-user\textbf{[at]}atnf.csiro.au,
that users can subscribe to keep up to date with changes, updates, and
other news about \duchamp. To subscribe, send an email (from the
account you wish to subscribe to the list) to
duchamp-user-request\textbf{[at]}atnf.csiro.au with the single word
``subscribe'' in the body of the message. To be removed from this
list, send a message with ``unsubscribe'' in its body to the same
address.

\secB{Beta Versions}

On the \duchamp website there may be a beta version listed in the
downloads section. As \duchamp is still under development, there will
be times when there has been new functionality added to the code, but
the time has not yet come to release a new minor (or indeed major)
version. 

Sometimes I will post the updated version of the code on the website
as a ``beta'' version, particularly if I'm interested in people
testing it. It will not have been tested as rigorously as the proper
releases, but it will certainly work in the basic cases that I use to
test it during development. So feel free to give it a try -- the
\texttt{CHANGES} file will usually detail what is different to the last
numbered release.