user-ref.html
来自「麻省理工的计算光子晶体的程序」· HTML 代码 · 共 1,487 行 · 第 1/5 页
HTML
1,487 行
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"><HTML><HEAD><TITLE>User Reference</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="developer.html">next</a>, <a href="analysis-tutorial.html">previous</a>, or <a href="index.html">main</a> section.<hr><h1>User Reference</h1><p>Here, we document the features exposed to the user by the MITPhotonic-Bands package. We do not document the Scheme language or thefunctions provided by libctl (see also the <ahref="http://ab-initio.mit.edu/libctl/doc/user-ref.html">userreference</a> section of the <ahref="http://ab-initio.mit.edu/libctl/doc/">libctl manual</a>).<h2><a name="input-vars">Input Variables</a></h2><p>These are global variables that you can set to control variousparameters of the Photonic-Bands computation. They are also listed(along with their current values) by the <code>(help)</code> command.In brackets after each variable is the type of value that it shouldhold. (The classes, complex datatypes like<code>geometric-object</code>, are described in a later subsection.The basic datatypes, like <code>integer</code>, <code>boolean</code>,<code>cnumber</code>, and <code>vector3</code>, are defined by libctl.)<dl><dt><code>geometry</code> [list of <code>geometric-object</code> class]<dd>Specifies the geometric objects making up the structure beingsimulated. When objects overlap, later objects in the list takeprecedence. Defaults to no objects (empty list).<p><dt><code>default-material</code> [<code>material-type</code> class]<dd>Holds the default material that is used for points not in anyobject of the geometry list. Defaults to air (epsilon of 1). Seealso <code>epsilon-input-file</code>, below.<p><dt><code>ensure-periodicity</code> [<code>boolean</code>]<dd>If true (the default), then geometric objects are treated as ifthey were shifted by all possible lattice vectors; i.e. they are madeperiodic in the lattice.<p><dt><code>geometry-lattice</code> [<code>lattice</code> class]<dd>Specifies the basis vectors and lattice size of the computationalcell (which is centered on the origin of the coordinate system).These vectors form the basis for all other 3-vectors in the geometry,and the lattice size determines the size of the primitive cell. Ifany dimension of the lattice size is the special value<code>no-size</code>, then the dimension of the lattice is reduced(i.e. it becomes two- or one-dimensional). (That is, the dielectricfunction becomes two-dimensional; it is still, in principle, a threedimensional system, and the k-point vectors can be three-dimensional.)Generally, you should make any <code>no-size</code> dimension(s)perpendicular to the others. Defaults to the orthogonal x-y-z vectorsof unit length (i.e. a square/cubic lattice).<p><dt><code>resolution</code> [<code>number</code> or <code>vector3</code>]<dd>Specifies the computational grid resolution, in pixels per latticeunit (a lattice unit is one basis vector in a given direction). If<code>resolution</code> is a <code>vector3</code>, then specifies adifferent resolution for each direction; otherwise the resolution isuniform. (The grid size is then the product of the lattice size andthe resolution, rounded up to the next positive integer.) Defaults to<code>10</code>.<p><dt><code>grid-size</code> [<code>vector3</code>]<dd>Specifies the size of the discrete computational grid along eachof the lattice directions. <em>Deprecated:</em> the preferred methodis to use the <code>resolution</code> variable, above, in which casethe <code>grid-size</code> defaults to <code>false</code>. To get thegrid size you should instead use the <code>(get-grid-size)</code>function.<p><dt><code>mesh-size</code> [<code>integer</code>]<dd>At each grid point, the dielectric constant is averaged over a"mesh" of points to find an effective dielectric tensor. This mesh isa grid with <code>mesh-size</code> points on a side. Defaults to 3.Increasing <code>mesh-size</code> makes the the average dielectricconstant sensitive to smaller structural variations without increasingthe grid size, but also means that computing the dielectric functionwill take longer. (Using a <code>mesh-size</code> of <code>1</code>turns <em>off</em> dielectric function averaging and the creation ofan effective dielectric tensor at interfaces. Be sure you know whatyou're doing before you worsen convergence in this way.)<p><dt><code>dimensions</code> [<code>integer</code>]<dd>Explicitly specifies the dimensionality of the simulation; if thevalue is less than 3, the sizes of the extra dimensions in<code>grid-size</code> are ignored (assumed to be one). Defaults to 3.<em>Deprecated:</em> the preferred method is to set<code>geometry-lattice</code> to have size </code>no-size</code> inany unwanted dimensions.<p><dt><code><a name="k-points">k-points</a></code> [list of<code>vector3</code>]<dd>List of Bloch wavevectors to compute the bands at, expressed inthe basis of the reciprocal lattice vectors. The reciprocal latticevectors are defined as follows: Given the lattice vectors<code>R<sub>i</sub></code> (<em>not</em> the basis vectors), thereciprocal lattice vector <code>G<sub>j</sub></code> satisfies<code>R<sub>i</sub> * G<sub>j</sub> = 2*Pi*delta<sub>i,j</sub></code>,where <code>delta<sub>i,j</sub></code> is the Kronecker delta (1 for<code>i = j</code> and 0 otherwise). (<code>R<sub>i</sub></code> forany <code>no-size</code> dimensions is taken to be the correspondingbasis vector.) Normally, the wavevectors should be in the firstBrillouin zone (<a href="#first-brillouin-zone">see below</a>).<code>k-points</code> defaults to none (empty list).<p><dt><code>num-bands</code> [<code>integer</code>]<dd>Number of bands (eigenvectors) to compute at each kpoint. Defaults to 1.<p><dt><code>target-freq</code> [<code>number</code>]<dd>If zero, the lowest-frequency <code>num-bands</code> states aresolved for at each k point (ordinary eigenproblem). If non-zero,solve for the <code>num-bands</code> states whose frequencies are havethe smallest absolute difference with <code>target-freq</code>(special, "targeted" eigenproblem). Beware that the targeted solverconverges more slowly than the ordinary eigensolver and may require alower <code>tolerance</code> to get reliable results. Defaults to 0.<p><dt><code>tolerance</code> [<code>number</code>]<dd>Specifies when convergence of the eigensolver is judged to havebeen reached (when the eigenvalues have a fractional change less than<code>tolerance</code> between iterations). Defaults to 1.0e-7.<p><dt><code>filename-prefix</code> [<code>string</code>]<dd>A string prepended to all output filenames. Defaults to<code>""</code> (no prefix).<p><dt><code>epsilon-input-file</code> [<code>string</code>]<dd>If this string is not <code>""</code> (the default), then itshould be the name of an HDF5 file whose first/only dataset defines adielectric function (over some discrete grid). This dielectricfunction is then used in place of <code>default-material</code>(<i>i.e.</i> where there are no <code>geometry</code> objects). Thegrid of the epsilon file dataset need not match<code>grid-size</code>; it is scaled and/or linearly interpolated asneeded. The lattice vectors for the epsilon file are assumed to bethe same as <code>geometry-lattice</code>. [ Note that, even if thegrid sizes match and there are no geometric objects, the dielectricfunction used by MPB will not be exactly the dielectric function ofthe epsilon file, unless you also set <code>mesh-size</code> to<code>1</code> (see above). ]<p><dt><code>eigensolver-block-size</code> [<code>integer</code>]<dd>The eigensolver uses a "block" algorithm, which means that itsolves for several bands simultaneously at each k-point.<code>eigensolver-block-size</code> specifies this number of bands tosolve for at a time; if it is zero or >= <code>num-bands</code>,then all the bands are solved for at once. If<code>eigensolver-block-size</code> is a negative number, -<i>n</i>,then MPB will try to use nearly-equal block-sizes close to <i>n</i>.Making the block size a small number can reduce the memoryrequirements of MPB, but block sizes > 1 are usually more efficient(there is typically some optimum size for any given problem).Defaults to -11 (i.e. solve for around 11 bands at a time).<p><dt><code>simple-preconditioner?</code> [<code>boolean</code>]<dd>Whether or not to use a simplified preconditioner; defaults to<code>false</code> (this is fastest most of the time). (Turning thison increases the number of iterations, but decreases the time for eachiteration.)<p><dt><code>deterministic?</code> [<code>boolean</code>]<dd>Since the fields are initialized to random values at the start ofeach run, there are normally slight differences in the number ofiterations, etcetera, between runs. Setting<code>deterministic?</code> to <code>true</code> makes thingsdeterministic (the default is <code>false</code>).<p><dt><code>eigensolver-flags</code> [<code>integer</code>]<dd>This variable is undocumented and reserved for use by Jedi Masters only.</dl><h2><a name="predef-vars">Predefined Variables</a></h2><p>Variables predefined for your convenience and amusement.<dl><dt><code>air</code>, <code>vacuum</code> [<code>material-type</code> class]<dd>Two aliases for a predefined material type with a dielectricconstant of 1.<dt><code>nothing</code> [<code>material-type</code> class]<dd>A material that, effectively, punches a hole through otherobjects to the background (<code>default-material</code> or<code>epsilon-input-file</code>).<p><dt><code>infinity</code> [<code>number</code>]<dd>A big number (1.0e20) to use for "infinite" dimensions of objects.</dl><h2><a name="output-vars">Output Variables</a></h2><p>Global variables whose values are set upon completion of theeigensolver.<dl><dt><code>freqs</code> [list of <code>number</code>]<dd>A list of the frequencies of each band computed for the last kpoint. Guaranteed to be sorted in increasing order. The frequency ofband <code>b</code> can be retrieved via <code>(list-ref freqs (- b1))</code>.<p><dt><code>iterations</code> [<code>integer</code>]<dd>The number of iterations required for convergence of the last k point.<p><dt><code>parity</code> [<code>string</code>]<dd>A string describing the current required parity/polarization(<code>"te"</code>, <code>"zeven"</code>, etcetera, or <code>""</code>for none), useful for prefixing output lines for grepping.</dl><p>Yet more global variables are set by the <code>run</code> function(and its variants), for use after <code>run</code> completes or by aband function (which is called for each band during the execution of<code>run</code>.<dl><dt><code>current-k</code> [<code>vector3</code>]<dd>The k point (from the <code>k-points</code> list) most recently solved.<p><dt><code>gap-list</code> [list of <code>(<i>percent freq-min freq-max</i>)</code> lists]<dd>This is a list of the gaps found by the eigensolver, and is set bythe <code>run</code> functions when two or more k-points are solved.(It is the empty list if no gaps are found.)<p><dt><code>band-range-data</code> [list of <code>((<i>min . kpoint</i>) . (<i>max . kpoint</i>))</code> pairs (of pairs)]<dd>For each band, this list contains the minimum and maximumfrequencies of the band, and the associated k points where the extremaare achieved. Note that the bands are defined by sorting thefrequencies in increasing order, so this can be confused if two bandscross.</dl><h2><a name="classes">Classes</a></h2><p>Classes are complex datatypes with various "properties" which mayhave default values. Classes can be "subclasses" of other classes;subclasses inherit all the properties of their superclass, and can beused any place the superclass is expected. An object of a class isconstructed with:<pre>(make <i>class</i> (<i>prop1 val1</i>) (<i>prop2 val2</i>) ...)</pre><p>See also the <a href="http://ab-initio.mit.edu/libctl/doc/">libctlmanual</a>.<p>MIT Photonic-Bands defines several types of classes, the mostnumerous of which are the various geometric object classes. You canalso get a list of the available classes, along with their propertytypes and default values, at runtime with the <code>(help)</code>command.<h3><a name="lattice">lattice</a></h3><p>The lattice class is normally used only for the<code>geometry-lattice</code> variable, and specifies the threelattice directions of the crystal and the lengths of the correspondinglattice vectors.<dl><dt><code>lattice</code><dd>Properties:<dl><dt><code>basis1</code>, <code>basis2</code>, <code>basis3</code> [<code>vector3</code>]<dd>The three lattice directions of the crystal, specified in thecartesian basis. The lengths of these vectors are ignored--only theirdirections matter. The lengths are determined by the<code>basis-size</code> property, below. These vectors are then usedas a basis for all other 3-vectors in the ctl file. They default tothe x, y, and z directions, respectively.<dt><code>basis-size</code> [<code>vector3</code>]<dd>The components of <code>basis-size</code> are the lengths of thethree basis vectors, respectively. They default ot unit lengths.<dt><code>size</code> [<code>vector3</code>]⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?