1 The output user interface

This section of the manual describes the Matlab output interface for SuperNEC.

1.1 Overview of Output interface

The output interface for SuperNEC consists of a number of viewers (all of which can be run from the command-line), linked by an output viewer executive, which summarises information in a SuperNEC output file and allows the user to filter, select and then view particular components of the output (such as radiation patterns, structures and so on).

The components of the output viewer are listed in Table 1.

Component	Function name	Description	Section
Executive	snecout	Summarises information in a NEC/SuperNEC output file and allows the user to filter, select and view components in the appropriate viewer.	1.2
Near Field Viewer	nrfldplot	Displays electric and magnetic near fields, defined in either rectangular or polar coordinates. Handles multiple frequencies and overlaying of a simulated structure on plots.	1.3
Radiation Pattern Viewer	radpatplot	Displays 2D and 3D radiation patterns as either rectangular or polar plots. 3D viewer handles multiple frequencies and overlaying of simulated structure on plots; 2D viewer allows overlaying of multiple plots in the same plane of cut and displays simulated structure with plot	1.4
Impedance Plotter	impplot	Displays 2D plots of impedance vs. frequency, in a number of different formats: Smith charts, VSWR plots, return loss, magnitude, phase, real and imaginary.	1.6
Efficiency Plotter	effplot	Displays 2D plots of power parameters vs. frequency, such as: efficiency, input power, radiated power, structure loss, network loss.	1.6
Coupling Plotter	cplplot	Displays coupling values versus frequency.	1.6
Structure Viewer	strucplot	Displays the simulated structure, with the option of superimposing either currents or charges on the MoM segments.	1.5

Table 1 : Components of the output viewer.

Each of these components are discussed separately in the section referenced by Table 1. To demonstrate their use, the next section takes you through a step-by-step tutorial on using the output viewers and executive.

1.2 Output Viewer Executive

1.2.1 Description

The output viewer executive snecout is a graphical interface that allows the user to interactively process SuperNEC output files. All results produced by a SuperNEC simulation can be accessed via the snecout interface. Using snecout, you can also combine multiple output files into one set of results, which can then be plotted simultaneously for comparison purposes.

1.2.2 Calling Syntax

snecout is started from the Matlab command line as follows:

snecout(filename)

where filename is a string variable containing the path and filename of the SuperNEC output file that is to be processed, e.g., ‘filename = 'c:\Output\Case1.out'’. Note that the filename must include the SuperNEC output file extension.

snecout

In this case the user is prompted via a standard ‘File Load’ GUI to select the required SuperNEC output file to process.

1.2.3 Using the output viewer executive

Figure 1 shows a typical instance of snecout. snecout works on a filtering principle. A summary of results contained in the SuperNEC output file can be selectively displayed in the larger right-hand (results) list box by choosing settings for the tab bar group (along the top of the display) and the two smaller left-hand list boxes.

Figure 1 : The snecout Window

The tab bar group is used to display specific types of SuperNEC output that may be contained in the output file. There are 4 mutually exclusive tab settings which filter the results shown in the results list box.

· Radiation Patterns : Display only radiation patterns contained in the SuperNEC output file.

· Near Fields : Display Electric and Magnetic near fields contained in the SuperNEC output file.

· Currents/Charges : Display the current and charge distributions contained in the SuperNEC output file.

· Parameter vs. Frequency : Display the excitation, coupling, efficiency and gain (or gain-ratio) results contained in the SuperNEC output file as a function of frequency.

The top left-hand list box (Available structures) lists all the structures that are contained in the SuperNEC output file. Selecting a particular model (it is possible to select either all or none of the models using the provided buttons), will filter the results contained in the results list box to only display those results associated with the selected structure. Similarly the bottom left-hand list box (Available Frequencies) lists all the frequencies at which the structure was simulated in the SuperNEC output file. Selecting particular frequencies will filter the results displayed in the results list box to only display those results at the selected frequencies.

Using the above mechanisms it is relatively easy to, for example, quickly identify the radiation patterns in a particular frequency range for a particular model structure. The identified radiation patterns can then be displayed by selecting the appropriate line in the results list box and pressing the plot button, located along the bottom of the snecout window.

In addition to the above basic functionality snecout provides some additional features.

1.2.3.1 Check Boxes

· Structure : When plotting some SuperNEC results it is possible to display the results in conjunction with the structure that was simulated. Check this box to include the structure in the displays. Note that the structure check box is automatically selected for charge and current displays.

· Overlay : If multiple plots are selected for display it is sometimes possible and convenient, to display the results on the same set of axes. Check this box to display multiple results on the same set of axes. Note that the overlay check box is not available for near field, current or charge results.

1.2.3.2 Push Buttons

· Plot Button : to display the selected results.

· Workspace : The raw data of the selected results can be sent to the Matlab workspace for later use using this button (assuming you are not running the runtime version of SuperNEC). If selected, the user is prompted for a variable name. If only one type of data has been selected e.g., only magnetic near field data, the data is stored directly to the named workspace variable. If multiple data types have been selected, e.g., both magnetic and electric near field data, the data is stored to the named workspace variable as a structure with fields for each data type.

· Load Button : to load another SuperNEC output file. Note that this new output data is merged with the already loaded output data. This means that the results from multiple SuperNEC output files can be viewed simultaneously.

· Exit Button : to close snecout.

Finally note that the bottom of the snecout window contains dynamic context sensitive help, e.g., run the pointer over the Available Frequencies list box and the help displays

Filter output summary by selected frequencies

1.3 Near-field Viewer

1.3.1 Description

The near-field Viewer displays 3D near electric or magnetic fields in spherical and rectangular coordinates. The viewer can handle multiple planes of data (i.e., many x, y and z values, or R, f and q values), as well as multiple frequencies. The user can select not only the plot type (from wireframe, mesh, surface, 3D contour, contour and pcolor plots) but also the component to view and either the magnitude or phase of that component. Thus, a single viewer gives full control over the plot type, values displayed and method of display.

The near-field viewer will accept SuperNEC structures which will be superimposed on the near-field plot.

NOTE : Currently spherical near-fields are not displayed correctly.

1.3.2 Calling Syntax

The near-field viewer is called as follows:

fig = nrfldplot(coords, data, x, y, z, freq);

fig = nrfldplot(nfStruct);

The calling syntaxes are equivalent. The second bundles the 6 arguments into a structure with fields the same as the argument names:

Arguments :

coords : 0 or 'r' for rectangular coordinates, 1 or 's' for spherical

data : An m x n x p x 6 x nF matrix of complex field values. SuperNEC returns magnitude and phase of gains in three directions. It is these values which are passed to the viewer.

x : First coordinate vector (x or R) of length m.

y : Second coordinate vector (y or Phi) of length n.

z : Third coordinate values (z or Theta) of length p

freq : Frequency vector of length nF.

1.3.2.1 Passing Structure Data

The structure is passed to the near-field viewer in a separate function call:

fig = nrfldplot(Figh, 'Structure', StructData);

This would typically be sent to the plot handle returned by the nrfldplot routine.

A typical example of the near-field viewer is shown in Figure 2.

Figure 2 : The near-field viewer.

1.3.3 Using the near-field viewer GUI

The near-field viewer GUI is designed to enable rapid visual exploration of near-field data. In order to harness the power of the near-field viewer, it is important to understand the capabilities and features of the viewer. This section explains these features.

The near-field viewer contains a SuperNEC standard ‘File’ menu, described in section 1.7.

1.3.3.1 Selecting the Active Data Set

The near-field viewer always holds more data than it can display, for example, each data point consists of four different components (x, y and z components, as well as the total field strength), each of which have two properties (magnitude and phase). In addition, the near-field data may consist of a complete description of the near fields in multiple planes (i.e., multiple x, y and z values) and at multiple frequencies. However, current visualisation techniques only allow us to view one of those planes at a particular frequency at any time. The user is therefore able to select the plane, frequency, component and property to be displayed. A discussion of how the data is then presented is given in section 1.3.3.2

Plane selection is achieved using the ‘Plane’ pull-down menu. The user can select between any of the available planes in which a surface can be extracted from the data. Thus, if multiple values of x, y and z are passed to the near-field viewer, all planes may be selected. However, if near-fields were computed in a single plane (say x=2.4), then the plane selection will be locked to constant x at a value of 2.4.

Once the plane has been selected (assuming you are not locked to a single value), a slider at the bottom left of the figure allows you to select a particular value in that plane. You can also enter a specific value in the edit box next to the slider, but note that the value will ‘snap’ to the nearest value in the near-field data (i.e., interpolation does not occur).

Component and Property Selection. The near-field viewer allows you to select the component to view and the property of that component to display. This is achieved using the ‘View’ menu option. By default, the total magnitude of the near-field is displayed.

Þ Selection of the colourmap is important when viewing phase plots. The near-field viewer does not unwrap phase plots, so a phase of 0 degrees is not necessarily given a similar colour to a phase of 360 degrees. One colourmap (‘hsv’) wraps around, so that phase plots look wrapped (except when interpolated shading is requested).

1.3.3.2 Plot Types

The near-field viewer will show the currently selected data in any of the following formats (using the ‘Type’ pull-down menu):

Wireframe

Mesh

Surface

3D Contour

Contour

Pseudocolour

Plot types are described as follows:

Wireframe : The plot is depicted as wires joined between data points. The spaces between the wires is hollow, i.e., hidden lines are not removed.

Mesh : The plot is depicted as wires joined between data points. Hidden lines are removed in this plot.

Surface : The plot is depicted as a complete surface. The characteristics of the surface depend on the shading and lighting properties.

3D Contour : The data is plotted as contour lines with the height of the contour shown on the plot.

(Flat) Contour : The data is plotted as contour lines. The contours are located in real space (i.e., at x, y, z values).

Pseudocolor : A more detailed contour plot. A pseudocolor plot creates a surface in real space with the colour at each point determined by the data.

From the above descriptions, we define two sets of plot types :

Pseudo-surfaces are surfaces in which one of the dimensions is used to represent the near-field data. The first 4 surfaces are pseudo-surfaces because height is used to describe the data values (magnitude or phase).

Coordinate-surfaces are surfaces in which the data is represented in true space, i.e., spatially located. Coordinate surfaces are restricted to 2D contours and pseudo-colour plots.

1.3.3.3 Lighting and Shading

All surfaces can be visually highlighted using Matlab’s lighting and shading facilities. From the near-field GUI, the ‘Options | Shading’ and ‘Options | Lighting’ menus control these properties.

1.3.3.4 Other Options

The ‘Options’ menu allows the user to perform the following:

Grid : turns the grid on (checked) or off (unchecked).

Box : turns the axes box on (checked) or off (unchecked). When set on, the axes is presented as a box. When off, only the sides of the axes with tick marks is drawn with a border.

Title : Allows the title to be changed. Edit the title and use the ‘<Esc>‘ key to exit the label editing mode.

Xlabel : Allows the label of the X-axis to be changed. Edit the label and use the ‘<Esc>‘ key to exit the label editing mode.

Ylabel : Allows the label of the Y-axis to be changed. Edit the label and use the ‘<Esc>‘ key to exit the label editing mode.

Zlabel : Allows the label of the Z-axis to be changed. Edit the label and use the ‘<Esc>‘ key to exit the label editing mode.

Clabel : Allows the label of the colourbar to be changed. Edit the label and use the ‘<Esc>‘ key to exit the label editing mode.

1.3.3.5 Colourmap Control

The ‘Colourmap’ menu offers control over the colourmap:

Length : Sets the number of colours used in the colourmap.

Range : Controls the colourmap range. Choose from the following :

Auto : scales the colourmap so that the maximum displayed value is at the top of the colourmap and the minimum displayed value is at the bottom. This is the default.

Total : attempts to provide a comparative display of the data values by setting the colourmap to the total value in the selected plane and frequency. Thus changing the sliders along the bottom of the display allows a comparative display of data through the particular dimension and/or frequency.

User : allows the user to specify the colourmap range. This should be entered as a 2-element vector, specifying the ‘[min max]’ values to use for the colourmap. Any values outside this range are displayed in the closest colour, thus, if the lower limit is set to -0.4, then any values below -0.4 will be represented in the lowest colour in the colourmap. For more discussion on colourmaps, see the Using Matlab Graphics documentation.

Map : Selects the colourmap to use from a range of existing colourmaps. Of these, only ‘hsv’ has a wraparound effect (the maximum value is the same colour as the minimum value) and is useful for displaying phase data.

Brighten : Makes the colourmap brighter. Note that selecting a new colourmap (using the ‘ColourMap | Map’ menu) resets the map.

Darken : Makes the colourmap darker. Note that selecting a new colourmap (using the ‘ColourMap|Map’ menu) resets the map.

Spin : Cycles the colourmap. This option is only available on displays with 256 colours or less.

1.3.3.6 Superimposing Structures

Superimposing structures on a near-field plot enables (in most instances) physical interpretation of spatial locations (e.g., regions near the excitation point, symmetry, etc.) The ‘View | Structures’ submenu provides control over how a structure is superimposed on a plot. Note that this menu is disabled if a structure has not been passed to the near-field viewer.

Visible : chooses whether the structure should be superimposed or not.

LineWidth : selects the width of lines used to display the plot. This property has no effect on GTD objects (cylinders and plates).

Color : selects the colour of the structure. This can be used to make the structure stand out in a particular colourmap. The default colour is black.

XOR : Erase, when checked, plots the structure in XOR erasemode. For a complete description of the erasemode properties consult the Using Matlab Graphics documentation.

Scale : modifies the scale of the structure relative to the surface being plotted.

1.3.3.7 Superimposing Vectors

Since the data passed to the near-field viewer typically consists of the x, y and z components of the near-fields, it is possible to superimpose vectors on the near-field viewer coordinate surfaces only (the vectors are meaningless in pseudo-surfaces). This can be achieved using the ‘View | Vectors’ menu option. Vectors are always plotted in black as arrows starting at the specified data points and with a length scaled according to field strength.

1.4 Radiation Pattern Viewer

1.4.1 Description

The Radiation Pattern Viewer consists of two GUIs which handle 2D and 3D radiation patterns. Radiation patterns in SuperNEC are specified in spherical coordinates. The 3D radiation pattern viewer is capable of accepting radiation patterns at multiple frequencies. The 2D viewer is capable of intelligently overlaying multiple plots of the same plane of cut on the same axes. Both radiation pattern viewers will accept SuperNEC structures which will be superimposed on the 3D plot, or plotted next to the 2D plot, for orientation purposes.

1.4.2 Calling Syntax

The radiation pattern viewers (radpatplot, radpat2d and radpat3d) are called as follows:

fig = radpatplot(gain, phi, theta, freq);

fig = radpatplot(rpStruct);

fig = radpat2d(....);

fig = radpat3d(....);

fig = radpat...(....,'-overlay');

The calling syntaxes are equivalent. The second call bundles the 4 arguments into a structure with fields the same as the argument names:

Gain : The nP ´ nT ´ 3 ´ nF gain matrix. The third dimension contains the gains in order: ‘major/vert’, ‘minor/horiz’, ‘total’. All values should be in dBi.

Phi : A vector of azimuth angles (degrees) of length nP.

Theta : A vector of elevation angles (degrees) of length nT.

Freq : Frequency vector of length nF.

The final form of calling syntax can be used to attempt an overlay of 2D plots (although all functions accept the ‘-overlay’ switch, only the 2D viewer actually overlays plots).

Þ Only 2D plots in the same plane of cut (azimuth or elevation) can be overlaid and a maximum of 6 plots can be placed on one 2D pattern viewer.

1.4.2.1 Passing Structure Data

The structure is passed to the radiation pattern viewer in a separate function call:

fig = radpatplot('Structure', StructData, Figh);

This would typically be sent to the plot handle returned by one of the above function calls. Multiple structures cannot be overlaid on a single plot. Subsequent calls passing structures simply overwrite any previous structures in the viewer.

‘radpatplot’ determines the correct viewer to open and calls the specific viewer function call. The specific viewers may also be called directly using the functions ‘radpat2d’ and ‘radpat3d’. Arguments for direct calls are identical to those for ‘radpatplot’.

Each of the radiation pattern viewers will now be discussed separately.

1.4.3 3D Radiation Patterns

A typical example of the 3D Radiation Pattern Viewer is shown in Figure 3.

Figure 3 : 3D radiation pattern viewer ‘radpat3d’

The Radiation Pattern Viewers contain a SuperNEC standard ‘File’ menu, described in 1.7.

1.4.3.1 Using the 3D Radiation Pattern Viewer GUI

The 3D radiation pattern viewer GUI is designed to enable rapid visual exploration of 3D radiation patterns. In order to harness the power of the viewer, it is important to understand the capabilities and features of the viewer. The next few sections explain these features.

1.4.3.2 Selecting the Active Data Set

The radiation pattern (radpat) viewer always holds more data than it can display, for example, each data point consists of three different components (major/vertical, minor/horizontal and total gains). In addition, the radpat data may consist of a complete description of the radpat at multiple frequencies. However, current visualisation techniques only allow us to view one of frequencies at any instance.

Although radpat data is typically defined in polar coordinates, the user may wish to view the data in rectangular coordinates, mapping f to one dimension, q to the other and the gain to the third.

The user is therefore able to select the frequency, component and coordinate axis on which to display the data. A discussion of how the data is then presented is given in section 1.4.3.3.

Frequency selection is achieved through the slider at the bottom right of the viewer. If this slider is not visible, then only one frequency has been passed to the radpat viewer. You may select the frequency either using the slider (clicking on the arrows changes to the next highest or lowest frequency; pressing in the trough steps 2 frequency values at a time), or by typing in the desired frequency in the edit box next to the slider (if that frequency is not available, the nearest frequency is used and the edit box is updated to reflect this).

Component Selection. The radpat viewer allows you to select which component you are viewing using the ‘View | Component’ menu option. By default, the Total gain is displayed. Options are ‘Major/Vertical’, ‘Minor/Horizontal’ and ‘Total’.

Þ Currently, the radiation pattern viewer is not capable of differentiating electric from magnetic fields, or major/minor from vertical/horizontal components. This will be possible in a future version of the radiation pattern viewers.

Coordinate axis selection is made through selecting one of the ‘Rectangular’, ‘Polar’ or ‘Ground’ options in the ‘View’ menu. the differences are described below :

Rectangular : The data is presented with f along the x-axis, q long the y-axis and gain along the z-axis.

Polar : The data is presented in true space as a 3D polar plot. The radius at each point is defined by the gain, scaled so that the lowest value is zero length.

Ground : In polar coordinates, but showing only that part of the pattern above ground.

1.4.3.3 Plot Types

The radpat viewer will show the currently selected data in any of the following formats (using the ‘Type’ pull-down menu) :

Wireframe

Mesh

Surface

Pseudocolour

Plot types are describes as follows :

Wireframe : The plot is depicted as wires joined between data points. The spaces between the wires is hollow, i.e., hidden lines are not removed.

Þ This plot type is particularly useful when viewing a radiation pattern with the structure overlaid, as the structure is able to show ‘through’ the data spaces.

Mesh : The plot is depicted as wires joined between data points. Hidden lines are removed in this plot.

Surface : The plot is depicted as a complete surface. The characteristics of the surface depend on the shading and lighting properties.

Pseudocolor : A sphere of constant radius coloured by the gain. This plot type is useful for viewing more of the structure than would normally be seen by the surface plot.

1.4.3.4 Excluding data from the view

Sometimes it is useful to exclude certain sections of data from being displayed. For example, to hide ‘clutter’ in a particularly varying plot, you may want to exclude everything between f = 0 and f = 270 degrees. This can be accomplished using the ‘View | Exclude’ menu option.

Once you have selected this option, you are asked to enter 2 limits; one for f and one for q. Data that corresponds to angles between these values is data that must not be displayed. Clearing either of these values and pressing ‘<Enter>‘ displays all data.

1.4.3.5 Lighting and Shading

All surfaces can be presented using Matlab’s lighting and shading facilities. From the 3D radpat GUI, the ‘Options | Shading’ and ‘Options | Lighting’ menus control these properties.

1.4.3.6 Other Options

The ‘Options’ menu allows the user to perform the following :

Title : Allows the title to be changed. Edit the title and use the ‘<Esc>‘ key to exit the label editing mode.

Clabel : Allows the label of the colourbar to be changed. Edit the label and use the ‘<Esc>‘ key to exit the label editing mode.

1.4.3.7 Colourmap Control

The ‘Colourmap’ menu offers control over the colourmap:

Length : Used for selecting the length of the colourmap. Choose between standard values of ‘16’, ‘64’, ‘256’ or a user-defined length.

Range : Controls the colourmap range, from one of three choices:

Auto : scales the colourmap so that the maximum displayed value is at the top of the colourmap and the minimum displayed value is at the bottom. This is the default.

User : allows the user to specify the colourmap range. This should be entered as a 2-element vector, specifying the ‘[min max]’ values to use for the colourmap. Any values outside this range are displayed in the closest colour, thus if the lower limit is set to -0.4, then any values below -0.4 will be represented in the lowest colour in the colourmap. For more discussion on colourmaps, see the Using Matlab Graphics documentation.

The radius and/or height of plots are effected by setting the colourmap range.

Brighten : Makes the colourmap brighter. Note that selecting a new colourmap (using the ‘ColourMap | Map’ menu) resets the map brightness.

Darken : Makes the colourmap darker. Note that selecting a new colourmap (using the ‘ColourMap | Map’ menu) resets the map.

Spin : Cycles the colourmap. This option is only available on displays with 256 colours or less.

1.4.3.8 Superimposing Structures

Superimposing structures on a radiation pattern plot enables (in most instances) physical interpretation of spatial orientation. The ‘View | Structures’ submenu provides control over how a structure is superimposed on a plot. Note that this menu is disabled if a structure has not been passed to the radiation pattern viewer.

Visible : chooses whether the structure should be superimposed or not.

LineWidth : selects the width of lines used to display the plot. This property has no effect on GTD objects (cylinders or plates).

Color : selects the colour of the structure. This can be used to make the structure stand out in a particular colourmap. The default colour is black.

XOR : Erase when checked, plots the structure in XOR erasemode. For a complete description of the erasemode properties, consult the Using Matlab Graphics documentation.

Scale : modifies the scale of the structure, relative to the surface being plotted.

1.4.3.9 Slicing the 3D View: Passing Data to the 2D Viewer

You may wish to view the 3D pattern from a SuperNEC simulation and then plot a particular slice of that pattern in 2D. This capability is provided by the controls at the bottom left of the 3D viewer. A diagram of the controls is shown in Figure 4.

Figure 4 : Showing the 3D viewer slice controls

The controls consist of a checkbox which enables or disables the other controls and :

· A popup-menu which allows you to select the plane of cut; either constant f (i.e., an elevation cut) or constant q (a conical cut).

· An edit box which displays the present angle of the cut and where you can type a specific desired value (the value will ‘snap’ to the nearest available cut in the data set);

· A slider which allows you to step through available values (either singly, using the buttons, or in steps of 4 by clicking on the trough);

· A button labelled ‘2D’ which passes the currently selected data (as well as the structure, if present) to the 2D viewer.

If the slice controls are selected, a line is drawn on the current dataset showing the currently selected plane.

Þ If you have elected to exclude data from the 3-D plot, the line showing the plane is still drawn at the values of the data points.

1.4.4 2D Radiation Patterns

A typical example of the 2D Radiation Pattern Viewer is shown in Figure 5.

Figure 5 : A typical 2D radiation pattern shown in the radpat2d viewer.

1.4.4.1 Using the 2D Radiation Pattern Viewer GUI

The 2D radiation pattern viewer GUI (radpat2d) is designed to enable rapid visual exploration of 2D radiation patterns. The next few sections explain the features of the viewer.

1.4.4.2 Selecting the Active Data Set

The radiation pattern (radpat) viewer always contains more data than it can display: Each data point consists of three different components (major/vertical, minor/horizontal and total gains). A filtering scheme is once again employed.

Although radiation pattern data is typically defined in polar coordinates, the user may wish to view the data in rectangular coordinates, mapping either f or q to the x-axis and the gain component to the z-axis. Another useful plot type is the ‘ground’ plot, which shows all data above the ‘ground’ (z = 0).

Ground plots only make sense with constant f (or elevation) plots. Therefore, this option is disabled for azimuth plots (constant q).

The user is therefore able to select the component and coordinate axis on which to display the data.

Component Selection. The radpat viewer allows you to select the component you wish to view using the ‘View | Component’ menu option. By default, the Total gain is displayed. Options are ‘Major/Vertical’, ‘Minor/Horizontal’ and ‘Total’.

Þ Currently, the radiation pattern viewers are not capable of differentiating electric from magnetic fields, or major/minor from vertical/horizontal components. This will be possible in a future version of the radiation pattern viewers.

Coordinate axis selection is made through selecting one of the ‘Rectangular’, ‘Polar’ or ‘Ground’ options in the ‘View’ menu. The differences are described below:

Rectangular : The data is presented with f or q along the X-axis and gain along the Z-axis.

Polar : The data is presented in polar coordinates. The radius at each point is defined by the gain, scaled so that the lowest value (or user-defined lower limit) is zero length.

Ground : In polar coordinates, but the pattern below ground level is not displayed. This plot type is only available for elevation plots.

Þ It is important to think of all of the plot types as different views of the same data and not as different plots. Therefore, any change to limits, tick marks, or grid visibility, apply to all views, not just the current view.

1.4.4.3 Options

The ‘Options’ menu provides flexibility in defining limits in angle and magnitude, tick marks, grids, magnitude units, labels and the origin placement for polar plots. This section discusses these options.

Grid visibility : is controlled using the ‘Options | Ang-Grid’ and ‘Options | Mag-Grid’ options. If checked, the corresponding grid will be visible. Note that this applies to both rectangular and polar plots. Thus, if ‘Options | Ang-Grid’ is unchecked, rectangular plots will not show vertical gridlines and polar plots will not show angle rays.

Limits : can be set using the ‘Options | Limits’ submenu. You can set either the ‘Angle’ limits or the ‘Magnitude’ limits. Angle limits must lie within the range [-360, 360]. Magnitude limits are defined in dBi. If you enter an empty string, then the limits are set to the maximum and minimum values that exist in the data available to the viewer.

Labels : can be changed either by clicking directly on the labels in the figure, or by selecting the corresponding submenu from the ‘Options | Labels’ menu. Type in the label and press ‘<ESC>‘ to end label editing.

Þ Labels are reset when you change plot views. Thus, it is recommended that you change labels immediately before you print or save the figure.

Þ You can define X-axis and Y-axis labels for a polar plot! This practice is not recommended, but is not disabled.

Units : for the magnitude can be selected using the ‘Options | Units’ menu. Select from:

DBi : The default setting and the assumed units for any data passed to the radiation pattern viewer.

DBd : or dipole dB. Defined as dBi-2.14dB

dB (Norm) : Normalised dB so that the maximum magnitude is 0.

Þ The point at which normalised dB occurs may not be visible in the current plot.

Ticks : can be controlled using the ‘Options | Ticks’ submenu. Ticks are placed on the axes where gridlines and values occur. Selecting either ‘Angle’ or ‘Magnitude’ will bring up a dialog which contains the present tick values represented as a Matlab vector. Modify the vector and press ‘Ok’ to update the ticks for that property.

Þ Ticks are reset by defining new limits. Set the axis limits before selecting tick marks.

Þ Remember that this setting affects all plots. Thus, if you select many angular ticks, you will get many rays in the polar plot and many vertical lines in the rectangular plot.

Origin : control for polar plots is performed using the ‘Options | Origin’ submenu. Choices are ‘Right’, ‘Top’, ‘Left’ or ‘Bottom’. This controls only the polar plot (not ground plots) and changes the position at which 0 degrees occurs. The same data is plotted at all four origins in the following table:

Origin = right

Origin = left

Origin = top

Origin = bottom

1.4.4.4 Line Control

Line control is common to all 2D viewers for SuperNEC. Please see section 1.7.

1.4.4.5 Markers

Markers enable you to display information about a specific point on a 2D plot. Markers are discussed in section 1.7.1

1.4.4.6 Superimposing Structures

If a structure has been passed to the 2D radiation pattern viewer, then it is displayed to the right of the plot. This same space is used to display the legend (‘View | Legend’). You can choose to see the structure or turn it off using the ‘View | Structure’ menu option. Presently, you cannot resize the legend or the structure view.

Orientation of the structure is performed using the following algorithm:

· If the plot type is polar or ground, the structure is oriented in the same direction as the plot. Thus, if you draw a circle around the structure, the angles in the plot and in the structure should correspond.

· If the plot type is rectangular, the structure is oriented so that the mid-point of the angle axis on the rectangular plot corresponds to the bottom of the structure view. Thus, if you ‘unwrapped’ a circle drawn around the structure, you will get the same angles as those found along the x-axis.

1.5 Current Charge and Structure Plotter

1.5.1 Description

The Structure Plotter strucplot displays the simulated structure in a Matlab 3D figure window. If available, currents and charges on MoM segments can be superimposed on the structure.

Þ The Structure Plotter obtains data from a SuperNEC output file, not the input file. The Structure Editor (see the input user reference manual) allows you to visualise geometries prior to simulation.

1.5.2 Calling Syntax

The structure plotter is called as follows:

fig = strucplot(necStruct)

fig = strucplot(necStruct, currData, chargeData)

The first calling syntax displays only the structure passed in necStruct. The second allows current data and/or charge data to be passed along with the structure. Either currData or chargeData can be empty.

Þ Unlike other viewers, where the data is passed and then the structure, this viewer requires all data to be passed in one command. Other viewers used the structure as an auxiliary display; this viewer displays the structure as the primary data.

1.5.2.1 Data Format

necStruct is a Matlab structure variable usually obtained from the ‘sndata/struct’ method. Data formats for necStruct are defined in section 1.9.

currData is a Matlab structure variable usually obtained from the ‘sndata/current’ method.

chargeData is a Matlab structure variable usually obtained from the ‘sndata/charge’ method.

The only restriction on necStruct, currData and chargeData is that their indices representing MoM segment data must be equal. That is, the length of the necStruct.Segments and the row dimension of currData.currents and chargeData.charges must the same.

1.5.2.2 Example Usage

A typical example of the Structure Plotter is shown in Figure 6.

Figure 6 : The structure plotter.

1.5.3 Using the Structure Plotter GUI

The Structure Plotter GUI is designed to enable rapid visual exploration of structures and current/charge data. The following sections describe the features of the structure plotter.

The Structure Plotter contains a SuperNEC standard ‘File’ menu, described in section 1.7.5.

1.5.3.1 Selecting Data to Visualise

The structure plotter can store data about the structure, currents and charges. However, only one of these sets of data can be viewed at any stage. This is done by superimposing the required data onto a 3D view of the structure. To control this, a menu and some user-interface controls are provided.

The ‘View’ menu allows you to select the data to superimpose on the structure. You can select from :

None : Displays no data. The structure is drawn in a single colour, defined by the ‘View | Structure | Colour’ setting.

Radius : Displays the radius of each segment as a colour indexed by the colourmap on the right side of the display. The colourmap is controlled by the ‘Options’ menu.

Current : Displays either the magnitude or phase of current density on segments.

Charge : Displays either the magnitude or the phase of charge density on segments.

In all cases except ‘None’, a colourmap is used to map data values to visible colours. The colourmap is controlled by the ‘Options’ menu.

The other interaction with data concerns multiple frequencies for currents and/or charges. In cases where multiple sets of current and/or charge data is supplied to the structure plotter, a slider and edit box become visible in the status bar at the bottom of the display. These controls allow you to select the currently visible frequency. This is done either by dragging the slider or typing the frequency into the edit box. If you type a frequency which is not available, the nearest available frequency is used.

1.5.3.2 Manipulating the Structure

The Structure Plotter automatically allows you to zoom in and out of the structure and pan and/or rotate the viewpoint. This is discussed in full in section 1.7.3.

Other options in the structure plotter’s ‘View’ menu allow you to modify the way the structure is displayed. These menu items are grouped under the ‘Structure’ menu from the ‘View’ main menu. The following can be modified:

Colour : This sets the base colour for the structure. Any part of a structure which has no data superimposed will be drawn in this colour.

Þ All UTD objects are drawn as solid. The inside is drawn in a lighter shade than the default colour, in order to show boundaries.

LineWidth : This sets the width of displayed segments in standard Matlab line width units. A line width of 1 is extremely small on high resolution displays. A setting of 2 is useful for highlighting segments.

1.5.3.3 Display Options

The ‘Options’ menu provides various display control settings. These allow you to tailor the default display to your own tastes. The following menu items are available under ‘Options’:

Background : You can select a colour for the background, from ‘White’, ‘Black’ or an arbitrary colour selected using the ‘User’ option.

Þ A black background is useful for accentuating colours on segments.

Title : Allows you to set the display title.

Clabel : Allows you to set the label for the colourbar. Note that changing the view data type using the ‘View’ menu changes the colourbar label.

Renderer : Allows you to select from ‘Painters’ and ‘ZBuffer’ rendering algorithms. Painters, although slow, is useful for generating scalable printed results (PostScript, Windows Metafile).

1.5.3.4 Colourmap Control

The ‘Colourmap’ menu provides complete control over the colourmap. The following items are available in this menu:

Length : This allows you to set the length of the colourmap. You can choose any of the available lengths, or define your own with the ‘User’ option. A shorter length colourmap means more distinct colour changes.

Map : This allows you to select the colourmap from a range of predefined colourmaps.

Range : This selects the range over which the current colourmap changes. Any values outside the range is mapped to the nearest colour. You can select from:

Auto : This scales the colourmap to the minimum and maximum ranges for the displayed data.

Total : This fixes the range to the minimum and maximum ranges for all data of the defined type (irrespective of frequency). Select this to easily observe the effect of different frequencies.

User : You can select your own colourmap range.

The colourmap range is set for the displayed data type: changing data types resets the colourmap range to the last range for the new type.

Brighten : This brightens the current colourmap. You can use this more than once to enhance the effect or use ‘Darken’ to cancel it. Selecting a new colourmap using the ‘Map’ option also resets the colourmap brightness.

Darken : This darkens the current colourmap. You can use this more than once to enhance the effect or use ‘Brighten’ to cancel it. Selecting a new colourmap using the ‘Map’ option also resets the colourmap brightness.

Spin : (Only available on 8-bit displays) This will spin the colourmap allowing you to view changes in the data displayed as the colours cycle through the range defined.

1.6 Parameter vs. Frequency Viewer

1.6.1 Description

The SuperNEC impedance data viewer impplot, the efficiency viewer effplot, the coupling viewer cplplot and the Gain / GainRatio viewer are all 2D plotters with a very similar look-and-feel and are thus documented together, even though they exist as four separate GUIs. Differences in the interfaces will be pointed out.

Since the purpose of the plotter is generally to plot some parameter versus frequency, I have used the maximum plot space available. There are thus no other UI controls cluttering the screen and therefore all user interaction takes place via the menus and the mouse.

The plotter GUI essentially allows most aspects of the actual plot to be controlled via menu options or mouse events. It plots up to 6 lines (data sets) in the same plot window.

1.6.2 Calling Syntax

The viewer is generally called from the snecout viewer, but may be called from the command line and passed a structure of data. For historical reasons, the impedance plotter also accepts data in cell arrays, but the other plotters do not. Type ‘help impplot’ at the Matlab command line for this older calling syntax.

The plotters in this section are called with: impplot effplot cplplot gainplot impplot and the specific calling syntax is given below:

Figh = impplot(impStruct[, '-overlay']);

Figh = effplot(effStruct[, '-overlay']);

Figh = cplplot(cplStruct[, '-overlay']);

Figh = gainplot(gainStruct[, '-overlay']);

Arguments :

impStruct : A structure with fields:

freq : A 1´ n real vector of frequencies in MHz.

impedance : A 1 ´ n complex vector of impedance in Ohms.

effStruct : A structure with fields:

freq : A 1´ n real vector of frequencies in MHz.

InputPower : A 1 ´ n real vector of input power in Watts.

radiatedPower : A 1 ´ n real vector of radiated power in Watts.

structureLoss : A 1 ´ n real vector of structure loss in Watts.

networkLoss : A 1 ´ n real vector of network loss in Watts.

efficiency : A 1 ´ n real vector of efficiency in percent.

cplStruct : A structure with fields:

freq : A 1 ´ n real vector of frequencies, assumed in MHz.

coupling : A 1 ´ n real vector of coupling in dBs.

gainStruct : A structure with fields:

freq : A nF ´ 1 real vector of frequencies, assumed in MHz.

phi : An m ´ 1 real vector of phi values.

theta : An n ´ 1 real vector of theta values.

field : An m ´ n ´ 3 ´ nF matrix of field values. In the third dimension, the third element is Total Gain, which is what gainplot uses.

'-overlay' : If this flag is passed to the plotter, an existing figure is sought. If one is found and there is space in that figure for more lines, then the plot is sent there. Otherwise, a new figure is created.

1.6.3 Menus

All user interaction with the plotters takes place through the menus. These are designed to have the same look-and-feel across all the plotters and other 2-D plotters in SuperNEC (e.g., radpat2d). The function of each drop-down menu is described below:

File : Miscellaneous file operations.

Refresh : Updates the plot to the stored parameters if, for some reason, it has become corrupted.

Save : Save an m-file that will replicate the current figure.

Þ Note that not all handles/callbacks etc. will be valid in the regenerated figure that was saved in this way, but the plot will look the same!

Print : Print graph. Pulls up Matlab’s standard printing dialogs. Can also print to a file.

Print to File : Provides another means of printing the figure to a file.

Page Setup : Brings up the standard Matlab print position dialog.

Close : Close the figure.

Format : Chooses the format (type) of the plot. This option is not available in the coupling plotter, which can only display coupling!

The impedance plotter can display the output in many forms. In the case of complex data, the impedance can also be converted to admittance, as well as reflection coefficient in some cases. An overview of the plot formats is given below:

Smith Chart : Displays the impedance or admittance data on a Smith Chart.

Magnitude : Displays the magnitude of the impedance, admittance or reflection coefficient versus frequency.

Phase : Displays the phase of the impedance, admittance or reflection coefficient versus frequency.

Real : Displays the real part of the impedance, admittance or reflection coefficient versus frequency.

Imaginary : Displays the imaginary part of the impedance, admittance or reflection coefficient versus frequency.

VSWR : Calculates the VSWR of the impedance data assuming a characteristic impedance, Z₀ and displays it versus frequency.

Return Loss : Displays the return loss of the antenna when attached to a system whose input impedance is equal to Z₀.

In the case of the efficiency plotter, the format options are:

Efficiency : Displays the efficiency given by SuperNEC versus frequency.

Network Loss : Displays the total power loss in Watts in any networks in the simulation (transmission lines and two port networks) versus frequency.

Structure Loss : Displays the total power loss in Watts in the actual structure (i.e., wires, due to a non-infinite conductivity or applied loads) versus frequency.

Radiated Power : Displays the calculated radiated power in Watts versus frequency.

Input Power : Displays the input power in Watts versus frequency.

In the case of the Gain Plotter, the format options are:

Gain : Displays the gain at a particular (q, f) angle versus frequency.

Gain Ratio : Displays the ratio of the gain at one (q, f) versus another. This enables one to plot the Front/Back ratio to be plotted.

Options : The options menu controls most of the axes parameters of the plot and generally allows the user to tailor the ‘look’ of the plot. The menu items marked (Boolean) will have a check mark next to the menu item if they are ‘true’.

Some of the Options menu items are not applicable for all plot types. E.g., a Smith Chart does not allow an x or y axis label, or allow axis limits to be changed, since this simply does not make sense. If the menu item is inapplicable, it is disabled (‘greyed out’).

Z₀ : (impedance plotter only) Pulls up a dialog prompting for the system characteristic impedance, Z₀, in Ohms, which is used in the VSWR and the return loss plot formats.

Angles : (Gain Plotter only) Pulls up a dialog box prompting for a (q, f) angle in the ‘forward’ direction and another in the ‘backward’ direction. Obviously if a gain ratio is not required, the ‘backward’ angles can be left at the defaults, as they are ignored. (The default angles are +ve x axis versus -ve x axis.) The same dialog box is used when the user mouse clicks on the title which is automatically generated showing the (q, f) values that are applicable to that plot.

Legend : (Boolean) Whether or not the legend box must be shown.

Grid : (Boolean) Whether or not the gridlines must be shown.

Labels : (Boolean) Whether or not the axis labels must be shown.

Þ Note that the label texts can themselves be edited by a LMB mouse event.

Marker legend : (Boolean) Whether or not to display the legend of the markers.

Axis Limits : Sub menu allowing a choice of ‘Auto’, ‘Manual’ (which pulls up a dialog to set the limits).

Axis Scaling : Sub Menu allowing a ‘Linear’, ‘Semilogx’, ‘Semilogy’ and ‘Loglog’ axis scales.

Ticks : Sub-menu for setting tick marks in both the X and Y direction.

Line 1 : The Line menus. There are six ‘slots’ in the plotters for data. I.e., six different data sets can be overlaid and plotted versus frequency. The six ‘Line’ menus control the attributes of those six lines.

Visible : (Boolean) Whether the line is to be visible or not. If invisible, the corresponding entry in the legend will also be removed.

Colour : Pulls up a Sub-Menu to set the line colour to one of the seven predefined colours. The current line colour will be checked.

Linetype : Pulls up a Sub-Menu to set the line type to one of the 4 predefined Matlab linetypes. The current line type will be checked.

Text : Pulls up a dialog box which sets the legend text associated with that line.

Þ This also assumes that the legend needs to be shown and will plot the legend box if it was not yet plotted.

1.6.4 Mouse Interaction

All other user interaction with the plotters is via the mouse. The mouse button-down events are referred to as LMB, MMB and RMB for Left, Middle and Right mouse buttons respectively.

Þ If your mouse has only two buttons, then an MMB event is usually triggered by a simultaneous LMB and RMB event.

1.6.4.1 The lines

A LMB, MMB, or a RMB event on any data line will pull up a triangular ‘marker’ at the nearest data point. This type of marker will be familiar to anyone who has used an HP Network Analyser. Each marker has a number associated with it, printed just above the triangle and the marker is drawn in the same colour as the data line.

A LMB event on an existing marker, followed by a ‘drag’ will reposition the marker to the nearest data point to the mouse position. The Marker Legend is updated when the mouse button is released.

A RMB event on an existing marker deletes that marker. Any other markers will be renumbered accordingly and the Marker Legend will be suitably updated.

1.6.4.2 The labels

A LMB, MMB, or a RMB on the x and y axis labels will bring up a dialog box which allows the label text to be edited.

Þ Since the x axis label is common to all plot formats (except Smith, of course) it is remembered across plot format changes, whereas the y label will change according to the plot format. Naturally, changes to the label of a particular plot format, will be remembered upon a return to that format.

As a special case in the gain plotter, the (q, f) angles applicable to that plot are automatically added to the ‘title’ label. Any mouse click on this title label will bring the dialog box which allows those angles to be changed.

1.6.4.3 The legend

A LMB or a MMB in the white area of the legend box will start a move operation if a ‘drag’ occurs.

The legend box is placed in the top right corner of the plot by default. No attempt whatever is made to avoid data on the plot. The legend box may be moved anywhere within the plot area and if the mouse is dragged ‘outside’ the limits of the plot, the box will automatically ‘snap’ to that edge.

Þ e.g., To position the legend in the left bottom corner of the figure, drag the legend beyond the bottom left hand corner and release it.

A LMB or a MMB on the text in the legend box pulls up a dialog box allowing the text corresponding to that line to be changed. This is the same as using the ‘Text’ sub-menu of the ‘Line’ menu items.

A RMB anywhere in the legend deletes the legend from the plot. It can be resurrected via the ‘Options’ menu.

1.6.4.4 The marker legend

If markers have been placed on the data lines and the ‘Marker legend’ sub-menu item has been chosen from the ‘Options’ menu, then a LMB anywhere within the marker legend followed by a ‘drag’ initiates a ‘move’ operation, in identical manner to the legend above.

A MMB anywhere in the marker legend will display the ‘alternative’ units. By default, the full complex impedance value is shown at the frequency in question; the alternative value is generally the format of the plot. I.e. in a magnitude plot, the default is the complex impedance and the alternative is the magnitude. In the special case of the Smith Chart, the alternative value is VSWR. For the efficiency plotter, the alternative value is always efficiency.

A RMB anywhere in the marker legend will delete the legend from the plot.

1.6.5 Importing data from other Sources.

It is often necessary to overlay the plots produced by these plotters with data that has been measured. A common need is to overlay impedance data with that measured by a Network Analyser. Software usually exists to extract such data via an HPIB interface and this gets saved in a data file usually in column format. The simplest way to overlay this is as follows:

· Get the plotter up on the screen with the relevant SuperNEC data.

· Load the measured data file using the ‘load’ command. E.g.,

load measured.dat

· Construct the required struct. E.g.,

meas.freq = measured(:,1);

meas.impedance = measured(:,2) + j.*measured(:,3);

· Pass the struct to the plotter with an overlay option. E.g.,

impplot (meas, '-overlay');

The data will appear in the plotter and may be manipulated just like the SuperNEC output data.

1.7 General Features of the Output Viewers

This section discusses general features available in all output viewers. Specifically, Markers (annotation for lines in 2D plots) are discussed in section 1.7.1; Control of lines in 2D plots is discussed in section 1.7.2; and Viewpoint control in 3D plots is discussed in section 1.7.3.

Finally, section 1.7.4 discusses some general problems known to occur in the Output Interface.

1.7.1 Markers

Markers allow you to annotate a 2D plot in SuperNEC. An example of an annotated plot is shown in Figure 7. Once placed, a marker can be moved and the marker legend can be moved anywhere within the plot limits or turned off.

Figure 7 : Markers example.

Markers can be added to the following types of plots:

· 2D Radiation Patterns : radpat2d or radpatplot with 2D radiation pattern data.

· Impedance Plots : impplot.

· Efficiency Plots :effplot.

· Coupling Plots : cplplot

· Gain or Gain Ratio Plots : gainplot.

1.7.1.1 Manipulating Markers

Adding markers is accomplished using the LMB on the line you wish to add the marker to. There is no limit to the number of markers which may be added to a plot (however, eventually the marker legend will become too large for the plot)

Moving an existing marker is achieved by dragging the marker with the LMB to the required position on the line (Dragging is accomplished by holding down the left mouse button while moving the mouse). When you have released the LMB, the new data for the marker will be displayed in the marker legend, if it is visible.

Deleting markers is as simple as clicking the RMB on the marker you wish to remove. Any subsequent markers are renumbered.

1.7.1.2 The Marker Legend

The marker legend displays information about the data at the marker locations. This is different for all plots, but typically consists of the independent value at that point (e.g., angle in a radiation pattern plot) and two dependent values: the ‘raw’ value (the original data, e.g., total gain for the radiation pattern) and the ‘displayed’ value (possibly the vertical component for the radiation pattern).

You can choose whether to show marker legends and where the marker legend is located. All of this is accomplished using menus and/or the legend itself.

Marker legend visibility is controlled using a menu option (usually ‘View | Show Markers’), or by clicking the RMB on the marker legend itself (to make it invisible).

Marker legend position is controlled by dragging the marker legend with the LMB. Note that there is a certain defined rectangle in which you can drag the marker legend (usually inside the plot). If you drag the rectangle outside this area, it will automatically snap to the edge of the rectangle.

Þ The marker legend will remain fixed to each edge of the rectangle you define. This is most useful when you have positioned the marker legend in a corner of a plot and add or remove markers: the legend will remain in that corner.

Displayed values are controlled only through the MMB on the marker legend. This toggles the currently displayed dependent value between the ‘raw’ and ‘displayed’ values. The marker legend heading changes to reflect the current data value being displayed.

1.7.2 Controlling 2D Plot Line Characteristics

All 2D plots in SuperNEC provide the same menu options for changing the properties of lines. This section discusses these properties. All 2D plots can accept a maximum of 6 lines. Each of these lines has a menu option ‘Line<n>‘ where ‘<n>‘ refers to the line number. The menu options available are:

Visible : When checked, the line is visible. When unchecked, the line and any markers on that line are not displayed. Selecting this menu option toggles the status.

Colour : This allows you to select the colour of the line from a list of predefined colours. Currently, user-defined line colour is not supported.

LineType : You can choose between solid, dashed, dash-dotted and dotted line types.

Text : This menu option allows you to change the label of the line. If the label is visible in the figure, you can change the label in the figure and press ‘<ESC>‘ when done. Otherwise, an edit box pops up requesting the new label.

1.7.3 Viewpoint Control in 3D Plots

All SuperNEC 3D plots have the capability of the viewpoint being zoomed, panned and rotated. This allows you to focus on a particular feature of the plot or to view the plot from different angles. This feature is turned on by default in all output viewer plots.

Viewpoint control takes the form of dragging the mouse over the 3D axes. The button held down during the drag defines the action as follows:

· The LMB allows you to rotate the view. Left and right alters the azimuth angle and up and down alters the elevation angle. During the drag, the azimuth and elevation are reported in the Status line if the plot has one.

Þ Start this action at the bottom of the axes to get a better understanding of the rotation action: Dragging left always decreases the azimuth and may confuse you if you are in the back half of the view.

· The MMB (or ‘<Shift>‘-LMB) zooms into (drag up) or out (drag down) of the current view. This has the effect of enlarging or shrinking the displayed object.

Þ The object being viewed may spill over the edges of the figure. This is normal behaviour, as if you were so close you could not see the edges (imagine holding a picture frame up and looking only through the frame; now move towards the image and the edges disappear beyond the frame)

· The RMB (or ‘<Ctrl>‘-LMB) pans the viewpoint, in all four directions. This has the effect of moving you and your viewpoint up, down left or right. This is useful for zooming in on an edge of the image.

Double-clicking at any stage while zoom mode is active resets the view to the normal Matlab view.

Þ This view may appear to be small. Simply zoom in on the present location and you can resize the view to a larger one. The reason the view is small has to do with the original axes position and the viewpoint.

While zooming and/or dragging, a box will appear showing you the new axes position. When you release the mouse button, the figure’s viewpoint changes to match the outline.

Þ This box does not appear when OpenGL rendering is used. This is a feature of Matlab 5.2 and above only. See the Matlab manual for more information.

Þ Sometimes the box will not be visible, particularly when you have zoomed in very close to the image. This is normal behaviour and the zooming/rotating/panning is still functioning.

1.7.4 Known Problems with Output Interface

This section takes the form of a Frequently-Asked-Questions database. Before reporting a bug and if any weird behaviour occurs, check this list to see if a solution has been found.

Why does my 3D view sometimes appear incredibly small or disappear altogether?

This is a known problem with the zooming algorithms and will be fixed in a future release. This problem is most likely to occur when rotating the view to an elevation of 90 degrees (a full ground view). The problem can be solved by double-clicking in the figure to reset the figure’s position and target. You will not lose the rotation view you have specified.

Sometimes my 3D view looks chopped off. I cannot see all my data.

This could be due to two reasons:

1. You have zoomed in so close to a view that some of the data is ‘behind’ your viewing position. Zoom out or double-click to reset the view.

2. You have switched plot types and the viewpoint is not resetting. In this case, please send the data you are viewing and a complete description of this problem to SuperNEC@poynting.ee.wits.ac.za. An example of a good description is:

Run the near-field plotter on enclosed data nrfld and select PColor plot type. Now zoom in so that half the view is outside the screen and switch to Surface view type.

In the interim, double-click on the view to reset the position and target of the viewpoint.

My cylinders are being displayed incorrectly in the structure plotter. What's wrong?

Most likely, your end-cap angles are wrong. Select the data in the NEC Output Viewer and send it to the workspace. If elements 4 and 5 are around 90 degrees, this means your end-caps are almost vertical, which makes for an interesting cylinder!

When Print UIs is selected, I get strange colours in my printouts

There is a bug in the uicontrol printing algorithms in Matlab (version 5.2). The colour of uicontrols is only correct when using a 256-colour display. Print the figure without uicontrols or change your display to 256 colours to print the uicontrols.

I have an OpenGL Graphics card. Why is that option disabled in all viewers?

At the time of release, the OpenGL rendering algorithms in Matlab are considered too buggy to be reliable. However, we have been assured that fixes will be available soon. Hence, the items have been greyed out, but the features have not been removed.

1.7.5 Generic File Menus

All of the output viewer GUIs have the capability of saving a figure to disk, or printing figures to a file or printer. These capabilities are standard to all viewers and access through the ‘File’ menu. The following items in the ‘File’ menu are part of the saving/printing interface:

Save : Saves the file to a Matlab ‘m’ and ‘mat’ file combination which you can execute to restore the figure.

Þ Although the figure is restored with many user interface controls, it may be possible that the figure is no longer completely interactive. However, the display will look the same as the original figure.

Print : Brings up a cross-platform print dialog that enables you to select the device and whether to print to a file or to a printer.

Print to File : Shows a dialog from which one can specify a file to which the current figure should be saved. The dialog also provides a means for choosing the file format.

Page Setup : Opens a page setup dialog. Change the settings and press ‘OK’ to update the page settings for the figure.

Þ If you are continually changing settings to the same values, you may want to store them in your ‘matlabrc.m’ file. Contact support at ‘SuperNEC@poynting.ee.wits.ac.za’ for more information on how to do this.

Print Uis : If this setting is checked, User Interface controls are printed with your figure. This may be useful for example to document some of the settings on the figure.

Close : Closes the figure.

Other items in the ‘File’ menu are discussed in the specific viewer documentation.

1.8 Output Interface Command-Line Reference

This section documents the command-line interface for the output portion of SuperNEC. Commands and functions used to query output files, obtain data and visualise output data, are presented in this chapter.

The SuperNEC package has been designed to allow both graphical and command-line interaction with NEC structures. Although the emphasis in previous chapters has been on graphical interfaces, almost all of the functionality of the graphical interface is available through command-line functions as well. This chapter discusses these functions.

1.8.1 Organisation of this Chapter

This chapter has been designed more as a reference than an introduction. The user is referred to previous chapters for introductory usage of these commands.

Section 1.8.2 provides a quick reference guide to functions and methods. This takes the form of tables of functions with single-line descriptions. The tables are broken up into specific areas of the output interface, viz. viewers, data loading and general functions. A reference to the page detailing each function is given in the quick reference table.

After the quick reference tables, a discussion of the NEC data pool concept is given in section 1.9.

1.8.2 Output Interface Quick Reference Tables

The following tables provide a summary of the functions defined in the output interface. The tables are presented in three categories:

· Viewers, which document all of the output viewer functions (which create figures with uicontrols)

· Data loading which documents the sndata object and methods

· General Functions which documents other functions which are part of the output interface.

snecout	NEC output file reader GUI
nrflgplot	3D near-field plotter.
radpat2d	2D radiation pattern plotter
radpat3d	3D radiation pattern plotter
radpatplot	Radiation pattern plotter executive; handles 2d and 3d data.
structplot	Structure plotter including currents and charges.
cplplot	Coupling plotter.
effplot	Efficiency vs. frequency plotter, including structure losses, etc.
impplot	2D impedance vs. frequency plotter, including Smith charges, VSWR plots, etc.
gainplot	Gain or gain ratio vs. frequency plotter.

Table 2 : SuperNEC output interface viewers

sndata	Load or append an output file to NEC data pool
charge	Obtain charge data
couple	Obtain coupling data
current	Obtain current data
imped	Obtain impedance data
neare	Obtain near electric field data
nearh	Obtain near magnetic field data
power	Obtain power data
rpfield	Obtain radiation pattern (far field) field data
rpgain	Obtain radiation pattern (far field) gain data
struct	Obtain geometry data
summary	Obtain summary of NEC data pool
surfield	Obtain surface field data

Table 3 : SuperNEC output interface data loading functions.

necstruct	Describes the data structure of SuperNEC geometry data
smithgrid	Draw a Smith chart grid
Vswr	Compute VSWR from impedance data

Table 4 : SuperNEC output interface general functions.

1.9 SuperNEC Data Pool - Command-Line Access to SuperNEC Results

The Matlab interface to SuperNEC provides both command-line and graphical access to data from a SuperNEC simulation. The graphical access is discussed from section 1 onwards. This section describes command-line accessibility. The command-line access is more complete than the graphical form, since not all information from a SuperNEC simulation can be visually interpreted.

The result of a SuperNEC (or NEC) simulation is an ASCII output file. This output file contains information about the original commands used to perform the simulation and all output results calculated and requested by the simulation. Before it can be usefully interpreted, a parser must interpret each line to extract the meaning. The result in this Matlab interface is an object which can then be manipulated. However, for speed and memory considerations, the data is first loaded into a common memory pool (This memory pool resides in the memory space of the function snres and is cleared whenever the function snres is cleared.). Each request to parse a file results in one or more models, which contain the result of all simulations performed on a single NEC model (or geometry), being added to the SuperNEC data pool. Various functions then allow you to access that data from Matlab. These functions, as well as the data loading function sndata, are listed in 1.9.

All command-line access should consist of the following steps:

· Load the data into the common pool using sndata. See the sndata command for an example.

· If you wish to compare multiple results files, load those into the common pool using sndata.

· From now until you no longer need the data, do not clear the function ‘snres’! This will clear all your data. Note that the Matlab statement ‘clear all’ or ‘clear f