NC Functions


There are various types of functions in NC. Among them are model, control, system, user defined and card functions.

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.

A model function is the shortest way in NC to describe antenna geometries and define 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 ("execute") 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 a 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 system and user defined functions. Indeed, if you have a control function, you can generate a card deck by calling user defined functions instead of using runModel.

The rest of this section describes the NC system calls. For information on user defined functions, see here. There is also a set of functions that can directly generate a NEC-2 card, see here. As mentioned above, extensions can be found 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 v0 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 are primarily created for used by the Spreadsheet model, but can also be used in any 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-2 card deck. This is not the general affine transformation that is available in NC, but the specific non-concatenatable GM transform in NEC-2. The 6 parameters are used to create a NEC-2 GM card when the values are not all zero. For details, please refer to the NEC-2 documentation of the GM card.

arcCard( arcRadius, startAngle, endAngle, wireRadius, segments, rX, rY, rZ, tX, tY, tZ )

The arcCard function generates a NEC-2 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-2 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-2 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 r1 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-2 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 determines the center of the patch. 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 lets 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-2 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-2 manual. The transformation arguments are as defined in the wireCard function above and lets 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-2 SP card and a companion SC card for an 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-2 manual. The transformation arguments are as defined in the wireCard function above and lets 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-2 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-2 manual. The transformation arguments are as defined in the wirecard function above and lets 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-2 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-2 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-2 manual. The transformation arguments are as defined in the wireCard function above and lets 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).

To obtain a transform with an arbitrary 3x3 matrix, use:

transformWithMatrix( a11, a12, a13, a21, a22, a23, a31, a32, a33 )

Returns a transform whose matrix elements are a11, a12, ..., a33, with no translation.

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 )
conductivityAtSegments( element, sigma, fromSegment, toSegment )

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, electricalLength )
crossedLongTransmissionLine( element1, element2, z0, electricalLength )

Transmission line of impedance z0 between element1 and element2, of given electrical length, crossed version with 180 degree reversal.

terminatedTransmissionLine( element1, element2, z0, electricalLength, y1r, y1i, y2r, y2i )
crossedTerminatedTransmissionLine( element1, element2, z0, electricalLength, 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

freespace()
poorGround()
averageGround()
goodGround()
perfectGround()
saltWaterGround()
freshWaterGround()
ground( relative dielectric constant, conductivity ) - conductivity is in mho/m.

useSommerfeldGround( state ) - use Sommerfeld-Norton approximation (state = 1 is yes, 0 is no).


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 NEC-2:

maxGain
averageGain
azimuthAngleAtMaxGain
elevationAngleAtMaxGain
directivity
frontToBackRatio
frontToRearRatio


Other Functions

printf( format string, varargs )

pause( seconds )

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 ) - (state = 0, use double precision. state=1, use quad precision).