nec2++
1.7.0

nec++ Library Functions. More...
Go to the source code of this file.
Typedefs  
typedef struct nec_context  nec_context 
Functions  
Initialization and Cleanup  
Functions dealing with antenna simulation contexts. The contexts should be created before a simulation begins and deleted after the simluation is complete to recover any memory allocated.  
nec_context *  nec_create (void) 
Create an nec_context and initialize it. More...  
long  nec_delete (nec_context *in_context) 
Delete an nec_context object. More...  
Antenna Geometry  
Functions for creating wires and surface patches, as well as geometry transformations  
long  nec_wire (nec_context *in_context, int tag_id, int segment_count, double xw1, double yw1, double zw1, double xw2, double yw2, double zw2, double rad, double rdel, double rrad) 
Create a straigt wire. More...  
long  nec_sp_card (nec_context *in_context, int ns, double x1, double y1, double z1, double x2, double y2, double z2) 
Surface Patch (SP Card) More...  
long  nec_sc_card (nec_context *in_context, int i2, double x3, double y3, double z3, double x4, double y4, double z4) 
Surface Patch Continuation (SC Card) More...  
long  nec_gm_card (nec_context *in_context, int itsi, int nrpt, double rox, double roy, double roz, double xs, double ys, double zs, int its) 
Coordinate Transformation. More...  
long  nec_gx_card (nec_context *in_context, int i1, int i2) 
Reflection in Coordinate Planes. More...  
long  nec_geometry_complete (nec_context *in_context, int gpflag) 
Indicate that the geometry is complete (GE card) More...  
Error Handling  
Functions for error handling and utility  
long  nec_benchmark (void) 
Benchmark the libnecpp engine. A score of 1 is roughly an Athlon XP 1800. More...  
const char *  nec_error_message (void) 
Get the last error message All functions return a long. If this is != 0. Then an error has occurred. The error message can be retrieved with this function.  
Antenna Environment  
Functions for specifying the ground and antenna excitation, frequency and loading.  
long  nec_medium_parameters (nec_context *in_context, double permittivity, double permeability) 
Set the prameters of the medium (permittivity and permeability) More...  
long  nec_gn_card (nec_context *in_context, int iperf, int nradl, double epse, double sig, double tmp3, double tmp4, double tmp5, double tmp6) 
Ground Card Examples: More...  
long  nec_fr_card (nec_context *in_context, int in_ifrq, int in_nfrq, double in_freq_mhz, double in_del_freq) 
FR card. More...  
long  nec_ek_card (nec_context *in_context, int itmp1) 
To control use of the extended thinwire kernel approximation. More...  
long  nec_ld_card (nec_context *in_context, int ldtyp, int ldtag, int ldtagf, int ldtagt, double tmp1, double tmp2, double tmp3) 
LD card (Loading) More...  
long  nec_ex_card (nec_context *in_context, int extype, int i2, int i3, int i4, double tmp1, double tmp2, double tmp3, double tmp4, double tmp5, double tmp6) 
EX card (Excitation) More...  
long  nec_excitation_voltage (nec_context *in_context, int tag, int segment, double v_real, double v_imag) 
Voltage Source Excitation. More...  
long  nec_excitation_current (nec_context *in_context, double x, double y, double z, double a, double beta, double moment) 
Current Source Excitation. More...  
long  nec_excitation_planewave (nec_context *in_context, int n_theta, int n_phi, double theta, double phi, double eta, double dtheta, double dphi, double pol_ratio) 
Planewave Excitation (Linear Polarization) More...  
long  nec_tl_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4, double tmp1, double tmp2, double tmp3, double tmp4, double tmp5, double tmp6) 
long  nec_nt_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4, double tmp1, double tmp2, double tmp3, double tmp4, double tmp5, double tmp6) 
long  nec_xq_card (nec_context *in_context, int itmp1) 
XQ Card (Execute) More...  
long  nec_gd_card (nec_context *in_context, double tmp1, double tmp2, double tmp3, double tmp4) 
Simulation Output  
Functions for calculating radiation patterns, and requesting printed output of simulation results.  
long  nec_rp_card (nec_context *in_context, int calc_mode, int n_theta, int n_phi, int output_format, int normalization, int D, int A, double theta0, double phi0, double delta_theta, double delta_phi, double radial_distance, double gain_norm) 
Standard radiation pattern parameters. More...  
long  nec_pt_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4) 
Print Flag (Printing of Currents. More...  
long  nec_pq_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4) 
long  nec_kh_card (nec_context *in_context, double tmp1) 
long  nec_ne_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4, double tmp1, double tmp2, double tmp3, double tmp4, double tmp5, double tmp6) 
long  nec_nh_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4, double tmp1, double tmp2, double tmp3, double tmp4, double tmp5, double tmp6) 
long  nec_cp_card (nec_context *in_context, int itmp1, int itmp2, int itmp3, int itmp4) 
long  nec_pl_card (nec_context *in_context, char *ploutput_filename, int itmp1, int itmp2, int itmp3, int itmp4) 
Analysis of Output  
Functions for calculating statistics from simulation outputs. These are useful for automatic optimization.  
double  nec_gain (nec_context *in_context, int freq_index, int theta_index, int phi_index) 
Get the gain from a radiation pattern. More...  
double  nec_gain_max (nec_context *in_context, int freq_index) 
Get the maximum gain from a radiation pattern. More...  
double  nec_gain_min (nec_context *in_context, int freq_index) 
Get the minimum gain from a radiation pattern. More...  
double  nec_gain_mean (nec_context *in_context, int freq_index) 
Get the mean gain from a radiation pattern. More...  
double  nec_gain_sd (nec_context *in_context, int freq_index) 
Get the standard deviation of the gain from a radiation pattern. More...  
double  nec_gain_rhcp_max (nec_context *in_context, int freq_index) 
double  nec_gain_rhcp_min (nec_context *in_context, int freq_index) 
double  nec_gain_rhcp_mean (nec_context *in_context, int freq_index) 
double  nec_gain_rhcp_sd (nec_context *in_context, int freq_index) 
double  nec_gain_lhcp_max (nec_context *in_context, int freq_index) 
double  nec_gain_lhcp_min (nec_context *in_context, int freq_index) 
double  nec_gain_lhcp_mean (nec_context *in_context, int freq_index) 
double  nec_gain_lhcp_sd (nec_context *in_context, int freq_index) 
double  nec_impedance_real (nec_context *in_context, int freq_index) 
Impedance: Real Part.  
double  nec_impedance_imag (nec_context *in_context, int freq_index) 
Impedance: Imaginary Part.  
long nec_benchmark  (  void  ) 
Benchmark the libnecpp engine. A score of 1 is roughly an Athlon XP 1800.
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::benchmark().
nec_context* nec_create  (  void  ) 
Create an nec_context and initialize it.
context*  An nec_context pointer. 
References nec_context::initialize().
long nec_delete  (  nec_context *  in_context  ) 
Delete an nec_context object.
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
long nec_ek_card  (  nec_context *  in_context, 
int  itmp1  
) 
To control use of the extended thinwire kernel approximation.
itmp1 

err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::set_extended_thin_wire_kernel().
long nec_ex_card  (  nec_context *  in_context, 
int  extype,  
int  i2,  
int  i3,  
int  i4,  
double  tmp1,  
double  tmp2,  
double  tmp3,  
double  tmp4,  
double  tmp5,  
double  tmp6  
) 
EX card (Excitation)
in_context  The nec_context created with nec_create() 
extype  Type of excitation

i2  Tag number the source segment. This tag number along with the number to be given in (i3), which identifies the position of the segment in a set of equal tag numbers, uniquely definer the source segment.

i3  Equal to m, specifies the mth segment of the set of segments whose tag numbers are equal to the number set by the previous parameter. If the previous parameter is zero, the number in (i3) must be the absolute segment number of the source. 
i4  Meaning Depends on the extype parameter. See http://www.nec2.org/part_3/cards/ex.html 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::ex_card().
long nec_excitation_current  (  nec_context *  in_context, 
double  x,  
double  y,  
double  z,  
double  a,  
double  beta,  
double  moment  
) 
Current Source Excitation.
in_context  The nec_context created with nec_create() 
x   X position in meters. 
y   Y position in meters. 
z   Z position in meters. 
a   a in degrees. a is the angle the current source makes with the XY plane as illustrated on figure 15. 
beta   beta in degrees. beta is the angle the projection of the current source on the XY plane makes with the X axis. 
moment   "Current moment" of the source. This parameter is equal to the product Il in amp meters. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::ex_card().
long nec_excitation_planewave  (  nec_context *  in_context, 
int  n_theta,  
int  n_phi,  
double  theta,  
double  phi,  
double  eta,  
double  dtheta,  
double  dphi,  
double  pol_ratio  
) 
Planewave Excitation (Linear Polarization)
in_context  The nec_context created with nec_create() 
n_theta   Number of theta angles desired for the incident plane wave . 
n_phi   Number of phi angles desired for the incident plane wave. 
theta   Theta in degrees. Theta 19 defined in standard spherical coordinates as illustrated 
phi   Phi in degrees. Phi is the standard spherical angle defined lned in the XY plane. 
eta   Eta in degrees. Eta is the polarization angle defined as the angle between the theta unit vector and the direction of the electric field for linear polarization or the major ellipse axis for elliptical polarization. 
dtheta   Theta angle stepping increment in degrees. 
dphi   Phi angle stepping increment in degrees. 
pol_ratio   Ratio of minor axis to major axis for elliptic polarization (major axis field strength  1 V/m). 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::ex_card().
long nec_excitation_voltage  (  nec_context *  in_context, 
int  tag,  
int  segment,  
double  v_real,  
double  v_imag  
) 
Voltage Source Excitation.
in_context  The nec_context created with nec_create() 
tag  Tag number of the source segment. This tag number along with the number to be given in (segment), which identifies the position of the segment in a set of equal tag numbers, uniquely definer the source segment.

segment  Equal to m, specifies the mth segment of the set of segments whose tag numbers are equal to the number set by the previous parameter. If the previous parameter is zero, the number in (segment) must be the absolute segment number of the source. 
v_real  real part of the voltage excitation (Volts) 
v_imag  imaginary part of the voltage excitation (Volts) 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::ex_card().
long nec_fr_card  (  nec_context *  in_context, 
int  in_ifrq,  
int  in_nfrq,  
double  in_freq_mhz,  
double  in_del_freq  
) 
FR card.
in_context  The nec_context created with nec_create() 
in_ifrq  0 is a linear range of frequencies, 1 is a log range. 
in_nfrq  The number of frequencies 
in_freq_mhz  The starting frequency in MHz. 
in_del_freq  The frequency step (in MHz for ifrq = 0) 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::fr_card().
double nec_gain  (  nec_context *  in_context, 
int  freq_index,  
int  theta_index,  
int  phi_index  
) 
Get the gain from a radiation pattern.
freq_index  The rp_card frequency index. If this parameter is 0, then the first simulation results are used. Subsequent simulations will store their results at higher indices. 
theta_index  The theta index (starting at zero) of the radiation pattern 
phi_index  The phi index (starting at zero) of the radiation pattern 
References nec_context::get_gain().
double nec_gain_max  (  nec_context *  in_context, 
int  freq_index  
) 
Get the maximum gain from a radiation pattern.
freq_index  The rp_card frequency index. If this parameter is 0, then the first simulation results are used. Subsequent simulations will store their results at higher indices. 
double nec_gain_mean  (  nec_context *  in_context, 
int  freq_index  
) 
Get the mean gain from a radiation pattern.
freq_index  The rp_card frequency index. If this parameter is 0, then the first simulation results are used. Subsequent simulations will store their results at higher indices. 
double nec_gain_min  (  nec_context *  in_context, 
int  freq_index  
) 
Get the minimum gain from a radiation pattern.
freq_index  The rp_card frequency index. If this parameter is 0, then the first simulation results are used. Subsequent simulations will store their results at higher indices. 
double nec_gain_sd  (  nec_context *  in_context, 
int  freq_index  
) 
Get the standard deviation of the gain from a radiation pattern.
freq_index  The rp_card frequency index. If this parameter is 0, then the first simulation results are used. Subsequent simulations will store their results at higher indices. 
long nec_geometry_complete  (  nec_context *  in_context, 
int  gpflag  
) 
Indicate that the geometry is complete (GE card)
in_context  The nec_context created with nec_create() 
gpflag  Geometry ground plain flag.

err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::geometry_complete().
long nec_gm_card  (  nec_context *  in_context, 
int  itsi,  
int  nrpt,  
double  rox,  
double  roy,  
double  roz,  
double  xs,  
double  ys,  
double  zs,  
int  its  
) 
Coordinate Transformation.
itsi  Tag number increment. 
nprt  The number of new Structures to be generated 
ROX  Angle in degrees through which the structure is rotated about the Xaxis. A positive angle causes a righthand rotation. 
ROY  Angle of rotation about Yaxis. 
ROZ  Angle of rotation about 
XS  X, Y. Z components of vector by which 
YS  structure is translated with respect to 
ZS  the coordinate system. 
ITS  This number is input as a decimal number but is rounded to an integer before use. Tag numbers are searched sequentially until a segment having a tag of this segment through the end of the sequence of segments is moved by the card. If ITS is zero the entire structure is moved. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
long nec_gn_card  (  nec_context *  in_context, 
int  iperf,  
int  nradl,  
double  epse,  
double  sig,  
double  tmp3,  
double  tmp4,  
double  tmp5,  
double  tmp6  
) 
Ground Card Examples:
1) Infinite ground plane nec_gn_card(nec, 1, 0, 0, 0, 0, 0, 0, 0);
2) Radial Wire Ground Plane (4 wires, 2 meters long, 5mm in radius) nec_gn_card(nec, 4, 0, 0.0, 0.0, 2.0, 0.005, 0.0, 0.0)
iperf  Groundtype flag

nradl  Number of radial wires in the ground screen approximation, O implies no ground screen. 
epse  Relative dielectric constant for ground in the vicinity of the antenna. Zero in the case of perfect ground. 
sig  Conductivity in mhos/meter of the ground in the vicinity of the antenna. Use zero in the case of a perfect ground. If SIG is input as a negative number, the complex dielectric constant Ec = Er j sigma/omaga epslon is set to EPSR  SIG. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::gn_card().
long nec_gx_card  (  nec_context *  in_context, 
int  i1,  
int  i2  
) 
Reflection in Coordinate Planes.
i1   Tag number increment. 
i2   This integer is divided into three independent digits, in columns 8, 9, and 10 of the card, which control reflection in the three orthogonal coordinate planes. A one in column 8 causes reflection along the Xaxis (reflection in Y, Z plane); a one in column 9 causes reflection along the Yaxis; and a one in column 10 causes reflection along the Z axis. A zero or blank in any of these columns causes the corres ponding reflection to be skipped. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
long nec_ld_card  (  nec_context *  in_context, 
int  ldtyp,  
int  ldtag,  
int  ldtagf,  
int  ldtagt,  
double  tmp1,  
double  tmp2,  
double  tmp3  
) 
LD card (Loading)
in_context  The nec_context created with nec_create() 
ldtyp  Type of loading (5 = segment conductivity) 
ldtag  Tag (zero for absolute segment numbers, or in conjunction with 0 for next parameter, for all segments) 
ldtagf  Equal to m specifies the mth segment of the set of segments whose tag numbers equal the tag number specified in the previous parameter. If the previous parameter (LDTAG) is zero, LDTAGF then specifies an absolute segment number. If both LDTAG and LDTAGF are zero, all segments will be loaded. 
ldtagt  Equal to n specifies the nth segment of the set of segments whose tag numbers equal the tag number specified in the parameter LDTAG. This parameter must be greater than or equal to the previous parameter. The loading specified is applied to each of the mth through nth segments of the set of segments having tags equal to LDTAG. Again if LDTAG is zero, these parameters refer to absolute segment numbers. If LDTAGT is left blank, it is set equal to the previous parameter (LDTAGF). 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::ld_card().
long nec_medium_parameters  (  nec_context *  in_context, 
double  permittivity,  
double  permeability  
) 
Set the prameters of the medium (permittivity and permeability)
permittivity  The electric permittivity of the medium (in farads per meter) 
permeability  The magnetic permeability of the medium (in henries per meter) 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::medium_parameters().
long nec_pt_card  (  nec_context *  in_context, 
int  itmp1,  
int  itmp2,  
int  itmp3,  
int  itmp4  
) 
Print Flag (Printing of Currents.
IPTFLG  Print control flag, specifies the type of format used in printing segment currents. The options are:

IPTAG   Tag number of the segments for which currents will be printed. 
IPTAGF   Equal to m, specifies the mth segment of the set of segments having the tag numbers of IPTAG, at which printing of currents starts. If IPTAG is zero or blank, then IPTAGF refers to an absolute segment number. If IPTAGF is blank, the current is printed for all segments. 
IPTAGT   Equal to n specifies the nth segment of the set of segments having tag numbers of IPTAG. Currents are printed for segments having tag number IPTAG starting at the m th segment in the set and ending at the nth segment. If IPTAG is zero or blank, then IPTAGF and IPTAGT refer to absoulte segment numbers. In IPTAGT is left blank, it is set to IPTAGF. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::pt_card().
long nec_rp_card  (  nec_context *  in_context, 
int  calc_mode,  
int  n_theta,  
int  n_phi,  
int  output_format,  
int  normalization,  
int  D,  
int  A,  
double  theta0,  
double  phi0,  
double  delta_theta,  
double  delta_phi,  
double  radial_distance,  
double  gain_norm  
) 
Standard radiation pattern parameters.
calc_mode  This integer selects the mode of calculation for the radiated field. Some values of (calc_mode) will affect the meaning of the remaining parameters on the card. Options available for calc_mode are:

n_theta  The number of theta angles. 
n_phi  The number of phi angles. 
output_format  The output format:

normalization  Controls the type of normalization of the radiation pattern

D  Selects either power gain or directive gain for both standard printing and normalization. If the structure excitation is an incident plane wave, the quantities printed under the heading "gain" will actually be the scattering cross section (a/lambda 2 ) and will not be affected by the value of d. The column heading for the output will still read "power" or "directive gain," however.

A   Requests calculation of average power gain over the region covered by field points.

theta0   Initial theta angle in degrees (initial z coordinate in meters if calc_mode = 1). 
phi0   Initial phi angle in degrees. 
delta_theta   Increment for theta in degrees (increment for z in meters if calc_mode = 1). 
delta_phi   Increment for phi in degrees. 
radial_distance   Radial distance (R) of field point from the origin in meters. radial_distance is optional. If it is zero, the radiated electric field will have the factor exp(jkR)/R omitted. If a value of R is specified, it should represent a point in the farfield region since near components of the field cannot be obtained with an RP card. (If calc_mode = 1, then radial_distance represents the cylindrical coordinate phi in meters and is not optional. It must be greater than about one wavelength.) 
gain_norm   Determines the gain normalization factor if normalization has been requested in the normalization parameter. If gain_norm is zero, the gain will be normalized to its maximum value. If gain_norm is not zero, the gain wi11 be normalized to the value of gain_norm. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::rp_card().
long nec_sc_card  (  nec_context *  in_context, 
int  i2,  
double  x3,  
double  y3,  
double  z3,  
double  x4,  
double  y4,  
double  z4  
) 
Surface Patch Continuation (SC Card)
in_context  The nec_context created with nec_create() 
i2  Weird integer parameter. 
x3  The x coordinate of patch corner 3. 
y3  The y coordinate of patch corner 3. 
z3  The z coordinate of patch corner 3. 
x4  The x coordinate of patch corner 4. 
y4  The y coordinate of patch corner 4. 
z4  The z coordinate of patch corner 4. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
long nec_sp_card  (  nec_context *  in_context, 
int  ns,  
double  x1,  
double  y1,  
double  z1,  
double  x2,  
double  y2,  
double  z2  
) 
Surface Patch (SP Card)
in_context  The nec_context created with nec_create() 
ns  The Patch Type.

x1  The x coordinate of patch corner1. 
y1  The y coordinate of patch corner1. 
z1  The z coordinate of patch corner1. 
x2  The x coordinate of patch corner2. 
y2  The y coordinate of patch corner2. 
z2  The z coordinate of patch corner2. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
long nec_wire  (  nec_context *  in_context, 
int  tag_id,  
int  segment_count,  
double  xw1,  
double  yw1,  
double  zw1,  
double  xw2,  
double  yw2,  
double  zw2,  
double  rad,  
double  rdel,  
double  rrad  
) 
Create a straigt wire.
in_context  The nec_context created with nec_create() 
tag_id  The tag ID. 
segment_count  The number of segments. 
xw1  The x coordinate of the wire starting point. 
yw1  The y coordinate of the wire starting point. 
zw1  The z coordinate of the wire starting point. 
xw2  The x coordinate of the wire ending point. 
yw2  The y coordinate of the wire ending point. 
zw2  The z coordinate of the wire ending point. 
rad  The wire radius (meters) 
rdel  For tapered wires, the. Otherwise set to 1.0 
rrad  For tapered wires, the. Otherwise set to 1.0 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::wire().
Referenced by c_geometry::wire().
long nec_xq_card  (  nec_context *  in_context, 
int  itmp1  
) 
XQ Card (Execute)
Purpose: To cause program execution at points in the data stream where execution is not automatic. Options on the card also allow for automatic generation of radiation patterns in either of two vertical cuts.
in_context  The nec_context created with nec_create() 
itmp1  Options controlled by (I1) are: 0  no patterns requested (normal case). 1  generates a pattern cut in the XZ plane, i.e., phi = 0 degrees and theta varies from 0 degrees to 90 degrees in 1 degree steps. 2  generates a pattern cut in the YZ plane, i.e., phi = 90 degrees theta varies from 0 degrees to 90 degrees in 1 degree steps. 3  generates both of the cuts described for the values 1 and 2. 
err  0 indicates that the result is successful and 1 indicates that an error occurred. Call nec_error_message() for a detailed message. 
References nec_context::xq_card().