IBM Release 1.93 User Manual

?88,.d88b, d8888b d8888b 88bd8b,d88b .d888b,
‘?88’ ?88d8P’ ?88d8b_,dP 88P’‘?8P’?8b ?8b,

88b d8P88b d8888b d88 d88 88P ‘?8b
888888P’‘?8888P’‘?888P’d88’ d88’ 88b‘?888P’

88P’
d88
?8P

A Programmable Optimizing

Electro-Magnetic Simulator

Release 1.93

January 22, 2008

(Updated January 23, 2008)

Phil Hobbs

IBM T. J. Watson Research Center

Yorktown Heights, NY

ii

POEMS:

A Programmable Optimizing

Electro-Magnetic Simulator

Release 1.70

August 21, 2007

Phil Hobbs

IBM T. J. Watson Research Center

Yorktown Heights, NY

iii

Chapter 1.

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1. Motivation (1)

2. HOW POEMS WORKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.1. Program Organization (6); 2.2. The Front-End Script:
poems.cmd (6); 2.3. The FDTD Engine: FIDO/TEMPEST (7); 2.4. The
Postprocessor: EMPOST (7); 2.5. The Visualization System: VIS5D
(8); 2.6. Cluster Control (8)

3. USING POEMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.1. Command Reference (10); 3.2. The Computational Domain
(31); 3.3. OBJECTS (32); 3.4. MATERIALS (33); 3.5. SOURCES (33);

3.6. Optimization (37); 3.7. Predefined Constants (41);

3.8. Predefined Mathematical Functions (43); 3.9. Analytical Pupil
Functions (48); 3.10. Material Parameter Functions (48); A. TEMPEST
and General FDTD Information (49)

Appendix A.: V-Antenna Optimization Run . . . . . . . . . . . . . . 51

A.1. POEMS INPUT: DIPOLE2I.PAR (52); A.2. tempest Input File:
DIPOLE2I.PAR.IN (62); A.3. Postprocessor orders:
DIPOLE2I.ORDERS (65); A.4. Run Results: DIPOLE2I.SIMPLEX
(75)

Appendix B.: Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

B.1. FDTD and TEMPEST (81); B.2. REXX (83); B.3. X Window System
Configuration (83); B.4. Release Notes (84)

iv

Chapter 1.

Introduction

1.1. Motivation

POEMS is a tool for analyzing and synthesizing wavelength-scale electromagnetic devices.

It is similar to existing 3-D vector electromagnetic simulators in many ways; it takes an
input file and produces E and H field values, pictures, and scalar outputs such as energy
flux through surfaces. POEMS can simulate such structures as waveguide tapers and
bends, photonic crystals, antennas, resonators, and couplers. It is competitive in power
and features for such uses, and is also available free to anyone inside IBM.

However, its capabilities go well beyond there. The name POEMS is short for
Programmable Optimizing Electromagnetic Simulator. What makes POEMS special are three
attributes:

1. Its technological orientation. You can calculate the total power dissipated in a
resonator, compute the efficiencies of Gaussian and Airy beams in driving a waveguide
horn, plot the far-field pattern of a scatterer, or give a grating a half-wave of spherical
aberration, in one or two source lines each. The simulation output can be displayed and
explored using VIS5D, an advanced interactive visualization program that comes with the

POEMS distribution. The simulation geometry can be exported as a CATS .ctxt or Autocad

.DXF file for import into mask design or mechanical CAD packages.

2. Its readability. The previous point makes POEMS sound like APL or Perl, but it isn’t at
all. People can easily read and understand one another’s POEMS files (or their own from
six months ago). Function parameters can be symbols or mathematical expressions, and
are passed in the form of assignments, e.g. phase = pi/6 or width = sqrt(area) rather
than as long lists of floating-point numbers that all have to be in the right order.
Parametrized macros can be used to reduce the amount of repeated code for similar
operations. The effect is to make POEMS more like a math program and less like a
simulator.

3. Its power and generality. It is one thing to analyze the performance of a design once
it is finished, and quite another to synthesize a good design for a particular purpose.

POEMS is an optimizing simulator. Given suitable starting points, it will automatically

adjust any parameters you specify to optimize any criterion you give it. The parameters
and merit functions are completely user-specified—many properties of the device may
depend on each parameter, if desired. For example, you can optimize the shape of an
antenna to maximize the power dissipated in the load resistance, for plane wave
illumination, or optimize the aberration coefficients of a grating to improve a free-space to
waveguide transition. There are lots of programs to analyze given structures.

1

Of course, there is one very good reason why such a capability has not been available
before: it can be quite slow. One simulation can take minutes or hours to run, so an
optimization requiring many runs may take quite a while. While this is still a cogent
objection in many cases, POEMS’ ability to scale to large clusters can make this pretty
snappy. Even without a cluster, the continued improvements in personal computer CPU
speed and memory size allow nontrivial multi-parameter optimizations to be run on a
laptop in a few hours, with little or no supervision. Given the economic importance of
many of these devices, e.g phase shift masks and optical waveguide devices, there is now
a large class of problems for which an optimizing FDTD simulator is a useful tool. This
is particularly true when the simulator can run seamlessly on one machine or a large
cluster of machines of different types and architectures, as POEMS can.

Furthermore, the same techniques designers use to guide existing simulators, e.g. physical
and analytical models, can be used with POEMS, with an order-of-magnitude decrease in
the amount of time spent baby-sitting the simulator.

The current release of POEMS, V 1.63, does almost all of these things already, and more
are under development.

1.1.1. Philosophy

The idea of POEMS is to keep the design problem in view, and to make the program fade
into the background. This doesn’t need fancy user interfaces so much as freedom from
limitations and constant manual-reading. This philosophy drove the design, leading to
these goals:

Clarity:

Power:

-Accept human-readable input with no unnecessary parameter order
dependencies;

-Use mnemonic names;

-Provide accurate and specific error messages

-Understand optical terms, e.g. amplitude and phase, aberration coefficients,
power dissipation, efficiency, mode matching with commonly used pupil
functions e.g. Gaussian and Airy (uniform pupil);

-Provide high-level geometric constructs, e.g. gratings and smooth curved
tapers and bends;

-Specify dimensions the way you’d measure with calipers—round correctly
and avoid worries about counting from 0 or from 1;

-Automate fiddly things that go wrong easily, e.g. configuring the perfectly­matched layer (PML) absorption directions or figuring out n and k for a
normal conductor

-Use the best existing open-source software, e.g. FFTW and VIS5D

-Work on many platforms, at least Linux, OS/2, and Windows (The author is
an OS/2 diehard but recognizes the quixotic character of this)

-Provide advanced visualization tools: bitmaps, animations, and (especially) 3-

2

dimensional visualization via VIS5D

-Be free for anyone inside IBM to use

and, most importantly,

-Provide a powerful way to optimize structures for a given purpose, e.g.
couplers, masks, antennas, and so forth.

To avoid wasted effort, as much as possible of the information generated by the
simulation needs to be kept for further use and for sanity checks along the way. It
should also be possible to stop an optimization run in the middle and restart it without
losing the previous results, using the RESTART command line option (see Section 3.1.1).
The current release of POEMS does all of these things.

1.1.2. Structure

POEMS consists of a front-end script that handles all the housekeeping, optimization, and

interface duties, a simulation engine, a postprocessor to turn raw values of E and H into
useful output, and a visualization system based on VIS5D. The simulation engines are
currently TEMPEST, a finite-difference time-domain (FDTD) simulation code developed by
Alfred Wong and Tom Pistor at the University of California at Berkeley, whose single­processor form is widely available in C source; and FIDO, a plug-compatible program
written from scratch. FIDO accepts the subset of the TEMPEST input file format used by

POEMS, with some extensions, so that single-processor simulation can be run on both, and

the results compared. FIDO is a significantly more advanced design than TEMPEST, since it
precomputes a strategy for the computation instead of just putting a huge switch
statement inside a triply-nested for() loop. In addition, it is multithreaded, which allows
efficient utilization of symmetric multiprocessor (SMP) machines without additional user
effort. On a dual-processor 2.8 GHz Xeon machine running Windows XP, FIDO is about

2.5x faster than TEMPEST on a typical problem--2x for two CPUs, and 25% faster on a per­CPU basis. With this release, FIDO can now run on clusters of Linux, Windows, or OS/2
clusters connected over a TCP/IP network. There is some performance penalty for this,
mainly due to communications latency, but for simulations large enough that each time
step takes at least 0.5 second, the scaling is excellent.

The user interacts with the front-end script via a high-level input file. Commands in the
input file are parsed in the order written. For example, you can’t use a variable at a
point above its definition in the file.

1.1.3. Optimization

The POEMS optimizer is currently a vanilla Nelder-Mead downhill simplex algorithm,
similar to the Numerical Recipes AMOEBA routine. (A simplex is an N-dimensional figure
with N+1 vertices--examples are triangles and tetrahedrons.) Nelder-Mead stays out of
trouble pretty well in optimizing continuous functions, unless the simplex gets
pathologically long and skinny, in which case it complains. Most of the time, though,
we’re optimizing simulation geometry, i.e. which block gets which material. Object
dimensions come only in integer multiples of the local cell size, so rounding occurs before
the object is generated. Changing the requested size has no effect whatever until it

3

crosses the centre line of a cell, causing a discontinuous change in the actual object size,
and hence in the simulation results. On small scales, therefore, the partial derivatives of
any penalty function will be zero in most places, with delta-functions sprinkled round,
and the penalty function surfaces exhibit multidimensional cliffs and canyons. This is
why we’re not using one of those fancy variable metric optimizers. POEMS has no way of
exploring the bottom of a canyon it never encounters, so for simulations with significant
economic importance, it’s worth restarting the simulator a few times using the RESTARTS
parameter of the COMPUTE statement. (For more discussion, see e.g. W. H. Press et al,
Numerical Recipes in C, 2ndEd., Cambridge (UK), Cambridge University Press, 1991.

4

Front-End Script
POEMS.CMD

POEMS
Parameters
File

foo.par

FIDO
Input File

foo.par.in

FDTD Engine:

FIDO + CLUSTER SCRIPT

FIDO
Log File

foo.par.err

FIDO

Output File

foo.par.out

FIDO

Field Files

POSTPROC
Orders File

foo.orders

Postprocessor:

EMPOST.EXE

POSTPROC

RESULTS

foo.results

Optimization Loop

Image
Files

Bitmap
Image
Files

CAD
Export Utility

CAD File

Vis5D

Visualization Files

Vis5D.EXE

Visualization

System

or TEMPEST

Figure 2.1: POEMS system organization

5

2. HOW POEMS WORKS

2.1. Program Organization

The POEMS system consists of six parts: the front-end script (poems.cmd), which controls
the whole process, communicating with the user, doing the less CPU-intensive tasks (such
as CAD file generation) and controlling the rest; the FDTD simulation engine (FIDO or

TEMPEST), which takes a simulation description file and produces binary files of simulated

E and H field values; the postprocessor (EMPOST), which takes those huge binary files and
produces secondary binary data and pictures, including VIS5D interactive visualizations;
Vis5D itself, an open-source data visualization program running under the X Window
system; and, optionally, a cluster control script (fidossh) that distributes parameters,
starts the simulator instances, and collects data afterwards. We’ll examine these in turn.

2.2. The Front-End Script: poems.cmd

The front end script poems.cmd is the part of POEMS that the user will interact with
(almost exclusively). It parses the input file, performs error checking, and handles all the
symbols and equations. It generates the intermediate files that are used as input by

FIDO/TEMPEST and EMPOST, and produces log files and console output to keep the user

informed as to the progress of the run. The script is written in REXX, whose advanced
parsing capabilities and very flexible stem processing made it a natural choice. Speed is
not a serious issue, since only a tiny part of the run time is spent in the REXX code;
almost all is used in the FDTD simulation.

2.2.1. Script Operation

The concept underlying the script’s design is that the user should be able to optimize or
step anything he likes, in any combination. Therefore, user-defined functions,
expressions, and variables are accepted anywhere an argument is required; as in a math
program, these variables and functions can depend on each other in any fashion
consistent with top-to-bottom parsing of the input file. This is straightforward in a single
simulation run, but is a little more involved where stepping and optimization is being
used: the program cannot make any assumptions about which simulation parameters can
depend on the controlling variables. Accordingly, an optimization or stepping run is
organized as follows.

a. Enter SETUP mode
b. Parse the input file and set all the variables. Note which variables are to be stepped

or optimized (the controlling variables).
c. Enter OPTIMIZE or STEP mode. For each iteration,
(i)Update the controlling variables for the current iteration
(ii) Parse the input file, setting all the variables except the controlling ones. This
preserves all the dependencies.
(iii) Generate the intermediate files for FIDO/TEMPEST and EMPOST, based on the current
values of all the variables.
(iv)Run FIDO/TEMPEST, capturing its console output to a file.
(v)If FIDO/TEMPEST fails, stop. If it succeeds, call EMPOST to generate the inputs to the

6

merit function, plus any binary file, list, or slice bitmaps requested. Doing this on each
iteration takes little time and helps in supervising the run’s progress.
(vi)Based on the computed merit function, update the optimization simplex. If
convergence has occurred, exit. Otherwise, compute new values of the controlling
variables for the next iteration and keep iterating. If the current point is the best so far,
save all the bitmap, list, and mode files under another name.

Of course, in order for this to do anything useful, you have to specify a merit function (or
penalty function for pessimists) that depends on the simulation output.

2.3. The FDTD Engine: FIDO/TEMPEST

POEMS started out life using TEMPEST as its main component. TEMPEST is a more or less

vanilla single-processor FDTD engine, written originally for simulation of phase-shift
masks, but quite widely used for a variety of applications. It is described in its own
documents, which accompany the POEMS distribution. Due to the limitations of TEMPEST,
in particular its lack of subgridding and multiprocessor capabilities, POEMS now relies
principally on a specially written FDTD engine called FIDO, for FInite difference time
DOmain. In broad outline, each of these programs parses an input file containing
human-readable, hard-coded specifications of the simulation domain, boundaries,
materials, objects, sources, and binary output files; constructs and runs a FDTD
simulation as specified, stopping when the specified degree of convergence has been
attained or the maximum cycles exceeded, and producing large binary files full of E and
H values. TEMPEST comes with Matlab scripts to plot these simulated fields and do
simple manipulations on them. Section A.2 has an example of a FIDO/TEMPEST input file
generated by poems.cmd.

TEMPEST also has some more advanced capabilities, e.g. Fourier boundary conditions, far-

field computation (via the orders output command), and more complicated source
shapes, that POEMS ignores in favour of its own more general versions. This was done for
reasons of usability and to avoid being tied too tightly to one particular simulator engine.
One additional (and most important) attribute of TEMPEST is that it is well validated.
Besides having been tested on problems whose analytical solution is known, it has done a
good job for lots of people over several years. For this reason, FIDO was written to be a
plug-compatible superset of TEMPEST: it takes the same input files, and can do the same
simulations, but FIDO is about 50% faster on a per-processor basis and can do subgridded
and clusterized simulations as well. Thus in new situations we can test our simulations
using TEMPEST and then refine them using FIDO.

2.4. The Postprocessor: EMPOST

Large binary files full of E and H values are not very useful by themselves. The tool set
provided by POEMS requires a lot of CPU-intensive calculations and binary manipulations
that are much better done in C++ than in REXX. Accordingly, POEMS uses a
postprocessor written in C++ to do most of its numerical work. EMPOST takes a human­readable but quite rigidly formatted orders file that specifies what is to be done on what
data. An example is shown in Section A.3.

It is occasionally useful to run the postprocessor manually, e.g. when we want to change

7

from a linear to a logarithmic scale, change a colour palette, or something like that;
simple changes like that are easily made directly to the generated file. EMPOST’s calling
syntax is

empost orders_file results_file

The second argument is the name of a file that EMPOST produces, containing numerical
results of the named orders, e.g. integrals, fluxes, mode matching coefficients, and so on.
These are in the form of assignment statements, and are parsed by POEMS when
postprocessing is completed. POEMS then uses these to compute the value of the penalty
function for the current iteration.

2.5. The Visualization System: VIS5D

VIS5D is an advanced visualization program originally written for meteorological data. It
runs under the X Window System, which is native to Linux and other Unix derivatives,
but which has to be added to Windows and OS/2. Windows users can install
Hummingbird Exceed, which works well with VIS5D once all the arcane X parameters are
set up. See Appendix B for a working sample X configuration.

The Vis5D conversion code in empost is based on a stand-alone program by Theodore G.
van Kessel. In this release, it is fully integrated into EMPOST. Both animated and static
Vis5D files are generated using the MOVIE3D statement.

2.6. Cluster Control

There are lots of ways to structure a cluster, lots of communications styles (such as the
Message Passing Interface (MPI), and lots of cluster management systems such as the Sun
Grid Engine (SGE). POEMS is not tied to any of these, but is easily adapted to them. The
main script runs on a frontend machine. Inter-host communication requires no specific
support other than a high capacity, low latency TCP/IP network. FIDO uses TCP/IP
socket communication between fido subdomains running on different hosts, and local
communication between subdomains running on the same host. To allow the user
control, cluster control is not hardcoded into POEMS, but relies on an external script. The
supplied script is fidossh, which uses a shared file system (e.g. NFS, XFS, or PVFS2) for
communication and ssh for cluster node control, This design is suitable for clusters of up
to perhaps 20 nodes, depending on filesystem performance. The high bandwidth host-to­host communication is organized in a distributed fashion between cluster hosts, so the
frontend machine does not become a bottleneck in small and medium sized clusters. For
larger clusters, FIDO can use a hierarchical supervision scheme, where a single frontend
node is not forced to supervise hundreds or thousands of hosts, but the cluster script
would have to be tailored for the application.

The downside of this flexibility is that the user has to apportion the work manually.
Future versions of POEMS will help automate this, based on the CPU speed, number of
cores, and amount of memory possessed by each host. Probably it will remain
semiautomatic unless the subdomains can be made very small.

8

2.6.1. Parallel Processing

[Under construction]

FIDO is a powerful and versatile simulation engine, which can compute simulations using

inhomogeneous cubic grids on uniprocessors, symmetric multiprocessors (SMPs), and
clusters tied together with TCP/IP. From the POEMS user’s point of view, SMPs act just
like uniprocessors, except that an N-way SMP needs its work divided up into at least N
chunks, and the load balancing is manual--usually it’s easy. This section discusses
multiprocessor operations; technical details are in Appendix C.

9

3. USING POEMS

Everything in POEMS is case-insensitive. Case is preserved but not significant in file
names; specifying two names equal except for case will cause the first to be overwritten
in Windows and OS/2 but not in Linux.

3.1. Command Reference

3.1.1. poems Command-Line Options

The calling syntax for POEMS is

poems parmfile <- option1 <option2 <option3>>>

where the options are one of DEBUG VERBOSE and RESTART.
DEBUG prints lots of debugging information,
VERBOSE prints more detail in the ordinary console output, and
RESTART causes POEMS to parse the specified simplex file and
restart the optimization run following the last completed iteration."

3.1.2. GLOBAL Group

ASSERT Syntax: ASSERT <expression>

Allows the user to add parameter error checking to the simulations.
ASSERT functions very much like the assert() macro in C. Each
time the input file is parsed (i.e. at the beginning of the run and
before each iteration of the optimizer or stepper), <expression> is
evaluated. If the result is zero, the run is stopped and a specific
error message printed.

Example: ASSERT SourceZ ≤ Zsize-Tpml-lambda

COMMENT Syntax: COMMENT anything you want to say

Specifies a string that is to be included in all text and HTML output
files. Useful for identifying information. You can use as many of
these as you like. The output files will be more readable if you
keep the total line length reasonable, e.g. 75 columns.
Comment lines treat trailing commas as punctuation, not line
continuation characters, so multi-line comments must be coded as a
separate COMMENT statement for each comment line.

DEBUG Syntax: DEBUG on|off

Output lots of debugging information as the run proceeds. Useful
mostly for the developer.

10

FREQ Syntax: FREQ <frequency in Hz>
LAMBDA Syntax: LAMBDA <wavelength in metres>

Specify the frequency or free-space wavelength of the excitation
sources (all will be the same). FREQ is an alternative to
LAMBDA—use one or the other, but not both.

Examples:

FREQ 200*THz
FREQ c/(1.464*700*nm) /* 700 nm in fused SiO2*/
LAMBDA 1.55*micron /* Communication wavelength */
LAMBDA 6.328e-7 /* He-Ne laser */

FUNCTION Define a user math function. User functions can be anything REXX

can evaluate, plus elementary functions (sin, cos, tan, asin, acos,
atan, atan2, exp, ln), Bessel functions of the first kind of integer
order (Jn(x)), complete elliptic integrals, and a few other odds and
ends. Once defined, a user function can be used freely in
expressions anywhere a literal number or a variable could.
Functions may be defined in terms of variables, literals, or other
functions, subject to the file parsing rules. When optimization is
enabled, functions whose output values depend on variables being
optimized over will have their definitions updated on each iteration
to reflect the new values of these variables.

If the name of a formal parameter of the function is the same as
that of a user variable, the formal parameter will override the user
variable inside the function. Otherwise, any variables used by the
function will be taken from the global scope. This allows functions
to be parameterized by other variables, e.g. scale factors or offsets,
which are not in the formal parameter list.

Syntax:

FUNCTION name(arg1, arg2,..., argN) = <expression>

Examples:

FUNCTION myfunc(a,x,q)=exp(a)*atan(q/x)*sqrt(23+q)
FUNCTION parab(x,y,focus)=(x*x+y*y)/(4*focus)
FUNCTION cone(x,y)=sqrt(parab(x,y,1)

HOSTS Specifies a file containing TCP/IP information on the hosts available

to run the current simulation.

Syntax: HOSTS <hostfile>

where entries in the given file are of the form

11

/* <optional_comment>
<IP> <name> <port> <CPUs> <speed> <RAM MB> <Arch> <OS>
e.g. for a Thinkpad T23 laptop,

/* Kukla--1.13 GHz PIII

127.0.0.1 localhost 1066 1 1.0 768 X86 OS/2 4.5

The port number is used for FIDO supervisory control, i.e. if this
host is supervising N other hosts, those N connect to the supervisor
using this port number. This port can be anything that doesn’t
conflict with another service on the same cluster, but the unofficial
"well-known" port for POEMS is 1066. All hosts can use the same
port number.

NB: Hosts are identified by their hostname (as specified by the
$HOSTNAME environment variable, rather than by IP address. This
makes it possible to test cluster simulations on a single host by adding
multiple names for the same host in the hostfile, and specifying different
aliases in different SUBDOMAIN statements in the parameters file.
Cluster script fidossl sets the HOSTNAME variable for each fido instance,
which means that the host’s predefined hostname is not used.

MACDEF Define a user macro. Macros are parametrized groups of POEMS

statements, as opposed to functions, which compute numeric values.
Macros are defined and expanded much like C preprocessor macros,
except for the MACDEF and MACRO keywords. A macro
definition must consist of a single logical line (i.e. if it spans more
than one line in the source file, line continuation characters must be
used to concatenate them into one logical line). Semicolons must be
used to separate individual POEMS statements within the logical line.
Both numeric and string values can be passed as macro parameters.
Macros do not have local variables other than their pass parameters-

-other symbolic names will have their normal meaning from the
local context at the time of macro expansion. Macro parameter
names are dummy variables and will not collide with variables of
the same name in the local context--context variables with the same
name as the dummy will be inaccessible.

12

Macros are allowed to contain macros, i.e. the MACRO statement is
permitted inside a MACDEF. (This is a powerful and dangerous
feature.) Macro recursion is not supported. NB: Since POEMS
comments always extend to the end of the current line, any
comments inside a macro definition must be at the end of a lexical
line, following the line continuation character, as shown below.

Syntax: MACDEF name(arg1, ..., argN) <logical line of code>

Example: This macro plots field files over a fixed volume, with a

given name and field component. The parameters xsize, ysize, zsize
are not macro parameters, but will be supplied from the current
context when the macro is expanded. Note the string concatenation
used to generate the file names.

MACDEF FieldAll(kwd, fname)), /* Make I and Q field files

/* with appropriate file names and symbolic limits
FIELD variable=kwd xlo=0 xhi=xmax ylo=0 yhi=ymax ,
zlo=0 zhi=zsize phase=0.0 state=steady file=fname’i’; ,
FIELD variable=kwd xlo=0 xhi=xsize ylo=0 yhi=ysize ,
zlo=0 zhi=zsize phase=2*atan(1) state=steady /* etc
file=fname’q’;

MACRO Expand a user macro. Unlike MACDEF, which must be in the

GLOBAL group, MACRO can be used anywhere. Macro expansion
is typographical, like C macros. String concatenation is performed,
as shown in the previous example.

Syntax: MACRO name(arg1, ..., argN);

Example: Using the example from the MACDEF statement,

MACRO FieldAll(Ex, Ant01Ex);

is equivalent to

FIELD variable=Ex xlo=0 xhi=xsize ylo=0 yhi=ysize ,
zlo=0 zhi=zsize phase=0.0 state=steady file=Ant01Exi;,
FIELD variable=Ex xlo=0 xhi=xsize ylo=0 yhi=ysize ,
zlo=0 zhi=zsize phase=2*atan(1) state=steady ,
file=Ant01Exq;

POSTPROCESSOR Tell POEMS which postprocessor executable to use (currently the

only choice available is empost).

Syntax: POSTPROCESSOR <postprocessor command line>

PRINT Print output, similar to the REXX SAY statement. Any number of

arguments may be supplied, and strings and expressions may occur
in any order. Strings inside double quotes will be printed as is,
whereas expressions will be evaluated first. PRINT statements are
executed each time the input file is parsed, i.e. at the beginning of
the run and before each tempest iteration.

13

Syntax: PRINT <"string"> <expression> ....

RANDOMSEED Supply a seed to the pseudorandom number generator.

Pseudorandom numbers are used only to choose starting points for
the optimizer. The points visited by the optimizer for a given
problem can be changed by choosing a different seed.

Syntax: RANDOMSEED <expression>

The value of <expression> must be in [0, 999,999,999], and its value
is rounded to an integer before use. Thus values must round to
different integers for them to be distinct for this purpose.

Example: RANDOMSEED 314159265

SET Defines a variable and sets its initial value. The expression may

contain literals, arithmetic and logical operators, predefined
functions, and user functions.

Syntax: SET name = <expression>

Example: set hypot=sqrt(a*a+b*b)

SIMULATOR Give POEMS a simulator command line to use (no default). For

single-host simulations, this is just the simulator executable, but for
clusters, it should consist of a command processor, script name, and
any additional variables expected by the cluster script. To make
this easier, POEMS defines two special variables, as follows.

Name Expands To
$h Name of a file containing a list of all hosts actually used in

the simulation, one host per line

$f Name of a file containing a list of all files that need to be

distributed to the compute hosts for the current simulation.

POEMS constructs the command line by appending an at-sign (@)

and the name of a file containing the input parameters expected by

FIDO, then passes the resulting command line to the current shell.

The script blocks until the simulation returns.

Syntax: SIMULATOR <filename> [ <special variable> [<special
variable> ]]

14

Example: SIMULATOR /usr/local/tempest/tempest

SIMULATOR rexx d:\poems\fido\fidossh.cmd $h $f

TITLE Give a title to the run. This title is printed in each file, and is also

used to generate names for the intermediate file and log file, and for
the postprocessor orders file. No default.

Syntax: TITLE Waveguide3a

VERBOSE Turn on verbose output. Sometimes helpful in figuring out what’s

going on. It’s sufficiently verbose that it’s probably best to redirect
it to a file or a pager program such as less.

Syntax: VERBOSE on | off

3.1.3. WORLD Group

BOUNDARY Sets boundary conditions for a given axis to be either periodic

(PERIODIC) or mirror-symmetrical (SYMMETRY). Only one need
be set for each axis; if both are specified, they must be the same,
since symmetry applies at both sides in FIDO/TEMPEST. (Deprecated
boundary type ILLUM is the same as PERIODIC, and is provided
for backward compatibility with earlier versions of POEMS.)

Parameters: xmin xmax ymin ymax zmin zmax
Syntax: BOUNDARY <parameter> PERIODIC | SYMMETRY

SUBDOMAIN Defines a simulation domain. A domain is the portion of the

computational world assigned to one thread. Since the current
version of tempest runs on a single processor, all domains will be
joined together into one big tempest run. FIDO supports multithread
simulations, so you don’t lose anything by putting them in.
Parameter domain_name must not contain whitespace. For multiple­host simulations, the SUBDOMAIN keyword takes an optional
hostname and base port number, indicating which host this
subdomain is to run on, and the name of a supervisor host whose
fido instance will control that host. If these parameters are not
supplied, the given subdomain runs on the local host. (The
supervisor parameter should not be supplied for the host in overall
control.) All subdomains running on a given machine must specify
the same supervisor, or a runtime error will result. Each

15

subdomain uses 6 sockets, attached to port, port+1,..., port+5, all of
which must be unique on the given host, though there is nothing to
stop different hosts from using the same port numbers. Port
numbers must be between 0 and 65535, and it is usually best to use
numbers greater than 16384.

Syntax:
SUBDOMAIN <domain_name> [host=<host> port=<port> ,

super=<super>]

BASICSTEP Specify the size of the cubical cells that make up the current

subdomain. SI units are suggested, because the scaling between E
and H used internally assumes SI units.
From POEMS’s point of view, this number isn’t necessarily set in
stone: the step size, time step, and domain size can all be controlled
by the optimizer or the stepper if desired. For future use, keywords
XBASICSTEP, YBASICSTEP, and ZBASICSTEP are also allowed, but
since in this release the cells must be cubical, only one of the four
may be specified.

Syntax: BASICSTEP <expression>

Examples: BASICSTEP lambda/20.5

BASICSTEP 0.1*micron

XRANGE
YRANGE
ZRANGE Sets the X, Y, or Z limits of the current domain. The parameters

must obey max_expression > min_expression ≥ 0.0.

Syntax: XRANGE <min_expression> <max_expression>

3.1.4. MATERIAL Group

DEFINE Defines the parameters of a material to POEMS.

Parameters: matname type epsReal epsImag muReal muImag n k
conductivity
Types: dielectric metal PML conductor PEC black magnetic

Type dielectric

Ordinary nonmagnetic material, with n ≥ k. Most optical

16

materials are of this type: vacuum, air, glass, and plastics.

Parameters: n, k (real and imaginary refractive index)
Example:

DEFINE matname= BlackGlass type=dielectric n=1.52 k=1e-3

Type metal

Nonmagnetic dispersive material which may have negative
dielectric constant at the frequency of interest, which is
equivalent to having n < k, e.g. metals in the infrared. Other
conductive materials can be modelled as conductor type.
There are two ways of specifying a metal: using the n and k
values at the centre wavelength of the sources, or using a file
produced FITMAT, which fits Debye and Lorentz poles to
user-supplied n,k data.

Parameters: n, k , file
Example:

DEFINE matname= Gold3_1um type=metal n=0.3 k=11.23
DEFINE matname= Nickel type=metal file=nickel.poles

Type conductor

Normal conductor, with ε = ε0+jσ/ω Useful for metal

waveguide boundaries, at frequencies where the normal
conduction model applies (below about 1 THz). In optical
simulations, ordinary conductors are primarily useful in
simulating loads.

Parameters: conductivity (in units of (Ωm)-1)

Example:

DEFINE matname=copper type=conductor conductivity=5.8e7

Type magnetic

Magnetic material, whose properties are specified by

complex µ and ε, specified in SI units, not the relative µ and
ε.

Parameters: epsReal epsImag muReal muImag

Example:

DEFINE name=ferrite type=magnetic epsReal=18,

epsImag=0 muReal=220 muImag=1.1

17

Type PEC
Type black

Perfect conductor. All fields inside a PEC are zero.
Sometimes useful for saving CPU cycles in regions where the
fields are known to be zero, e.g. deep inside metal objects.

Parameters: none

3.1.5. OBJECT Group

Like all dimensions in POEMS, object dimensions are measured from edge to edge, as you
would measure with calipers. All dimensions are correctly rounded to the nearest
multiple of basicstep in the subdomain in which they occur. A cell is included if its centre
lies inside the specified region. This can lead to steps at boundaries between
subdomains with different basicstep values, due to differences in rounding.

When an object’s midline is specified in terms of a curve, e.g. FAN, GRATING, CURVE,
and 3DCURVE, the end points of the curve are taken to lie at the centre of the outermost
plane of blocks on each end. This makes sure that if the local object axis is highly
inclined, the outermost blocks don’t disappear due to their centres falling outside the
region, as they would if the endpoint were taken to lie in the outer face. Sufficiently
inclined objects may still become discontinuous.

BLOCK Adds a rectangular prism (like a shoe box) of material matname,

covering the region xlo ≤ x ≤ xhi, ylo ≤ y ≤ yhi, zlo ≤ z ≤ zhi. Like

everything else in POEMS, these dimensions will be rounded to the
nearest cell boundaries.

Parameters: matname xlo xhi ylo yhi zlo zhi
Example:

block matname = AirPML xlo=0 xhi=8*dx ylo = 0 yhi=ymax ,

FAN Adds a fan shaped object such as a dielectric waveguide horn or

taper. A fan is specified by a choice of curve and rectangular end
faces 1 and 2, defined by their diagonal points ((xlo1,ylo1,zlo1),
(xhi1,yhi1,zhi1)) and ((xlo2,ylo2,zlo2), (xhi2,yhi2,zhi2)). These must be
parallel and lie in a coordinate plane. Intervening planes are
defined by the choice of taper and the taper parameter, which is a
scale factor for the domain of the curve—increasing the parameter
causes the taper to be sharper, and decreasing it makes the taper
more gradual. Allowed tapers are LINEAR, EXPONENTIAL, and
ERF. Exponential tapers are useful for converting guided waves to
free space, and ERF tapers are useful for converting between
different-sized waveguides without strong back reflections from
either end.

zlo=0 zhi=zmax

18

If the two end faces are the same size and shape, all the curve
shapes are equivalent. The end faces can be offset laterally, so that
a fan statement can build a diagonal line.

Parameters: matname taper taperpar xlo1 xhi1 ylo1 yhi1 zlo1 zhi1 xlo2

xhi2 ylo2 yhi2 zlo2 zhi2

GRATING Adds a planar grating with lines of rectangular cross-section. The

line width and phase of the grating are arbitrary, and specified with
user functions of the coordinate variables. Thus the grating can
have its properties altered in a very general way during
optimization, e.g. having its Seidel aberration coefficients controlled
to optimize a coupling efficiency. Gratings are implemented by
evaluating phasefunc at a grid of points in the plane, and
constructing a phase contour map. Each grating line is generated

by following the contours at integral multiples of 2π, and centring a

rectangular block of total width defined by widthfunc on the contour
line, so that the grating’s diffractive strength is also a function of
position. Making the width too large or too small will result in the
spaces or lines disappearing, which is one way of making a grating
with a non-rectangular boundary. The default spacing between
phase points is two cells, but this can cause the script to run very
slowly, so it can be overridden with the optional parameter interval.
The interval parameter determines the grid on which the phase and
width functions are sampled, which influences the accuracy of the
contour maps and hence the grating placement.

Parameters: matname orientation xlo xhi ylo yhi zlo zhi widthfunc

phasefunc [interval]

HOLLOWBOX Adds a hollow box (rectangular shell) of specified outer dimensions

and thickness. It is implemented by dividing up the rectangular
box into 26 smaller blocks: 6 for the faces, 12 for the edges, and 8
for the corners. This primitive is especially useful for using PMLs
to isolate a region from its surroundings. When used with PMLs,
the outer dimensions must be the same as those of the simulation
domain. The PML absorption directions will be the outward
normals for the flat faces, outward-directed face diagonals for the
edges, and outward-directed body diagonals for the corners.

Parameters: mattype xlo xhi ylo yhi zlo zhi thickness

TILEDPLANE Adds a tiled plane (thick rectangular sheet) of specified outer

dimensions. It is implemented by dividing up the rectangular sheet
into 9 smaller blocks: 1 for the face, 4 for the edges, and 4 for the

19

corners. This primitive is especially useful with plane wave
illumination, where we want PMLs only on the front and back faces
of the region. The wide face of the object must touch one of the
faces of the simulation domain. The PML absorption directions will
be the outward normals for the face, outward-directed face
diagonals for the edges, and outward-directed body diagonals for
the corners. If for some reason you call this with an ordinary
material, it just adds a regular block.

Parameters: mattype xlo xhi ylo yhi zlo zhi

CURVE Adds a curved object whose path is expressed by a user-defined

planar curve, (u(s), v(s)), and whose outline is swept out by the
region f(q,r) > 0 as the parameter s advances from slo to shi.
Variable q is the normal to the plane, and r is parallel to q × (du/ds,
dv/ds). This statement can be used to make very general curved
objects of variable cross-section. Due to the uniform rectangular
grid employed by FIDO/TEMPEST, curved objects will look somewhat
different depending on the direction of their axes at any given
place. POEMS attempts to minimize this effect.

Parameters: mattype slo shi perp hfunc vfunc

Not implemented in this release.

3DCURVE Like CURVE, but the axial curve is allowed to be nonplanar. This

statement is more complicated to use, due to the noncommuting
property of 3-D rotations—in specifying the functions u, v, w, it’s
easy to get mixed up by the way they rotate around.

Parameters:

Not implemented in this release.

CYLINDER Adds an object whose axis is a straight line, but whose outline is an

arbitrary function of the perpendicular coordinate.

Parameters: mattype axis lo hi maxradius insidefunc

Not implemented in this release.

20

3.1.6. SOURCE Group

GAUSSIAN Produces a TEM00 Gaussian beam, centred at (x, y, z), with 1/e

2

diameter width, whose axis is specified by the vector(kx, ky, kz),
which can have any length. The E field is linearly polarized, with
components (mag*Ex, mag*Ey, mag*Ez). Circular or elliptical
polarizations can be synthesized by using two with different phases.
In this release, orientation must be XY, because tempest can’t handle
plane waves whose source locus isn’t perpendicular to z. Also in
this release, the focus of the beam is at the plane of excitation, i.e.
xfocus, yfocus, and zfocus don’t do anything yet. This will be fixed in
the next release.

Parameters: x y z width kx ky kz Ex Ey Ez mag phase n k orientation

AIRY Similar to Gaussian, but with a uniform pupil function, giving rise

to an Airy pattern (J1(x)/x) at the focus.

Parameters:Not implemented in this release.

PUPILFUNCTION Similar to GAUSSIAN, but allowing a general user function f(u,v) to

be used as the pupil function. GAUSSIAN is already implemented
on top of this function, but it hasn’t been exposed for this release.

Parameters:Not implemented in this release.

PLANE Adds a linearly polarized plane wave source. The position

parameters x, y, z specify the point at which the plane wave has the
given phase.

Parameters: x y z kx ky kz Ex Ey Ez mag phase orientation

MODEFILE Adds a mode file source. Mode files are lists of E field components

vs position, produced by the MODEFILE output statement in a
previous POEMS run, allowing the output of one run to become the
input of another. This is especially useful in waveguide problems
such as the one in Section 3.6.3. The coordinates specified are the
centre of the mode array, which is in general offset from the origin.

Parameters: file x y z orientation

21

POINT Adds a linearly-polarized point electric dipole source at the given

position. Point sources whose polarization is not x, y, or z
(diagonally, circularly, or elliptically polarized) can be implemented
as two or three point sources with appropriately chosen magnitude
and phase.

Parameters: x y z Ex Ey Ez mag phase

3.1.7. COMMAND Group

COMPUTE Supply control parameters to FIDO/TEMPEST. Parameters mincycles

and maxcycles control the number of cycles of the excitation
frequency that each simulation may use; setting the lower limit
occasionally helps in avoiding spurious early convergence, and the
upper puts a bound on the amount of run time. Adjusting
maxcycles to a small number such as 1-3 is useful when setting up a
run, because you can get rapid feedback on whether your geometry
is correct, and whether your PMLs are likely to cause problems.
Slightly higher values are useful in the early stages of an
optimization, where extreme accuracy in penalty function evaluation
is not needed, but run time is a serious concern. See the TEMPEST
documentation for more details. Start with a value of 0.01 or 0.001
for reltolerance, and don’t set mincycles or timestep until you really
need to.

Parameters: reltolerance maxcycles mincycles timestep

3.1.8. OUTPUT Group

INDEXN Tells tempest to produce a field file containing the real part of the

refractive index at each point. This is useful to show which
material is where in the simulation domain.

Parameters: xlo xhi ylo yhi zlo zhi file

DECIMATE Specify that only 1 out of decimation points is to be kept in each axis.

Parameters: xdecimation ydecimation zdecimation

Not implemented in this release.

22

FIELD Tells tempest to produce a field file containing the specified field

variable at each point.

Parameters: variable xlo xhi ylo yhi zlo zhi x y z file

phase state

3.1.9. POSTPROCESS Group

CAD Produces a .ctxt (2-D) or 2-D or 3-D DXF file of the entire

simulation domain, suitable for importation into a CAD program,
e.g. for numerically controlled machining, photomask generation, or
documentation. In a 3-D DXF file, each block in the simulation
domain becomes a set of six 3DFACE entities. In a .ctxt or 2-D DXF
file, each block is projected onto two rectangles, representing the
upper and lower faces in the given orientation. POEMS DXF files
are known to import properly into several CAD packages including
Autodesk Inventor. Note that length unit used in the DXF file is
metres unless otherwise specified--since many CAD packages use a
fixed number of decimals, this may cause confusion when the
sample domain is very small (e.g. in optical waveguides). Note that
the orientation is ignored in a 3-D file.

Parameters: file filetype dimensions orientation units xcut ycut zcut space

Examples: CAD file=ofile3.dxf filetype=dxf dimensions=3

CAD file=ofile2.dxf filetype=dxf dimensions=2,
units=micron orientation=ZX
CAD file=ofile.ctxt filetype=ctxt units=micron,
orientation=XY

The CAD statement also permits defining a line (for 2-D) or a plane
(3-D), parallel to a coordinate axis, at which extra space is to be
inserted, for use with shadow mask fabrication. For instance, for a
bridge width of 1.5 µm, you can add the following to the CAD
statement:

CAD file=mask.ctxt filetype=ctxt units=micron orientation=XY,
xcut=1.8*um space=1.5*um

WEBPAGE Produces a static HTML page containing all the relevant run

parameters, output bitmaps, and links to other files such as DXF
and Vis5D.

Parameters: file

23

FARFIELD Computes the far-field limit of the fields at a given plane, specified

as xlo ≤ x ≤ xhi, ylo ≤ y ≤ yhi, zlo ≤ z ≤ zhi. Because this range must

specify a plane, the upper and lower limits of one axis must be the
same to within basicstep/2. The coordinates will be correctly
rounded to integral numbers of cells. We assume that the fields
propagate through an infinite half-space of refractive index n (which
obviously must be lossless). The refractive index is taken to be the
real part of the index in the actual model at the centre of the

supplied plane, {xmin ≤ x ≤ xmax, ymin ≤ y≤ ymax, zmin ≤ z ≤ zmax}.

The parameter direction can be up or down depending on which
direction we’re interested in. Internally, POEMS uses both E and H
field information to separate out the incoming and outgoing fields,
so the computed far field spectrum wht direction=down can be very
different from that with direction=up. At present this statement
produces bitmaps of s- and p-polarized field amplitude and phase at
each point (u, v) in the pupil plane.

Currently the FARFIELD statement can be applied only on planes of
uniform granularity, i.e. basicstep must be the same in all
subdomains cut by the given plane.

Parameters: name xlo xhi ylo yhi zlo zhi file direction

FLUX Computes an integral of the Poynting vector through the given

surface, in the inward direction. This isn’t quite the same as using
the INTEGRAL statement directly, because it adds the ability to
specify an interior point. A positive flux is going in the direction
towards from (xInside, yInside, zInside).

Parameters: name xinside yinside zinside xlo xhi ylo yhi zlo zhi

INTEGRAL Computes a volume or surface integral of a given field function by

summing all the blocks lying in the specified region. If the region
has a nonzero thickness (after rounding to the nearest multiple of
BASICSTEP), it’s normalized as a volume integral; if two have a
nonzero thickness, it’s normalized as a surface integral of the broad
face of the region; and if only one dimension has a nonzero size, it’s
normalized as a line integral. Specify the integrand field or
postprocess quantity as variable, and make sure there’s a matching
statement that generates an array of the given quantity, because it
won’t be done automatically.

Parameters: name variable xlo xhi ylo yhi zlo zhi

24