user-ref.html

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

<dt><code>(lattice->cartesian <i>x</i>)</code>, <code>(cartesian->lattice <i>x</i>)</code>
<dd>Convert <code><i>x</i></code> between the lattice basis (the basis
of the lattice vectors normalized to <code>basis-size</code>) and the
ordinary cartesian basis, where <code><i>x</i></code> is either a
<code>vector3</code> or a <code>matrix3x3</code>, returning the
transformed vector/matrix.  In the case of a matrix argument, the
matrix is treated as an operator on vectors in the given basis, and is
transformed into the same operator on vectors in the new basis.

<p><dt><code>(reciprocal->cartesian <i>x</i>)</code>, <code>(cartesian->reciprocal <i>x</i>)</code>
<dd>Like the above, except that they convert to/from reciprocal space
(the basis of the reciprocal lattice vectors).  Also, the cartesian
vectors output/input are in units of 2 Pi.

<p><dt><code>(reciprocal->lattice <i>x</i>)</code>, <code>(lattice->reciprocal <i>x</i>)</code>
<dd>Convert between the reciprocal and lattice bases, where the
conversion again leaves out the factor of 2 Pi (i.e. the lattice-basis
vectors are assumed to be in units of 2 Pi).

</dl>

<p>Also, a couple of rotation functions are defined, for convenience,
so that you don't have to explicitly convert to cartesian coordinates
in order to use libctl's <code>rotate-vector3</code> function (see the
<a href="http://ab-initio.mit.edu/libctl/doc/user-ref.html">libctl
reference</a>):

<dl>

<dt><code>(rotate-lattice-vector3 <i>axis theta v</i>)</code>, <code>(rotate-reciprocal-vector3 <i>axis theta v</i>)</code>
<dd>Like <code>rotate-vector3</code> , except that
<code><i>axis</i></code> and <code><i>v</i></code> are specified in
the lattice/reciprocal bases.

</dl>

<p><a name="first-brillouin-zone"></a>Usually, k-points are specified
in the first Brillouin zone, but sometimes it is convenient to specify
an arbitrary k-point.  However, the accuracy of MPB degrades as you
move farther from the first Brillouin zone (due to the choice of a
fixed planewave set for a basis).  This is easily fixed: simply
transform the k-point to a corresponding point in the first Brillouin
zone, and a completely equivalent solution (identical frequency,
fields, etcetera) is obtained with maximum accuracy.  The following
function accomplishes this:

<dl>

<dt><code>(first-brillouin-zone <i>k</i>)</code>
<dd>Given a k-point <code><i>k</i></code> (in the basis of the
reciprocal lattice vectors, as usual), return an equivalent point in
the first Brillouin zone of the current lattice
(<code>geometry-lattice</code>).

</dl>

<p>Note that <code>first-brillouin-zone</code> can be applied to the
entire <code>k-points</code> list with the Scheme expression:
<code>(map first-brillouin-zone k-points)</code>.

<h3><a name="run">Run functions</a></h3>

<p>These are functions to help you run and control the simulation.
The ones you will most commonly use are the <code>run</code> function
and its variants.  The syntax of these functions, and one lower-level
function, is:

<dl>

<dt><code>(run <i>band-func ...</i>)</code> <dd>This runs the
simulation described by the input parameters (see above), with no
constraints on the polarization of the solution.  That is, it reads
the input parameters, initializes the simulation, and solves for the
requested eigenstates of each k-point.  The dielectric function is
outputted to "<code>epsilon.h5</code>" before any eigenstates are
computed.  <code>run</code> takes as arguments zero or more "band
functions" <code>band-func</code>.  A band function should be a
function of one integer argument, the band index, so that
<code>(band-func which-band)</code> performs some operation on the
band <code>which-band</code> (e.g. outputting fields).  After every
k-point, each band function is called for the indices of all the bands
that were computed.  Alternatively, a band function may be a "thunk"
(function of zero arguments), in which case <code>(band-func)</code>
is called exactly once per k-point.

<p><dt><code>(run-zeven <i>band-func ...</i>), (run-zodd <i>band-func ...</i>)</code>
<dd>These are the same as the <code>run</code> function except that
they constrain their solutions to have even and odd symmetry with
respect to the z=0 plane.  You should use these functions
<em>only</em> for structures that are symmetric through the z=0 mirror
plane, where the third basis vector is in the z direction (0,0,1) and
is orthogonal to the other two basis vectors, and when the k vectors
are in the xy plane.  Under these conditions, the eigenmodes always
have either even or odd symmetry.  In two dimensions, even/odd
parities are equivalent to TE/TM polarizations, respectively (and are
often strongly analogous even in 3d).  Such a symmetry classification
is useful for structures such as waveguides and photonic-crystal slabs.
(For example, see the paper by S. G. Johnson <i>et al.</i>, "Guided
modes in photonic crystal slabs," <i>PRB</i> <b>60</b>, 5751, August
1999.)

<p><dt><code>(run-te <i>band-func ...</i>), (run-tm <i>band-func ...</i>)</code>
<dd>These are the same as the <code>run</code> function except that
they constrain their solutions to be TE- and TM-polarized,
respectively, in two dimensions.  The TE and TM polarizations are
defined has having electric and magnetic fields in the xy plane,
respectively.  Equivalently, the H/E field of TE/TM light has only a z
component (making it easier to visualize).

<p>These functions are actually equivalent to calling
<code>run-zeven</code> and <code>run-zodd</code>, respectively.

<p><a name="tetm-aniso">Note</a> that for the modes to be segregated
into TE and TM polarizations, the dielectric function must have mirror
symmetry for reflections through the xy plane.  If you use <a
href="#dielectric-anisotropic">anisotropic dielectrics</a>, you should
be aware that they break this symmetry if the z direction is not one
of the principle axes.  If you use <code>run-te</code> or
<code>run-tm</code> in such a case of broken symmetry, MPB will exit
with an error.

<p><dt><code>(run-yeven <i>band-func ...</i>), (run-yodd <i>band-func ...</i>)</code>
<dd>These functions are analogous to <code>run-zeven</code> and
<code>run-zodd</code>, except that they constrain their solutions to
have even and odd symmetry with respect to the y=0 plane.  You should
use these functions <em>only</em> for structures that are symmetric
through the y=0 mirror plane, where the second basis vector is in the
y direction (0,1,0) and is orthogonal to the other two basis vectors,
and when the k vectors are in the xz plane.

<p><dt><code>run-yeven-zeven</code>, <code>run-yeven-zodd</code>, <code>run-yodd-zeven</code>, <code>run-yodd-zodd</code>, <code>run-te-yeven</code>, <code>run-te-yodd</code>, <code>run-tm-yeven</code>, <code>run-tm-yodd</code>
<dd>These <code>run</code>-like functions combine the
<code>yeven</code>/<code>yodd</code> constraints with
<code>zeven</code>/<code>zodd</code> or
<code>te</code>/<code>tm</code>.  See also <code>run-parity</code>,
below.

<p><dt><code>(run-parity <i>p reset-fields band-func ...</i>)</code>
<dd>Like the <code>run</code> function, except that it takes two extra
parameters, a parity <code>p</code> and a boolean
(<code>true</code>/<code>false</code>) value
<code>reset-fields</code>.  <code>p</code> specifies a parity
constraint, and should be one of the predefined variables:

<ul>
<li><code>NO-PARITY</code>: equivalent to <code>run</code>
<li><code>EVEN-Z</code> (or <code>TE</code>): equivalent to <code>run-zeven</code> or <code>run-te</code>
<li><code>ODD-Z</code> (or <code>TM</code>): equivalent to <code>run-zodd</code> or <code>run-tm</code>
<li><code>EVEN-Y</code> (like <code>EVEN-Z</code> but for y=0 plane)
<li><code>ODD-Y</code> (like <code>ODD-Z</code> but for y=0 plane)
</ul>

<p>It is possible to specify more than one symmetry constraint
simultaneously by adding them, e.g. <code>(+ EVEN-Z ODD-Y)</code>
requires the fields to be even through z=0 and odd through y=0.  It is
an error to specify incompatible constraints (e.g. <code>(+ EVEN-Z
ODD-Z)</code>).  <b>Important:</b> if you specify the z/y parity, the
dielectric structure (and the k vector) <b>must</b> be symmetric about the
z/y=0 plane, respectively.

<p>If <code>reset-fields</code> is <code>false</code>, the fields from
any previous calculation will be reused as the starting point from
this calculation, if possible; otherwise, the fields are reset to
random values.  The ordinary <code>run</code> functions use a default
<code>reset-fields</code> of<code>true</code>.  Alternatively,
<code>reset-fields</code> may be a string, the name of an HDF5 file to
load the initial fields from (as exported by
<code>save-eigenvectors</code>, <a href="#eigen-fields">below</a>).

<p><dt><code>(display-eigensolver-stats)</code>
<dd>Display some statistics on the eigensolver convergence; this function is
useful mainly for MPB developers in tuning the eigensolver.

</dl>

<p>Several band functions for outputting the eigenfields are defined
for your convenience, and are described in the <b>Band output
functions</b> section, below.  You can also define your own band
functions, and for this purpose the functions described in the section
<b>Field manipulation functions</b>, below, are useful.  A band
function takes the form:

<pre>
(define (<i>my-band-func</i> which-band)
  <i>...do stuff here with band index which-band...</i>
)
</pre>

<p>Note that the output variable <code>freqs</code> may be used to
retrieve the frequency of the band (see above).  Also, a global
variable <code>current-k</code> is defined holding the current k-point
vector from the <code>k-points</code> list.

<p>There are also some even lower-level functions that you can call,
although you should not need to do most of the time:

<dl>

<dt><code>(init-params <i>p reset-fields?</i>)</code>

<dd>Read the input variables and initialize the simulation in
preparation for computing the eigenvalues.  The parameters are the
same as the first two parameters of <code>run-parity</code>.
This function <em>must</em> be called before any of the other
simulation functions below.  (Note, however, that the <code>run</code>
functions all call <code>init-params</code>.)

<p><dt><code>(set-parity <i>p</i>)</code>
<dd>After calling <code>init-params</code>, you can change the
parity constraint without resetting the other parameters by
calling this function.  Beware that this does not randomize the fields
(see below); you don't want to try to solve for, say, the TM
eigenstates when the fields are initialized to TE states from a
previous calculation.

<p><dt><code>(randomize-fields)</code>
<dd>Initialize the fields to random values.

<p><dt><code>(solve-kpoint <i>k</i>)</code>
<dd>Solve for the requested eigenstates at the Bloch wavevector
<code>k</code>.

</dl>

<h3><a name="find-k">The inverse problem: k as a function of frequency</a></h3>

<p>MPB's <code>(run)</code> function(s) and its underlying algorithms
compute the frequency <code>w</code> as a function of wavevector
<code>k</code>.  Sometimes, however, it is desirable to solve the
inverse problem, for <code>k</code> at a given frequency
<code>w</code>.  This is useful, for example, when studying coupling
in a waveguide between different bands at the same frequency
(frequency is conserved even when wavevector is not).  One also uses
<code>k(w)</code> to construct wavevector diagrams, which aid in
understanding diffraction (e.g. negative-diffraction materials and
super-prisms).  To solve such problems, therefore, we provide the
<code>find-k</code> function described below, which inverts
<code>w(k)</code> via a few iterations of Newton's method (using the
<a href="#group-vel">group velocity</a> <code>dw/dk</code>).  Because
it employs a root-finding method, you need to specify bounds on
<code>k</code> and a <em>crude</em> initial guess (order of magnitude
is usually good enough).

<dl>

<dt><code>(find-k <i>p omega band-min band-max kdir
                tol kmag-guess kmag-min kmag-max [band-func...]</i>)</code>

<dd>Find the wavevectors in the current geometry/structure for the
bands from <code><i>band-min</i></code> to
<code><i>band-max</i></code> at the frequency
<code><i>omega</i></code> along the <code><i>kdir</i></code> direction
in k-space.  Returns a list of the wavevector magnitudes for each
band; the actual wavevectors are <code>(vector3-scale <i>magnitude</i>
(unit-vector3 <i>kdir</i>))</code>.  The arguments of
<code>find-k</code> are:

<ul>

<li><code><i>p</i></code>: parity (same as first argument to
<code>run-parity</code>, <a href="#run">above</a>).

<li><code><i>omega</i></code>: the frequency at which to find the bands

<li><code><i>band-min</i></code>, <code><i>band-max</i></code>: the
range of bands to solve for the wavevectors of (inclusive).

<li><code><i>kdir</i></code>: the direction in k-space in which to
find the wavevectors.  (The magnitude of <code><i>kdir</i></code> is
ignored.)

<li><code><i>tol</i></code>: the fractional tolerance with which to
solve for the wavevector; <code>1e-4</code> is usually sufficient.
(Like the <code>tolerance</code> input variable, this is only the
tolerance of the numerical iteration...it does not have anything to do
with e.g. the error from finite grid <code>resolution</code>.)

<li><code><i>kmag-guess</i></code>: an initial guess for the k
magnitude (along <code><i>kdir</i></code>) of the wavevector at
<code><i>omega</i></code>.  Can either be a list (one guess for each
band from <code><i>band-min</i></code> to
<code><i>band-max</i></code>) or a single number (same guess for all
bands, which is usually sufficient).

<li><code><i>kmag-min</i></code>, <code><i>kmag-max</i></code>: a
range of k magnitudes to search; should be large enough to include the
correct k values for all bands.

<li><code><i>band-func</i></code>: zero or more <a
href="#band-funcs">band functions</a>, just as in <code>(run)</code>,
which are evaluated at the computed k points for each band.

</ul>

<p>The <code>find-k</code> routine also prints a line suitable for grepping:

<pre>
kvals: <i>omega</i>, <i>band-min</i>, <i>band-max</i>, <i>kdir-x</i>, <i>kdir-y</i>, <i>kdir-z</i>, <i>k magnitudes...</i>