% ----------------------------------------------------------------------- % 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} \secC{Basic installation} \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 lib (optional -- to create a library for development purposes)\\ > make clean (optional -- to remove the object files)\\ > make install } } \end{quote} This default setup will search in standard locations for the necessary libraries, and install the executable (\texttt{``Duchamp''}) in \texttt{/usr/local/bin} (a copy will also be in the current directory). The library (if you've made it) will be installed in \texttt{/usr/local/lib}, and the full set of header files will be installed in \texttt{/usr/local/include/duchamp} and subdirectories thereof. If you want these to go somewhere else, \eg if you don't have write-access to that directory, or you need to tweak the libraries, see the next section. Otherwise, jump to the testing section. \secC{Tweaking the installation process} The \texttt{configure} script allows the user to tailor the installation according to the particular requirements of their system. To install Duchamp in a directory other than \texttt{/usr/local/bin}, use the \texttt{--prefix} option with configure, specifying the directory above the \texttt{bin/} directory \eg \begin{quote} {\footnotesize \texttt{% > ./configure --prefix=/home/mduchamp} } \end{quote} and then run \texttt{make}, (\texttt{make lib} if you like), and \texttt{make install} as stated above. This will put the binary in the directory \texttt{/home/mduchamp/bin}. The library, if made, will be put in \texttt{/home/mduchamp/lib} and the header files in \texttt{/home/mduchamp/include/duchamp} and subdirectories. If the above-mentioned libraries have been installed in non-standard locations, or you have more than one version installed on your system, you can specify specific locations by using the \texttt{--with-cfitsio=}, \texttt{--with-wcslib=} or \texttt{--with-pgplot=} flags. For example: \begin{quote} {\footnotesize \texttt{% > ./configure --with-wcslib=/home/mduchamp/wcslib-4.2} } \end{quote} Duchamp can be compiled without \textsc{pgplot} if it is not installed on your system -- the searching and text-based output remains the same, but you will not have any graphical output. To manually specify this option, use the \texttt{--without-pgplot} flag: \begin{quote} {\footnotesize \texttt{% > ./configure --without-pgplot} } \end{quote} (Note that CFITSIO and WCSLIB are essential, however, so flags such as \texttt{--without-wcslib} or \texttt{--without-cfitsio} will not work.). Even if you do not give the \texttt{--without-pgplot} option, and the \textsc{pgplot} library is not found, Duchamp will still compile (albeit without graphical capabilities). An additional option that is useful is the ability to specify which compiler to use. This is very important for the Fortran compiler (used for linking due to the use of \textsc{pgplot}), particularly on Mac OS X, where \texttt{gfortran} is often used instead of \texttt{gcc}. To specify a particular Fortran compiler, use the \texttt{F77} flag: \begin{quote} {\footnotesize \texttt{% > ./configure F77=gfortran} } \end{quote} Of course, all desired flags should be combined in one \texttt{configure} call. For a full list of the options with \texttt{configure}, run: \begin{quote} {\footnotesize \texttt{% > ./configure --help} } \end{quote} Once \texttt{configure} has run correctly, simply run \texttt{make} and \texttt{make install} to build \duchamp and put it in the correct place (either \texttt{/usr/local/bin} or the location given by the \texttt{--prefix} option discussed above). \secC{Making sure it all works} Running make will create the executable \texttt{Duchamp-{\version}}. 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. You can then install \duchamp on your system via: \begin{quote} {\footnotesize \texttt{> make install} } \end{quote} \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://svn.atnf.csiro.au/trac/duchamp/newticket}% {http://svn.atnf.csiro.au/trac/duchamp/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.