cocoaNEC 2.0 Reference Manual
Kok Chen, W7AY
[w7ay (at) arrl.net]
Last updated: May 7, 2008
There are three parts to the cocoaNEC Reference Manual.
This part of the reference manual describes the elements
that are common to the spreadsheet Interface and the NC
programming language. Part II of the reference manual
describes the elements of the spreadsheet interface, Part
III of the manual describes the elements of the NC
programming language.
cocoaNEC Interface
The three cocoaNEC interfaces are accessed with the File
Menu.
The menu items in the top
section of the File Menu are used open a spreadsheet
interface. The menu items in the section below that are
used to open NC interface and the menu items in the section
below that are menu items to open NEC-2 Card Decks.
The Save and Save As... menu items are
common to all three interfaces. The currently active window
will be saved to a file. The default file extension for a
spreadsheet model is ".nec", the default file extension for
an NC file is ".nc" and the default file extension for a
card deck is ".deck".
You can export a spreadsheet model or an NC program as a
NEC-2 card deck by using the Export Card Deck... .
Many other antenna programs are cable of reading NEC-2 card
decks.
The Close (Command W) menu item will close the
active window.
Output data files that are generated by NEC-4 programs can
be directly read and and displayed in cocoaNEC's Output
window as if they are processed by cocoaNEC models:
Print Output View is
discussed in the next section.
cocoaNEC has an embedded NEC-2 engine that is based on the
nec2c program. cocoaNEC can also use the NEC-4 engine. For
details, see here.
Output Window
The cocoaNEC Output window is used to inspect the data from
the NEC-2 engine. The Output window is automatically opened
after NEC-2 successfully processes a deck. You can also
open the window with the Output Viewer menu item
in the Window menu of the main menu.
The graphical information in the Output window is culled
from the line printer output from the NEC-2 engine. The
line printer output from NEC-2 is displayed in the NEC2
Output tab view of the Output window.
The Figure 1 below shows a typical view of the Output
window, opened to the "SWR" view.
Figure 1 - SWR
Panel
As shown in the above figure,
the impedance of the feed point of an antenna is shown on a
Smith Chart. The reference resistance, in this case 50
ohms, is display on the top left of the window. This
represents the impedance of the center of the Smith Chart.
The impedance of the antenna is displayed at the bottom
right of the window, together with the VSWR.
There are two gray circles within the Smith Chart that are
concentric with the chart. The smaller circle is the 2.0:1
VSWR contour and the larger circle is the 3.0:1 VSWR
contour.
You can change the reference resistance of the Smith Chart
(and VSWR computations) by selecting the rightmost tab
button (Options) in the Output window and changing the
"Reference Zo" field.
Figure 2 - Options
Panel
If the cocoaNEC antenna model
includes a frequency "sweep," the antenna impedance for
each frequency will show up as a green dot on a Smith
chart. The frequencies that represent the end points in the
sweep are shown to the right of the dots.
Figure 3- SWR Sweep
The Elevation tab button in the Output window
takes you to the far field elevation radiation pattern of
the antenna.
Figure 4- Elevation
Pattern
The reference gain ("0 dB") for
the outer circle is shown on the top left of the plot as dB
referenced to an isotropic antenna. The gains for the inner
circles are labeled along the horizontal axis that extends
towards the right.
Notice that the logarithmic scale of the plot places the
-10 dB point about halfway out from the center. This
represent a scale factor of 0.89 per 2 dB, and is the
standard which is used in ARRL publications. There are two
other scale factors that you can choose in the Options
panel (see Figure 2 above). Figure 5 shows the pattern from
the same antenna as Figure 4, but with the scale factor of
0.80, to expand the region that is lower than -10 dB.
Figure 5 - Elevation
Pattern plotted at a scale of 0.80 per 2 dB
You can also expand the antenna pattern for the region
below -10 dB by choosing a scale factor of 0.92 per 2 dB.
The far field azimuth radiation pattern of the antenna can
be similarly viewed by selecting the Azimuth
panel.
Reference Plot
When you change some modeling parameters and run the same
model again, the output will replace the existing one.
However, if you have run multiple models during a cocoaNEC
session, the output for each model is saved into a
different context, and you can quickly retrieve any context
using the menu at the top of the Output window:
Figure 6 - Model
selection
When you no longer need an output, you can remove the
current selection by using the minus button on the
right of the selection menu.
NEC-2 and NEC-4 "runs" from the same model will create
different contexts. You can therefore compare NEC-2 outputs
with NEC-4 outputs. NEC-4 contexts will have a "(NEC-4)"
label in the context name.
cocoaNEC has a built in shortcut for you choose the current
selection as the "reference antenna." Simply go to the
Output Menu in the Menu Bar and select Use As
Reference.
Figure 7 - Setting a model
to be used as the reference antenna
cocoaNEC will now remember that
you want to use this antenna as the reference. In addition,
as shown in Figure 8, a dark gray square will appear to the
left of the selection menu each time you display this
antenna in the selection menu to remind you that it is
being used as the reference antenna.
Figure 8 - Reference
antenna indicator
Once you have chosen a
reference antenna, its plot will appear superimposed in the
plots of the other antennas that you select, as shown in
Figure 9.
Figure 9 - Elevation plot
together with a reference antenna
Notice the "Use Previous Run as Reference" Menu item in
Figure 7. Instead of using a different antenna model as the
reference, you can also use the most recent run from the
same model as the reference. If you select the "Use
Previous..." as an output option, you will be able to see
your progress as you change parameters of the model from
one run to the next.
The SWR View also places the feed point impedance(s) of the
chosen reference antenna into the Smith Chart, drawn as a
gray disc, as shown below:
Multiple Plots
There are other ways where multiple plots are superimposed
in the same view. These are controlled from the models
themselves (either from the spreadsheet or from the NC
descriptions). The following two figures show multiple
plots obtained from a frequency sweep, and from choosing
multiple azimuth patterns with different elevation angles.
Figure 10 - Elevation
plots for different Frequencies
Figure 11 - Azimuth plots
for different Elevation Angles
Polarization
cocoaNEC's output window defaults to plotting total power.
The NEC-2 engine also provides power gains for horizontal
and vertical polarizations. You can select which one to
plot in the Polarization menu in the Options panel
(Figure 2 above).
Geometry and Currents
The Geometry tab button takes you to the panel that shows
the geometry of the antenna. The geometry is scaled so that
the antenna dimensions remain contained in the view
whatever view angle is selected. Figure 12 shows what a two
element Yagi-Uda looks like in the geometry view.
Figure 12 - Geometry
View
The two fields at the bottom left of the window control the
viewing angle relative to the centroid of the antenna. An
elevation angle of 0 places the eye at the same height as
the centroid. An elevation angle of 90 degrees corresponds
to placing the eye straight above the centroid and looking
back at the antenna from the +z axis. An elevation angle of
-90 degrees corresponds to placing the eye below the
centroid and looking up at the antenna from the -z axis.
An azimuth angle of 0 corresponds to placing the eye on the
+x axis and looking back at the antenna. An azimuth angle
of 90 degrees corresponds to placing the eye on the +y
axis.
You can either set the angle by typing directly into the
fields, or by using the up and down stepper arrow buttons.
The buttons autorepeat, so you can hold down the button and
see an animation. The elevation angle has hard stops at -90
degrees and +90 degrees. The azimuth angle wraps around the
circle, with 360 degrees wrapping back to 0.
The Currents menu at the bottom right of the
window can be set to None, Scaled Magnitude, Magnitude,
Magnitude and Phase, and Magnitude and Relative
Phase.
With the Currents menu set to None, antenna
current information is not plotted. When the Currents menu
is set to Magnitude, the colors of the antenna
segments correspond to the magnitudes of the current.
Maximum current appears as a bright yellow and zero current
appears as dark gray. A scale is shown on the bottom left
corner of the view. The Scaled Magnitude
selection is similar to Magnitude selection except the low
current portions are stretched.
When the menu is set to Magnitude and Phase, the
currents appear as colors in the HSV color space. The phase angle of a
current corresponds to the hue of the color, and the
magnitude of a current corresponds to the value of the
HSV color (brighter colors carry larger currents). The
colors that correspond to the various phase angles for
the maximum current are shown in the color wheel on the
bottom left corner of the view.
The slider at the top left of the view magnifies the
structure geometry from the original 1x continuously up to
a scale factor of 16x. You can also "pan" the drawing up
and down and left to right by holding down the mouse in the
view and dragging the cursor while the mouse button is held
down. While the mouse is held down inside the Geometry
view, the cursor turns from an arrow to an open hand.
When the Geometry view is panned, a re-center button will
appear and you can reset the panning action with the
button:
The following shows the
Magnitude and Phase view of a Half Square antenna
with a reflector (note the scale slider has also been moved
to magnify the image slightly):
Figure 13 - Currents in
Magnitude and Phase (HSV Color)
The Magnitude and Relative
Phase setting is similar to the Magnitude and
Phase setting except all phase angles are referenced
to the phase of the current in the segment with the largest
current.
Sources and Loads
Voltage sources are drawn as open circles in the Geometry
view. Current sources are drawn with a double circle.
Loads such as impedance and RLC loads are displayed in the
Geometry view as small crosses.
Radials
Both the spreadsheet interface and NC in cocoaNEC have
provisions for adding radial wires. In addition to the
convenience factor, wires that are added with the special
radials mechanism are specially tagged so that the Output
window can avoid drawing them in the geometry panel.
The default state is to not draw the radials, but you can
force cocoaNEC to draw them by checking the Draw
Radials box in the Options panel (see Figure 2 above).
Figure 14 shows a dipole on top of a set of radials with 19
spokes.
Figure 14 - Drawn Radial
Wires
Directivity
Both the spreadsheet interface and the NC interface
automatically generate a far field radiation pattern over
the entire sphere at a resolution of 6 degrees. The post
processor averages the power over the entire volume and
divides that into the peak power that it finds. This number
is then converted to decibels and reported as the
directivity of the antenna in the Summary
panel of the Output window and also at the top right
corners of the azimuth and elevation plots. You might also
find other parameters of interests, such as front-to-back
and front-to-rear ratios and the azimuth and elevation
angles where the maximum gain was found, in the Summary
panel.
Summary
The Summary tab button takes you to a panel that shows the
azimuth plot, elevation plot and distilled NEC-2 output in
the same view:
Efficiency of the antenna will also be displayed in the
summary text if it is not 100%.
3-D Radiation Plot
The 3D tab button takes you to the
3-dimensional far field radiation plot.
The Azimuth text field below the plot allows you
to rotate the pattern. You can also change the azimuth
angle in increments of 15 degrees by using the stepper
arrows. The Contrast slider lets you fine tune the
contrast.
The radio buttons allow you to choose between two styles of
shading. When you choose Shape, the brightness of
a surface patch is based on the angle between the surface
normal and the direction of the antenna pattern. When you
select Gain, the brightness of a surface patch is
proportional to the antenna gain in the direction of the
antenna pattern.
You can change the plot's logarithmic scale in the Options
panel of the Output window (the default gain is the ARRL
ratio of 0.89 per 2 dB) . You can also change the
polarization of the 3D antenna pattern in the Options
panel.
The 3-D radiation pattern takes a considerable time to
compute, both when generating the pattern in the NEC-2
engine and when drawing in the Output window. If you have
no intention to inspect the 3D plot, you can reduce the
time used by the NEC-2 engine by disabling the generation
of RP cards for the 3D radiation pattern:
Please note that this state is not saved to the cocoaNEC
plist. To avoid confusion, the default state when you
launch cocoaNEC is to always enable 3D patterns.
Printing
You can print the currently opened view in
the Output Window by selecting the Print Output
View (Command-P) menu item in the File Menu. The
following figure shows what the printed output of the 3D
gain plot (of a 2 element phased vertical dipoles in free
space) looks like:
Documentation
You can open the cocoaNEC web documentation
in the default web browser from a Documentation menu in the
main menu of occoaNEC:
