Visualization Introductory remarks Structure data Mode profiles BEP/QUEP solutions Field viewer

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:

• Employ the MATLAB plot editor. This is not recommended in cases when plots are likely to have to be adapted later on, since manual alterations would have to be done all over again (experience shows that this is always the case).
• Edit the script file. The m-files are in ASCII format, with short comments included. Necessarily, the plot commands are collected at the end of the files, after the field data (note that the files may be relatively long, <pgdn> is likely to be tedious). Many of the variables that affect the outlook of the figure are explicitely assigned.
• Modify the output routines in matlvis.h, matlvis.cpp. Might require some effort to understand the so far not quite polished code.

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

• Run a main-program which includes one of the plot routines listed in the following sections. For example, the program facet.cpp contains the statement
     qfld.plot(fc, REP, -DWx, DWx, -DWz, DWz, 150, 150, 't', pc);
  At the corresponding position, the stderr output stream shows the line
     plot([-2.5, 2.5] x [-3, 3]) >> plrEyteI.m
  which indicates that the data for a plot of the real part of the E_y-component of a TE field on a window extending over the range [-2.5, 2.5] (x, vertical) times [-3, 3] (z, horizontal) has been dumped into a file named plrEyteI.m. Some remarks on the choice of filenames are contained in the introduction.
• Start the MATLAB environment. Make sure that the current path includes the folder where the file plrEyteI.m resides.
• At the MATLAB prompt, type
     plrEyteI
  to invoke the script file. This should bring up a window with the field plot.

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
   plot
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.

Examples:

• driver file tlwg.cpp, refractive index profile of a single Waveguide:
  
• driver file defcav.cpp, geometry of a sequence of waveguide segments SegWgStruct, refractive index levels are indicated by gray scales:
  
• driver file pcbend.cpp, structure data in a rectangular dielectric Circuit, gray scales indicate the local refractive indices:
  

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

Plots of mode profiles

... are facilitated by the method
   plot
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 E_x-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:

    

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
   adjustphase
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. 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:
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: 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 pi.
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.
fmovie		The related m-file generates an animation of the 'fancy' surface plot, that shows the periodic oscillations of the physical field in time.

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
   viewer.
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:

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

Ex, Ey, Ez, Hx, Hy, Hz		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.
Sx, Sz, w		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:

• In all states the plot title identifies what is actually shown at present.
• Not all combinations of selections / actions are reasonable, e.g. the Poynting vector components or the energy density, as well as all absolute values / squares of fields are constant in time, such that the animation is rather uninteresting. The square of a Poynting vector component does not represent a physically reasonable quantity ...
• Depending on your actual font size, the text windows might show only parts of (and perhaps not the most relevant parts) of the present numbers.
• The scale of the "colour axis" is adjusted as far as possible to render plots comparable, e.g. the same colour scale is used for plots of all electric field components. The scale changes, if the plot is switched to another physical quantity (e.g. the magnetic field) or if one switches between plots of the physical field and absolute values.
• The resolution of the plots in the viewer window, even if raised to full screen, cannot be better than the discretized field that has been exported to MATLAB.

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