installation.html

来自「麻省理工的计算光子晶体的程序」· HTML 代码 · 共 541 行 · 第 1/2 页

use HDF.  (If you don't have HDF5, you can still compile MPB, but you
won't be able to output the fields or the dielectric function.)

<p>HDF is a widely-used, free, portable library and file format
for multi-dimensional scientific data, developed in the National
Center for Supercomputing Applications (NCSA) at the University of
Illinois (UIUC, home of the <a
href="http://www.fightingillini.com/">Fighting Illini</a> and <i>alma
mater</i> to many of this author's fine relatives).

<p>There are two incompatible versions of HDF, HDF4 and HDF5 (no, not
HDF1 and HDF2).  We require the newer version, HDF5.  Many
visualization and data-analysis tools still use HDF4, but HDF5
includes an <code>h5toh4</code> conversion program that you can use if
you need HDF4 files.

<p>HDF5 includes parallel I/O support under MPI, which can be enabled
by configuring it with <code>--enable-parallel</code>.  (You may also
have to set the <code>CC</code> environment variable to
<code>mpicc</code>. The resulting HDF5 library, however, may not work
with the serial MPB.)  This is <em>not</em> required to use the
parallel version of MPB.  MPB includes optional code to support this
feature, and it may result in faster file I/O in the parallel MPB, but
it is currently untested.  (Let me know if you try it out; the worst
that can happen is that MPB crashes or outputs garbage fields.)

<p>You can get HDF and learn about it on the <a
href="http://hdf.ncsa.uiuc.edu">HDF Home Page</a>.  We have also
collected some links to <a
href="http://ab-initio.mit.edu/mpb/hdf.html">useful HDF software</a>.

<h2><a name="fftw">FFTW</a></h2>

<p>FFTW is a self-optimizing, portable, high-performance FFT
implementation, including both serial and parallel FFTs.  You can
download FFTW and find out more about it from the <a
href="http://www.fftw.org">FFTW Home Page</a>.

<p>If you want to use MPB on a parallel machine with MPI, you will
also need to install the MPI FFTW libraries (this just means including
<code>--enable-mpi</code> in the FFTW <code>configure</code> flags).

<h2><a name="readline">GNU Readline</a> <i>(optional)</i></h2>

<p>GNU Readline is a library to provide command-line history,
tab-completion, emacs keybindings, and other shell-like niceties to
command-line programs.  This is an <em>optional</em> package, but one
that can be used by Guile (see below) if it is installed; we recommend
getting it.  You can <a href="ftp://ftp.gnu.org/gnu/readline">download
Readline from the GNU ftp site</a>.  (Readline is typically
preinstalled on GNU/Linux systems).

<h2><a name="guile">GNU Guile</a></h2>

<p>GNU Guile is an extension/scripting language implementation based on
Scheme, and we use it to provide a rich, fully-programmable
user interface with minimal effort.  It's free, of course, and you can
download it from the <a
href="http://www.gnu.org/software/guile/">Guile Home
Page</a>.  (Guile is typically included with GNU/Linux systems.)

<p><em>Important:</em> If you are using an RPM-based Linux system with
Guile pre-installed, please note that you must also install the
<code>guile-devel</code> RPM (which should be on your CD, but is not
installed by default).

<h2><a name="autoconf">GNU Autoconf</a> <i>(optional)</i></h2>

<p>If you want to be a developer of the MPB package (as opposed to
merely a user), you will also need the GNU Autoconf program.  Autoconf
is a portability tool that generates <code>configure</code> scripts to
automatically detect the capabilities of a system and configure a
package accordingly.  You can find out more at the <a
href="http://sources.redhat.com/autoconf/">Autoconf Home Page</a>
(autoconf is typically installed by default on Linux systems).  In
order to install Autoconf, you will also need the GNU <code>m4</code>
program if you do not already have it (see the <a
href="http://www.seindal.dk/rene/gnu/">GNU m4 Home Page</a>).

<h2><a name="libctl">libctl</a></h2>

<p>Instead of using Guile directly, we separated much of the user
interface code into a package called libctl, in the hope that this
might be more generally useful.  libctl automatically handles the
communication between the program and Guile, converting complicated
data structures and so on, to make it even easier to use Guile to
control scientific applications.  Download libctl from the <a
href="http://ab-initio.mit.edu/libctl/">libctl home site</a>, unpack
it, and run the usual <code>configure</code>, <code>make</code>,
<code>make install</code> sequence.  You'll also want to browse its <a
href="http://ab-initio.mit.edu/libctl/doc/">manual</a>, as this will
give you a general overview of what the user interface will be like.

<p>If you are not the system administrator of your machine, and/or
want to install libctl somewhere else (like your home directory), you
can do so with the standard <code>--prefix=<i>dir</i></code> option to
<code>configure</code> (the default prefix is
<code>/usr/local</code>).  In this case, however, you'll need to
specify the location of the libctl shared files for the MPB package,
using the <code>--with-libctl=<i>dir</i>/share/libctl</code> option to
the MPB <code>configure</code> script.

<h2><a name="mpb">MIT Photonic-Bands</a></h2>

<p>Okay, if you've made it all the way here, you're ready to install
the MPB package and start cranking out eigenmodes.  (You can download
the latest version and read this manual at the <a
href="http://ab-initio.mit.edu/mpb/">MIT Photonic-Bands Homepage</a>.)
Once you've unpacked it, just run:

<pre>
./configure
make
</pre>

<p>to configure and compile the package (see below to install).
Hopefully, the <code>configure</code> script will correctly detect the
BLAS, FFTW, etcetera libraries that you've dutifully installed, as
well as the C compiler and so on, and the <code>make</code>
compilation will proceed without a hitch.  If not, it's a <a
href="http://www.tuxedo.org/~esr/jargon/html/entry/SMOP.html">Simple
Matter of Programming</a> to correct the problem.
<code>configure</code> accepts several flags to help control its
behavior.  Some of these are standard, like
<code>--prefix=<i>dir</i></code> to specify and installation directory
prefix, and some of them are specific to the MPB package
(<code>./configure --help</code> for more info).  The
<code>configure</code> flags specific to MPB are:

<dl>

<p><dt><code>--with-inv-symmetry</code>
<dd>Assume <a href="user-ref.html#inv-symmetry">inversion symmetry</a>
in the dielectric function, allowing us to use real fields (in Fourier
space) instead of complex fields.  This gives a factor of 2 benefit in
speed and memory.  In this case, the MPB program will be installed as
<code>mpbi</code> instead of <code>mpb</code>, so that you can have
versions both with and without inversion symmetry installed at the
same time.  To install <em>both</em> <code>mpb</code> and
<code>mpbi</code>, you should do:

<pre>
./configure
make
su -c "make install"
make distclean
./configure --with-inv-symmetry
make
su -c "make install"
</pre>

<p><dt><code>--with-hermitian-eps</code>
<dd>Support the use of <a
href="user-ref.html#dielectric-anisotropic">complex-hermitian
dielectric tensors</a> (corresponding to magnetic materials, which
break inversion symmetry).

<p><dt><code>--enable-single</code>
<dd>Use single precision (C <code>float</code>) instead of the default
double precision (C <code>double</code>) for computations.  (Not
recommended.)

<p><dt><code>--without-hdf5</code>
<dd>Don't use the HDF5 library for field and dielectric function
output.  (In which case, no field output is possible.)

<p><dt><code>--with-mpi</code>
<dd>Attempt to compile a <a href="user-ref.html#mpb-mpi">parallel
version of MPB</a> using MPI; the resulting program will be installed
as <code>mpb-mpi</code>.  Requires <a href="#mpi">MPI</a> and <a
href="#fftw">MPI FFTW</a> libraries to be installed, as described
above.

<p>Does <em>not</em> compile the serial MPB, or <code>mpb-data</code>;
if you want those, you should <code>make distclean</code> and
compile/install them separately.  

<p><code>--with-mpi</code> <em>can</em> be used along with
<code>--with-inv-symmetry</code>, in which case the program is
installed as <code>mpbi-mpi</code> (try typing that five times
quickly).

<p><dt><code>--with-libctl=<i>dir</i></code>
<dd>If libctl was installed in a nonstandard location (i.e. neither
<code>/usr</code> nor <code>/usr/local</code>), you need to specify
the location of the libctl directory, <code><i>dir</i></code>.  This
is either <code><i>prefix</i>/share/libctl</code>, where
<code><i>prefix</i><code> is the installation prefix of libctl, or the
original libctl source code directory.

<p><dt><code>--with-blas=<i>lib</i></code>
<dd>The <code>configure</code> script automatically attempts to detect
accelerated BLAS libraries, like DXML (DEC/Alpha), SCSL and SGIMATH
(SGI/MIPS), ESSL (IBM/PowerPC), ATLAS, and PHiPACK.  You can, however,
force a specific library name to try via
<code>--with-blas=<i>lib</i></code>.

<p><dt><code>--with-lapack=<i>lib</i></code>
<dd>Cause the <code>configure</code> script to look for a LAPACK
library called <code><i>lib</i></code> (the default is to use
<code>-llapack</code>).

<p><dt><code>--disable-checks</code>
<dd>Disable runtime checks.  (Not recommended; the disabled checks
shouldn't take up a significant amount of time anyway.)

<p><dt><code>--enable-prof</code>
<dd>Compile for performance profiling.

<p><dt><code>--enable-debug</code>
<dd>Compile for debugging, adding extra runtime checks and so on.

<p><dt><code>--enable-debug-malloc</code>
<dd>Use special memory-allocation routines for extra debugging (to
check for array overwrites, memory leaks, etcetera).

<p><dt><code>--with-efence</code>
<dd>More debugging: use the <a
href="http://perens.com/FreeSoftware/">Electric Fence</a> library, if
available, for extra runtime array bounds-checking.

</dl>

<p>You can further control <code>configure</code> by setting various
environment variables, such as:

<ul>

<li><code>CC</code>: the C compiler command

<li><code>CFLAGS</code>: the C compiler flags (defaults to <code>-O3</code>).

<li><code>CPPFLAGS</code>: <code>-I<i>dir</i></code> flags to tell the
C compiler additional places to look for header files.

<li><code>LDFLAGS</code>: <code>-L<i>dir</i></code> flags to tell the
linker additional places to look for libraries.

<li><code>LIBS</code>: additional libraries to link against.

</ul>

<p>Once compiled, the main program (as opposed to various test
programs) resides in the <code>mpb-ctl/</code> subdirectory, and is
called <code>mpb</code>.  You can install this program under
</code>/usr/local</code> (or elsewhere, if you used the
<code>--prefix</code> flag for <code>configure</code>), by running:

<pre>
su -c "make install"
</pre>

<p>The "su" command is to switch to <code>root</code> for installation
into system directories.  You can just do <code>make install</code> if
you are installing into your home directory instead.

<p>If you make a mistake (e.g. you forget to specify a needed
<code>-L<i>dir</i></code> flag) or in general want to start over from
a clean slate, you can restore MPB to a pristine state by running:

<pre>
make distclean
</pre>

<hr>
Go to the <a href="user-tutorial.html">next</a>, <a href="introduction.html">previous</a>, or <a href="index.html">main</a> section.

</BODY>
</HTML>