There are various types of functions in NC. Among them are the model function, the control function, numerous built-in functions, and user defined functions.

The model function describes antenna geometries and defines environmental parameters such as frequency and grounds. The simplest NC program consists of a single model function.

When the Run button in the NC window is clicked, cocoaNEC compiles the contents of the model function into an internal representation called a directed acyclic graph where each DAG node is a Cocoa object. If no errors are found, cocoaNEC then interprets ("executes") the graph ("code") from the model function once to generate an NEC-2 card deck file.

If a control function is not present, cocoaNEC sends the card deck file to NEC-2 or NEC-4 to be processed.

If a control function is present, cocoaNEC will not directly execute the code from the model function after the compilation phase. Instead, cocoaNEC compiles the model and control functions, and proceed to execute the code that is created by the control function instead of the model function. Code in the model function is executed when the model function is explicitly execute by the use of the runModel function call from the control function. By including more than one runModel function call in the control function (or a runModel inside a repeat loop inside the control function), the model function can be run multiple times, each time with a different set of global parameters.

After each runModel function call, and after NEC-2 or NEC-4 has finished computing, the control function has the capability to inspect some of the results in the NEC output listing. This is a mechanism to automatically "optimize" an antenna.

The control function is the only function in NC that can access results from NEC.

Both the model and control functions can call built-in and user defined functions. If you have a control function, you can generate a card deck by calling user defined functions instead of using runModel.

Additionally, NC provides a set of extended functions that are not directly translated into NEC cards. These include terminations, coax and twin lead models, insulated wire models, etc.

The rest of this section describes the NC built-in functions. For information on user defined functions, see here.

Geometry Functions

wire( x0, y0, z0, x1, y1, z1, radius, segments )
    Generates a wire element from coordinate ( x0, y0, z0 ) to (x1, y1, z1 ). With wire radius and number of segments. The result is a reference of type "element."

    The number of segments is changed to an odd number if the number that is passed into the function is an even number; this is to make sure the wire is fed in the exact center when an excitation is placed on the wire.
line( x0, y0, z0, x1, y1, z1, radius, segments )
    Same as wire (above), but the number of segments is not changed by cocoaNEC.
taperedWire( x0, y0, z0, x1, y1, z1, radius, segmentLength0, segmentLength1 )
    This is also similar to the wire function above, but segmenting information is not specified as a number but is instead specified as the segment length in units of wavelengths. segmentLength0 is the segment length at the first end of the wire and segmentLength1 is the segment length of the second end of the wire. NC will generate a wire made up of segment lengths that matches the two ends and follows a geometric progression (note: not arithmetic progression). If there is an excitation, load or network card on the wire, a segment for the excitation (etc.) will be placed at the middle segment of the wire.
In addition to the geometry functions above that use scalar numbers to specify coordinates, you can describe wire geometries using vector variables (see Vectors and Transforms). These are (please note that their names end with a "v"):

wirev( t, v0, v1, radius, segments )
linev( t, v0, v1, radius, segments )
taperedWirev( t, v0, v1, radius, segmentLength0, segmentLength1 )
    >v0 and v1 are vectors that represent coordinates in 3-space. In addition to the vectors and v1, the vector functions include a transform variable t. The transformation represented by the transform variable t is applied to v0 and v1 before the results are used to generate the actual coordinates for the wires. This allows you to rotate or move the wire element by just modifying the transform variable t.

    The other variables in the vector version of the geometry functions are the same as their counterparts in the scalar versions of the functions.

    The keyword nil can be used in place of the transform variable for the case where a transformation is not used. In this context, nil is equivalent to using identityTransform().
Card Deck Geometry Functions

The following are NC functions that can be used in NC programs to directly generate a NEC-2 card. You can think of this as analogous to "in-line assembly language".

wireCard( x0, y0, z0, x1, y1, z1, radius, segments, rX, rY, rZ, tX, tY, tZ )
    The wireCard function is similar to the wire function, except that wireCard includes 6 additional real arguments that define a geometric transformation -- the parameters rX, rY and rZ are rotation parameters and the parameters tX, tY and tZ are translation values as defined by the GM card of a NEC card deck. This is not the general affine transformation that is available in NC, but the specific non-concatenatable GM transform in NEC. The 6 parameters are used to create a NEC GM card when the values are not all zero. For details, please refer to the NEC documentation of the GM card.
arcCard( arcRadius, startAngle, endAngle, wireRadius, segments, rX, rY, rZ, tX, tY, tZ )
    The arcCard function generates a NEC GA card. The arcRadius, startAngle endAngle and wireRadius are real-valued variables and the segments argument is an integer. The transformation arguments are as defined in the wireCard function above. The angles are in degrees, and the orientation of the arc and the angles are referenced as in the NEC documentation. The plane of the arc can be rotated and the arc can be translated per the last 6 arguments.
helixCard<( spacing, helixLength, r0, r1, wireRadius, segments, rX, rY, rZ, tX, tY, tZ )
    The helixCard function generates a NEC GH card. The spacing, helixLength, r0, r1 and wireRadius are real-valued variables and the segments argument is an integer. The transformation arguments are as defined in the wireCard function above.

    The spacing parameter is the pitch of the helix (analogous to the distance between adjacent threads of a screw).

    r0 determines the x location of the the helix strand at z = 0, and determines the radius of the helix at z = helixLength. The helix spirals around the z axis starting at the coordinate (r0, 0, 0), but can be rotated and/or translated per the 6 last arguments of the helixCard function call.

    Please note that there are no separate x0,y0 and x1,y1 radial terms for the NEC-2 GH card, just the r1 and r2 terms for the NEC-4 GH card. This is to allow the use of the same helixCard call with both NEC-2 and NEC-4. NEC-2 and NEC-4 have different GH card formats.
patchCard( x1, y1, z1, nElevation, nAzimuth, patchArea, rX, rY, rZ, tX, tY, tZ )
    The patchCard function generates a NEC SP card for an arbitrarily shaped surface patch. The arguments x1, y1, z1, nElevation, nAzimuth and patchArea are real-valued variables. x1, y1 and z1 determine the center of the patch. The nElevation and nAzimuth arguments determine the elevation and azimuth angles of the surface normal. The transformation arguments are as defined in the wireCard function above and let you move the patch and its orientation.
rectangularPatchCard( x1, y1, z1, x2, y2, z2, x3, y3, z3, rX, rY, rZ, tX, tY, tZ )
    The rectangularPatchCard function generates a NEC SP card and a companion SC card for a rectangle surface patch. The arguments x1, y1, z1, x2, y2, z2, x3, y3 and z3 are real valued-variables that determine the three corners that uniquely defines the rectangle, as defined in the NEC manual. The transformation arguments are as defined in the wireCard function above and let you move the patch and its orientation.
triangularPatchCard( x1, y1, z1, x2, y2, z2, x3, y3, z3, rX, rY, rZ, tX, tY, tZ )
    The triangularPatchCard function generates a NEC SP card and a companion SC card for a triangular surface patch. The arguments x1, y1, z1, x2, y2, z2, x3, y3 and z3 are real-valued variables that determine the corners of the triangle, as defined in the NEC manual. The transformation arguments are as defined in the wireCard function above and let you move the patch and its orientation.
quadrilateralPatchCard( x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4, rX, rY, rZ, tX, tY, tZ )
    The quadrilateralPatchCard function generates a NEC SP card and a companion SC card for a quadrilateral surface patch. The arguments x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4 and z4 are real-valued variables that determine the four corners of the quadrilateral, as defined in the NEC manual. The transformation arguments are as defined in the wirecard function above and let you move the patch and its orientation.
multiplePatchCard( nx, ny, x1, y1, z1, x2, y2, z2, x3, y3, z3, rX, rY, rZ, tX, tY, tZ )
    The multiplePatchCard function generates a NEC SM card and a companion SC card for a multiple patch surface. The arguments nx and ny are integer values that describe the NX and NY parameters in the NEC SM card. The arguments x1, y1, z1, x2, y2, z2, x3, y3 and z3 are real-valued variables that determine the corners of each rectangular patch, as defined in the NEC manual. The transformation arguments are as defined in the wireCard function above and let you move the patch and its orientation.
Vector Functions

vect( x, y, z )
    Creates a vector for the coordinate (x, y, z) where x, y and z are reals (integers will be converted to reals).
Transform Functions

identityTransform()
    Returns an identity transform.
translateTransform( v )
    Returns a translation transform, where v is a vector that represents the translation amount.
rotateX( d )
    Returns a transform that rotates around the x-axis. d is a real parameter that specifies the rotation angle in degrees.
rotateY( d )
    Returns a transform that rotates around the y-axis. d is a real parameter that specifies the rotation angle in degrees.
rotateZ( d )
    Returns a transform that rotates around the z-axis. d is a real parameter that specifies the rotation angle in degrees.
matrixElement( t, i, j )
    Returns the real value of the (i,j) element of the 3x3 matrix of the transform t, (0 <= i,j < 3 ).
translationElement( t, i )
    Returns the real value of the i-th component of the translation of transform t, (0 <= i < 3).
transformWithMatrix( a11, a12, a13, a21, a22, a23, a31, a32, a33 )
    Returns a transform whose matrix elements are a11, a12, ..., a33, with no translation. Use to obtain a transform with an arbitrary 3x3 matrix.
Trigonometric Functions (radians)

sin( theta ) - sine of an angle in radians
cos( theta ) - cosine of an angle in radians
tan( theta ) - tangent of an angle in radians
asin( x ) - arc sine of a value, result in radians
acos( x ) - arc cosine of a value, result in radians
atan( y/x ) - arc tangent of a value, result in radians
atan2( y, x ) - arc tangent of a two dimension coordinate, result in radians with 4 quadrants

The results are "real" values.

Trigonometric Functions (degrees)

sind( theta ) - sine of an angle in degrees
cosd( theta ) - cosine of an angle in degrees
tand( theta ) - tangent of an angle in degrees
asind( x ) - arc sine of a value, result in degrees
acosd( x ) - arc cosine of a value, result in degrees
atand( y/x ) - arc tangent of a value, result in degrees
atan2d( y, x ) - arc tangent of a two dimension coordinate, result in degrees with 4 quadrants

The results are "real" values.

Mathematical Functions

sqrt( x ) - square root of x
pow( y, x ) - y to the power of x
exp( x ) - exponent of x
ln( x ) - natural log of x. I.e., inverse of exp(x)
log10( x ) - log base 10 of x
log( x ) - same as ln(x)
abs( x ) - the absolute value of an int
fabs( x ) - the absolute value of a real number

sinh( arg ) - hyperbolic sine
cosh( arg ) - hyperbolic cosine
tanh( arg ) - hyperbolic tangent
asinh( arg ) - inverse hyperbolic sine
acosh( arg ) - inverse hyperbolic cosine
atanh( arg ) - inverse hyperbolic tangent

Mathematical Constants
pi - ratio of circumference to diameter of a circle, i.e., 3.141592653589793...
c - speed of light in kilometers per millisecond, i.e., 299.7924... (frequency in MHz = c divided by wavelength in meters)

Element Feeding (Excitations)

voltageFeed( element, real, imag )
voltageFeedAtSegment( element, real, imag, segment )
    Feed the center of the wire element with a real and imaginary voltage. In the case of voltageFeedAtSegment>, feed the specific segment, rather than the center of the element. Segment numbers start at 1.
currentFeed( element, real, imag )>
currentFeedAtSegment( element, real, imag, segment )
    Feed the center of the wire element with a real and imaginary current. In the case of currentFeedAtSegment, feed the specific segment, rather than the center of the element. Segment numbers start at 1.
incidentPlaneWave( element, theta, phi, eta )
    Excite the wire element with a plane wave.
rightPolarizedIncidentPlaneWave( element, theta, phi, eta )
    Excite the wire element with a right-hand elliptically polarized plane wave.
leftPolarizedIncidentPlaneWave( element, theta, phi, eta )
    Excite the wire element with a right-hand elliptically polarized plane wave.
Element Loading (Loads and Traps)

impedanceLoad( element, R, X )
impedanceAtSegments( element, R, X, fromSegment, toSegment )
    Attaches a load of R+jX to a middle of a wire element, or in the case of impedanceAtSegments, to a range of segments. The range of segments includes fromSegment and toSegment. Segment numbers start at 1.
lumpedSeriesLoad( element, R, L, C )
distributedSeriesLoad( element, R, L, C )
seriesLoadAtSegments( element, R, L, C, perLength, fromSegment, toSegment )
    Attaches a series connected RLC load to a middle of a wire element or within a range of segments for the case of seriesLoadsAtSegments. The range of segments includes fromSegment and toSegment. Segment numbers start at 1. The distributedSeriesLoad case assumes that the R, L and C values are specified in units per meter, as with the seriesLoadsAtSegments case with the perLength argument is set to any non-zero value.
lumpedParallelLoad( element, R, L, C )
distributedParallelLoad( element, R, L, C )
parallelLoadAtSegments( element, R, L, C, perLength, fromSegment, toSegment )
    Attaches a parallel connected RLC load to a middle of a wire element or within a range of segments for the case of parallelLoadsAtSegments. The range of segments includes fromSegment and toSegment. Segment numbers start at 1. The distributedParallelLoad case assumes that the R, L and C values are specified in units per meter, as with the seriesLoadsAtSegments case when the perLength argument is set to any non-zero value.
resistiveLoad( element, R )
inductiveLoad( element, L )
capacitiveLoad( element, C )
    Attaches a resistive, inductive or capacitive load to a middle of a wire element
conductivity( element, sigma )
    Sets the conductivity of the entire wire element, expressed in mhos/meter. In the case of conductivityAtSegments, only apply the conductivity to a range of segments.
Terminations

For terminating loads, see Extensions Page.

Insulated Wires

insulate( element, permittivity, conductivity, radius )
    Adds an insulating sheath of dielectric or lossy material to a wire element.

    The permittivity argument specifies the relative permittivity of the sheath material. The conductivity of the sheath material in expressed in Siemens/meter. The radius parameter must be greater than the radius of the embedded wire element.
For NEC-4, insulated wires is implemented with the IS (insulated sheath) card.

The IS card is not available on NEC-2. When insulate is called with NEC-2, cocoaNEC will instead use the Yurkov approximation in place of a NEC-4 IS card.

For direct access to the Yurkov approximation, and also to the W4RNL insulation approximation, see Extensions page.

Networks and Transmission Lines

network( element1, element2, y11r, y11i, y12r, y12i, y22r, y22i )
networkAtSegments( element1, seg1, element2, seg2, y11r, y11i, y12r, y12i, y22r, y22i )
    Place a passive Y parameter two port network between the centers of element1 and element2. In the case of networkAtSegments, the network is connected at the specified segments instead of the centers of the elements.
transmissionLine( element1, element2, z0 )
crossedTransmissionLine( element1, element2, z0 )
transmissionLineAtSegments( element1, seg1, element2, seg2, z0 )
    Transmission line of impedance z0 between centers of element1 and element2, the crossed version has a 180 degree reversal. In the case of transmissionLineAtSegments, the transmission line is not connected at the centers of the two elements, but at the specified segment. You can cross the transmission line by sending the negative value of the impedance.
longTransmissionLine( element1, element2, z0, length )
crossedLongTransmissionLine( element1, element2, z0, length )
    Transmission line of impedance z0 between element1 and element2, of given length (m), crossed version with 180 degree reversal.
terminatedTransmissionLine( element1, element2, z0, length, y1r, y1i, y2r, y2i )
crossedTerminatedTransmissionLine( element1, element2, z0, length, y1r, y1i, y2r, y2i )
    Transmission line with admittance termination y1 on one end and y2 on the other end.
Physical Coax and Twin-lead Transmission Lines.

Please see Extensions page.

Frequency

setFrequency( f ) - remove any existing frequency selection(s) and set frequency of sources to f, in MHz.
addFrequency( f ) - add an additional frequency with f, in MHz.
frequencySweep( f0, f1, n ) - add n equal spaced frequencies from f0 to f1 (inclusive). f0 and f1 are in MHz.

Grounds

ground(relative dielectric constant, conductivity)
Use to set custom ground parameters. Conductivity is in mho/m.

freespace()
Nullifies the ground parameters and sets up freespace conditions (no ground plane). All other cases below model the effect of an infinite flat ground plane.

perfectGround()
Sets ground parameters for an ideal perfectly-conducting ground plane.

poorGround()
averageGround()
goodGround()
saltWaterGround()
freshWaterGround()
These functions set ground parameters commonly used for varies types of earth with finite conductivity.

useSommerfeldGround(state) - (state = 1 is yes, 0 is no).
By default, NEC uses a reflection-coefficient approximation for finitely-conducting earth. When useSommerfeldGround() state is yes, cocoNEC 3 uses the NEC-4.2 GN3 ground, involving Sommerfeld integrals.

Radiation Patterns (Antenna Patterns)

azimuthPlotForElevationAngle( angle ) - elevation angle in degrees.
elevationPlotForAzimuthAngle( angle ) - azimuth angle in degrees.

Radials

necRadials( length, wire radius, number of radials )
radials( x, y, z, length, wire radius, number of radials ) - ( x, y, z ) is center of radials.

Optimization Functions and Results

The following functions only available inside a control() function.

runModel()
vswr( feedNumber )
feedpointImpedanceReal( feedNumber )>
feedpointImpedanceImaginary( feedNumber )
feedpointVoltageReal( feedNumber )
feedpointVoltageImaginary( feedNumber )
feedpointCurrentReal( feedNumber )
feedpointCurrentImaginary( feedNumber )

The following are variables that can be used in a control() function to access the results from the NEC engine:

maxGain
averageGain
azimuthAngleAtMaxGain
elevationAngleAtMaxGain
directivity
frontToBackRatio
frontToRearRatio

Other Functions

printf( format string, varargs ) - Use to log variables in the Output Console.

pause( seconds ) - Use in control() to delay after calling runModel.

useExtendedKernel( state ) - Use Extended thin-wire kernel approximation (state = 1 is yes, 0 is no).

keepDataBetweenModelRuns( state ) - When the argument is set to 1 previously plotted feed points in the Smith Chart and the Scalar chart are not erased before new data is drawn.

useQuadPrecision( state ) - When state = 0, use double precision. When state = 1, use quad precision.