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:
|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.|
In conclusion, for plotting a field profile you may adhere to the following steps:
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).|
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
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:
|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:
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.
A plot of the electromagnetic energy density. For the facet example:
||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.|
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:
|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.|
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.|
|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.|
||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.|
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.
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:
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 ||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.|
Relevant source files: bepfld.h, bepfld.cpp, quepfld.h, quepfld.cpp, bundle.h, bundle.cpp, matlvis.h, matlvis.cpp.