mpb-1.4.2/ 0002755 0001754 0000144 00000000000 07631010734 006040 5 mpb-1.4.2/doc/ 0002755 0001754 0000144 00000000000 07631010727 006607 5 mpb-1.4.2/doc/acknowledgments.html 0000644 0001754 0000144 00000004367 07374654650 012627
Acknowledgments
Go to the next, previous, or main section.
Acknowledgments
This work was supported in part by the Materials Research Science
and Engineering Center program of the National Science Foundation
under Grant No. DMR-9400334, the U.S. Army Research Office under
contract/grant DAAG55-97-1-0366, a National Defense Science and
Engineering Fellowship, and an MIT Karl Taylor Compton Fellowship.
Clarendon Photonics, Inc., deserves special mention for funding
development of the parallel version of MPB.
This project is also deeply indebted to the free software community
for many invaluable tools and libraries, especially the GNU project
(for Guile, gcc, autoconf, and other software, as well as its
courageous leadership), the GNU/Linux operating system, the National
Center for Supercomputing Applications at the University of Illinois
(for HDF), and the LAPACK/BLAS developers.
S. G. Johnson thanks Dr. Matteo Frigo for his friendship,
inspiration, and definition of "legacy code" as "any program written
by a physicist." Dr. Shanhui Fan and Dr. Pierre R. Villeneuve endured
endless interruptions by their group-mate and were generous with their
patience and enthusiasm. Thanks to Dr. Douglas C. Allan of Corning
for pestering (and bribing) me to bring the program to a usable state,
and his colleague Karl Koch for being the first beta tester.
Robert D. Meade deserves credit for writing a predecessor to this
program that was used in our group for many years. Although it does
not share any code with MPB, his software blazed our algorithmic path
and formed an invaluable baseline for testing.
This project would not exist without the tireless guidance,
support, and encouragement of Prof. J. D. Joannopoulos of MIT. Thanks
for letting me do things my way, John!
Go to the next, previous, or main section.
mpb-1.4.2/doc/analysis-tutorial.html 0000644 0001754 0000144 00000051564 07442767513 013126
Data Analysis Tutorial
Go to the next, previous, or main section.
Data Analysis Tutorial
In the previous section, we focused on how to perform a calculation
in MPB. Now, we'll give a brief tutorial on what you might do with
the results of the calculations, and in particular how you might
visualize the results. We'll focus on two systems, one
two-dimensional and one three-dimensional.
First, we'll return to the two-dimensional triangular lattice of rods in
air from the tutorial. The control file for this calculation, which
can also be found in mpb-ctl/examples/tri-rods.ctl, will
consist of:
Notice that we're computing both TM and TE bands (where we expect a
gap in the TM bands), and are outputting the z component of the
electric field for the TM bands at the K point. (The
fix-efield-phase will be explained below.)
Now, run the calculation, directing the output to a file, by
entering the following command at the Unix prompt:
In most cases, the first thing we'll want to do is to look at the
dielectric function, to make sure that we specified the correct
geometry. We can do this by looking at the epsilon.h5
output file.
The first thing that might come to mind would be to examine
epsilon.h5 directly, say by converting it to a PNG image with
h5topng (from my free h5utils package),
magnifying it by 3:
unix% h5topng -S 3 epsilon.h5
The resulting image
(epsilon.png) is shown at right, and it initially seems
wrong! Why is the rod oval-shaped and not circular? Actually, the
dielectric function is correct, but the image is distorted because the
primitive cell of our lattice is a rhombus (with 60-degree acute
angles). Since the output grid of MPB is defined over the
non-orthogonal unit cell, while the image produced by
h5topng (and most other plotting programs) is square, the
image is skewed.
We can fix the image in a variety of ways, but the best way is
probably to use the mpb-data utility included (and
installed) with MPB. mpb-data allows us to rearrange the
data into a rectangular cell (-r) with the same
area/volume, expand the data to include multiple periods (-m
periods), and change the resolution per unit distance in
each direction to a fixed value (-n resolution).
man mpb-data or run mpb-data -h for more
options. In this case, we'll rectify the cell, expand it to three
periods in each direction, and fix the resolution to 32 pixels per
a:
unix% mpb-data -r -m 3 -n 32 epsilon.h5
It's important to use -n when you use -r,
as otherwise the non-square unit cell output by -r will
have a different density of grid points in each direction, and appear
distorted. The output of mpb-data is by default an
additional dataset within the input file, as we can see by running
h5ls:
Here, the new dataset
output by mpb-data is the one called
data-new. We can examine it by running
h5topng again, this time explicitly specifying the name
of the dataset (and no longer magnifying):
unix% h5topng epsilon.h5:data-new
The new epsilon.png output image is shown at right.
As you can see, the rods are now circular as desired, and they clearly
form a triangular lattice.
At this point, let's check for band gaps by picking out lines with
the word "Gap" in them:
unix% grep Gap tri-rods.out
Gap from band 1 (0.275065617068082) to band 2 (0.446289918847647), 47.4729292989213%
Gap from band 3 (0.563582903703468) to band 4 (0.593059066215511), 5.0968516236891%
Gap from band 4 (0.791161222813268) to band 5 (0.792042731370125), 0.111357548663006%
Gap from band 5 (0.838730315053238) to band 6 (0.840305955160638), 0.187683867865441%
Gap from band 6 (0.869285340346465) to band 7 (0.873496724070656), 0.483294361375001%
Gap from band 4 (0.821658212109559) to band 5 (0.864454087942874), 5.07627823271133%
The first five gaps are for the TM bands (which we ran first), and
the last gap is for the TE bands. Note, however that the < 1% gaps
are probably false positives due to band crossings, as described in
the user tutorial. There are
no complete (overlapping TE/TM) gaps, and the largest gap is the 47%
TM gap as expected. (To be absolutely sure of this and other band gaps, we
would also check k-points within the interior of the Brillouin zone,
but we'll omit that step here.)
Next, let's plot out the band structure. To do this, we'll first
extract the TM and TE bands as comma-delimited text, which can then be
imported and plotted in our favorite spreadsheet/plotting program.
The TM and TE bands are both plotted below against the "k index"
column of the data, with the special k-points labelled. TM bands are
shown in blue (filled circles) with the gaps shaded light blue, while
TE bands are shown in red (hollow circles) with the gaps shaded light
red.
Note that we truncated the upper frequencies at a cutoff of 1.0 c/a.
Although some of our bands go above that frequency, we didn't compute
enough bands to fill in all of the states in that range. Besides, we
only really care about the states around the gap(s), in most cases.
Now, let's actually examine the electric-field distributions for
some of the bands (which were saved at the K point, remember).
Besides looking neat, the field patterns will tell us about the
characters of the modes and provide some hints regarding the origin of
the band gap.
As before, we'll run mpb-data on the field output
files (named e.k11.b*.z.tm.h5), and then run
h5topng to view the results:
Here, we've used the -C option to superimpose (crude)
black contours of the dielectric function over the fields, -c
bluered to use a blue-white-red color table, -Z to
center the color scale at zero (white), and -d to specify
the dataset name for all of the files at once. man
h5topng for more information. (There are plenty of
data-visualization programs available if you want more sophisticated
plotting capabilities than what h5topng offers, of
course; you can use h5totxt to convert the data to a
format suitable for import into e.g. spreadsheets.)
Note that the dataset name is z.r-new, which is the
real part of the z component of the output of mpb-data.
(Since these are TM fields, the z component is the only non-zero part
of the electric field.) The real and imaginary parts of the fields
correspond to what the fields look like at half-period intervals in
time, and in general they are different. However, at K they are
redundant, due to the inversion symmetry of that k-point (proof left
as an exercise for the reader). Usually, looking at the real parts
alone gives you a pretty good picture of the state, especially if you
use fix-efield-phase (see below), which chooses the phase
to maximize the field energy in the real part. Sometimes, though, you
have to be careful: if the real part happens to be zero, what you'll
see is essentially numerical noise and you should switch to the
imaginary part.
The resulting field images are shown below:
TM band 1
TM band 2
TM band 3
TM band 4
TM band 5
TM band 6
TM band 7
TM band 8
Your images should look the same as the ones above. If we hadn't
included fix-efield-phase before
output-efield-z in the ctl file, on the other hand, yours
would have differed slightly (e.g. by a sign or a lattice shift),
because by default the phase is random.
When we look at the real parts of the fields, we are really looking
at the fields of the modes at a particular instant in time (and the
imaginary part is half a period later). The point in time (relative
to the periodic oscillation of the state) is determined by the phase
of the eigenstate. The fix-efield-phase band function
picks a canonical phase for the eigenstate, giving us a deterministic
picture.
We can see several things from these plots:
First, the origin of the band gap is apparent. The lowest band is
concentrated within the dielectric rods in order to minimize its
frequency. The next bands, in order to be orthogonal, are forced to
have a node within the rods, imposing a large "kinetic energy" (and/or
"potential energy") cost and hence a gap. Successive bands have more
and more complex nodal structures in order to maintain orthogonality.
(The contrasting absence of a large TE gap has to do with boundary
conditions. The perpendicular component of the displacement field
must be continuous across the dielectric boundary, but the parallel
component need not be.)
We can also see the deep impact of symmetry on the states. The K
point has C3v symmetry (not quite the full C6v
symmetry of the dielectric structure). This symmetry group has only
one two-dimensional representation--that is what gives rise to the
degenerate pairs of states (2/3, 4/5, and 7/8), all of which fall into
this "p-like" category (where the states transform like two orthogonal
dipole field patterns, essentially). The other two bands, 1 and 6,
transform under the trivial "s-like" representation (with band 6 just
a higher-order version of 1).
"Then were the entrances of this world made narrow, full of sorrow and
travail: they are but few and evil, full of perils, and very
painful." (Ezra 4:7)
Now, let us turn to a three-dimensional structure, a diamond
lattice of dielectric spheres in air. The basic techniques to compute
and analyze the modes of this structure are the same as in two
dimensions, but of course, everything becomes more complicated in 3d.
It's harder to find a structure with a complete gap, the modes are no
longer polarized, the computations are far bigger, and visualization
is much more difficult, for starters.
(The band gap of the diamond structure was first identified in:
K. M. Ho, C. T. Chan, and C. M. Soukoulis, "Existence of a photonic
gap in periodic dielectric structures," Phys. Rev. Lett.65, 3152 (1990).)
The control file for this calculation, which can also be found in
mpb-ctl/examples/diamond.ctl, consists of:
(set! geometry-lattice (make lattice
(basis-size (sqrt 0.5) (sqrt 0.5) (sqrt 0.5))
(basis1 0 1 1)
(basis2 1 0 1)
(basis3 1 1 0)))
; Corners of the irreducible Brillouin zone for the fcc lattice,
; in a canonical order:
(set! k-points (interpolate 4 (list
(vector3 0 0.5 0.5) ; X
(vector3 0 0.625 0.375) ; U
(vector3 0 0.5 0) ; L
(vector3 0 0 0) ; Gamma
(vector3 0 0.5 0.5) ; X
(vector3 0.25 0.75 0.5) ; W
(vector3 0.375 0.75 0.375)))) ; K
; define a couple of parameters (which we can set from the command-line)
(define-param eps 11.56) ; the dielectric constant of the spheres
(define-param r 0.25) ; the radius of the spheres
(define diel (make dielectric (epsilon eps)))
; A diamond lattice has two "atoms" per unit cell:
(set! geometry (list (make sphere (center 0.125 0.125 0.125) (radius r)
(material diel))
(make sphere (center -0.125 -0.125 -0.125) (radius r)
(material diel))))
; (A simple fcc lattice would have only one sphere/object at the origin.)
(set-param! resolution 16) ; use a 16x16x16 grid
(set-param! mesh-size 5)
(set-param! num-bands 5)
; run calculation, outputting electric-field energy density at the U point:
(run (output-at-kpoint (vector3 0 0.625 0.375) output-dpwr))
As before, run the calculation, directing the output to a file.
This will take a few minutes (2 minutes on our Pentium-II); we'll put
it in the background with nohup so that it will finish
even if we log out:
unix% nohup mpb diamond.ctl >& diamond.out &
Note that, because we used define-param and set-param! to define/set some
variables (see the libctl
manual), we can change them from the command line. For example,
to use a radius of 0.3 and a resolution of 20, we can just type mpb
r=0.3 resolution=20 diamond.ctl. This is an extremely useful feature,
because it allows you to use one generic control file for many
variations on the same structure.
As usual, all distances are
in the "dimensionless" units determined by the length of the lattice
vectors. We refer to these units as a, and frequencies are
given in units of c/a. By default, the lattice/basis vectors are
unit vectors, but in the case of fcc lattices this conflicts with the
convention in the literature. In particular, the canonical a
for fcc is the edge-length of a cubic supercell containing the lattice.
In order to follow this convention, we set the length of our basis
vectors appropriately using the basis-size property of
geometry-lattice. (The lattice vectors default to the
same length as the basis vectors.) If the cubic supercell edge has
unit length (a), then the fcc lattice vectors have length
sqrt(0.5), or (sqrt 0.5) in Scheme.
unix% grep Gap diamond.out
Gap from band 2 (0.396348703007373) to band 3 (0.440813418580596), 10.6227251392791%
We can also plot its band diagram, much as for the tri-rods case
except that now we can't classify the bands by polarization.
unix% grep freqs diamond.out > diamond.dat
The resulting band diagram, with the complete band gap shaded
yellow, is shown below. Note that we only computed 5 bands, so in
reality the upper portion of the plot would contain a lot more bands
(which are of less interest than the bands adjoining the gap).
Visualizing fields in a useful way for general three-dimensional
structures is fairly difficult, but we'll show you what we can with
the help of the free Vis5D
volumetric-visualization program, and the h5tov5d
conversion program from h5utils.
First, of course, we've got to rectangularize the unit cell using
mpb-data, as before. We'll also expand it to two
periods in each direction.
Then, we'll use h5tov5d to convert the resulting
datasets to Vis5D format, joining all the datasets into a single file
(diamond.v5d) so that we can view them simultaneously if
we want to:
Note that all of the datasets are named data-new (from
the original datasets called data) since we are looking
at scalar data (the time-averaged electric-field energy density). No
messy field components or real and imaginary parts this time; we have
enough to deal with already.
Now we can open the file with Vis5D and play around with various
plots of the data:
unix% vis5d diamond.v5d &
If you stare at the dielectric function long enough from various
angles, you can convince yourself that it is a diamond lattice:
The lowest two bands have their fields concentrated within the
spheres as you might expect, flowing along more-or-less linear paths.
The second band differs from the first mainly by the orientation of
its field paths. The fields for the first band at U are depicted
below, with the strongest fields (highest energy density) shown as the
most opaque, blue pixels. Next to it is the same plot but with an
isosurface at the boundary of the dielectric superimposed, so you can
see that the energy is concentrated inside the dielectric.
The first band above the gap is band 3. Its field energy densities
are depicted below in the same manner as above. The field patterns
are considerably harder to make out than for the lower band, but they
seem to be more diffuse and "clumpy," the latter likely indicating the
expected field oscillations for orthogonality with the lower bands.
Go to the next, previous, or main section.
mpb-1.4.2/doc/developer.html 0000644 0001754 0000144 00000032712 07443525546 011420
Developer Information
Go to the next, previous, or main section.
Developer Information
Here, we begin with a brief overview of what the program is
computing, and then describe how the program and computation are
broken up into different portions of the code.
Forgive the primitive math typography below; this will be rectified
when MathML is supported in a decent browser.
This section provides a whirlwind tour of the mathematics of
photonic band structure calculations and the algorithms that we
employ. For more detailed information, see:
The MIT Photonic-Bands Package takes a periodic dielectric
structure and computes the eigenmodes of that structure,
which are the electromagnetic waves that can propagate through the
structure with a definite frequency. This corresponds to solving an
eigenvalue problem M h = (w/c)^2 h, where h
is the magnetic field, w is the frequency, and M is the
Maxwell operator curl 1/epsilon curl. We also have an
additional constraint, that div h be zero (the magnetic
field must be "transverse").
Since the structure is periodic, we can also invoke Bloch's theorem
to write the states in the form exp(i k*x) times a
periodic function, where k is the Bloch wavevector. So,
at each k-point (Bloch wavevector), we need to solve for a discrete
set of eigenstates, the photonic bands of the structure.
To solve for the eigenstates on a computer, we must expand the
magnetic field in some basis, where we truncate the basis to some
finite number of points to discretize the problem. For example, we
could use a traditional finite-element basis in which the field is
taken on a finite number of mesh points and linearly interpolated in
between. However, it is expensive to enforce the transversality
constraint in this basis. Instead, we use a Fourier (spectral) basis,
expanding the periodic part of the field in terms of exp(i
G*x) planewaves. In this basis, the transversality constraint
is easy to maintain, as it merely implies that the planewave
amplitudes must be orthogonal to k + G.
In order to find the eigenfunctions, we could compute the elements
of M explicitly in our basis, and then call LAPACK or
some similar code to find the eigenvectors and eigenvalues. For a
three-dimensional calculation, this could mean finding the
eigenvectors of a matrix with hundreds of thousands of elements on a
side--daunting merely to store, much less compute. Fortunately, we
only want to know a few eigenvectors, not hundreds of thousands, so we
can use much less expensive iterative methods that don't
require us to store M explicitly.
Iterative eigensolvers require only that one supply a routine to
operate M on a vector (function). Starting with an
initial guess for the eigenvector, they then converge quickly to the
actual eigenvector, stopping when the desired tolerance is achieved.
There are many iterative eigensolver methods; we use a preconditioned
block minimization of the Rayleigh quotient which is further described
in the file src/matrices/eigensolver.c. In the Fourier
basis, applying M to a function is relatively easy: the
curls become cross products with i (k + G); the
multiplication by 1/epsilon is performed by using an FFT
to transform to the spatial domain, multiplying, and then transforming
back with an inverse FFT. For more information and references on
iterative eigensolvers, see the paper cited above.
We also support a "targeted" eigensolver. A typical iterative
eigensolver finds the p lowest eigenvalues and
eigenvectors. Instead, we can find the p eigenvalues
closest to a given frequency w0 by solving for the
eigenvalues of (M - (w0/c)^2)^2 instead of
M. This new operator has the same eigenvectors as
M, but its eigenvalues have been shifted to make those
closest to w0 the smallest.
The eigensolver we use is preconditioned, which means that convergence
can be greatly improved by suppling a good preconditioner matrix.
Finding a good preconditioner involves making an approximate inverse
of M, and is something of a black art with lots of trial
and error.
The initialization of the dielectric function deserves some
additional discussion, both because it is crucial for good
convergence, and because we use somewhat complicated algorithms for
performance reasons.
To ameliorate the convergence problems caused in a planewave basis
by a discontinuous dielectric function, the dielectric function is
smoothed (averaged) at the resolution of the grid. Another way of
thinking about it is that this brings the average dielectric constant
(over the grid) closer to its true value. Since different
polarizations of the field prefer different averaging methods, one has
to construct an effective dielectric tensor at the boundaries between
dielectrics, as described by the paper referenced above.
This averaging has two components. First, at each grid point the
dielectric constant (epsilon) and its inverse are averaged over a
uniform mesh extending halfway to the neighboring grid points. (The
mesh resolution is controlled by the mesh-size user input
variable.) Second, for grid points on the boundary between two
dielectrics, we compute the vector normal to the dielectric interface;
this is done by averaging the "dipole moment" of the dielectric
function over a spherically-symmetric distribution of points. The
normal vector and the two averages of epsilon are then combined into
an effective dielectric tensor for the grid point.
All of this averaging is handled by a subroutine in
src/maxwell/ (see below) that takes as input a function
epsilon(r), which returns the dielectric constant for a given
position r. This epsilon function must be as efficient as
possible, because it is evaluated a large number of times: the size of
the grid multiplied by mesh-size3 (in three
dimensions).
To specify the geometry, the user provides a list of geometric
objects (blocks, spheres, cylinders and so on). These are parsed into
an efficient data structure and are used to to provide the epsilon
function described above. (All of this is handled by the libctlgeom
component of libctl, described below.) At the heart of the epsilon
function is a routine to return the geometric object enclosing a given
point, taking into account the fact that the objects are periodic in
the lattice vectors. Our first algorithm for doing this was a simple
linear search through the list of objects and their translations by
the lattice vectors, but this proved to be too slow, especially in
supercell calculations where there are many objects. We addressed the
performance problem in two ways. First, for each object we construct
a bounding box, with which point inclusion can be tested rapidly.
Second, we build a hierarchical tree of bounding boxes, recursively
partitioning the set of objects in the cell. This allows us to search
for the object containing a point in a time logarithmic in the number
of objects (instead of linear as before).
The code is organized to keep the core computation independent of
the user interface, and to keep the eigensolver routines independent
of the operator they are computing the eigenvector of. The
computational code is located in the src/ directory, with
a few major subdirectories, described below. The Guile-based user
interface is completely contained within the mpb-ctl/
directory.
src/matrices/
This directory contains the eigensolver, in
eigensolver.c, to which you pass an operator and it
returns the eigenvectors. Eigenvectors are stored using the
evectmatrix data structure, which holds p
eigenvectors of length n, potentially distributed over
n in MPI. See src/matrices/README for more
information about the data structures. In particular, you should use
the supplied functions (create_evectmatrix, etcetera) to
create and manipulate the data structures, where possible.
The type of the eigenvector elements is determined by
scalar.h, which sets whether they are real or complex and
single or double precision. This is, in turn, controlled by the
--disable-complex and --enable-single
parameters to the configure script at install-time.
scalar.h contains macros to make it easier to support
both real and complex numbers elsewhere in the code.
Also in this directory is blasglue.c, a set of wrapper
routines to make it convienient to call BLAS and LAPACK routines from
C instead of Fortran.
src/util/
As its name implies, this is simply a number of utility routines
for use elsewhere in the code. Of particular note is
check.h, which defines a CHECK(condition,
error-message) macro that is used extensively in the
code to improve robustness. There are also debugging versions of
malloc/free (which perform lots of paranoia tests, enabled by
--enable-debug-malloc in configure), and MPI
glue routines that allow the program to operate without the MPI
libraries.
src/matrixio
This section contains code to abstract I/O for eigenvectors and
similar matrices, providing a simpler layer on top of the HDF5
interface. This could be modified to support HDF4 or other I/O
formats.
src/maxwell/
The maxwell/ directory contains all knowledge of
Maxwell's equations used by the program. It implements functions to
apply the Maxwell operator to a vector (in maxwell_op.c)
and compute a good preconditioner (in maxwell_pre.c).
These functions operate upon a representation of the fields in a
transverse Fourier basis.
In order to use these functions, one must first initialize a
maxwell_data structure with
create_maxwell_data (defined in maxwell.c)
and specify a k point with update_maxwell_data_k. One
must also initialize the dielectric function using
set_maxwell_dielectric by supplying a function that
returns the dielectric constant for any given coordinate. You can
also restrict yourself to TE or TM polarizations in two dimensions by
calling set_maxwell_data_polarization.
This directory also contains functions
maxwell_compute_dfield, etcetera, to compute the
position-space fields from the Fourier-transform representation
returned by the eigensolver.
mpb-ctl/
Here is the Guile-based user interface code for the eigensolver.
Instead of using Guile directly, this code is built on top of the
libctl library as described in previous sections. This
means that the user-interface code (in mpb.c) is fairly
short, consisting of a number of small functions that are callable by
the user from Guile.
The core of the user interface is the file mpb.scm,
the specifications file for libctl as described in the libctl manual.
Actually, mpb.scm is generated by configure
from mpb.scm.in (in order to substitute in parameters
like the location of the libctl library); you should only edit
mpb.scm.in directly. (You can regenerate
mpb.scm simply by running ./config.status
instead of re-running configure.)
The specifications file defines the data structures and subroutines
that are visible to the Guile user. It also defines a number of
Scheme subroutines for the user to call directly, like
(run). It is often simpler and more flexible to define
functions like this in Scheme rather than in C.
All of the code to handle the geometric objects resides in
libctlgeom, a set of Scheme and C utility functions included with
libctl (see the file utils/README in the libctl package).
(These functions could also be useful in other programs, such as a
time-domain Maxwell's equation simulator.)
Installation:
How to install and compile Photonic-Bands, including descriptions
of and links to software you must first download and install from
other sources.
User Tutorial:
In this section, we introduce the use of Photonic-Bands to compute a
photonic band structure. A simple tutorial illustrates how the basic
features are used to solve for the modes of example structures.
Data Analysis Tutorial:
Here, we walk through how you might analyze and visualize the results
from a couple of typical MPB calculations. Includes some pretty
pictures for those who don't like to read.
Developer Information:
In this section, we outline some of the internal structure and
algorithms used in Photonic-Bands, as an aid to outside developers
wishing to add new features and bugs.
Acknowledgments:
A project of this size could never be completed without the support
of many others, to whom we are very grateful.
Also see this section for referencing information.
Feedback
For professional consulting support of the MIT Photonic-Bands
package, and photonic band-gap applications in general, contact
Prof. John
D. Joannopoulos of MIT (phone: (617) 253-4806, fax: (617)
253-2562).
If you have questions or problems regarding MIT Photonic-Bands, you
are encouraged to join the mpb-discuss
mailing list. This way, you can get help from other users of the
software. In addition, this way other users can benefit from your
experience by reading the mpb-discuss
archives.
Alternatively, you may directly contact Steven G. Johnson at stevenj@alum.mit.edu.
Complicated problems may be referred to consulting, above.
mpb-1.4.2/doc/installation.html 0000644 0001754 0000144 00000057225 07561013646 012134
In this section, we outline the procedure for installing the MIT
Photonic-Bands package. Mainly, this consists of downloading and
installing various prerequisites. As much as possible, we have
attempted to take advantage of existing packages such as BLAS, LAPACK,
FFTW, and GNU Guile, in order to make our code smaller, more robust,
faster, and more flexible. Unfortunately, this may make the
installation of MPB more complicated if you do not already have these
packages.
You will also need an ANSI C compiler, of course (gcc is fine), and
installation will be easiest on a UNIX-like system (Linux is fine).
In the following list, some of the packages are dependent upon
packages listed earlier, so you should install them in more-or-less
the order given.
Note: Many of these libraries may be available in
precompiled binary form, especially for GNU/Linux systems. Be aware,
however, that library binary packages often come in two parts,
library and library-dev, and both
are required to compile programs using it.
Note: It is important that you use the same Fortran
compiler to compile Fortran libraries (like LAPACK) and for
configuring MPB. Different Fortran compilers often have incompatible
linking schemes. (The Fortran compiler for MPB can be set via the
F77 environment variable.)
First, let's review some important information about installing
software on Unix systems, especially in regards to installing software
in non-standard locations. (None of these issues are specific to MPB,
but they've caused a lot of confusion among our beloved users.)
Most of the software below, including MPB, installs under
/usr/localby default; that is, libraries go in
/usr/local/lib, programs in /usr/local/bin,
etc. If you don't have root privileges on your machine,
you may need to install somewhere else, e.g. under
$HOME/install (the install/ subdirectory of
your home directory). Most of the programs below use a GNU-style
configure script, which means that all you would do to
install there would be:
./configure --prefix=$HOME/install
when configuring the program; the directories
$HOME/install/lib etc. are created automatically as
needed.
Paths for Configuring
There are two further complications. First, if you install in a
non-standard location (and /usr/local is considered
non-standard by some proprietary compilers), you will need to tell the
compilers where to find the libraries and header files that you
dutifully installed. You do this by setting two environment variables:
Of course, substitute whatever installation directory you used. Do
this before you run the configure scripts,
etcetera. You may need to include multiple -L and
-I flags (separated by spaces) if your machine has stuff
installed in several non-standard locations. Bourne shell users
(e.g. bash or ksh) should use the
"export FOO=bar" syntax instead of csh's
"setenv FOO bar", of course.
You might also need to update your PATH so that you
can run the executables you installed (although
/usr/local/bin is in the default PATH on
many systems). e.g. if we installed in our home directory as
described above, we would do:
setenv PATH "$HOME/install/bin:$PATH"
Paths for Running (Shared Libraries)
Second, many of the packages installed below (e.g. Guile) are
installed as shared libraries. You need to make sure that your
runtime linker knows where to find these shared libraries. The bad
news is that every operating system does this in a slightly different
way. The good news is that, when you run make install
for the packages involving shared libraries, the output includes the
necessary instructions specific to your system, so pay close
attention! It will say something like "add LIBDIR to the
foobar environment variable," where
LIBDIR will be your library installation directory
(e.g. /usr/local/lib) and foobar is some
environment variable specific to your system
(e.g. LD_LIBRARY_PATH on some systems, including Linux).
For example, you might do:
setenv foobar "/usr/local/lib:$foobar"
Note that we just add to the library path variable, and don't replace
it in case it contains stuff already. If you use Linux and have
root privileges, you can instead simply run
/sbin/ldconfig, first making sure that
a line "/usr/local/lib" (or whatever) is in
/etc/ld.so.conf.
If you don't want to type these commands every time you log in, you
can put them in your ~/.cshrc file (or
~/.profile, or ~/.bash_profile, depending on
your shell).
MPB, and many of the libraries it calls, are written in C, but it
also calls libraries such as BLAS and LAPACK (see below) that are
usually compiled from Fortran. This can cause some added difficulty
because of the various linking schemes used by Fortran compilers.
MPB's configure script attempts to detect the Fortran
linking scheme automatically, but in order for this to work you
must use the same Fortran compiler and options with MPB as were used
to compile BLAS/LAPACK.
By default, MPB looks for a vendor Fortran compiler first
(f77, xlf, etcetera) and then looks for GNU
g77. In order to manually specify a Fortran compiler
foobar you would configure MPB with
'./configure F77=foobar ...'.
If, when you compiled BLAS/LAPACK, you used compiler options that
alter the linking scheme (e.g. g77's
-fcase-upper or -fno-underscoring), you will
need to pass the same flags to MPB via './configure
FFLAGS="...flags..." ...'.
One final note: you may run into trouble if you use a C compiler by
a different vendor than your Fortran compiler, due to incompatible
libraries. By default, MPB looks for a vendor C compiler
(cc) first, but you can specify a different C compiler
with './configure CC=foobar ...'.
The first thing you must have on your system is a BLAS
implementation. "BLAS" stands for "Basic Linear Algebra Subroutines,"
and is a standard interface for operations like matrix multiplication.
It is designed as a building-block for other linear-algebra
applications, and is used both directly by our code and in LAPACK (see
below). By using it, we can take advantage of many highly-optimized
implementations of these operations that have been written to the BLAS
interface. (Note that you will need implementations of BLAS levels 1-3.)
You can find more BLAS information, as well as a basic
implementation, on the BLAS
Homepage. Once you get things working with the basic BLAS
implementation, it might be a good idea to try and find a more
optimized BLAS code for your hardware. Vendor-optimized BLAS
implementations are available as part of the Compaq CXML, IBM ESSL,
SGI sgimath, and other libraries. Recently, there has also been work
on self-optimizing BLAS implementations that can achieve performance
competitive with vendor-tuned codes; see the ATLAS homepage (and also PhiPACK).
Links to more BLAS implementations can be found on SAL. I recommend ATLAS,
but it does take some time to compile.
Note that the generic BLAS does not come with a
Makefile; compile it with something like:
mkdir blas && cd blas # the BLAS archive does not create its own directory
get http://www.netlib.org/blas/blas.tgz
gunzip blas.tgz
tar xf blas.tar
f77 -c -O3 *.f # compile all of the .f files to produce .o files
ar rv libblas.a *.o # combine the .o files into a library
su -c "cp libblas.a /usr/local/lib" # switch to root and install
(Replace -O3 with your favorite optimization options.
On Linux, I use g77 -O3 -fomit-frame-pointer
-funroll-loops, with -malign-double -mcpu=i686 on
a Pentium II.) Note that MPB looks for the standard BLAS library with
-lblas, so the library file should be called
libblas.a and reside in a standard directory like
/usr/local/lib. (See also below for the
--with-blas=lib option to MPB's
configure script, to manually specify a library location.)
LAPACK, the Linear Algebra PACKage, is a standard collection of
routines, built on BLAS, for more-complicated (dense) linear algebra
operations like matrix inversion and diagonalization. You can
download LAPACK from the LAPACK Home Page. More
LAPACK links can be found on SAL.
Note that MPB looks for LAPACK by linking with
-llapack. This means that the library must be called
liblapack.a and be installed in a standard directory like
/usr/local/lib (alternatively, you can specify another
directory via the LDFLAGS environment variable as
described earlier). (See also below for the
--with-lapack=lib option to MPB's
configure script, to manually specify a library location.)
Optionally, MPB is able to run on a distributed-memory parallel
machine, and to do this we use the standard MPI message-passing
interface. You can learn about MPI from the MPI Home Page.
Most commercial supercomputers already have an MPI implementation
installed; two free MPI implementations that you can install yourself
are MPICH and LAM. MPI is not required
to compile the ordinary, uniprocessor version of MPB.
In order for the MPI version of MPB to run successfully, we have a
slightly nonstandard requirement: each process must be able to read
from the disk. (This way, Guile can boot for each process and they
can all read your control file in parallel.) Many (most?) commercial
supercomputers, Linux Beowulf
clusters, etcetera, satisfy this requirement.
Also, in order to get good performance, you'll need fast
interconnect hardware such as Myrinet; 100Mbps Ethernet probably won't
cut it. The speed bottleneck comes from the FFT, which requires most
of the communications in MPB. FFTW's MPI transforms (see below) come with benchmark programs that will
give you a good idea of whether you can get speedups on your system.
Of course, even with slow communications, you can still benefit from
the memory savings per CPU for large problems.
As described below, when you configure MPB with
MPI support (--with-mpi), it installs itself as
mpb-mpi. See also the user reference section for
information on using MPB on parallel machines.
We require a portable, standard binary format for outputting the
electromagnetic fields and similar volumetric data, and for this we
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.)
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 Fighting Illini and alma
mater to many of this author's fine relatives).
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 h5toh4 conversion program that you can use if
you need HDF4 files.
HDF5 includes parallel I/O support under MPI, which can be enabled
by configuring it with --enable-parallel. (You may also
have to set the CC environment variable to
mpicc. The resulting HDF5 library, however, may not work
with the serial MPB.) This is not 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.)
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 FFTW Home Page.
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
--enable-mpi in the FFTW configure flags).
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 optional package, but one
that can be used by Guile (see below) if it is installed; we recommend
getting it. You can download
Readline from the GNU ftp site. (Readline is typically
preinstalled on GNU/Linux systems).
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 Guile Home
Page. (Guile is typically included with GNU/Linux systems.)
Important: If you are using an RPM-based Linux system with
Guile pre-installed, please note that you must also install the
guile-devel RPM (which should be on your CD, but is not
installed by default).
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 configure scripts to
automatically detect the capabilities of a system and configure a
package accordingly. You can find out more at the Autoconf Home Page
(autoconf is typically installed by default on Linux systems). In
order to install Autoconf, you will also need the GNU m4
program if you do not already have it (see the GNU m4 Home Page).
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 libctl home site, unpack
it, and run the usual configure, make,
make install sequence. You'll also want to browse its manual, as this will
give you a general overview of what the user interface will be like.
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 --prefix=dir option to
configure (the default prefix is
/usr/local). In this case, however, you'll need to
specify the location of the libctl shared files for the MPB package,
using the --with-libctl=dir/share/libctl option to
the MPB configure script.
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 MIT Photonic-Bands Homepage.)
Once you've unpacked it, just run:
./configure
make
to configure and compile the package (see below to install).
Hopefully, the configure 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 make
compilation will proceed without a hitch. If not, it's a Simple
Matter of Programming to correct the problem.
configure accepts several flags to help control its
behavior. Some of these are standard, like
--prefix=dir to specify and installation directory
prefix, and some of them are specific to the MPB package
(./configure --help for more info). The
configure flags specific to MPB are:
--with-inv-symmetry
Assume inversion symmetry
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
mpbi instead of mpb, so that you can have
versions both with and without inversion symmetry installed at the
same time. To install bothmpb and
mpbi, you should do:
./configure
make
su -c "make install"
make distclean
./configure --with-inv-symmetry
make
su -c "make install"
Use single precision (C float) instead of the default
double precision (C double) for computations. (Not
recommended.)
--without-hdf5
Don't use the HDF5 library for field and dielectric function
output. (In which case, no field output is possible.)
--with-mpi
Attempt to compile a parallel
version of MPB using MPI; the resulting program will be installed
as mpb-mpi. Requires MPI and MPI FFTW libraries to be installed, as described
above.
Does not compile the serial MPB, or mpb-data;
if you want those, you should make distclean and
compile/install them separately.
--with-mpican be used along with
--with-inv-symmetry, in which case the program is
installed as mpbi-mpi (try typing that five times
quickly).
--with-libctl=dir
If libctl was installed in a nonstandard location (i.e. neither
/usr nor /usr/local), you need to specify
the location of the libctl directory, dir. This
is either prefix/share/libctl, where
prefix is the installation prefix of libctl, or the
original libctl source code directory.
--with-blas=lib
The configure 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
--with-blas=lib.
--with-lapack=lib
Cause the configure script to look for a LAPACK
library called lib (the default is to use
-llapack).
--disable-checks
Disable runtime checks. (Not recommended; the disabled checks
shouldn't take up a significant amount of time anyway.)
--enable-prof
Compile for performance profiling.
--enable-debug
Compile for debugging, adding extra runtime checks and so on.
--enable-debug-malloc
Use special memory-allocation routines for extra debugging (to
check for array overwrites, memory leaks, etcetera).
--with-efence
More debugging: use the Electric Fence library, if
available, for extra runtime array bounds-checking.
You can further control configure by setting various
environment variables, such as:
CC: the C compiler command
CFLAGS: the C compiler flags (defaults to -O3).
CPPFLAGS: -Idir flags to tell the
C compiler additional places to look for header files.
LDFLAGS: -Ldir flags to tell the
linker additional places to look for libraries.
LIBS: additional libraries to link against.
Once compiled, the main program (as opposed to various test
programs) resides in the mpb-ctl/ subdirectory, and is
called mpb. You can install this program under
/usr/local (or elsewhere, if you used the
--prefix flag for configure), by running:
su -c "make install"
The "su" command is to switch to root for installation
into system directories. You can just do make install if
you are installing into your home directory instead.
If you make a mistake (e.g. you forget to specify a needed
-Ldir flag) or in general want to start over from
a clean slate, you can restore MPB to a pristine state by running:
make distclean
Go to the next, previous, or main section.
mpb-1.4.2/doc/introduction.html 0000644 0001754 0000144 00000034633 07374654650 012162
Introduction
Go to the next or main section.
Introduction
MIT Photonic-Bands is a software package to
compute definite-frequency eigenstates of Maxwell's equations in
periodic dielectric structures. Its primary intended application is
the study of photonic crystals: periodic dielectric
structures exhibiting a band gap in their optical modes, prohibiting
propagation of light in that frequency range. However, it could also
be easily applied to compute other optical dispersion relations and
eigenstates (e.g. for conventional waveguides such as fiber-optic cables).
This manual assumes that the reader is familiar with concepts from
solid-state physics such as eigenstates, band structures, and Bloch's
theorem. We also do not attempt (much) to instruct the reader on
photonic crystals or other optical applications for which this code
might be useful. For an excellent introduction to all of these topics
in the context of photonic crystals, see the book Photonic Crystals: Molding
the Flow of Light, by J. D. Joannopoulos, R. D. Meade, and
J. N. Winn (Princeton, 1995).
Some of the main design goals we were thinking about when we
developed this package were the following (see also the feature
list at the MPB home page):
Fully vectorial, three-dimensional calculations for arbitrary
Bloch wavevectors. (The only approximation is the spatial
discretization, or equivalently the planewave cutoff.)
Flexible interface. Readable, extensible, scriptable...see
also the libctl
design goals.
Parallel. (Can run on a single-processor machine, but is also
supports parallel machines with MPI.)
"Targeted" eigensolver: find modes nearest to a specified
frequency, not just the lowest-frequency bands. (For defect
calculations.)
Modularity. The eigensolver, Maxwell's equations, user interface,
and so on, should be oblivious to each other as much as possible.
This way, they can be debugged separately, combined in various ways,
replaced, used in other programs...all the usual benefits of modular
design.
Take advantage of inversion symmetry in the dielectric
function, but don't require it. (This means that we have to handle
both real and complex fields.)
There are two common computational approaches to studying
dielectric structures such as photonic crystals: frequency-domain and
time-domain. We feel that each has its own place in a researcher's
toolbox, and each has unique advantages and disadvantages. MPB is
frequency-domain; that is, it does a direct computation of the
eigenstates and eigenvalues of Maxwell's equations (using a planewave
basis). Each field computed has a definite frequency. In contrast,
time-domain techniques iterate Maxwell's equations in time; the
computed fields have a definite time (at each time step) but not a
definite frequency per se. It seems worthwhile to say a few
words about each method, and to explain why we want a frequency-domain
code. (Our group has both time-domain and frequency-domain software,
and we use both techniques extensively.)
Time-domain methods are well-suited to computing things that
involve evolution of the fields, such as transmission and resonance
decay-time calculations. They can also be used to calculate band
structures and for finding resonant modes, by looking for peaks in the
Fourier transform of the system response to some input. The main
advantage of this is that you get all the frequencies (peaks) at once
from a calculation involving propagation of a single field. There are
several disadvantages to this technique, however. First, it is hard
to be confident that you have found all of the states--you may have
coupled weakly to some state by accident, or two states may be close
in frequency and appear as a single peak; this is especially
problematic in higher-order resonant-cavity and waveguide
calculations. Second, in the Fourier transform, the frequency
resolution is inversely related to the simulation time; to get 10
times the resolution you must run your simulation 10 times as long.
Third, the time-step size must be proportional to the spatial-grid
size for numerical stability; thus, if you double the spatial
resolution, you must double the number of time steps (the length of
your simulation), even if you are looking at states with the same
frequency as before. Fourth, you only get the frequencies of the
states; to get the eigenstates themselves (so that you can see what
the modes look like and do calculations with them), you must run the
simulation again, once for each state that you want, and for a time
inversely proportional to the frequency-spacing between adjacent
states (i.e. a long time for closely-spaced states).
In contrast, frequency-domain methods like those in MPB are in many
ways better-suited to calculating band structures and eigenstates.
(Here, we consider the case of an iterative eigensolver like
the one in MPB, which iteratively improves approximate eigenstates.
Dense solvers, which factorize the matrix directly, are impractical
for large problems because of the huge size of the matrix, and because
they compute many more eigenvectors than are desired. In iterative
methods, the operator is only applied to individual vectors and is
never itself computed explicitly.) First, you don't have to worry
about missing states--even closely-spaced modes will appear as two
eigenvalues in the result. Second, the error in the frequency in an
iterative eigensolver typically decays exponentially with the number
of iterations, so the number of iterations is logarithmic in the
desired tolerance. Third, the number of iterations typically remains
almost constant even as you increase the resolution (the work for each
iteration increases, of course, but that happens in time-domain too).
Fourth, you get both the frequencies and the eigenstates at the same
time, so you can look at the modes immediately (even closely-spaced
ones).
A traditional disadvantage of frequency-domain methods was that you
had to compute all of the lowest eigenstates, up to the desired one,
even if you didn't care about the lower ones. This was especially
problematic in defect calculations, in which a large supercell is
used, because in that case the lower bands are "folded" many times in
the Brillouin zone. Thus, you often had to compute a large number of
bands in order to get to the one you wanted (incurring large costs
both in time and in storage). These disadvantages largely disappear
in MPB, however, with the advent of its "targeted" eigensolver--with
it, you can solve directly for the localized defect states (i.e the
states in the band gap) without computing the lower bands.
In order to shed some light on the past development and design
decisions of the Photonic-Bands package, I thought I'd write a few
paragraphs about its history. Read on to enjoy my narcissist
ramblings.
Many different people have written codes to compute the modes of
periodic dielectric materials (although we don't know of any others
that have been freely released). I have had experience with several
programs written within our group, and this experience has guided the
design of MIT Photonic-Bands.
The first program of this sort that I came in contact with, and the
code that was used in our group until the development of this package,
was initially written around 1990 (in Fortran 77) by R. D. Meade. As
this software grew organically over time, several problems became
apparent. First, the input format was inflexible (difficult to add
new features without breaking old simulations), sensitive to
whitespace and other formatting, and required repeated entry of
information that was often the same from file to file. Often, pre-
and post-processing steps were required using additional scripts and
tools. Second, the many parts of the program had become intertwined,
lacking modularity or a clear flow of control; this made it difficult
to follow or modify substantially. Parallelizing it, or removing
constraints that it imposed like inversion symmetry, or even replacing
the input format seemed impractical. Besides, even reading code with
variables named gxgzco (in common block
cabgv) (honest!) is a mind-altering experience.
After an initial experience in the Spring of 1996 at writing a code
based on a wavelet, rather than a planewave, basis (which turned out
not to be practical), I set out to write a replacement for our Fortran
eigensolver. My main aims at this time (Fall 1996) were a more
flexible and powerful input format and a code that would be amenable
to parallelization. I succeeded in achieving a working code with
similar convergence to the old code (after some pain),
but I discovered several things. I had lots of fun learning to use
lex and yacc (Yet Another Compiler-Compiler)
to make a flexible, C-like input format with variables and other
advanced features. Having input files that were almost, but not
quite, like a programming language made me realize, however, that what
I really wanted was a programming language--no matter how
many features I added, I always wanted one more "simple" thing. As
far as parallelization, I quickly realized that I had a problem: I
needed a parallel FFT, and the only ones that were available were
proprietary (non-portable), used incompatible data distribution
formats, and were often designed to be called only from special
languages like HPF. That, plus my dissatisfaction with the available
free FFTs, led me to embark on a side project (with my friend Matteo
Frigo of MIT's Laboratory for Computer Science) to develop a new, free
FFT library, FFTW, that included
portable parallel routines. Also, I decided that attempting to
support too many models of parallel programming (threads, MPI, Cray
shmem) in one program resulted in a mess; it was better
to stick with MPI (supporting running only a single process too, of
course). Another mistake I discovered was that I allowed the
eigensolver to get too intertwined with the specific problem of
Maxwell's equations--the eigensolver knew about the data structures
for the fields, etcetera, making it difficult to plug in replacement
eigensolvers, test things in isolation, or to implement features like
the "targeted" eigensolver of Photonic-Bands (which diagonalizes a
different operator). The whole program was too mired in complexity.
Finally, in the interim I had learned about block eigensolver
algorithms. Not only can such algorithms leverage prepackaged,
highly-optimized routines like BLAS and LAPACK, but they also promised
to be inherently more suited for parallelization (since they remove
the serial process of solving for the bands one by one). All of these
things convinced me that I needed to rewrite the code again from
scratch.
So, I started work on the new package (in Spring 1998), this time
determined to develop and debug each component (matrix operations,
eigensolver, maxwell operator, user input) in isolation. At the same
time, I was thinking about how I would implement the user control
language, wanting to develop a general tool that could be applied to
other problems and software in our research. It seemed clear that, in
order to get other people to use it in their programs, as well as to
avoid a lot of the manual labor that went into my previous effort, I
wanted to automatically generate the user/program interface from an
abstract specification. As for the control language, I briefly
considered implementing my own, but was happily led to GNU Guile
instead, which gave me a powerful language with little effort. So
armed, I set out to write libctl (which generates the Guile interface
from an abstract Scheme specification), partially as an experiment to
see how hard it would be and what the result would look like. After a
weekend of work, it was obvious that I had a powerful tool; I spent
couple of weeks adding some finishing touches, writing documentation,
and so on, and proudly showed it off to my groupmates in the hope that
they could use it for their programs. Without a real example of a
program using libctl, however, it was hard to convince them to plug a
scripting language into their existing, working codes. So, I went
back to puttering at my eigensolvers.
Of course, all this time I was allegedly doing real research, and
long periods would go by with little progress on the Photonic-Bands
package. The original, Fortran code was still working, and in time
one learned to bear its quirks and limitations with stoicism, although
we cringed every time we had to show it to anyone else. By the summer
of 1999, I had a working block eigensolver (supporting several
iteration-scheme variants), a Maxwell operator to plug into the
eigensolver (including a "targeted" operator, whose convergence I was
unhappy with), and a test program to do convergence experiments on
bands of a Bragg mirror. I hadn't attached any general user
interface, field output, or other necessary components. At this
point, Dr. Doug Allan of Corning (a former student of
Prof. Joannopoulos), heard about the new code--in particular, the
targeted eigensolver--and began clamoring to try it out. Not put off
by my excuses, he asked for a copy of my current code, regardless of
its status, to play with. Not wanting to refuse, but aghast at the
prospect of someone seeing my masterpiece only half-painted, I told
him to give me a week...in which time I added the interface and
discovered that I had a useful tool. Over the next week, I added many
features, fixed bugs, and wrote documentation, drawing near to a
release at last...
Go to the next or main section.
mpb-1.4.2/doc/license.html 0000644 0001754 0000144 00000010606 07443525546 011053
License and Copyright
Go to the previous or main sections.
License and Copyright
Omnis enim res, quae dando non deficit, dum habetur
et non datur, nondum habetur, quomodo habenda est.
"For if a thing is not diminished by being shared with others, it is not
rightly owned if it is only owned and not shared."
(Saint Augustine,
De
Doctrina Christiana, c. 396 AD.)
MIT Photonic-Bands 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.
This program 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 this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA. You can also find it on the GNU web site:
As a clarification, we should note that Scheme control
(ctl) files, written by the user (i.e. not containing
code distributed with MIT Photonic-Bands) and loaded at runtime by the
MIT Photonic-Bands software, are not considered derived works
of MIT Photonic-Bands and do not fall thereby under the
restrictions of the GNU General Public License.
In addition, all of the example Scheme code in this manual, as well
as the example ctl files in the mpb-ctl/examples/
directory, may be freely used, modified, and redistributed, without
any restrictions. (The warranty disclaimer still applies, of course.)
We kindly ask you to reference the MIT Photonic-Bands package and
its authors in any publication for which you used MPB. (You are not
legally required to do so; it is up to your common sense to
decide whether you want to comply with this request or not.) The
preferred citation is our paper on MPB and related topics:
@Article{Johnson2001:mpb,
author = {Johnson, Steven~G. and Joannopoulos, J.~D.},
title = {Block-iterative frequency-domain methods for Maxwell's equations in a planewave basis},
journal = {Opt. Express},
year = 2001,
volume = 8,
number = 3,
pages = {173--190},
url = {http://www.opticsexpress.org/abstract.cfm?URI=OPEX-8-3-173}
}
If you want a one-sentence description of the algorithm
for inclusion in a publication, we recommend:
Fully-vectorial eigenmodes of Maxwell's equations with periodic
boundary conditions were computed by preconditioned conjugate-gradient
minimization of the block Rayleigh quotient in a planewave basis,
using a freely available software package [ref].
The resulting image
(
Here, the new dataset
output by 
