Visualization of fields and structure data

Usually a proper plot of the optical field gives the best idea about what's happening in a given structure. Besides, field visualizations are required e.g. for checking the correctness of results, and for purposes of demonstration, also for publishing.

Since graphics capabilities are not directly incorporated into the Metric programs, a plot requires to export suitable data sets, where the output format naturally depends on the numerical software for which the data is intended. In principle the field-methods and related routines of Mode, ModeArray, BepField, and QuepField objects give access to the optical fields; structural information is provided by the methods of the underlying Waveguide and SegWgStruct containers. Hence the export routines are favourably implemented as member functions of these objects.

This section describes a collection of functions which export the field and structural data to MATLAB script files (extension '.m'). The routines are declared / defined in structure.h, structure.cpp for the structural data, in slamode.h, slamode.cpp for mode profiles, and in slamarr.h, slamarr.cpp, bepfld.h, bepfld.cpp, quepfld.h, quepfld.cpp, for the mode interference fields, with helper functions found in matlvis.h and matlvis.cpp (the latter actually write the MATLAB commands).

Besides merely the field data, a proper figure requires further information, e.g. about axis annotations or scaling ratios. Almost always, a sketch of the structure under consideration is usually appropriate (helpful for immediate on-screen inspection as well as for publishing). This information is at hand when the export routine is executed, and at this moment one has usually a shape of the final plot already in mind. Therefore, the output m-files produce an entire figure when invoked in MATLAB, including plot commands, axis annotations, scaling, and, if appropriate, lines or patches to indicate the dielectric structure. In this way the path from the raw solver output to an acceptable plot is short and almost automatized.

Since 'acceptable' is a matter of taste (and of the actual problem), some ways to change the look of the final figures are to be mentioned:

A few global options influence the output (possible settings are YES and NO):

Mlop_Colour Decides, whether the plot uses colours. Set this value to NO (i.e. include a statement Mlop_Colour=NO; in your driver file) to enforce a gray scale figure.
Mlop_Print Most types of m-files contain print commands at the very end, which are commented, if this option is not set to YES. Doing so enforces MATLAB to write a graphics file (encapsulated postscript (.eps) or portable network graphics (.png)) at completing the figure setup.
Mlop_Contour Contour lines are added to image plots, if this option is set to YES.

These options may be useful, if an entire sequence of graphics is to be generated automatically. They are introduced in matlvis.h and predefined in matlvis.cpp. Note that the same changes can also be effected by manually altering/uncommenting the related commands in the output m-files.

In conclusion, for plotting a field profile you may adhere to the following steps:

Most of the the figures shown below are generated in this way, without any further editing.

So far the description relates to the preparation of figures that are, besides the on screen viewing, eventually designed for printing / publishing. Frequently, however, one likes to inspect a field on screen in all details, where all aspects like the different electric and magnetic components, the components of the Poynting vector, energy density, the refractive index structure, etc., should be conveniently accessible. The BepField and QuepField objects provide a viewer method for that purpose.

Plots of refractive index profiles

Plots of refractive index profiles are helpful in particular for checking whether the geometry and material properties of a given problem have been properly encoded. Thus a corresponding method
is provided by the containers Waveguide, SegWgStruct, and Circuit as declared/defined in structure.h, structure.cpp. In all cases two variants of the method exist: one that accepts only two id characters for the filename, and another, where in addition a plot domain can be specified.


Relevant source files: structure.h, structure.cpp.

Plots of mode profiles

... are facilitated by the method
of Mode objects, as declared/defined in slamode.h, slamode.cpp. Internally the mode profiles are represented analytically, with piecewise definitions that correspond to the piecewise constant refractive index of the multilayer slab waveguides. The profile plots consist therefore of pieces of (discretized) curves. Only in case of Ex-components (normal to the dielectric interfaces) this should lead to discontinuous functions. For all other components, inspection of continuity can serve to check the mode solver results.

The following arguments need to be provided to one of the variants of the plot method:

cp A component identifier of type Fcomp, one of EX, EY, EZ, HX, HY, HZ, or SZ for the components of the electric field, the magnetic field, or the Poynting vector component along the waveguide axis.
foa an attribute for field output, type Afo, one of MOD, SQR, REP = ORG, IMP, for the modulus, the absolute square, the real part (the 'original' field) and the imaginary parts of the in general complex mode profiles. Forward traveling versions of the modes are considered, where for the phase (here: the choice that certain components are purely real) the convention as described for mode objects applies. Note that according to that convention the transverse components Ex, Ey, Hx, Hy of guided modes are real (not all are nonzero, depending on the polarization), while the longitudinal components Ez, Hz are purely imaginary, i.e. certain combinations of cp and foa lead to zero plots.
disp The output Interval, i.e. a pair [x0, x1], the plot window on the x axis.
np The number of points on an (more or less) equidistant 1-D mesh on the display window, where the originally analytically represented mode profiles are evaluated for plotting.
ext0, ext1 Two characters that enter the name of the destination file; cf. the comments on the filename convention.
pltype A character, one of 'L' or 'V'. With argument 'L' the method produces an m-file that includes both the field and structure information, and the full MATLAB plot commands. A letter 'V' leads to an m-file that represents an additional curve, i.e. one that, if executed after one related to an 'L'-plot, adds a single curve to the existing MATLAB figure window (structure data and the related plot commands are thus not included in the 'V'-m-file).

Defaults values are supplied for all arguments, with the exception of the filename id, by a second variant of the plot method.

Example plots that correspond to the driver file tlwg.cpp, profiles of the fundamental and first order TE (left) and TM modes of the three-layer slab waveguide:

Three-layer slab waveguide, TE mode profiles    Three-layer slab waveguide, TM mode profiles

Entering a line tefEy00L at the MATLAB prompt should bring up a figure window that shows the principal electric component of the fundamental TE mode. The subsequent command tefEy01V adds the curve of the first order mode (alternatively, the line tefEy01V can be entered at the place indicated at the bottom of the file tefEy00L.m). An analogous procedure applies to the TM profiles.

Relevant source files: slamode.h, slamode.cpp.

Mode interference fields, BEP/QUEP solutions

The BEP/QUEP solvers approximate solutions to the scattering problems that consist primarily of complex valued functions of two variables, each representing one of the six electromagnetic field components (some are zero, depending on the polarization). By taking the real part of these, after multiplying with the harmonic time dependence exp(i omega t) for frequency omega = 2 pi/T and period T, one obtains snapshots of the physical fields at a specific time t. While obviously the wave pattern repeat periodically, one should be aware that the snapshots may differ significantly for different times within one interval [0, T], in particular if (partly) standing waves are present. Here the obvious way out is to generate animations of the oscillating field pattern. When this is not possible, e.g. for a printout, suitable time values need to be selected.

An alteration of the time at which physical fields are evaluated can be interpreted alternatively as a common phase change of all external input waves, and consequently of all complex field values over the entire computational domain, say for fixed t=0. The BepField and QuepField containers provide a method
for that purpose. Several variants are introduced in bepfld.h, bepfld.cpp, quepfld.h, quepfld.cpp; the different arguments determine how the the overall phase the solution is modified:

argument behaviour
a single double value phi The entire solution is multiplied by the complex value exp(i phi).
a pair of coordinates x, z The overall phase is adjusted such that a REP/ORG-plot of the principal field component (Ey for TE, Hy for TM) exhibits the maximum level at position x, z.
two integers numx, numz Adjust the global phase, such that a plot of the physical principal field component exhibits an overall field maximum (<-> time snapshot of an extremal state in case of a configuration with partially standing waves); the maximum is determined on a regular mesh of numx x mumz points on a reasonable computational window.
no argument . . . as before, with coarse defaults for numx, numz.

These preparations done, the routines can be invoked that export field plots to m-files. These are member functions of ModeArray, BepField, and Quepfield objects; the following list shows example plots generated by the driver file facet.cpp:

plot Image plot related to a single field component, specific time-snapshots of the physical fields. The white-blue-black colourmap is meant to give quantitative impressions in both colour and gray scale prints. White lines indicate any dielectric interfaces. Contour lines can be added by uncommenting the related lines in the m-file.
real part, imaginary part, and absolute value of the principal component
Example: real part, imaginary part, and modulus of the principal electric field component around the facet.
plot, no component identifiers A plot of the electromagnetic energy density. For the facet example:
Electromagnetic energy density around a waveguide facet
plot, FSid identifier A plot of a quantity that relates to a (positive) "strength" of the optical electromagnetic field, without referring to individual field components. The argument of type FSid accepts the values of mE, mH, qE, qH, or mW to identify the modulus (m) or square (q) of electric (E) or magnetic (H) field vector, or the electromagnetic energy density (mW), respectively.
phasemap The argument ('phase', wrapped to [0, 2 pi]) of a complex field component. In case of the facet: the phase of the principal electric component:
Phasemap (wrapped) of the principal component
Note that the 'blocky' appearance is due to the limited resolution of the discretized sample of the original analytic fields that is exported for plotting, and due to the colour scale discontinuities at jumps 0/2π.
movie Visualization of the time harmonic oscillations of the physical fields. The method produces an m-file that, if executed in MATLAB, generates an animated sequence of the former time snapshots.
fplot A 'fancy' style surface plot of a specified field component. Black lines on the surface indicate the dielectric discontinuities. For the facet example: the Metric logo.
Waveguide facet, surface plot of the principal component
fmovie The related m-file generates an animation of the 'fancy' surface plot, that shows the periodic oscillations of the physical field in time.

Common arguments of these methods are:

cp A component identifier of type Fcomp, one of EX, EY, EZ, HX, HY, HZ, or SX, SZ for the components of the electric field, the magnetic field, or the two relevant Poynting vector components. Note that not all components are nonzero, depending on the polarization.
foa an attribute for field output, type Afo, one of MOD, SQR, REP = ORG, IMP, for the modulus, the absolute square, the real part (the 'original' field) and the imaginary parts of the complex fields.
xbegxend, zbegzend The display window, a rectangular region in the x-z-plane.
npx, npz The number of points per axis of a rectangular equidistant 2-D mesh on the display window, where the originally analytically represented fields are evaluated for plotting.
ext0, ext1 Two characters that enter the name of the destination file; cf. the comments on the filename convention.
ntfr The number of time frames included in the animations.

Not all arguments apply to all methods, please consult the declarations of the methods in the respective header files. Since expansion coefficients are not stored in ModeArray objects (cf. the remarks on mode interference evaluation), these have to be supplied explicitly to the respective plotting routines.

Some of the former methods are also provided by objects of type View, used to accumulate field information when evaluating bundles of vQUEP solutions for the simulation of semi-guided beams. For these objects the arguments concerning the field discretization are stored internally, and are being supplied through the constructor.

Relevant source files: slamarr.h, slamarr.cpp, bepfld.h, bepfld.cpp, quepfld.h, quepfld.cpp, bundle.h, bundle.cpp, matlvis.h, matlvis.cpp.

Field viewer

For detailed on-screen inspection, rather than for purposes of printing or publication, the BepField, QuepField, and View containers provide a method
The method accepts only the discretization data, i.e. the extension of the computational window and the numbers of discretization points, and the two filename id characters as arguments, cf. the former section on visualization of BEP/QUEP solutions (in case of objects of type View this information is supplied via the constructor, and store internally).

A screen shot of the MATLAB window generated by the viewer m-file (use 'save as', then open in MATLAB) from the driver example facet.cpp looks as follows:

Facet example, MATLAB field viewer window

The figure window combines a plot area with a couple of GUI elements:

ExEyEz, HxHyHz Select one of the electromagnetic field components. Depending on the polarization, half of these are zero.
slider t=0 ... T Adjust the time for snapshots of physical field components within one period / set the overall phase of the field.
<< # >> Animate a stationary, time harmonic field; after an initial "recording" period (required by the MATLAB movie function), the plot window shows as many periods of the physical waves as specified by the number in the central text area, with time running forward (>>) or backward (<<).
F|F||F|^2 Display the physical field directly (F), the modulus (|F|) or the absolute square (|F|^2) of the field in complex representation.
SxSzw Show the vertical or the horizontal component of the Poynting vector, or the local energy density.
n Display the refractive index profile.
plot window A click on the plot window places a crosshair at the pointer position.
text fields x, z The present crosshair coordinates. Input in the text fields moves the crosshair to the respective position.
--- Horizontal cross section plot: Open a window that shows a horizontal section at the vertical crosshair position x through the plot that is displayed at the moment.
| Vertical cross section plot: Open a window that shows a vertical section at the horizontal crosshair position z through the plot that is displayed at the moment.
colourbar A click on the colourbar draws contour lines at the respective field level.

Further comments:

Note that the viewer is intended for on-screen inspection; facilities for exporting figures are thus explicitly not included. You might wish to use the former plotting / animation methods instead.

Relevant source files: bepfld.h, bepfld.cpp, quepfld.h, quepfld.cpp, bundle.h, bundle.cpp, matlvis.h, matlvis.cpp.