~ Octave
~ Meep

Future Use
MPB Intro

MPB Intro

Here are a few basics to help get you started.

The following website is the best reference, if not the only reference I have found. The authors Steven G. Johnson and J. D. Joannopoulos have everything organized by topics, making it an easy and quick reference.

Ubuntu is the easiest version of linux to use. MPB will run on other Unix based operating systems but I will focus on Ubuntu here, simply because it's easy and I use it personally.

Installation -

Open up the Ubuntu Software Center. It may have a different name depending on your version of Ubuntu. Search for MPB and install it. If you want to manually install it, the wiki has some pointers in the installation section.

MPB requires other packages to properly function. You will also need some software to manipulate and plot data. Here is a list of programs I recommend downloading. Some of these are not required for MPB to function, but the extra functionality won't hurt anything. More detail about each package is available on the wiki. Just search for each of these in the software center and make sure they're installed. Whenever you see a "-dev" option, install that too. For example, there might be a "guile" and "guile-dev".


Test the installation -

Make sure MPB will listen to you by asking to see the manual and version. Hitting "q" will get you out of the manual when you're done with it.

user@comp:~$ man mpb
user@comp:~$ mpb --version
MIT Photonic Bands 1.4.2, Copyright (C) 1999-2001 by MIT.
Using libctl 3.1 and Guile 1.8.7.

Control Files -

MPB does not have a GUI. This is intentional and gives us much more flexibility than a graphical interface would. Although a GUI usually makes it easier to get started, the interface into MPB was still designed for non-programmers. MPB is used with a mix of a terminal and what they call a ctl file. A ctl file is truly the heart of any simulation. It is simply a text document used to store the description of what we want to do or the simulation we want to perform.

Here is an example control file I snagged from the wiki.

-------------------------------------- simple.ctl start ---------------------------------------
(set! geometry-lattice (make lattice (size 1 1 no-size)))
(set! geometry (list (make cylinder (center 0 0 0) (radius 0.2) (height infinity)
(material (make dielectric (epsilon 12))))))
(set! num-bands 2)
(set! k-points (list (vector3 1 0 0)))
(set! resolution 32)
(run-tm output-efield-z)
------------------------------------------ simple.ctl end -------------------------------------

The GNU Guile scripting language is used inside a ctl file to describe each simulation. Remember, we installed GNU Guile, Libctl, and Scheme. These three scripting languages are all build on top of each other. This means we can use any command or script from any of the three languages in our ctl files.

I'm not going to explain how to write a control file because the wiki does a better job than I could. Reference the wiki for a line by line explaination of various control files.

Run a Simulation -

Lets say you have MPB installed and a control file ready and waiting. To run the simulation, open a terminal and navigate to the control file using your dandy Unix commands (cd folder, cd .., and ls). Once you find your control file, type [ mpb test.ctl > output.out ] and there you go.

user@comp:~$ ls
user@comp:~$ mpb test.ctl > output.out

MPB will simulate the control file called "test.ctl" and save any printed outputs to a text file called "output.out".

MPB discretized the structure into funny shaped cells. Graphics programs generally assume X & Y data have a 1:1 relationship, but this is only true if using a square grid. MPB includes a package to correct this effect, called mpb-data. It can do a variety of manipulations but here is the important one. For more detail on the usage of mpb-data, run [ man mpb-data ].

mpb-data -r -m 3 -n 32 epsilon.h5

This command is not going to create another output file. It will create another section within epsilon.h5 with the corrected data. [ -m 3 ] tells mpb-data to repeat the output of our structure 3 times in each direction, for a total of 9. Cascading the structure can make it easier to see what the fields are doing, similar to zooming out in order to get a broader view. [ -n 32 ] sets the resolution to a constant value. Using a value of 32 will provide us with 32 pixels per distance unit. [ -r ] is the important option and tells mpb-data to convert each cell to rectangular form. To view the corrected data in graphical form, use the following.

h5topng epsilon.h5:data-new

Adding [ :data-new ] to the end tells h5topng to look for the new section with corrected data. How do we know what section to look for? Notice, we never told it to call the new section [ data-new ]. H5 is a binary format. This means we can't simply open the epsilon.h5 file in a text editor to see what's in it. Luckily, the H5utils can help us with this too. The following command will show us what data is included in our epsilon.h5 file.

h5ls epsilon.h5

A list of included data sections will now be displayed. Within the list we can see [ data-new ]; which, I highlighted in bold. There were many other datasets in this file but I only present a few here.

Dataset {32, 32}
Dataset {96, 83}

Dataset {SCALAR}
Dataset {32, 32}
Dataset {96, 83}
Dataset {32, 32}
Dataset {96, 83}
Dataset {32, 32}
Dataset {96, 83}
Dataset {32, 32}
Dataset {96, 83}
lattice\ vectors
Dataset {3, 3}

Notice, the mpb-data function we ran earlier did more than create a corrected data section called data- new. It actually created a corrected section for ever set of data in epsilon.h5. Each corrected section is appended by [ -new ].

h5topng -C epsilon.h5:data-new -c bluered -Z -d z.r-new e.k*.b*.z.tm.h5

This line extracts the data from epsilon.h5:data-new and places it on top of the field data in e.k*.b*.z.tm.h5. [ -c bluered -Z ] tells h5topng to create a color scheme from blue to red. [ -d z.r-new ] designates the corrected section of data. Up to now, we haven't looked at the output frequencies found by MPB. When we execute a control file with [ mpb controlfile.ctl > controlfile.out ], all the outputs, including the frequencies found, are saved in controlfile.out. We really only need the lines that include frequency data. To extract the lines with frequency data, we will take advantage of a handy unix command, grep.

grep freqs: filename.out > filename.dat

Using grep in this form will find any line in filename.out, that includes the string [ freqs: ], and copy it into the file filename.dat. Here is an example of what you should see in the new filename.dat file.

tmfreqs:, k index, k1, k2, k3, kmag/2pi, tm band 1, tm band 2, tm band 3, tm band 4
tmfreqs:, 1, 0, 0, 0, 0, 0, 0.0662258, 0.0936001, 0.0989622
tmfreqs:, 2, 0, 0.2, 0, 0.02, 0.0179639, 0.0635636, 0.0872282, 0.0949472
tmfreqs:, 3, 0, 0.4, 0, 0.04, 0.0347071, 0.0538705, 0.0818556, 0.0978577
tmfreqs:, 4, 0, 0.6, 0, 0.06, 0.0347071, 0.0538705, 0.0818556, 0.0978577
tefreqs:, k index, k1, k2, k3, kmag/2pi, te band 1, te band 2, te band 3, te band 4
tefreqs:, 1, 0, 0, 0, 0, 0, 0.0947458, 0.0973766, 0.0983135
tefreqs:, 2, 0, 0.2, 0, 0.02, 0.0195063, 0.0777336, 0.0993367, 0.100443
tefreqs:, 3, 0, 0.4, 0, 0.04, 0.0389471, 0.0585115, 0.104798, 0.105473
tefreqs:, 4, 0, 0.6, 0, 0.06, 0.0389471, 0.0585115, 0.104798, 0.105473

MPB outputs frequency data in comma delimited form, making it easy to plot. The comma delimited file can be viewed in any plotting program; such as, excel or matlab. Personally, I used Octave, simply because it's free. To create a graph, use the last 5 columns of the data file as the Y-axis. The x-axis can be the second column (k-index) or the third-fifth columns (kx,ky,kz).

That's it for a very basic introduction to MPB. Create your control file, run it in a terminal, and play with the output. See, not having a GUI really isn't that bad. Although, to run practical simulations, there are a few more tricks you will want to know. Just read through the wiki tutorial and you'll be ready to go. The tutorial is good at explaining what you need to know and leaves details for the manual or reference section.

Alternative Terminal Options -

You will probably spend an excessive amount of time using the terminal from here on. For some additional functionality, try downloading Guake Terminal. Guake can be opened and closed quickly using F12, supports multiple tabs, and has a bunch of other fun hot keys. Another cool terminal is called byobu. Byobu can display all kinds of nifty info about your computer or a custom script. I haven't found a real good use for it, but it's still entertaining to watch the memory, processing power, and temperature change while running scripts.