[303] | 1 | % ----------------------------------------------------------------------- |
---|
| 2 | % app-install.tex: Section about how to download, install and run |
---|
| 3 | % Duchamp. |
---|
| 4 | % ----------------------------------------------------------------------- |
---|
| 5 | % Copyright (C) 2006, Matthew Whiting, ATNF |
---|
| 6 | % |
---|
| 7 | % This program is free software; you can redistribute it and/or modify it |
---|
| 8 | % under the terms of the GNU General Public License as published by the |
---|
| 9 | % Free Software Foundation; either version 2 of the License, or (at your |
---|
| 10 | % option) any later version. |
---|
| 11 | % |
---|
| 12 | % Duchamp is distributed in the hope that it will be useful, but WITHOUT |
---|
| 13 | % ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
---|
| 14 | % FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
---|
| 15 | % for more details. |
---|
| 16 | % |
---|
| 17 | % You should have received a copy of the GNU General Public License |
---|
| 18 | % along with Duchamp; if not, write to the Free Software Foundation, |
---|
| 19 | % Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
---|
| 20 | % |
---|
| 21 | % Correspondence concerning Duchamp may be directed to: |
---|
| 22 | % Internet email: Matthew.Whiting [at] atnf.csiro.au |
---|
| 23 | % Postal address: Dr. Matthew Whiting |
---|
| 24 | % Australia Telescope National Facility, CSIRO |
---|
| 25 | % PO Box 76 |
---|
| 26 | % Epping NSW 1710 |
---|
| 27 | % AUSTRALIA |
---|
| 28 | % ----------------------------------------------------------------------- |
---|
[158] | 29 | \secA{Obtaining and installing \duchamp} |
---|
| 30 | \label{app-install} |
---|
| 31 | |
---|
[208] | 32 | \secB{Installing} |
---|
[258] | 33 | The \duchamp web page can be found at the following location:\\ |
---|
[158] | 34 | \href{http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}% |
---|
| 35 | {http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}\\ |
---|
| 36 | Here you can find a gzipped tar archive of the source code that can be |
---|
| 37 | downloaded and extracted, as well as this User's Guide in postscript |
---|
| 38 | and hyperlinked PDF formats. |
---|
| 39 | |
---|
| 40 | To build \duchamp, you will need three main external libraries: |
---|
[168] | 41 | \textsc{pgplot}, \textsc{cfitsio} (this needs to be version 2.5 or |
---|
| 42 | greater -- version 3+ is better) and \textsc{wcslib}. If these are not |
---|
| 43 | present on your system, you can download them from the following |
---|
| 44 | locations: |
---|
[158] | 45 | \begin{itemize} |
---|
| 46 | \item \textsc{pgplot}: |
---|
| 47 | \href{http://www.astro.caltech.edu/~tjp/pgplot/}% |
---|
[231] | 48 | {\footnotesize http://www.astro.caltech.edu/~tjp/pgplot/} |
---|
[158] | 49 | \item \textsc{cfitsio}: |
---|
| 50 | \href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}% |
---|
[231] | 51 | {\footnotesize http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html} |
---|
[158] | 52 | \item \textsc{wcslib}: |
---|
| 53 | \href{http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}% |
---|
[231] | 54 | {\footnotesize http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html} |
---|
[158] | 55 | \end{itemize} |
---|
| 56 | |
---|
[334] | 57 | \secC{Basic installation} |
---|
| 58 | |
---|
[258] | 59 | \duchamp can be built on Unix/Linux systems by typing (assuming that |
---|
[158] | 60 | the prompt your terminal provides is a \texttt{> } -- don't type this |
---|
| 61 | character!): |
---|
| 62 | \begin{quote} |
---|
[231] | 63 | {\footnotesize |
---|
[158] | 64 | \texttt{% |
---|
| 65 | > ./configure\\ |
---|
| 66 | > make\\ |
---|
[336] | 67 | > make clean (optional -- to remove the object files)\\ |
---|
[335] | 68 | > make install } |
---|
[231] | 69 | } |
---|
[158] | 70 | \end{quote} |
---|
| 71 | |
---|
[334] | 72 | This default setup will search in standard locations for the necessary |
---|
| 73 | libraries, and install the executable (\texttt{``Duchamp''}) in |
---|
| 74 | \texttt{/usr/local/bin} (a copy will also be in the current |
---|
| 75 | directory). If you want this to go somewhere else, \eg if you don't |
---|
| 76 | have write-access to that directory, or you need to tweak the |
---|
| 77 | libraries, see the next section. Otherwise, jump to the testing |
---|
| 78 | section. |
---|
[158] | 79 | |
---|
[334] | 80 | \secC{Tweaking the installation process} |
---|
| 81 | |
---|
| 82 | To install Duchamp in a directory other than \texttt{/usr/local/bin}, |
---|
[345] | 83 | use the \texttt{--prefix} option with configure, specifying the |
---|
| 84 | directory above the \texttt{bin/} directory \eg |
---|
[158] | 85 | \begin{quote} |
---|
[231] | 86 | {\footnotesize |
---|
[158] | 87 | \texttt{% |
---|
[345] | 88 | > ./configure --prefix=/home/mduchamp} |
---|
[231] | 89 | } |
---|
[158] | 90 | \end{quote} |
---|
[345] | 91 | and then run \texttt{make} and \texttt{make install} as stated |
---|
| 92 | above. This will put the binary in the directory |
---|
| 93 | \texttt{/home/mduchamp/bin}. |
---|
[334] | 94 | |
---|
| 95 | If the above-mentioned libraries have been installed in non-standard |
---|
| 96 | locations, or you have more than one version installed on your system, |
---|
| 97 | you can specify specific locations by using the |
---|
| 98 | \texttt{--with-cfitsio=<dir>}, \texttt{--with-wcslib=<dir>} or |
---|
| 99 | \texttt{--with-pgplot=<dir>} flags. For example: |
---|
[158] | 100 | \begin{quote} |
---|
[231] | 101 | {\footnotesize |
---|
[334] | 102 | \texttt{% |
---|
[335] | 103 | > ./configure --with-wcslib=/home/mduchamp/wcslib-4.2} |
---|
[231] | 104 | } |
---|
[158] | 105 | \end{quote} |
---|
[334] | 106 | And then just run \texttt{make} in the usual fashion. |
---|
[158] | 107 | |
---|
[334] | 108 | Duchamp can be compiled without \textsc{pgplot} if it is not installed |
---|
| 109 | on your system -- the searching and text-based output remains the |
---|
| 110 | same, but you will not have any graphical output. To manually specify |
---|
| 111 | this option, use the \texttt{--without-pgplot} flag: |
---|
| 112 | \begin{quote} |
---|
| 113 | {\footnotesize |
---|
| 114 | \texttt{% |
---|
[335] | 115 | > ./configure --without-pgplot} |
---|
[334] | 116 | } |
---|
| 117 | \end{quote} |
---|
[320] | 118 | |
---|
[336] | 119 | (Note that CFITSIO and WCSLIB are essential, however, so flags such as |
---|
| 120 | \texttt{--without-wcslib} or \texttt{--without-cfitsio} will not |
---|
| 121 | work.). Even if you do not give the \texttt{--without-pgplot} option, |
---|
| 122 | and the \textsc{pgplot} library is not found, Duchamp will still |
---|
| 123 | compile (albeit without graphical capabilities). |
---|
[334] | 124 | |
---|
| 125 | \secC{Making sure it all works} |
---|
| 126 | |
---|
[321] | 127 | Running make will create the executable \texttt{Duchamp}. You can |
---|
| 128 | verify that it is running correctly by running the verification shell |
---|
| 129 | script: |
---|
[158] | 130 | \begin{quote} |
---|
[231] | 131 | {\footnotesize |
---|
[158] | 132 | \texttt{> VerifyDuchamp.sh} |
---|
[231] | 133 | } |
---|
[158] | 134 | \end{quote} |
---|
| 135 | This will use a dummy FITS image in the \texttt{verification/} |
---|
| 136 | directory -- this image has some Gaussian random noise, with five |
---|
| 137 | Gaussian sources present, plus a dummy WCS. The script runs |
---|
[279] | 138 | Duchamp on this image with four different sets of inputs, and |
---|
[158] | 139 | compares to known results, looking for differences and reporting |
---|
| 140 | any. There should be none reported if everything is working correctly. |
---|
| 141 | |
---|
[208] | 142 | \secB{Running \duchamp} |
---|
[258] | 143 | You can then run \duchamp on your own data. This can be done in one |
---|
[158] | 144 | of two ways. The first is: |
---|
| 145 | \begin{quote} |
---|
[231] | 146 | {\footnotesize |
---|
[158] | 147 | \texttt{> Duchamp -f [FITS file]} |
---|
[231] | 148 | } |
---|
[158] | 149 | \end{quote} |
---|
| 150 | where \texttt{[FITS file]} is the file you wish to search. This method |
---|
| 151 | simply uses the default values of all parameters. |
---|
| 152 | |
---|
| 153 | The second method allows some determination of the parameter values by |
---|
| 154 | the user. Type: |
---|
| 155 | \begin{quote} |
---|
[231] | 156 | {\footnotesize |
---|
[158] | 157 | \texttt{> Duchamp -p [parameter file]} |
---|
[231] | 158 | } |
---|
[158] | 159 | \end{quote} |
---|
| 160 | where \texttt{[parameterFile]} is a file with the input parameters, |
---|
| 161 | including the name of the cube you want to search. There are two |
---|
| 162 | example input files included with the distribution. The smaller one, |
---|
| 163 | \texttt{InputExample}, shows the typical parameters one might want to |
---|
| 164 | set. The large one, \texttt{InputComplete}, lists all possible |
---|
| 165 | parameters that can be entered, and a brief description of them. To |
---|
[231] | 166 | get going quickly, just replace the \texttt{"your-file-here"} in the |
---|
| 167 | \texttt{InputExample} file with your image name, and type |
---|
[158] | 168 | \begin{quote} |
---|
[231] | 169 | {\footnotesize |
---|
[158] | 170 | \texttt{> Duchamp -p InputExample} |
---|
[231] | 171 | } |
---|
[158] | 172 | \end{quote} |
---|
| 173 | |
---|
[294] | 174 | To disable the use of X-window plotting (in displaying the map of |
---|
[298] | 175 | detections), one can either set the parameter \texttt{flagXOutput = |
---|
| 176 | false} or use the \texttt{-x} command-line option: |
---|
[294] | 177 | \begin{quote} |
---|
| 178 | {\footnotesize |
---|
| 179 | \texttt{> Duchamp -x -p [parameter file]} |
---|
| 180 | }, or\\ |
---|
| 181 | {\footnotesize |
---|
| 182 | \texttt{> Duchamp -x -f [FITS file]} |
---|
| 183 | } |
---|
| 184 | \end{quote} |
---|
| 185 | |
---|
[158] | 186 | The following appendices provide details on the individual parameters, |
---|
[258] | 187 | and show examples of the output files that \duchamp produces. |
---|
[208] | 188 | |
---|
| 189 | \secB{Feedback} |
---|
| 190 | It may happen that you discover bugs or problems with \duchamp, or you |
---|
| 191 | have suggestions for improvements or additional features to be |
---|
| 192 | included in future releases. You can submit a ``ticket'' (a trackable |
---|
[258] | 193 | bug report) at the \duchamp Trac wiki at the following location:\\ |
---|
[231] | 194 | \href{http://sourcecode.atnf.csiro.au/cgi-bin/trac\_duchamp.cgi/newticket}% |
---|
| 195 | {\footnotesize |
---|
| 196 | http://sourcecode.atnf.csiro.au/cgi-bin/trac\_duchamp.cgi/newticket} |
---|
| 197 | \\(there is a link to this page from the Duchamp website). |
---|
[208] | 198 | |
---|
| 199 | There is also an email exploder, duchamp-user\textbf{[at]}atnf.csiro.au, |
---|
| 200 | that users can subscribe to keep up to date with changes, updates, and |
---|
| 201 | other news about \duchamp. To subscribe, send an email (from the |
---|
| 202 | account you wish to subscribe to the list) to |
---|
| 203 | duchamp-user-request\textbf{[at]}atnf.csiro.au with the single word |
---|
| 204 | ``subscribe'' in the body of the message. To be removed from this |
---|
| 205 | list, send a message with ``unsubscribe'' in its body to the same |
---|
| 206 | address. |
---|
| 207 | |
---|
[264] | 208 | \secB{Beta Versions} |
---|
| 209 | |
---|
| 210 | On the \duchamp website there may be a beta version listed in the |
---|
| 211 | downloads section. As \duchamp is still under development, there will |
---|
| 212 | be times when there has been new functionality added to the code, but |
---|
| 213 | the time has not yet come to release a new minor (or indeed major) |
---|
| 214 | version. |
---|
| 215 | |
---|
| 216 | Sometimes I will post the updated version of the code on the website |
---|
| 217 | as a ``beta'' version, particularly if I'm interested in people |
---|
| 218 | testing it. It will not have been tested as rigorously as the proper |
---|
| 219 | releases, but it will certainly work in the basic cases that I use to |
---|
| 220 | test it during development. So feel free to give it a try -- the |
---|
| 221 | \texttt{CHANGES} file will usually detail what is different to the last |
---|
| 222 | numbered release. |
---|