📄 user-tutorial.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"><HTML><HEAD><TITLE>User Tutorial</TITLE><LINK rel="Contents" href="index.html"><LINK rel="Copyright" href="license.html"><LINK rel="Start" href="index.html"></HEAD><BODY TEXT="#000000" BGCOLOR="#FFFFFF">Go to the <a href="analysis-tutorial.html">next</a>, <a href="installation.html">previous</a>, or <a href="index.html">main</a> section.<hr><h1>User Tutorial</h1><p>In this section, we'll walk through the process of computing theband structure and outputting some fields for a two-dimensionalphotonic crystal using the MIT Photonic-Bands package. This shouldgive you the basic idea of how it works and some of the things thatare possible. Here, we tell you the truth, but not the whole truth.The <a href="user-ref.html">User Reference</a> section gives a morecomplete, but less colloquial, description of the features supportedby Photonic-Bands. See also the <a href="analysis-tutorial.html">dataanalysis tutorial</a> in the next section for more examples, focusedon analyzing and visualizing the results of MPB calculations.<h2><a name="ctl">The ctl File</a></h2><p>The use of the Photonic-Bands package revolves around the controlfile, abbreviated "ctl" and typically called something like<code>foo.ctl</code> (although you can use any filename extension youwish). The ctl file specifies the geometry you wish to study, thenumber of eigenvectors to compute, what to output, and everything elsespecific to your calculation. Rather than a flat, inflexible fileformat, however, the ctl file is actually written in a scriptinglanguage. This means that it can be everything from a simple sequenceof commands setting the geometry, etcetera, to a full-fledged programwith user input, loops, and anything else that you might need.<p>Don't worry, though--simple things are simple (you don't need to bea <ahref="http://www.tuxedo.org/~esr/jargon/html/entry/Real-Programmer.html">RealProgrammer</a>), and even there you will appreciate the flexibilitythat a scripting language gives you. (e.g. you can input things inany order, without regard for whitespace, insert comments where youplease, omit things when reasonable defaults are available...)<p>The ctl file is actually implemented on top of the libctl library,a set of utilities that are in turn built on top of the Schemelanguage. Thus, there are three sources of possible commands andsyntax for a ctl file:<ul><li>Scheme, a powerful and beautiful programming languagedeveloped at MIT, which has a particularly simple syntax: allstatements are of the form <code>(<i>functionarguments...</i>)</code>. We run Scheme under the GNU Guileinterpreter (designed to be plugged into programs as a scripting andextension language). You don't need to learn much Scheme for a basicctl file, but it is always there if you need it; you can learn moreabout it from these <ahref="http://ab-initio.mit.edu/libctl/doc/guile-links.html">Guile andScheme links</a>.<p><li>libctl, a library that we built on top of Guile to simplifycommunication between Scheme and scientific computation software.libctl sets the basic tone of the user interface and defines a numberof useful functions. See the <ahref="http://ab-initio.mit.edu/libctl/">libctl home page</a>.<p><li>The MIT Photonic-Bands package, which defines all the interfacefeatures that are specific to photonic band structure calculations.This manual is primarily focused on documenting these features.</ul><p>It would be an excellent idea at this point for you to go read the<a href="http://ab-initio.mit.edu/libctl/doc/">libctl manual</a>,particularly the <ahref="http://ab-initio.mit.edu/libctl/doc/basic-user.html">Basic UserExperience</a> section, which will give you an overview of what theuser interface is like, provide a crash course in the Scheme featuresthat are most useful here, and describe some useful general features.We're not going to repeat this material (much), so learn it now!<p>Okay, let's continue with our tutorial. The MIT Photonic-Bands(MPB) program is normally invoked by running something like:<pre>unix% mpb <i>foo.ctl</i> >& <i>foo.out</i></pre><p>which reads the ctl file <code>foo.ctl</code> and executes it,saving the output to the file <code>foo.out</code>. (Some sample ctlfiles are provided for you in the <code>mpb-ctl/examples/</code>directory.) However, as you already know (since you obediently readthe libctl manual, right?), if you invoke <code>mpb</code> with noarguments, you are dropped into an <em>interactive</em> mode in whichyou can type commands and see their results immediately. Why don'tyou do that right now, in your terminal window? Then, you can pastein the commands from the tutorial as you follow it and see what theydo. Isn't this fun?<h2><a name="sq-rods">Our First Band Structure</a></h2><p>As our beginning example, we'll compute the band structure of atwo-dimensional square lattice of dielectric rods in air. In ourcontrol file, we'll first specify the parameters and geometry of thesimulation, and then tell it to run and give us the output.<p>All of the parameters (each of which corresponds to a Schemevariable) have default setting, so we only need to specify the ones weneed to change. (For a complete listing of the parameter variablesand their current values, along with some other info, type<code>(help)</code> at the <code>guile></code> prompt.) One of theparameters, <code>num-bands</code>, controls how many bands(eigenstates) are computed at each k point. If you type<code>num-bands</code> at the prompt, it will return the currentvalue, <code>1</code>--this is too small; let's set it to a largervalue:<pre>(set! num-bands 8)</pre><p>This is how we change the value of variables in Scheme (if you type<code>num-bands</code> now, it will return <code>8</code>). The nextthing we want to set (although the order really doesn't matter), isthe set of k points (Bloch wavevectors) we want to compute the bandsat. This is controlled by the variable <code>k-points</code>, a listof 3-vectors (which is initially empty). We'll set it to the cornersof the irreducible Brillouin zone of a square lattice, Gamma, X, M,and Gamma again:<pre>(set! k-points (list (vector3 0 0 0) ; Gamma (vector3 0.5 0 0) ; X (vector3 0.5 0.5 0) ; M (vector3 0 0 0))) ; Gamma</pre><p>Notice how we construct a list, and how we make 3-vectors; noticealso how we can break things into multiple lines if we want, and thata semicolon ('<code>;</code>') marks the start of a comment.Typically, we'll want to also compute the bands at a lot ofintermediate k points, so that we see the continuous band structure.Instead of manually specifying all of these intermediate points,however, we can just call one of the functions provided by libctl tointerpolate them for us:<pre>(set! k-points (interpolate 4 k-points))</pre><p>This takes the <code>k-points</code> and linearly interpolates fournew points between each pair of consecutive points; if we type<code>k-points</code> now at the prompt, it will show us all 16 pointsin the new list:<p><code>(#(0 0 0) #(0.1 0.0 0.0) #(0.2 0.0 0.0) #(0.3 0.0 0.0) #(0.40.0 0.0) #(0.5 0 0) #(0.5 0.1 0.0) #(0.5 0.2 0.0) #(0.5 0.3 0.0) #(0.50.4 0.0) #(0.5 0.5 0) #(0.4 0.4 0.0) #(0.3 0.3 0.0) #(0.2 0.2 0.0)#(0.1 0.1 0.0) #(0 0 0))</code><p>As is <a href="#units">described below</a>, all spatial vectors inthe program are specified in the basis of the lattice directionsnormalized to <code>basis-size</code> lengths (default isunit-normalized), while the k points are specified in the basis of the(unnormalized) reciprocal lattice vectors. In this case, we don'thave to specify the lattice directions, because we are happy with thedefaults--the lattice vectors default to the cartesian unit axes(i.e. the most common case, a square/cubic lattice). (The reciprocallattice vectors in this case are also the unit axes.) We'll see howto change the lattice vectors in later subsections.<p>Now, we want to set the geometry of the system--we need to specifywhich objects are in the primitive cell of the lattice, centered onthe origin. This is controlled by the variable <code>geometry</code>,which is a list of geometric objects. As you know from reading thelibctl documentation, objects (more complicated, structured datatypes), are created by statements of the form <code>(make <i>type</i>(<i>property1 value1</i>) (<i>property2 value2</i>) ...)</code>.There are various kinds (sub-classes) of geometric object: cylinders,spheres, blocks, ellipsoids, and perhaps others in the future. Rightnow, we want a square lattice of rods, so we put a single dielectriccylinder at the origin:<pre>(set! geometry (list (make cylinder (center 0 0 0) (radius 0.2) (height infinity) (material (make dielectric (epsilon 12))))))</pre><p>Here, we've set several properties of the cylinder: the<code>center</code> is the origin, its <code>radius</code> is 0.2, andits <code>height</code> (the length along its axis) is<code>infinity</code>. Another property, the <code>material</code>,it itself an object--we made it a dielectric with the property thatits <code>epsilon</code> is 12. There is another property of thecylinder that we can set, the direction of its axis, but we're happywith the default value of pointing in the z direction.<p>All of the geometric objects are ostensibly three-dimensional, butsince we're doing a two-dimensional simulation the only thing thatmatters is their intersection with the xy plane (z=0). Speaking ofwhich, let us set the dimensionality of the system. Normally, we dothis when we define the size of the computational cell, controlled bythe <code>geometry-lattice</code> variable, an object of the<code>lattice</code> class: we can set some of the dimensions to havea size <code>no-size</code>, which reduces the dimensionality of thesystem.<pre>(set! geometry-lattice (make lattice (size 1 1 no-size)))</pre><p>Here, we define a 1x1 two-dimensional cell (defaulting to square).This cell is <i>discretized</i> according to the<code>resolution</code> variable, which defaults to <code>10</code>(pixels/lattice-unit). That's on the small side, and this is only a2d calculation, so let's increase the resolution:<pre>(set! resolution 32)</pre><p>This results in a 32x32 computational grid. For efficientcalculation, it is best to make the grid sizes a power of two, orfactorizable into powers of small primes (such as 2, 3, 5 and 7). Asa rule of thumb, you should use a resolution of at least<code>8</code> in order to obtain reasonable accuracy.<p>Now, we're done setting the parameters--there are other parameters,but we're happy with their default values for now. At this point,we're ready to go ahead and compute the band structure. The simplestway to do this is to type <code>(run)</code>. Since this is atwo-dimensional calculation, however, we would like to split the bandsup into TE- and TM-polarized modes, and we do this by invoking<code>(run-te)</code> and <code>(run-tm)</code>.<p>These produce a lot of output, showing you exactly what the code isdoing as it runs. Most of this is self-explanatory, but we shouldpoint out one output in particular. Among the output, you should seelines like:<p><code>tefreqs:, 13, 0.3, 0.3, 0, 0.424264, 0.372604, 0.540287, 0.644083, 0.81406, 0.828135, 0.890673, 1.01328, 1.1124</code><p>These lines are designed to allow you to easily extract theband-structure information and import it into a spreadsheet forgraphing. They comprise the k point index, the k components andmagnitude, and the frequencies of the bands, in comma-delimitedformat. Each line is prefixed by "tefreqs" for TE bands, "tmfreqs"for TM bands, and "freqs" for ordinary bands (produced by<code>(run)</code>), and using this prefix you can extract the datayou want from the output by passing it through a program like<code>grep</code>. For example, if you had redirected the output to afile <code>foo.out</code> (as described earlier), you could extractthe TM bands by running <code>grep tmfreqs foo.out</code> at the Unixprompt. Note that the output includes a header line, like:<p><code>tefreqs:, k index, kx, ky, kz, kmag/2pi, band 1, band 2, band 3, band 4, band 5, band 6, band 7, band 8</code><p>explaining each column of data. Another output of the<code>run</code> is the list of band gaps detected in the computedbands. For example the <code>(run-tm)</code> output includes thefollowing gap output:<pre>Gap from band 1 (0.282623311147724) to band 2 (0.419334798706834), 38.9514660888911%Gap from band 4 (0.715673834754345) to band 5 (0.743682920649084), 3.8385522650349%</pre><p>This data is also stored in the variable <code>gap-list</code>,which is a list of <code>(<i>gap-percent gap-min gap-max</i>)</code>lists. It is important to realize, however, that this band-gap datamay include "false positives," from two possible sources:<ul>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -