user-ref.html

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

sign is chosen.  See also the <code>fix-*field-phase</code> band
functions, above, which are convenient wrappers around
<code>fix-field-phase</code>

<p><dt><code>(compute-field-energy)</code>
<dd>Given the H or D fields, computes the corresponding energy density
function (normalized by the total energy in H or D, respectively).  Also
prints the fraction of the field in each of its cartesian components
in the following form (suitable for grepping):

<pre>
<i>f</i>-energy-components:, <i>k-index</i>, <i>band-index</i>, <i>x-fraction</i>, <i>y-fraction</i>, <i>z-fraction</i>
</pre>

<p>where <code><i>f</i></code> is either <code>h</code> or
<code>d</code>.  The return value of <code>compute-field-energy</code>
is a list of 7 numbers: <code>(<i>U xr xi yr yi zr zi</i>)</code>.
<code><i>U</i></code> is the total, unnormalized energy, which is in
arbitrary units deriving from the normalization of the eigenstate
(e.g. the total energy for H is always 1.0).  <code><i>xr</i></code>
is the fraction of the energy in the real part of the field's x
component, <code><i>xi</i></code> is the fraction in the imaginary
part of the x component, etcetera (<code><i>yr + yi =
y-fraction</i></code>, and so on).

</dl>

<p>Various integrals and other information about the eigenstate can be
accessed by the following functions, useful e.g. for perturbation
theory.  Functions dealing with the field vectors require a field to
be loaded, and functions dealing with the energy density require an
energy density to be loaded via <code>compute-field-energy</code>.

<dl>

<dt><code>(compute-energy-in-dielectric <i>min-eps max-eps</i>)</code>
<dd>Returns the fraction of the energy that resides in dielectrics
with epsilon in the range <code>min-eps</code> to
<code>max-eps</code>.

<p><dt><code>(compute-energy-in-objects <i>objects...</i>)</code>
<dd>Returns the fraction of the energy inside zero or more geometric
objects.

<p><dt><code>(compute-energy-integral <i>f</i>)</code>
<dd><code><i>f</i></code> is a function <code>(<i>f u eps
r</i>)</code> that returns a number given three parameters:
<code><i>u</i></code>, the energy density at a point;
<code><i>eps</i></code>, the dielectric constant at the same point;
and <code><i>r</i></code>, the position vector (in lattice
coordinates) of the point.  <code>compute-energy-integral</code>
returns the integral of <code><i>f</i></code> over the unit cell.
(The integral is computed simply as the sum over the grid points times
the volume of a grid pixel/voxel.)  This can be useful e.g. for
perturbation-theory calculations.

<p><dt><code>(compute-field-integral <i>f</i>)</code>
<dd>Like <code>compute-energy-integral</code>, but
<code><i>f</i></code> is a function <code>(<i>f F eps r</i>)</code>
that returns a number (possibly complex) where <code><i>F</i></code>
is the complex field vector at the given point.

<p><dt><code>(get-epsilon-point <i>r</i>)
<dd>Given a position vector <code><i>r</i></code> (in lattice
coordinates), return the interpolated dielectric constant at that
point.  (Since MPB uses a an effective dielectric tensor internally,
this actually returns the mean dielectric constant.)

<p><dt><code>(get-epsilon-inverse-tensor-point <i>r</i>)
<dd>Given a position vector <code><i>r</i></code> (in lattice
coordinates), return the interpolated inverse dielectric tensor (a 3x3
matrix) at that point.  (Near a dielectric interface, the effective
dielectric constant is a tensor even if you input only scalar
dielectrics; see the <a href="developer.html#epsilon">epsilon
overview</a> for more information.)  The returned matrix may be
complex-Hermetian if you are employing magnetic materials.

<p><dt><code>(get-energy-point <i>r</i>)
<dd>Given a position vector <code><i>r</i></code> (in lattice
coordinates), return the interpolated energy density at that point.

<p><dt><code>(get-field-point <i>r</i>)
<dd>Given a position vector <code><i>r</i></code> (in lattice
coordinates), return the interpolated (complex) field vector at that point.

<p><dt><code>(get-bloch-field-point <i>r</i>)
<dd>Given a position vector <code><i>r</i></code> (in lattice
coordinates), return the interpolated (complex) Bloch field vector at that
point (this is the field without the exp(ikx) envelope).

</dl>

<p>Finally, we have the following functions to output fields (either
the vector fields, the scalar energy density, or epsilon), with the
option of outputting several periods of the lattice.

<dl>

<dt><code>(output-field <i>[ nx [ ny [ nz ] ] ]</i>)</code>
<dt><code>(output-field-x <i>[ nx [ ny [ nz ] ] ]</i>)</code>
<dt><code>(output-field-y <i>[ nx [ ny [ nz ] ] ]</i>)</code>
<dt><code>(output-field-z <i>[ nx [ ny [ nz ] ] ]</i>)</code>
<dd>Output the currently-loaded field.  The optional (as indicated by
the brackets) parameters <code>nx</code>, <code>ny</code>, and
<code>nz</code> indicate the number of periods to be outputted along
each of the three lattice directions.  Omitted parameters are assumed
to be 1.  For vector fields, <code>output-field</code> outputs all of
the components, while the other variants output only one component.

<p><dt><code>(output-epsilon <i>[ nx [ ny [ nz ] ] ]</i>)</code>

<dd>A shortcut for calling <code>get-epsilon</code> followed by
<code>output-field</code>.  Note that, because epsilon is a tensor, a
number of datasets are outputted in <code>"epsilon.h5"</code>:

<ul>
<li><code>"data"</code>: 3/trace(1/epsilon)
<li><code>"epsilon.{xx,xy,xz,yy,yz,zz}"</code>: the components of the
(symmetric) dielectric tensor.
<li><code>"epsilon_inverse.{xx,xy,xz,yy,yz,zz}"</code>: the components of the
(symmetric) inverse dielectric tensor.
</ul>

</dl>

<h3><a name="mult-fields">Storing and combining multiple fields</a></h3>

<p>In order to perform operations involving multiple fields,
e.g. computing the Poynting vector <b>E</b>x<b>H</b>, they must be
stored in field variables.  Field variables come in two flavors,
real-scalar (rscalar) fields, and complex-vector (cvector) fields.
There is a pre-defined field variable <code>cur-field</code>
representing the currently-loaded field (see above), and you can
"clone" it to create more field variables with one of:


<dl>

<dt><code>(field-make <i>f</i>)</code>
<dd>Return a new field variable of the same type and size as the field
variable <code><i>f</i></code>.  Does <em>not</em> copy the field
contents (see <code>field-copy</code> and <code>field-set!</code>,
below).

<p><dt><code>(rscalar-field-make <i>f</i>)</code>
<dt><code>(cvector-field-make <i>f</i>)</code>
<dd>Like <code>field-make</code>, but return a real-scalar or
complex-vector field variable, respectively, of the same size as
<code><i>f</i></code> but ignoring <code><i>f</i></code>'s type.

<p><dt><code>(field-set! <i>fdest fsrc</i>)</code>
<dd>Set <code><i>fdest</i></code> to store the same field values as
<code><i>fsrc</i></code>, which must be of the same size and type.

<p><dt><code>(field-copy <i>f</i>)</code>
<dd>Return a new field variable that is exact copy of
<code><i>f</i></code>; this is equivalent to calling
<code>field-make</code> followed by <code>field-set!</code>.

<p><dt><code>(field-load <i>f</i>)</code>

<dd>Loads the field <code><i>f</i></code> as the current field, at
which point you can use all of the functions in the <a
href="#cur-field">previous section</a> to operate on it or output it.

</dl>

<p>Once you have stored the fields in variables, you probably want to
compute something with them.  This can be done in three ways:
combining fields into new fields with <code>field-map!</code>
(e.g. combine <b>E</b> and <b>H</b> to <b>E</b>x<b>H</b>), integrating
some function of the fields with <code>integrate-fields</code>
(e.g. to compute coupling integrals for perturbation theory), and
getting the field values at arbitrary points with
<code>*-field-get-point</code> (e.g. to do a line or surface integral).
These three functions are described below:

<dl>

<dt><code>(field-map! <i>fdest func [f1 f2 ...]</i>)</code>
<dd>Compute the new field <code><i>fdest</i></code> to be
<code>(<i>func f1-val f2-val ...</i>)</code> at each point in the
grid, where <code><i>f1-val</i></code> etcetera is the corresponding
value of <code><i>f1</i></code> etcetera.  All the fields must be of
the same size, and the argument and return types of
<code><i>func</i></code> must match those of the
<code><i>f1...</i></code> and <code><i>fdest</i></code> fields,
respectively.  <code><i>fdest</i></code> may be the same field as one
of the <code><i>f1...</i></code> arguments.  Note: all fields are
<em>without</em> Bloch phase factors exp(ikx).

<p><dt><code>(integrate-fields <i>func [f1 f2 ...]</i>)</code>
<dd>Compute the integral of the function <code>(<i>func r [f1 f2
...]</i>)</code> over the computational cell, where
<code><i>r</i></code> is the position (in the usual lattice basis) and
<code><i>f1</i></code> etc. are fields (which must all be of the same
size).  (The integral is computed simply as the sum over the grid
points times the volume of a grid pixel/voxel.) Note: all fields are
<em>without</em> Bloch phase factors exp(ikx).  See also the note <a
href="#mult-fields-bloch">below</a>.


<p>
<dt><code>(cvector-field-get-point <i>f r</i>)</code>
<dt><code>(cvector-field-get-point-bloch <i>f r</i>)</code>
<dt><code>(rscalar-field-get-point <i>f r</i>)</code>
<dd>Given a position vector <code><i>r</i></code> (in lattice
coordinates), return the interpolated field cvector/rscalar from
<code><i>f</i></code> at that point.
<code>cvector-field-get-point-bloch</code> returns the field
<em>without</em> the exp(ikx) Bloch wavevector, in analogue to
<code>get-bloch-field-point</code>.

</dl>

<p>You may be wondering how to get rid of the field variables once you
are done with them: you don't, since they are <a
href="http://www.tuxedo.org/~esr/jargon/html/entry/GC.html">garbage
collected</a> automatically.

<p>We also provide functions, in analogue to e.g <code>get-efield</code>
and <code>output-efield</code> above, to "get" various useful
functions as the <a href="#cur-field">current field</a> and to output
them to a file:

<dl>

<dt><code>(get-poynting <i>which-band</i>)</code>
<dd>Loads the Poynting vector
<b>E</b><sup><small>*</small></sup>x<b>H</b> for the band
<code>which-band</code>, the flux density of electromagnetic energy
flow, as the current field.  1/2 of the real part of this vector is the
time-average flux density (which can be combined with the imaginary
part to determine the amplitude and phase of the time-dependent flux).

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

<p><dt><code>(get-tot-pwr <i>which-band</i>)</code>
<dd>Load the time-averaged electromgnetic-field energy density
(|<b>H</b>|<sup><small>2</small></sup> +
epsilon*|<b>E</b>|<sup><small>2</small></sup>) for
<code>which-band</code>.  (If you multiply the real part of the
Poynting vector by a factor of 1/2, above, you should multiply by a
factor of 1/4 here for consistency.)

<p><dt><code>(output-tot-pwr <i>which-band</i>)</code>
<dd>Output the time-averaged electromgnetic-field energy density
(above) for <code>which-band</code>.

</dl>

<p>As an example, below is the Scheme source code for the
<code>get-poynting</code> function, illustrating the use of the
various field functions:

<pre>
(define (get-poynting which-band)
  (get-efield which-band)                      ; put E in cur-field
  (let ((e (field-copy cur-field)))            ; ... and copy to local var.
    (get-hfield which-band)                    ; put H in cur-field
    (field-map! cur-field                      ; write ExH to cur-field
                (lambda (e h) (vector3-cross (vector3-conj e) h))
                e cur-field)
    (cvector-field-nonbloch! cur-field)))      ; see below
</pre>

<h4><a name="mult-fields-bloch">Stored fields and Bloch phases</a></h3>

<p>Complex vector fields like <b>E</b> and <b>H</b> as computed by MPB
are physically of the Bloch form: exp(ikx) times a periodic function.
What MPB actually stores, however, is just the periodic function, the
Bloch envelope, and only multiplies by exp(ikx) for when the fields
are output or passed to the user (e.g. in integration functions).
This is mostly transparent, with a few exceptions noted above for
functions that do not include the exp(ikx) Bloch phase (it is somewhat
faster to operate without including the phase).

<p>On some occasions, however, when you create a field with
<code>field-map!</code>, the resulting field should <em>not</em> have
any Bloch phase.  For example, for the Poynting vector
<b>E</b><sup><small>*</small></sup>x<b>H</b>, the exp(ikx) cancels
because of the complex conjugation.  After creating this sort of
field, we must use the special function
<code>cvector-field-nonbloch!</code> to tell MPB that the field is
purely periodic:

<dl>

<dt><code>(cvector-field-nonbloch! <i>f</i>)</code>
<dd>Specify that the field <code><i>f</i></code> is <em>n