File: installation.xml

package info (click to toggle)
apbs 1.0.0-2
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 38,840 kB
  • ctags: 7,893
  • sloc: ansic: 44,537; xml: 21,399; sh: 20,613; fortran: 17,796; yacc: 2,922; python: 2,804; makefile: 567; lex: 294; sed: 205; java: 134; awk: 26
file content (463 lines) | stat: -rw-r--r-- 22,601 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
<chapter id="installation-sect"> <title>Installation</title> 
	<para>The following sections outline the installation of APBS on a generic
		UNIX platform as well as installation instructions for various specific
		machines.</para> 

	<sect1 id="obtaining-sect"> <title>Availability</title>
		<para>The latest version of APBS can always be found at <ulink url="http://apbs.sourceforge.net/">
				http://apbs.sourceforge.net</ulink>.  APBS is available in both source code form and
			binaries for a variety of architectures.</para>
	</sect1>

	<sect1> <title>Binary installation</title>

		<para>
			We currently offer binaries for the RedHat Linux platform on a variety of architectures as well as command line binaries for WinXP and Mac OS X.  Binaries can be downloaded from the <ulink url="http://agave.wustl.edu/apbs/download">APBS download page</ulink>.  For all other systems, please install from source on your particular platform and feel free to contact the <link linkend="mailing-lists">APBS users mailing list</link> for more help and/or to request a binary for that system.
		</para>

		<para>
			APBS binaries are provided in compressed tar format (*.tgz).  On most systems, the binaries can be unarchived by simply double-clicking or opening the archive.  This can also be accomplished on the comamnd line by
			<screen>
<prompt>$</prompt> <userinput>gzip -dc apbs-&apbsver;-XYZ.tgz | tar xvf -</userinput>
			</screen>
			where <userinput>XYZ</userinput> is the particular architecture of the binary you downloaded.
			Note that this will expand into a directory called <filename>apbs-&apbsver;-XYZ</filename>.  The contents of this directory can be placed anywhere on your system that you prefer (and have access to).  The specific sub-directory of this archive is described in <xref linkend="install-dirs"/>, which contains information about the location of documentation, examples, libraries, header files, and binaries.  The APBS binaries do not contain dependencies on special data files, etc. and can be moved out of this directory structure without causing any problems for APBS execution.
		</para>

	</sect1>

	<sect1> <title>Source installation</title>

		<para>If you were unable to find the binary pacakge for your system, or would like to compile APBS
			yourself, you'll need to read the instructions in this section.</para>

		<sect2 id="prerequisites-sect"> <title>Prerequisites</title>  
			<para>In order to install APBS from the source code, you will need:
				<itemizedlist> 
					<listitem> <para>C and Fortran compilers</para> </listitem>
					<listitem> <para>The APBS source code (see 
							<link linkend="obtaining-sect">above</link>)</para> </listitem>
				</itemizedlist>
				<note>
					<para> Note that the <ulink url="http://www.scicomp.ucsd.edu/~mholst">Holst
							group</ulink> <ulink
							url="http://www.scicomp.ucsd.edu/~mholst/codes/maloc/index.html">MALOC</ulink>
						source code is now provided with APBS to facilitate installation.</para>
				</note>
				It may also be useful to have:
				<itemizedlist>
					<listitem> 
						<para>A version of MPI (try <ulink
								url="http://www-unix.mcs.anl.gov/mpi/mpich/">MPICH</ulink>)
							for parallel jobs.  
							<note>
								<para>
									MPI isn't strictly necessary if the <link
										linkend="elec-async"><option>async</option></link>
									option is used.
								</para>
							</note>
						</para>
					</listitem>
					<listitem>
						<para>A vendor-supplied version of BLAS for optimal performance.  APBS
							will attempt to locate common BLAS libraries during the
							configuration process.</para>
					</listitem>
				</itemizedlist>
			</para>
		</sect2>

		<sect2 id="tested-systems"> <title>Tested systems</title>
			<para> Source-code-based installation has been tested on the following systems
				<itemizedlist>
					<listitem> AMD 64 (Opteron) running Fedora Core 6 Linux </listitem>
					<listitem> IBM Power4 running RedHat Enterprise Linux 3 </listitem>
					<listitem> SGI Itanium2 (Altix) running IRIX/Linux </listitem>
					<listitem> Apple PowerPC running Mac OS X </listitem>
					<listitem> Apple x86_64 running Mac OS X </listitem>
				</itemizedlist>
				However, the installation procedure is rather generic and generally works on most
				UNIX-based systems.  System-specific installation notes and caveats are provided in
				<xref linkend="machine-sect"/>.
			</para>
		</sect2>

		<sect2 id="setup-sect"> <title>Preparation for installation</title>

			<para>In what follows, I'll be assuming you're using 
				<ulink url="http://www.gnu.org/software/bash/bash.html">bash</ulink>, a shell available
				on most platforms (UNIX and non-UNIX).</para>

			<sect3> <title>Compiler variables</title>
				<para>First, please look at <xref linkend="machine-sect"/> section of this document for
					appropriate compiler flags, etc. to be set via pre-configuration environmental
					variables.  This section outlines generic installation procedures with default
					compilers and options.</para>
			</sect3>

			<sect3> <title>Installation directories</title>
				<para>There are a few directories you'll need to identify prior to installation.  The
					first, which we'll call <parameter>APBS_SRC</parameter>, will contain the APBS
					and MALOC source code.  This directory can be deleted after installation, if you
					wish.  The second directory will be the permanent location for APBS and MALOC;
					we'll call this <parameter>APBS_PREFIX</parameter>.  If you have root
					permission, you could pick a global directory such as
					<filename>/usr/local</filename> for this; otherwise, pick a directory for which
					you have write permission.  The following commands set up the directories and
					environmental which point to them:
					<screen>
<prompt>$</prompt> <userinput>export APBS_SRC=/home/soft/src</userinput>
<prompt>$</prompt> <userinput>export APBS_PREFIX=/home/soft</userinput>
<prompt>$</prompt> <userinput>mkdir -p ${APBS_SRC} ${APBS_PREFIX}</userinput>
					</screen>
				</para>
			</sect3>

			<sect3> <title>Unpacking the source code</title>
				<para>You're now ready to unpack the source code:
					<screen>
<prompt>$</prompt> <userinput>cd ${APBS_SRC}</userinput>
<prompt>$</prompt> <userinput>gzip -dc apbs-&apbsver;.tar.gz | tar xvf -</userinput>
					</screen>
				</para>
			</sect3>

		</sect2>

		<sect2> <title>Configuring, compiling, and installing</title>
			<para> Before compiling/installing APBS, you need to configure with the autoconf
				<literal>configure</literal> script.  You can examine the various configure options with
				the <option>--help</option> option.  For many platforms, no options need to be
				specified.  Therefore, most users <emphasis>who want single-CPU (not parallel)
					binaries</emphasis> can configure as follows:
				<screen>
<prompt>$</prompt> <userinput>cd ${APBS_SRC}/apbs</userinput>
<prompt>$</prompt> <userinput>./configure --prefix=${APBS_PREFIX}</userinput>
				</screen>
				Other configuration options, including the compilation of parallel binaries and the use
				of machine-specific compilers and Python usage, are discussed in <xref
					linkend="machine-sect"/>.
			</para>
			<para>
				Assuming all has gone well with the configuration (you'll generally get an error message
				if configuration fails), you're ready to compile 
				<screen>
<prompt>$</prompt> <userinput>make all</userinput>
				</screen>
				and install APBS:
				<screen>
<prompt>$</prompt> <userinput>make install</userinput>
				</screen>
			</para>
		</sect2>

		<sect2 id="install-dirs"> <title>APBS directory structure</title>
			<para>
				The APBS installation process (whether compiled from source or installed as pre-compiled binaries) will create several directories under
				<parameter>${APBS_PREFIX}</parameter>:
				<itemizedlist>
					<listitem> 
						<para> <filename>bin</filename>, where the main
							<filename>apbs</filename> binary resides</para>
					</listitem>
					<listitem> 
						<para> <filename>share</filename>, which contains the documentation (user guide, tutorial, programmer's guide) as well as a number of
							examples and test cases for APBS </para>
					</listitem>
					<listitem> 
						<para> <filename>include</filename>, which contains header files for
							using APBS libraries with other applications </para>
					</listitem>
					<listitem> 
						<para> <filename>lib</filename>, which contains library files for
							using APBS libraries with other applications </para>
					</listitem>
					<listitem> 
						<para> <filename>tools</filename>, which contains a number of "helper"
							applications for use with APBS. </para>
					</listitem>
				</itemizedlist>
				At this point you are ready to use APBS; either by calling the binary directly or adding
				the above directory to your path.  As mentioned above, there are also several tools
				provided with APBS that remain in the APBS directory; these are described in later
				portions of this manual.  You may wish to copy these to a global location (or the same
				place as your APBS binary) at this time.
			</para>
		</sect2>

		<sect2> <title id="machine-sect">System-specific notes</title>
			<important>
				<para> If you have tips or tricks on improving APBS performance and/or installation on
					your machine, please <link linkend="mailing-lists">let us know!</link> </para>
			</important>
			<para>This section provides tips on compiling APBS on specific platforms and outlines some of
				the basic options available for parallel execution, Python linkage, etc.  Note that many
				aspects of this section have changed from previous releases.  In particular, APBS now
				tries to detect the optimal compilers and BLAS libraries on most systems without user
				intervention.
			</para>
			<para>
				As described above, the default configure-make-install procedure is
				<screen>
<prompt>$</prompt> <userinput>./configure --prefix=${APBS_PREFIX}</userinput>
<prompt>$</prompt> <userinput>make </userinput>
<prompt>$</prompt> <userinput>make install</userinput>
				</screen>
				The configure script includes a number of generic options to manually set default
				compilers, link behaviors, preprocessors, etc.  These can be reviewed by running
				<screen>
<prompt>$</prompt> <userinput>./configure --help</userinput>
				</screen>
			</para>

			<sect3> <title>Using an external BLAS library</title> 
				<para>If an optimized (vendor) BLAS library is available, it should be used with APBS since it will generally provide better performance.  This can be enabled by the <code>--with-blas=...</code> option.  The configure-make-install procedure is:
					<screen>
<prompt>$</prompt> <userinput>./configure --with-blas='-L/path/to/blas -lblas'</userinput>
<prompt>$</prompt> <userinput>make</userinput>
<prompt>$</prompt> <userinput>make install</userinput>
					</screen>
					where <userinput>/path/to/blas</userinput> is the location of a library named <userinput>libblas.a</userinput>.
				</para>
			</sect3>

			<sect3> <title>Python support</title> 
				<para>Python libraries and related tools can be enabled at configure-time.  Currently,
					Python libraries compile on most Linux and Mac systems.  Other systems are
					untested.  The configure-make-install procedure is:
					<screen>
<prompt>$</prompt> <userinput>./configure --enable-python --prefix=${APBS_PREFIX}</userinput>
<prompt>$</prompt> <userinput>make </userinput>
<prompt>$</prompt> <userinput>make install</userinput>
					</screen>
				</para>
			</sect3>

			<sect3> <title>Parallel (MPI) support</title>
				<para> APBS uses MPI for parallel execution.  In general, MPI support requires informing
					the APBS configure script about:
					<itemizedlist>
						<listitem>
							<para> MPI compiler options.  For most MPI implementations, you
								simply need to set the <parameter>CC</parameter> and
								<parameter>F77</parameter> variables to point to the
								MPI-savvy C and FORTRAN compilers.  However, it is
								occasionally necessary to manually specify compiler
								options by setting 
								<parameter>CFLAGS</parameter>,
								<parameter>CPPFLAGS</parameter>,
								<parameter>FFLAGS</parameter>, and
								<parameter>LDFLAGS</parameter> before configuration.
							</para>
						</listitem>
						<listitem>
							<para> MPI library/header file locations.  As outlined below,
								paths to the library and header files for <ulink
									url="http://www.lam-mpi.org/">LAM</ulink> and
								<ulink
									url="http://www-unix.mcs.anl.gov/mpi/">MPICH</ulink>
								implementations of MPI can be specified with the
								<option>--with-lam</option>,
								<option>--with-mpich</option>, or
								<option>--with-mpich2</option> configure options.  Other
								MPI implementations will require the 
								<parameter>CFLAGS</parameter>,
								<parameter>CPPFLAGS</parameter>,
								<parameter>FFLAGS</parameter>, and
								<parameter>LDFLAGS</parameter> variables to be set
								correctly before configuration to locate the required
								headers and libraries. </para>
						</listitem>
					</itemizedlist>
				</para>

				<sect4> <title>LAM MPI</title>
					<para> It is important that you enable FORTRAN support and use the same
						compilers you will use to compile APBS when installing/compiling 
						<ulink url="http://www.lam-mpi.org/">LAM MPI</ulink>.  For example, if
						your C compiler is set in the environmental variable
						<parameter>${CC}</parameter> and your FORTRAN compiler is set in the
						environmental variable <parameter>${F77}</parameter>, then you should
						configure <emphasis>LAM</emphasis> with the command
						<screen>
<prompt>$</prompt> <userinput>./configure --prefix=${MPI_PREFIX} --with-fc=${F77}</userinput>
						</screen>
					</para>
					<para> Let <parameter>${MPI_PREFIX}</parameter> be an environmental variable
						pointing to the directory where <ulink
							url="http://www.lam-mpi.org/">LAM MPI</ulink> is installed.  
						In
						other words, <filename>${MPI_PREFIX}/lib</filename> should contain the
						LAM MPI libraries and <filename>${MPI_PREFIX}/include</filename> should
						contain the LAM MPI header files.  The configure-make-install procedure
						is then
						<screen>
<prompt>$</prompt> <userinput>export CC=${MPI_PREFIX}/bin/mpicc</userinput>
<prompt>$</prompt> <userinput>export F77=${MPI_PREFIX}/bin/mpif77</userinput>
<prompt>$</prompt> <userinput>./configure --with-lam=${MPI_PREFIX} --prefix=${APBS_PREFIX}</userinput>
<prompt>$</prompt> <userinput>make </userinput>
<prompt>$</prompt> <userinput>make install</userinput>
						</screen>
						This procedure was tested with LAM MPI 7.2.1.
					</para>
				</sect4>

				<sect4> <title>MPICH1</title>
					<para> It is important that you enable FORTRAN support and use the same
						compilers you will use to compile APBS when installing/compiling 
						<ulink url="http://www-unix.mcs.anl.gov/mpi/mpich1/">MPICH1</ulink>.
						For example, if your C compiler is set in the environmental variable
						<parameter>${CC}</parameter> and your FORTRAN compiler is set in the
						environmental variable <parameter>${F77}</parameter>, then you should
						configure <emphasis>MPICH1</emphasis> with the command
						<screen>
<prompt>$</prompt> <userinput>./configure --prefix=${MPI_PREFIX} ... --enable-f77</userinput>
						</screen>
						where <option>...</option> denotes other machine-specific options such as 
						<option>--with-device=ch_p4</option> or
						<option>--with-arch=LINUX</option>.
					</para>
					<para> Let <parameter>${MPI_PREFIX}</parameter> be an environmental variable
						pointing to the directory where 
						<ulink url="http://www-unix.mcs.anl.gov/mpi/mpich1/">MPICH1</ulink> 
						is installed.  In other words, <filename>${MPI_PREFIX}/lib</filename>
						should contain the
						MPICH1 
						libraries and <filename>${MPI_PREFIX}/include</filename> should contain
						the 
						MPICH1 
						header files.  The configure-make-install procedure
						is then
						<screen>
<prompt>$</prompt> <userinput>export CC=${MPI_PREFIX}/bin/mpicc</userinput>
<prompt>$</prompt> <userinput>export F77=${MPI_PREFIX}/bin/mpif77</userinput>
<prompt>$</prompt> <userinput>./configure --with-mpich=${MPI_PREFIX} --prefix=${APBS_PREFIX}</userinput>
<prompt>$</prompt> <userinput>make </userinput>
<prompt>$</prompt> <userinput>make install</userinput>
						</screen>
						This procedure was tested with MPICH2 1.0.6p1.
					</para>
				</sect4>

				<sect4> <title>MPICH2</title>
					<para> It is important that you enable FORTRAN support and use the same
						compilers you will use to compile APBS when installing/compiling 
						<ulink url="http://www-unix.mcs.anl.gov/mpi/mpich1/">MPICH2</ulink>.
					</para>
					<para> Let <parameter>${MPI_PREFIX}</parameter> be an environmental variable
						pointing to the directory where 
						<ulink url="http://www-unix.mcs.anl.gov/mpi/mpich2/">MPICH2</ulink> 
						is installed.  In other words, <filename>${MPI_PREFIX}/lib</filename>
						should contain the
						MPICH2 
						libraries and <filename>${MPI_PREFIX}/include</filename> should contain
						the 
						MPICH2 
						header files.  The configure-make-install procedure
						is then
						<screen>
<prompt>$</prompt> <userinput>export CC=${MPI_PREFIX}/bin/mpicc</userinput>
<prompt>$</prompt> <userinput>export F77=${MPI_PREFIX}/bin/mpif77</userinput>
<prompt>$</prompt> <userinput>./configure --with-mpich2=${MPI_PREFIX} --prefix=${APBS_PREFIX}</userinput>
<prompt>$</prompt> <userinput>make </userinput>
<prompt>$</prompt> <userinput>make install</userinput>
						</screen>
						This procedure was tested with MPICH1 1.2.7p1.
					</para>
				</sect4>


			</sect3>

			<sect3> <title>FEtk support</title>
				<para> 
					In order to enable support for the finite element features in APBS, you must
					compile it against the <ulink url="http://www.fetk.org">FEtk</ulink> libraries.
					<emphasis>Please use the same compilers for both APBS and FEtk.</emphasis>
					Let <parameter>${FETK_PREFIX}</parameter> be an environmental variable pointing
					to the directory where FEtk was installed.  In other words,
					<filename>${FETK_PREFIX}/lib</filename> should contain the FEtk machine-specific
					library directories and <filename>${FETK_PREFIX}/include</filename> should
					contain the FEtk header files.  You'll first need to identify the appropriate
					library directory for your system in <filename>${FETK_PREFIX}/lib</filename>.
					For the purposes of this example, let's suppose this directory is
					<filename>${FETK_PREFIX}/lib/x86_64-unknown-linux-gnu</filename>.
					The configure-make-install procedure for APBS is then
					<screen>
<prompt>$</prompt> <userinput>./configure --with-fetk-include=${FETK_PREFIX}/include --with-fetk-library=${FETK_PREFIX}/lib/x86_64-unknown-linux-gnu --prefix=${APBS_PREFIX}</userinput>
<prompt>$</prompt> <userinput>make </userinput>
<prompt>$</prompt> <userinput>make install</userinput>
					</screen>
				</para>
			</sect3>

			<sect3> <title>Windows</title>
				<para>We are happy to now provide native APBS command line binaries for Windows.  The
					binary is probably the best option available, but if you would still like to
					compile your own binaries you will need to use either the Cygwin or MinGW
					environments.  Binaries compiled under Cygwin tend to require Cygwin DLLs and
					thus can only be run on systems with Cygwin.  Performance for the Windows
					binaries and all compiled systems will be fairly mediocre as they depend on the
					GNU compilers.</para>
				<para>If you do choose to use Cygwin and compile your own code, compilation should be
					rather straightforward.</para>
			</sect3>

			<sect3> <title>Macintosh</title>
				<para>We are happy to now provide a Mac install package for Mac OS 10.4 
					(Tiger).  Unfortunately this is the only binary for Mac that we have
					available, so users on OS 10.3 may have to compile binaries for themselves - you
					may want to examine the
					<ulink url="http://sourceforge.net/mailarchive/forum.php?forum=apbs-users">apbs-users 
						mailing list</ulink> which has a number of threads which discuss
					installation on Mac OS platforms.  Alternatively you can try using
					Fink for the installation - please see Bill Scott's excellent 
					guidelines at <ulink url="http://chemistry.ucsc.edu/~wgscott/xtal"> 
						http://chemistry.ucsc.edu/~wgscott/xtal</ulink>. </para>
				<para>A few notes about compiling on Macintosh:
					<orderedlist>
						<listitem>
							<para>It has become apparent from the mailing lists that some
								"packages" of the GNU development software available for MacOS
								contain different major versions of the C and FORTRAN compilers.  
								This is very bad; APBS will not compile with different versions of 
								the C and FORTRAN compilers. If you use GCC 4.0, for instance,
								gfortran 4.0 will work while g77 3.3 will not. If you see link 
								errors involving "restFP" or "saveFP" this is most likely the 
								cause.</para>
						</listitem>
						<listitem>
							<para>In gcc 4.0 (included in <ulink
									url="http://www.apple.com/macosx/features/xcode/">Xcode</ulink>
								2.0 and higher) the -fast option turns on the -fast-math flag.
								This flag optimizes by using rounding, and thus can lead to
								inaccuate results and should be avoided.</para>
						</listitem>
						<listitem>
							<para>As it stands now the autoconf script does not support using
								the native vecLib framework as an architecture-tuned BLAS 
								replacement.  In testing there were only slight timing 
								improvements over using the MALOC-supplied BLAS as it is.</para>
						</listitem>
						<listitem>
							<para>We have had success using IBM's XLF for Mac in conjunction
								with GCC 4.0, although the corresponding XLC compilers do not 
								seem to work under Tiger.</para>
						</listitem>
					</orderedlist>  
				</para>
				<para> Finally, Dave Gohara has prepared 
					<ulink
						url="http://www.macresearch.org/tutorial_building_configure_make_projects_in_xcode">a
						nice tutorial</ulink>
					on building APBS from within <ulink
						url="http://www.apple.com/macosx/features/xcode/">Xcode</ulink> to take
					advantage of its development and debugging features.
				</para>
			</sect3>


		</sect2>
	</sect1>
</chapter>