user-ref.html

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

</pre>

</dl>

<h3><a name="band-funcs">Band/output functions</a></h3>

<p>All of these are functions that, given a band index, output the
corresponding field or compute some function thereof (in the primitive
cell of the lattice).  They are designed to be passed as band
functions to the <code>run</code> routines, although they can also be
called directly.  See also the section on <a href="#field-norm">field
normalizations</a>.

<dl>

<dt><code>(output-hfield <i>which-band</i>)</code>
<dt><code>(output-hfield-x <i>which-band</i>)</code>
<dt><code>(output-hfield-y <i>which-band</i>)</code>
<dt><code>(output-hfield-z <i>which-band</i>)</code>
<dd>Output the magnetic (H) field for <code>which-band</code>; either
all or one of the components, respectively.

<p><dt><code>(output-dfield <i>which-band</i>)</code>
<dt><code>(output-dfield-x <i>which-band</i>)</code>
<dt><code>(output-dfield-y <i>which-band</i>)</code>
<dt><code>(output-dfield-z <i>which-band</i>)</code>
<dd>Output the electric displacement (D) field for
<code>which-band</code>; either all or one of the components,
respectively.

<p><dt><code>(output-efield <i>which-band</i>)</code>
<dt><code>(output-efield-x <i>which-band</i>)</code>
<dt><code>(output-efield-y <i>which-band</i>)</code>
<dt><code>(output-efield-z <i>which-band</i>)</code>
<dd>Output the electric (E) field for <code>which-band</code>; either
all or one of the components, respectively.

<p><dt><code>(output-hpwr <i>which-band</i>)</code>
<dd>Output the time-averaged magnetic-field energy density (hpwr =
|<b>H</b>|<sup><small>2</small></sup>) for <code>which-band</code>.

<p><dt><code>(output-dpwr <i>which-band</i>)</code>
<dd>Output the time-averaged electric-field energy density (dpwr =
epsilon*|<b>E</b>|<sup><small>2</small></sup>) for
<code>which-band</code>.

<p><dt><code>(fix-hfield-phase <i>which-band</i>)</code>
<dt><code>(fix-dfield-phase <i>which-band</i>)</code>
<dt><code>(fix-efield-phase <i>which-band</i>)</code>
<dd>Fix the phase of the given eigenstate in a canonical way based on
the given spatial field (see also <code>fix-field-phase</code>,
below).  Otherwise, the phase is random; these functions also maximize
the real part of the given field so that one can hopefully just
visualize the real part.  To fix the phase for output, pass one of
these functions to <code>run</code> before the corresponding output
function, e.g. <code>(run-tm fix-dfield-phase output-dfield-z)</code>

<p>Although we try to maximize the "real-ness" of the field, this has
a couple of limitations.  First, the phase of the different field
components cannot, of course, be chosen independently, so an
individual field component may still be imaginary.  Second, if you use
<code>mpbi</code> to take advantage of <a href="#inv-symmetry">inversion
symmetry</a> in your problem, the phase is mostly determined elsewhere
in the program; <code>fix-_field-phase</code> in that case only
determines the sign.

</dl>

<p>See also below for the <code>output-poynting</code> and
<code>output-tot-pwr</code> functions to output the Poynting vector
and the total electromagnetic energy density, respectively.

<p>Sometimes, you only want to output certain bands.  For example,
here is a function that, given an band/output function like the ones
above, returns a new output function that only calls the first
function for bands with a large fraction of their energy in an object(s).
(This is useful for picking out defect states in supercell
calculations.)

<dl>

<dt><code>(output-dpwr-in-objects <i>band-func min-energy objects...</i>)</code>

<dd>Given a band function <code>band-func</code>, returns a new band
function that only calls <code>band-func</code> for bands having a
fraction of their electric-field energy greater than
<code>min-energy</code> inside the given objects (zero or more
geometric objects).  Also, for each band, prints the fraction of their
energy in the objects in the following form (suitable for grepping):

<pre>
dpwr:, <i>band-index</i>, <i>frequency</i>, <i>energy-in-objects</i>
</pre>

</dl>

<p><code>output-dpwr-in-objects</code> only takes a single band
function as a parameter, but if you want it to call several band
functions, you can easily combine them into one with the following
routine:

<dl>

<dt><code>(combine-band-functions <i>band-funcs...</i>)</code>
<dd>Given zero or more band functions, returns a new band function
that calls all of them in sequence.  (When passed zero parameters,
returns a band function that does nothing.)

</dl>

<p>It is also often useful to output the fields only at a certain k-point,
to let you look at typical field patterns for a given band while avoiding
gratuitous numbers of output files.  This can be accomplished via:

<dl>

<dt><code>(output-at-kpoint <i>k-point</i> <i>band-funcs...</i>)</code>
<dd>Given zero or more band functions, returns a new band function
that calls all of them in sequence, but only at the specified
<code>k-point</code>.  For other k-points, does nothing.

</dl>

<h3><a name="misc-funcs">Miscellaneous functions</a></h3>

<dl>

<p><dt><code>(retrieve-gap <i>lower-band</i>)</code>
<dd>Return the frequency gap from the band
#<code><i>lower-band</i></code> to the band
#(<code><i>lower-band</i></code>+1), as a percentage of mid-gap
frequency.  The "gap" may be negative if the maximum of the lower band
is higher than the minimum of the upper band.  (The gap is computed
from the <code>band-range-data</code> of the previous run.)

</dl>

<h4><a name="parity">Parity</a></h4>

<p>Given a set of eigenstates at a k-point, MPB can compute their
<i>parities</i> with respect to the z=0 or y=0 plane.  The z/y parity
of a state is defined as the expectation value (under the usual inner
product) of the mirror-flip operation through z/y=0, respectively.
For true even and odd eigenstates (see e.g.  <code>run-zeven</code>
and <code>run-zodd</code>), this will be +1 and -1, respectively; for
other states it will be something in between.

<p>This is useful e.g. when you have a nearly symmetric structure, such
as a waveguide with a substrate underneath, and you want to tell which
bands are even-like (parity &gt; 0) and odd-like (parity &lt; 0).
Indeed, any state can be decomposed into purely even and odd
functions, with absolute-value-squared amplitudes of (1+parity)/2 and
(1-parity)/2, respectively.

<dl>

<p><dt><code>display-zparities</code>, <code>display-yparities</code>
<dd>These are band functions, designed to be passed to
<code>(run)</code>, which output all of the z/y parities,
respectively, at each k-point (in comma-delimited format suitable for
grepping).

<p><dt><code>(compute-zparities)</code>
<dd>Returns a list of the parities about the z=0 plane, one number for
each band computed at the last k-point.

<p><dt><code>(compute-yparities)</code>
<dd>Returns a list of the parities about the y=0 plane, one number for
each band computed at the last k-point.

</dl>

<p>(The reader should recall that the magnetic field is only a
pseudo-vector, and is therefore multiplied by -1 under mirror-flip
operations.  For this reason, the magnetic field <i>appears</i> to have
opposite symmetry from the electric field, but is really the same.)

<h4><a name="group-vel">Group velocities</a></h4>

<p>Given a set of eigenstates at a given k-point, MPB can compute
their group velocities (the derivative of frequency with respect to
wavevector) using the Hellman-Feynmann theorem.  Three functions are
provided for this purpose, and we document them here from
highest-level to lowest-level.

<dl>

<p><dt><code>display-group-velocities</code>
<dd>This is a band function, designed to be passed to
<code>(run)</code>, which outputs all of the group velocity vectors
(in the Cartesian basis, in units of <i>c</i>) at each k-point.

<p><dt><code>(compute-group-velocities)</code>
<dd>Returns a list of group-velocity vectors (in the Cartesian basis,
units of <i>c</i>) for the bands at the last-computed k-point.

<p><dt><code>(compute-group-velocity-component <i>direction</i>)</code>
<dd>Returns a list of the group-velocity components (units of
<i>c</i>) in the given <i>direction</i>, one for each band at the
last-computed k-point.  <i>direction</i> is a vector in the
reciprocal-lattice basis (like the k-points); its length is ignored.
(This has the advantage of being three times faster than
<code>compute-group-velocities</code>.)

</dl>

<h2><a name="field">Field manipulation</a></h2>

<p>The Photonic-Bands package provides a number of ways to take the
field of a band and manipulate, process, or output it.  These methods
usually work in two stages.  First, one loads a field into memory
(computing it in position space) by calling one of the
<code>get</code> functions below.  Then, other functions can be called
to transform or manipulate the field.

<p>The simplest class of operations involve only the currently-loaded
field, which we describe in the <a href="#cur-field">second
subsection</a> below.  To perform more sophisticated operations,
involving more than one field, one must copy or transform the current
field into a new field variable, and then call one of the functions
that operate on multiple field variables (described in the <a
href="#mult-fields">third subsection</a>).

<h3><a name="field-norm">Field normalization</a></h3>

<p>In order to perform useful operations on the fields, it is
important to understand how they are normalized.  We normalize the
fields in the way that is most convenient for perturbation and
coupled-mode theory [c.f. SGJ et al., <i>PRE</i> <b>65</b>, 066611
(2002)], so that their energy densities have unit integral.  In
particular, we normalize the electric (<b>E</b>), displacement
(<b>D</b> = epsilon*<b>E</b>) and magnetic (<b>H</b> = -i/omega * curl
<b>E</b>) fields, so that:

<ul>

<li>integral epsilon*|<b>E</b>|<sup><small>2</small></sup> dxdydz = 1
<li>integral |<b>H</b>|<sup><small>2</small></sup> dxdydz = 1

</ul>

<p>where the integrals are over the computational cell.  Note the
volume element dxdydz (the volume of a grid pixel/voxel).  If you
simply sum |<b>H</b>|<sup><small>2</small></sup> over all the grid
points, therefore, you will get (# grid points) / (volume of cell).

<p>Note that we have dropped the pesky factors of 1/2, pi, etcetera
from the energy densities, since these do not appear in
e.g. perturbation theory, and the fields have arbitrary units anyway.
The functions to compute/output energy densities below similarly use
epsilon*|<b>E</b>|<sup><small>2</small></sup> and
|<b>H</b>|<sup><small>2</small></sup> without any prefactors.

<h3><a name="cur-field">Loading and manipulating the current
field</a></h3>

<p>In order to load a field into memory, call one of the
<code>get</code> functions follow.  They should only be called after
the eigensolver has run (or after <code>init-params</code>, in the
case of <code>get-epsilon</code>).  One normally calls them after
<code>run</code>, or in one of the band functions passed to
<code>run</code>.

<dl>

<dt><code>(get-hfield <i>which-band</i>)</code>
<dd>Loads the magnetic (H) field for the band <code>which-band</code>.

<p><dt><code>(get-dfield <i>which-band</i>)</code>
<dd>Loads the electric displacement (D) field for the band
<code>which-band</code>.

<p><dt><code>(get-efield <i>which-band</i>)</code>
<dd>Loads the electric (E) field for the band <code>which-band</code>.
(This function actually calls <code>get-dfield</code> followed by
<code>get-efield-from-dfield</code>, below.)

<p><dt><code>(get-epsilon)</code>
<dd>Loads the dielectric function.

</dl>

<p>Once loaded, the field can be transformed into another field or a
scalar field:

<dl>

<dt><code>(get-efield-from-dfield)</code>
<dd>Multiplies by the inverse dielectric tensor to compute the
electric field from the displacement field.  Only works if a D field
has been loaded.

<p><dt><code>(fix-field-phase)</code>
<dd>Fix the currently-loaded eigenstate's phase (which is normally
random) in a canonical way, based on the spatial field (H, D, or E)
that has currently been loaded.  The phase is fixed to make the real
part of the spatial field as big as possible (so that you can
hopefully visualize just the real part of the field), and a canonical