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 | % ----------------------------------------------------------------------- |
---|
29 | \secA{Obtaining and installing \duchamp} |
---|
30 | \label{app-install} |
---|
31 | |
---|
32 | \secB{Installing} |
---|
33 | The \duchamp web page can be found at the following location:\\ |
---|
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: |
---|
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: |
---|
45 | \begin{itemize} |
---|
46 | \item \textsc{pgplot}: |
---|
47 | \href{http://www.astro.caltech.edu/~tjp/pgplot/}% |
---|
48 | {\footnotesize http://www.astro.caltech.edu/~tjp/pgplot/} |
---|
49 | \item \textsc{cfitsio}: |
---|
50 | \href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}% |
---|
51 | {\footnotesize http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html} |
---|
52 | \item \textsc{wcslib}: |
---|
53 | \href{http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}% |
---|
54 | {\footnotesize http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html} |
---|
55 | \end{itemize} |
---|
56 | |
---|
57 | \secC{Basic installation} |
---|
58 | |
---|
59 | \duchamp can be built on Unix/Linux systems by typing (assuming that |
---|
60 | the prompt your terminal provides is a \texttt{> } -- don't type this |
---|
61 | character!): |
---|
62 | \begin{quote} |
---|
63 | {\footnotesize |
---|
64 | \texttt{% |
---|
65 | > ./configure\\ |
---|
66 | > make\\ |
---|
67 | > make lib (optional -- to create a library for development |
---|
68 | purposes)\\ |
---|
69 | > make clean (optional -- to remove the object files)\\ |
---|
70 | > make install } |
---|
71 | } |
---|
72 | \end{quote} |
---|
73 | |
---|
74 | This default setup will search in standard locations for the necessary |
---|
75 | libraries, and install the executable (\texttt{Duchamp-\version}) |
---|
76 | in \texttt{/usr/local/bin}, along with a \texttt{Duchamp} symbolic |
---|
77 | link (a copy will also be in the current directory). The library (if |
---|
78 | you've made it) will be installed in \texttt{/usr/local/lib}, and the |
---|
79 | full set of header files will be installed in |
---|
80 | \texttt{/usr/local/include/duchamp} and subdirectories thereof. If |
---|
81 | you want these to go somewhere else, \eg if you don't have |
---|
82 | write-access to that directory, or you need to tweak the libraries, |
---|
83 | see the next section. Otherwise, jump to the testing section. |
---|
84 | |
---|
85 | \secC{Tweaking the installation process} |
---|
86 | |
---|
87 | The \texttt{configure} script allows the user to tailor the |
---|
88 | installation according to the particular requirements of their |
---|
89 | system. |
---|
90 | |
---|
91 | To install \duchamp in a directory other than \texttt{/usr/local/bin}, |
---|
92 | use the \texttt{--prefix} option with configure, specifying the |
---|
93 | directory above the \texttt{bin/} directory \eg |
---|
94 | \begin{quote} |
---|
95 | {\footnotesize |
---|
96 | \texttt{% |
---|
97 | > ./configure --prefix=/home/mduchamp} |
---|
98 | } |
---|
99 | \end{quote} |
---|
100 | and then run \texttt{make}, (\texttt{make lib} if you like), and |
---|
101 | \texttt{make install} as stated above. This will put the binary in the |
---|
102 | directory \texttt{/home/mduchamp/bin}. The library, if made, will be |
---|
103 | put in \texttt{/home/mduchamp/lib} and the header files will be put in |
---|
104 | \texttt{/home/mduchamp/include/duchamp} and subdirectories. |
---|
105 | |
---|
106 | If the above-mentioned libraries have been installed in non-standard |
---|
107 | locations, or you have more than one version installed on your system, |
---|
108 | you can specify specific locations by using the \texttt{configure} flags |
---|
109 | \texttt{--with-cfitsio=<dir>}, \texttt{--with-wcslib=<dir>} or |
---|
110 | \texttt{--with-pgplot=<dir>}. For example: |
---|
111 | \begin{quote} |
---|
112 | {\footnotesize |
---|
113 | \texttt{% |
---|
114 | > ./configure --with-wcslib=/home/mduchamp/wcslib-4.2} |
---|
115 | } |
---|
116 | \end{quote} |
---|
117 | |
---|
118 | Duchamp can be compiled without \textsc{pgplot} if it is not installed |
---|
119 | on your system -- the searching and text-based output remains the |
---|
120 | same, but you will not have any graphical output. To manually specify |
---|
121 | this option, you can either give \texttt{--without-pgplot} or |
---|
122 | \texttt{--with-pgplot=no} as arguments to \texttt{configure}: |
---|
123 | \begin{quote} |
---|
124 | {\footnotesize |
---|
125 | \texttt{% |
---|
126 | > ./configure --without-pgplot} |
---|
127 | } |
---|
128 | \end{quote} |
---|
129 | |
---|
130 | (Note that CFITSIO and WCSLIB are essential, however, so flags such as |
---|
131 | \texttt{--without-wcslib} or \texttt{--without-cfitsio} will not |
---|
132 | work.). Even if you do not give the \texttt{--without-pgplot} option, |
---|
133 | and the \textsc{pgplot} library is not found, Duchamp will still |
---|
134 | compile (albeit without graphical capabilities). |
---|
135 | |
---|
136 | An additional option that is useful is the ability to specify which |
---|
137 | compiler to use. This is very important for the Fortran compiler (used |
---|
138 | for linking due to the use of \textsc{pgplot}), particularly on Mac OS |
---|
139 | X, where \texttt{gfortran} is often used instead of \texttt{gcc}. To |
---|
140 | specify a particular Fortran compiler, use the \texttt{F77} flag: |
---|
141 | \begin{quote} |
---|
142 | {\footnotesize |
---|
143 | \texttt{% |
---|
144 | > ./configure F77=gfortran} |
---|
145 | } |
---|
146 | \end{quote} |
---|
147 | |
---|
148 | Of course, all desired flags should be combined in one |
---|
149 | \texttt{configure} call. For a full list of the options with |
---|
150 | \texttt{configure}, run: |
---|
151 | \begin{quote} |
---|
152 | {\footnotesize |
---|
153 | \texttt{% |
---|
154 | > ./configure --help} |
---|
155 | } |
---|
156 | \end{quote} |
---|
157 | Once \texttt{configure} has run correctly, simply run \texttt{make} |
---|
158 | and \texttt{make install} to build \duchamp and put it in the correct |
---|
159 | place (either \texttt{/usr/local/bin} or the location given by the |
---|
160 | \texttt{--prefix} option discussed above). |
---|
161 | |
---|
162 | \secC{Problems building Duchamp} |
---|
163 | |
---|
164 | While the configure script tries to get everything right, it can |
---|
165 | exhibit some quirks. For instance, in getting the X11 library |
---|
166 | configuration right, it will sometimes provide a |
---|
167 | \texttt{-R/path/to/X11} argument for the linking string. This is |
---|
168 | accepted by \texttt{ld}, but not by all versions of \texttt{gfortran}. |
---|
169 | This can cause the final linking step to fail (and for the |
---|
170 | \texttt{-lpgplot} argument to be left off). |
---|
171 | |
---|
172 | To fix this, a shell script is provided to quickly patch the Makefile |
---|
173 | if necessary. If you run make and it fails, due to this error: |
---|
174 | \begin{quote} |
---|
175 | {\footnotesize |
---|
176 | \texttt{% |
---|
177 | gfortran: error: unrecognized command line option â-Râ} |
---|
178 | } |
---|
179 | \end{quote} |
---|
180 | or similar, run |
---|
181 | \begin{quote} |
---|
182 | {\footnotesize |
---|
183 | \texttt{% |
---|
184 | > ./fixMakefile.sh} |
---|
185 | } |
---|
186 | \end{quote} |
---|
187 | and try again. If it still fails, you may have to manually edit the |
---|
188 | Makefile. Please log a bug report to let me know! |
---|
189 | |
---|
190 | |
---|
191 | |
---|
192 | \secC{Making sure it all works} |
---|
193 | |
---|
194 | Running make will create the executable \texttt{Duchamp-{\version}}. You can |
---|
195 | verify that it is running correctly by running the verification shell |
---|
196 | script: |
---|
197 | \begin{quote} |
---|
198 | {\footnotesize |
---|
199 | \texttt{> ./VerifyDuchamp.sh} |
---|
200 | } |
---|
201 | \end{quote} |
---|
202 | This will use a dummy FITS image in the \texttt{verification/} |
---|
203 | directory -- this image has some Gaussian random noise, with five |
---|
204 | Gaussian sources present, plus a dummy WCS. The script runs |
---|
205 | Duchamp on this image with nine different sets of inputs, and |
---|
206 | compares to known results, looking for differences and reporting |
---|
207 | any. There should be none reported if everything is working |
---|
208 | correctly. |
---|
209 | |
---|
210 | The script performs basic checks on the output files (results, log, |
---|
211 | VOTable, and annotation files), but ignores most of the actual values |
---|
212 | of source parameters (to avoid picking up just differences due to |
---|
213 | precision errors). For complete checks of the files, run |
---|
214 | \begin{quote} |
---|
215 | {\footnotesize |
---|
216 | \texttt{> ./VerifyDuchamp.sh -f} |
---|
217 | } |
---|
218 | \end{quote} |
---|
219 | Be warned that on some systems this could provide a large number of |
---|
220 | apparent errors which may only be due to precision differences. |
---|
221 | |
---|
222 | If everything worked, you can then install \duchamp on your system via: |
---|
223 | \begin{quote} |
---|
224 | {\footnotesize |
---|
225 | \texttt{> make install} |
---|
226 | } |
---|
227 | \end{quote} |
---|
228 | (this may need to be run as sudo depending on your system setup and |
---|
229 | your prefix directory). |
---|
230 | |
---|
231 | \secB{Running \duchamp} |
---|
232 | You can then run \duchamp on your own data. This can be done in one |
---|
233 | of two ways. The first is: |
---|
234 | \begin{quote} |
---|
235 | {\footnotesize |
---|
236 | \texttt{> Duchamp -f [FITS file]} |
---|
237 | } |
---|
238 | \end{quote} |
---|
239 | where \texttt{[FITS file]} is the file you wish to search. This method |
---|
240 | simply uses the default values of all parameters. |
---|
241 | |
---|
242 | The second method allows some determination of the parameter values by |
---|
243 | the user. Type: |
---|
244 | \begin{quote} |
---|
245 | {\footnotesize |
---|
246 | \texttt{> Duchamp -p [parameter file]} |
---|
247 | } |
---|
248 | \end{quote} |
---|
249 | where \texttt{[parameterFile]} is a file with the input parameters, |
---|
250 | including the name of the cube you want to search. There are two |
---|
251 | example input files included with the distribution. The smaller one, |
---|
252 | \texttt{InputExample}, shows the typical parameters one might want to |
---|
253 | set. The large one, \texttt{InputComplete}, lists all possible |
---|
254 | parameters that can be entered, and a brief description of them. To |
---|
255 | get going quickly, just replace the \texttt{"your-file-here"} in the |
---|
256 | \texttt{InputExample} file with your image name, and type |
---|
257 | \begin{quote} |
---|
258 | {\footnotesize |
---|
259 | \texttt{> Duchamp -p InputExample} |
---|
260 | } |
---|
261 | \end{quote} |
---|
262 | |
---|
263 | To disable the use of X-window plotting (in displaying the map of |
---|
264 | detections), one can either set the parameter \texttt{flagXOutput = |
---|
265 | false} or use the \texttt{-x} command-line option: |
---|
266 | \begin{quote} |
---|
267 | {\footnotesize |
---|
268 | \texttt{> Duchamp -x -p [parameter file]} |
---|
269 | }, or\\ |
---|
270 | {\footnotesize |
---|
271 | \texttt{> Duchamp -x -f [FITS file]} |
---|
272 | } |
---|
273 | \end{quote} |
---|
274 | |
---|
275 | The following appendices provide details on the individual parameters, |
---|
276 | and show examples of the output files that \duchamp produces. |
---|
277 | |
---|
278 | \secB{Feedback} |
---|
279 | It may happen that you discover bugs or problems with \duchamp, or you |
---|
280 | have suggestions for improvements or additional features to be |
---|
281 | included in future releases. You can submit a ``ticket'' (a trackable |
---|
282 | bug report) at the \duchamp Trac wiki at the following location:\\ |
---|
283 | \href{http://svn.atnf.csiro.au/trac/duchamp/newticket}% |
---|
284 | {http://svn.atnf.csiro.au/trac/duchamp/newticket} |
---|
285 | \\(there is a link to this page from the Duchamp website). |
---|
286 | |
---|
287 | There is also an email exploder, duchamp-user\textbf{[at]}atnf.csiro.au, |
---|
288 | that users can subscribe to keep up to date with changes, updates, and |
---|
289 | other news about \duchamp. To subscribe, send an email (from the |
---|
290 | account you wish to subscribe to the list) to |
---|
291 | duchamp-user-request\textbf{[at]}atnf.csiro.au with the single word |
---|
292 | ``subscribe'' in the body of the message. To be removed from this |
---|
293 | list, send a message with ``unsubscribe'' in its body to the same |
---|
294 | address. |
---|
295 | |
---|
296 | \secB{Beta Versions} |
---|
297 | |
---|
298 | On the \duchamp website there may be a beta version listed in the |
---|
299 | downloads section. As \duchamp is still under development, there will |
---|
300 | be times when there has been new functionality added to the code, but |
---|
301 | the time has not yet come to release a new minor (or indeed major) |
---|
302 | version. |
---|
303 | |
---|
304 | Sometimes I will post the updated version of the code on the website |
---|
305 | as a ``beta'' version, particularly if I'm interested in people |
---|
306 | testing it. It will not have been tested as rigorously as the proper |
---|
307 | releases, but it will certainly work in the basic cases that I use to |
---|
308 | test it during development. So feel free to give it a try -- the |
---|
309 | \texttt{CHANGES} file will usually detail what is different to the last |
---|
310 | numbered release. |
---|
311 | |
---|
312 | %%% Local Variables: |
---|
313 | %%% mode: latex |
---|
314 | %%% TeX-master: "Guide" |
---|
315 | %%% End: |
---|