user-ref.html

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

<dd>The size of the lattice (i.e. the length of the lattice vectors
<code>R<sub>i</sub></code>, in which the crystal is periodic) in units
of the basis vectors.  Thus, the actual lengths of the lattice vectors
are given by the components of <code>size</code> multiplied by the
components of <code>basis-size</code>.  (Alternatively, you can think
of <code>size</code> as the vector between opposite corners of the
primitive cell, specified in the lattice basis.)  Defaults to unit
lengths.

<p>If any dimension has the special size <code>no-size</code>, then
the dimensionality of the problem is reduced by one; strictly
speaking, the dielectric function is taken to be uniform along that
dimension.  (In this case, the <code>no-size</code> dimension should
generally be orthogonal to the other dimensions.)
</dl>

</dl>

<h3><a name="material-type">material-type</a></h3>

<p>This class is used to specify the materials that geometric objects
are made of.  Currently, there are three subclasses,
<code>dielectric</code>, <code>dielectric-anisotropic</code>, and
<code>material-function</code>.

<dl>

<dt><code>dielectric</code>
<dd>A uniform, isotropic, linear dielectric material, with one property:
<dl>
<dt><code>epsilon</code> [<code>number</code>]
<dd>The dielectric constant (must be positive).  No default value.  You
can also use <code>(index <i>n</i>)</code> as a synonym for
<code>(epsilon (* <i>n n</i>))</code>.
</dl>

<p><dt><code><a name="dielectric-anisotropic">dielectric-anisotropic</a></code>
<dd>A uniform, possibly anisotropic, linear dielectric material.  For
this material type, you specify the (real-symmetric, or possibly
complex-hermitian) dielectric tensor (relative to the cartesian xyz
axes):
<pre>
             a  u  v
epsilon =  ( u* b  w )
             v* w* c
</pre>
<p>This allows your dielectric to have different dielectric constants
for fields polarized in different directions.  The epsilon tensor must
be positive-definite (have all positive eigenvalues); if it is not,
MPB exits with an error.  (This does <em>not</em> imply that all of
the entries of the epsilon matrix need be positive.)

<p>The components of the tensor are specified via three properties:
<dl>
<dt><code>epsilon-diag</code> [<code>vector3</code>]
<dd>The diagonal elements (a b c) of the dielectric tensor.  No default value.
<dt><code>epsilon-offdiag</code> [<code>cvector3</code>]
<dd>The off-diagonal elements (u v w) of the dielectric tensor.
Defaults to zero.  This is a <code>cvector3</code>, which simply
means that the components may be complex numbers
(e.g. <code>3+0.1i</code>).  If non-zero imaginary parts are
specified, then the dielectric tensor is complex-hermitian.  This is
only supported when MPB is configured with the
<code>--with-hermitian-eps</code> flag.  This is not dissipative (the
eigenvalues of epsilon are real), but rather breaks time-reversal
symmetry, corresponding to a gyrotropic (magneto-optic) material.
Note that <a href="#inv-symmetry">inversion symmetry</a> may not mean
what you expect for complex-hermitian epsilon, so be cautious about
using <code>mpbi</code> in this case.

<dt><code>epsilon-offdiag-imag</code> [<code>vector3</code>]

<dd><em>Deprecated:</em> The imaginary parts of the off-diagonal
elements (u v w) of the dielectric tensor; defaults to zero.  Setting
the imaginary parts directly by specifying complex numbers in
<code>epsilon-offdiag</code> is preferred.
</dl>

<p>For example, a material with a dielectric constant of 3.0 for TE
fields (polarized in the xy plane) and 5.0 for TM fields (polarized in
the z direction) would be specified via <code>(make
(dielectric-anisotropic (epsilon-diag 3 3 5)))</code>.  Please <a
href="#tetm-aniso">be aware</a> that not all 2d anisotropic dielectric
structures will have TE and TM modes, however.

<p><dt><code>material-function</code>
<dd>This material type allows you to specify the material as an
arbitrary function of position.  (For an example of this, see the
<code>bragg-sine.ctl</code> file in the <code>examples/</code>
directory.)  It has one property:
<dl>
<dt><code>material-func</code> [<code>function</code>]
<dd>A function of one argument, the position <code>vector3</code> (in
lattice coordinates), that returns the material at that point.
</dl>
<p>Note that the function you supply can return <em>any</em> material;
wild and crazy users could even return another
<code>material-function</code> object (which would then have its
function invoked in turn).

</dl>

<p>Normally, the dielectric constant is required to be positive (or
positive-definite, for a tensor).  However, MPB does have a somewhat
experimental feature allowing negative dielectrics (e.g. in a plasma).
To use it, call the function <code>(allow-negative-epsilon)</code>
before <code>(run)</code>.  In this case, it will output the (real)
frequency <em>squared</em> in place of the (possibly imaginary)
frequencies.  (Convergence will be somewhat slower because the
eigenoperator is not positive definite.)

<h3><a name="geometric-object">geometric-object</a></h3>

<p>This class, and its descendants, are used to specify the solid
geometric objects that form the dielectric structure being simulated.
The base class is:

<dl>

<dt><code>geometric-object</code>
<dd>Properties:
<dl>
<dt><code>material</code> [<code>material-type</code> class]
<dd>The material that the object is made of (usually some sort of
dielectric).  No default value (must be specified).
<dt><code>center</code> [<code>vector3</code>]
<dd>Center point of the object.  No default value.
</dl>

</dl>

<p>One normally does not create objects of type
<code>geometric-object</code> directly, however; instead, you use one
of the following subclasses.  Recall that subclasses inherit the
properties of their superclass, so these subclasses automatically have
the <code>material</code> and <code>center</code> properties (which
must be specified, since they have no default values).

<p>Recall that all 3-vectors, including the center of an object, its
axes, and so on, are specified in the basis of the normalized lattice
vectors normalized to <code>basis-size</code>.  Note also that
3-vector properties can be specified by either <code>(<i>property</i>
(vector3 <i>x y z</i>))</code> or, equivalently,
<code>(<i>property</i> <i>x y z</i>)</code>.

<p>In a two-dimensional calculation, only the intersections of the
objects with the x-y plane are considered.

<dl>

<dt><code>sphere</code>
<dd>A sphere.  Properties:
<dl>
<dt><code>radius</code> [<code>number</code>]
<dd>Radius of the sphere.  No default value.
</dl>

<p><dt><code>cylinder</code>
<dd>A cylinder, with circular cross-section and finite height.  Properties:
<dl>
<dt><code>radius</code> [<code>number</code>]
<dd>Radius of the cylinder's cross-section.  No default value.
<dt><code>height</code> [<code>number</code>]
<dd>Length of the cylinder along its axis.  No default value.
<dt><code>axis</code> [<code>vector3</code>]
<dd>Direction of the cylinder's axis; the length of this vector is
ignored.  Defaults to point parallel to the z axis.
</dl>

<p><dt><code>cone</code>

<dd>A cone, or possibly a truncated cone.  This is actually a subclass
of <code>cylinder</code>, and inherits all of the same properties,
with one additional property.  The radius of the base of the cone is
given by the <code>radius</code> property inherited from
<code>cylinder</code>, while the radius of the tip is given by the new
property:
<dl>
<dt><code>radius2</code> [<code>number</code>]
<dd>Radius of the tip of the cone (i.e. the end of the cone pointed to
by the <code>axis</code> vector).  Defaults to zero (a "sharp" cone).
</dl>

<p><dt><code>block</code>
<dd>A parallelepiped (i.e., a brick, possibly with non-orthogonal
axes). Properties:
<dl>
<dt><code>size</code> [<code>vector3</code>]
<dd>The lengths of the block edges along each of its three axes.  Not
really a 3-vector (at least, not in the lattice basis), but it has
three components, each of which should be nonzero.  No default value.
<dt><code>e1</code>, <code>e2</code>, <code>e3</code> [<code>vector3</code>]
<dd>The directions of the axes of the block; the lengths of these
vectors are ignored.  Must be linearly independent.  They default to
the three lattice directions.
</dl>

<p><dt><code>ellipsoid</code>
<dd>An ellipsoid.  This is actually a subclass of <code>block</code>,
and inherits all the same properties, but defines an ellipsoid
inscribed inside the block.

</dl>

<p>Here are some examples of geometric objects created using the above
classes, assuming that the lattice directions (the basis) are just the
ordinary unit axes, and <code>m</code> is some material we have
defined:

<pre>
; A cylinder of infinite radius and height 0.25 pointing along the x axis,
; centered at the origin:
(make cylinder (center 0 0 0) (material m) 
               (radius infinity) (height 0.25) (axis 1 0 0))


; An ellipsoid with its long axis pointing along (1,1,1), centered on
; the origin (the other two axes are orthogonal and have equal
; semi-axis lengths):
(make ellipsoid (center 0 0 0) (material m)
                (size 0.8 0.2 0.2)
		(e1 1 1 1)
		(e2 0 1 -1)
		(e3 -2 1 1))

; A unit cube of material m with a spherical air hole of radius 0.2 at
; its center, the whole thing centered at (1,2,3):
(set! geometry (list
		(make block (center 1 2 3) (material m) (size 1 1 1))
		(make sphere (center 1 2 3) (material air) (radius 0.2))))
</pre>

<h2><a name="functions">Functions</a></h2>

<p>Here, we describe the functions that are defined by the
Photonic-Bands package.  There are many types of functions defined,
ranging from utility functions for duplicating geometric objects to
run functions that start the computation.

<p>See also the <a
href="http://ab-initio.mit.edu/libctl/doc/user-ref.html">reference
section</a> of the libctl manual, which describes a number of useful
functions defined by libctl.

<h3><a name="geom-utils">Geometry utilities</a></h3>

<p>Some utility functions are provided to help you manipulate
geometric objects:

<dl>

<dt><code>(shift-geometric-object <i>obj shift-vector</i>)</code>
<dd>Translate <code>obj</code> by the 3-vector <code>shift-vector</code>.

<p><dt><code>(geometric-object-duplicates <i>shift-vector min-multiple max-multiple obj</i>)</code>
<dd>Return a list of duplicates of <code>obj</code>, shifted by
various multiples of <code>shift-vector</code> (from
<code>min-multiple</code> to <code>max-multiple</code>, inclusive, in
steps of 1).

<p><dt><code>(geometric-objects-duplicates <i>shift-vector min-multiple max-multiple obj-list</i>)</code>
<dd>Same as <code>geometric-object-duplicates</code>, except operates
on a list of objects, <code>obj-list</code>.  If <i>A</i> appears
before <i>B</i> in the input list, then all the duplicates of <i>A</i>
appear before all the duplicates of <i>B</i> in the output list.

<p><dt><code>(geometric-objects-lattice-duplicates <i>obj-list [ ux uy uz ]</i>)</code>
<dd>Duplicates the objects in <code>obj-list</code> by multiples of
the lattice basis vectors, making all possible shifts of the
"primitive cell" (see below) that fit inside the lattice cell.  (This
is useful for supercell calculations; see the <a
href="user-tutorial.html">tutorial</a>.)  The primitive cell to
duplicate is <code>ux</code> by <code>uy</code> by <code>uz</code>, in
units of the basis vectors.  These three parameters are optional; any
that you do not specify are assumed to be <code>1</code>.

<p><dt><code>(point-in-object? <i>point obj</i>)</code>
<dd>Returns whether or not the given 3-vector <code>point</code> is
inside the geometric object <code>obj</code>.

<p><dt><code>(point-in-periodic-object? <i>point obj</i>)</code>
<dd>As <code>point-in-object?</code>, but also checks translations of
the given object by the lattice vectors.

<p><dt><code>(display-geometric-object-info <i>indent-by obj</i>)</code>
<dd>Outputs some information about the given <code>obj</code>,
indented by <code>indent-by</code> spaces.

</dl>

<h3><a name="coordconvert">Coordinate conversion functions</a></h3>

<p>The following functions allow you to easily convert back and forth
between the lattice, cartesian, and reciprocal bases.  (See also the
<a href="user-tutorial.html#units">note on units</a> in the tutorial.)

<dl>