nec_context.h

矩量法仿真电磁辐射和散射的源代码（c++）

#ifndef __nec_context__
#define __nec_context__

/*
	Copyright (C) 2004-2005  Timothy C.A. Molteno
	[e-mail] 
	
	This program is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 2 of the License, or
	(at your option) any later version.
	
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.
	
	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the Free Software
	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#include "common.h"
#include "c_ggrid.h"
#include "math_util.h"
#include "matrix_algebra.h"
#include "electromag.h"
#include "nec_radiation_pattern.h"
#include "nec_results.h"
#include "nec_output.h"
#include "nec_ground.h"
#include "c_plot_card.h"

class c_geometry;

enum excitation_return
{
	FREQ_PRINT_NORMALIZATION = 0,
	FREQ_LOOP_CONTINUE = 1,
	FREQ_LOOP_CARD_CONTINUE = 2
};

/**
	0=E VOLTAGE (A),
	1=LINEAR WAVE (B),
	2= R CIRC WAVE (B)
	3=L CIRC WAVE (B),
	4= CURRENT (C),
	5= VOLTAGE DISC.
*/
enum excitation_type
{
	EXCITATION_VOLTAGE = 0,
	EXCITATION_LINEAR = 1,
	EXCITATION_CIRC_RIGHT = 2,
	EXCITATION_CIRC_LEFT = 3,
	EXCITATION_CURRENT = 4,
	EXCITATION_VOLTAGE_DISC = 5
};

/*!
	A nec_context object is the container for an nec2++ simulation. A c_geometry object
	is associated with the nec_context, and then after the simulation is done, the results
	can be requested from this object.
 */
class nec_context
{
public:
	nec_context();
	virtual ~nec_context();
	
	// Called after construction...
	void initialize();
	

	void calc_prepare();
	
	inline c_geometry* get_geometry()
	{
		return m_geometry;
	}
	
	/*! \brief Get the maximum gain in dB.
	
	This function requires a previous rp_card() method to have been called.
	
	\return The maximum gain in dB or -999.0 if no radiation pattern had been previously requested.
	This only works for a SINGLE FRQUENCY rp_card request.
	*/
	double get_maximum_gain(int index = 0)
	{
		nec_radiation_pattern* rp = get_radiation_pattern(index);
		if (NULL == rp)
			return -999.0;
			
		return rp->get_maximum_gain_db();
	}
	
	/*! \brief Get Antenna Input Parameter Results
	\param index The zero-based index for the result (simulations can return more than one set of results).
	\return The requested antenna input parameter data (or NULL if the result does not exist).
	\note You must NOT delete the nec_antenna_input object when finished with it.
	*/
	inline nec_antenna_input* get_input_parameters(int index)
	{
		return m_results.get_antenna_input(index);
	}
	
	/*! \brief Get Normalized Receiving Pattern Results
	\param index The zero-based index for the result (simulations can return more than one set of results).
	\return The requested radiation pattern data (or NULL if the result does not exist).
	\note You must NOT delete the nec_norm_rx_pattern object when finished with it.
	*/
	inline nec_norm_rx_pattern* get_norm_rx_pattern(int index)
	{
		return m_results.get_norm_rx_pattern(index);
	}
	
	/*! \brief Get Radiation Pattern results
	\param index The zero-based index for the result (simulations can return more than one set of results).
	\return The requested radiation pattern data (or NULL if the result does not exist).
	\note You must NOT delete the results object when finished with it.
	*/
	inline nec_radiation_pattern* get_radiation_pattern(int index)
	{
		return m_results.get_radiation_pattern(index);
	}
		
	/*! \brief Get structure excitation results
	\param index The zero-based index for the result (simulations can return more than one set of results).
	\return The requested radiation pattern data (or NULL if the result does not exist).
	\note You must NOT delete the results object when finished with it.
	*/
	inline nec_structure_excitation* get_structure_excitation(int index)
	{
		return m_results.get_nec_structure_excitation(index);
	}

	inline void set_output(nec_output_file in_output, nec_output_flags in_output_flags)
	{
		m_output = in_output;
		m_output_flags = in_output_flags;
		
		m_output_fp = m_output.get_fp();
	}
	
	inline void set_results_stdout(bool flag)
	{
		m_results.set_stdout(flag);
	}
	
	inline void set_results_format(enum RESULT_FORMAT result_format)
	{
		m_results.m_result_format = result_format;
	}
	
	inline void set_gain_only(bool flag)
	{
		m_output_flags.set_gain_only(flag);
	}
	
	
	/*!\brief Benchmark the libnecpp engine. A score of 100 is roughly an Athlon XP 1800. */
	static nec_float benchmark();
	
	/*! \brief Signal the end of a geometry description.
	
	This function prepares for a calculation by calling calc_prepare().
	*/
	void geometry_complete(int card_int_1, int card_int_2);

	
	
	
	/*! Add a wire to the geometry,
	
	All co-ordinates are in meters.
	
		\param tag_id The tag ID.
		\param segment_count The number of segments.
		\param xw1 The x coordinate of the wire starting point.
		\param yw1 The y coordinate of the wire starting point.
		\param zw1 The z coordinate of the wire starting point.
		\param xw2 The x coordinate of the wire ending point.
		\param yw2 The y coordinate of the wire ending point.
		\param zw2 The z coordinate of the wire ending point.
		\param rad The wire radius (meters)
		\param rdel For tapered wires, the. Otherwise set to 1.0
		\param rrad For tapered wires, the. Otherwise set to 1.0
	*/
	void wire(int tag_id, int segment_count,
		nec_float xw1, nec_float yw1, nec_float zw1,
		nec_float xw2, nec_float yw2, nec_float zw2,
		nec_float rad, nec_float rdel, nec_float rrad);

	/*! Add an arc to the geometry,
	
	All co-ordinates are in meters.
	
		\param tag_id The tag ID.
		\param segment_count The number of segments.
		\param rada The radius.
		\param ang1 The angle of the arc starting point.
		\param ang2 The angle of the arc end point.
		\param rad The wire radius.
	*/
	void arc( int tag_id, int segment_count, nec_float rada,
			nec_float ang1, nec_float ang2, nec_float rad );
			
	
	/*! \brief Add an helix to the geometry,
	
	\remark The helix is a versatile geometry element. For example, to generate a spiral printed circuit antenna, use a helix of zero height.

	All co-ordinates are in meters.
	
		\param tag_id The tag ID.
		\param segment_count The number of segments.
		\param s The turn spacing.
		\param h1 The total length of the helix (negative for a left-handed helix).
		\param a1 x-start radius.
		\param b1 y-start radius.
		\param a2 x-end radius.
		\param b2 y-end radius.
		\param rad The wire radius.
	*/
	void helix(int tag_id, int segment_count, nec_float s, nec_float hl, nec_float a1, nec_float b1,
			nec_float a2, nec_float b2, nec_float rad);
	
	
	/*! "fr" card, frequency parameters
	\verbatim	
	FREQUENCY
	I1- O= LINEAR STEP, 1=MULTIPLICATIVE
	I2- NO. STEPS, BLANK=1
	F1- FREQUENCY OR START FREQUENCY
	F2- FREQ INCREMENT, ADD OR MULTIPLY
	\endverbatim
	*/
	void fr_card(int in_ifrq, int in_nfrq, nec_float in_freq_mhz, nec_float in_del_freq);
	
	/*! 1: "ld" card, loading parameters
	\verbatim
	LD	LOADING
		itmp1- 	-1 CANCEL LOADS,
			0=SERIES RLC LUMP,
			1=PARALLEL RLC LUMP,
			2=SERIES DIST.,
			3=PARALLEL DIST. (A),
			4=Z (B),
			5=WIRE COND. (C)
		itmp2- TAG# TO BE LOADED, BLANK/0= USE ABSOLUTE #s	
		itmp3- SEG# OF TAG # TO START LOADS, OR ABSOLUTE SEG#
		itmp4- SEG# OF TAG# TO END LOADS, OR OR ABSOLUTE SEG#
		F1- RES., OHMS, OR (A) OHMS/UNIT LENGTH, OR (B) RES. OR (C) OHMS/METER
		F2- IND., HENRY, OR (A) HY/LENGTH OR (B) REACT. OR (C) BLANK
		F3- CAP,. FARAD, OR (A,B) BLANK
	\endverbatim
	*/
	void ld_card(int itmp1, int itmp2, int itmp3, int itmp4, nec_float tmp1, nec_float tmp2, nec_float tmp3);
	
	/*! \brief Ground parameters under the antenna
	
	\remark Specifies the relative dielectric constant and conductivity of ground in the vicinity of the antenna. In addition, a second set of ground parameters for a second medium can be specified, or a radial wire ground screen can be modeled using a reflection coefficient approximation.
	
	\param ground_type (was IPERF) Ground-type flag. The options are:
		\arg \c -1 - Nullifies ground parameters previously used and sets free-space condition. The remainder of the parameters should be zero in this case. 
		\arg \c O - Finite ground, reflection-coefficient approximation.
		\arg \c 1 - Perfectly conducting ground.
		\arg \c 2 - Finite ground, Sommerfeld/Norton method. 
	
	\param rad_wire_count (was NRADL) - Number of radial wires in the ground screen approximation; Set to zero implies no ground screen.
	
	\param EPSE (F1) - Relative dielectric constant for ground in the vicinity of the antenna. Set to zero in case of a perfect ground.
	\param SIG (F2) - Conductivity in mhos/meter of the ground in the vicinity of the antenna. Set to zero in the case of a perfect ground. If SIG is input as a negative number, the complex dielectric constant Ec = Er -j*sigma/(omega*epsilonzero) is set to EPSR - |SIG|.
	
	\remark
	 
	Options for Remaining Floating Point Fields (F3-F6):
		\li a. For an infinite ground plane, F3 through F6 are blank. 
		\li b. Radial wire ground screen approximation (NRADL nonzero). The ground screen is always centered at the origin, i.e., at (0,0,0), and lies in the XY plane. (F3) - The radius of the screen in meters. (F4) - Radius of the wires used in the screen, in meters. (F5) & (F6) - Blank.
		\li c. Second medium parameters (NRADL = O) for medium outside the region of the first medium (cliff problem). These parameters alter the far field patterns but do not affect the antenna impedance or current distribution. (F3) - Relative dielectric constant of medium 2. (F4) - Conductivity of medium 2 in mhos/meter. (F5) - Distance in meters from the origin of the coordinate system to the join between medium 1 and 2. This distance is either the radius of the circle where the two media join or the distance out the positive X axis to where the two media join in a line parallel to the Y axis. Specification of the circular or linear option is on the RP card. See Figure 16. (F6) - Distance in meters (positive or zero) by which the surface of medium 2 is below medium 1.
	*/
	void gn_card(int ground_type, int rad_wire_count, nec_float tmp1, nec_float tmp2, nec_float tmp3, nec_float tmp4, nec_float tmp5, nec_float tmp6);
	
	
	/*! "ex" card, excitation parameters
	\verbatim
			EX	EXCITE STRUCTURE, LAST ENCOUNTERED=USED
				I1- 0=E VOLTAGE (A), 1=LINEAR WAVE (B), 2= R CIRC WAVE (B)
				3=L CIRC WAVE (B), 4= CURRENT (C), 5= VOLTAGE DISC. (A)
				I2- (A) SOURCE TAG#, (B) # TH ANGLS, (C) BLANK
				I3- (A) SOURCE SEG#, (B) # PH ANGLS, (C) BLANK
				I4- (A) XX= ADMIT.,IMPED. PRINT, X=0 NO/1 DO, (BC), 1= ADM. PRINT
				F1- (A) EREAL, (B) TH ANGL, (C) X OF SOURCE
				F2- (A) EIMAG, (B) PH ANGL, (C) Y OF SOURCE
				F3- (A) NORM FOR I4, (B) ET ANGL, Z OF SOURCE
				F4- (A) BLANK, (B) TH INC, (C) ALPHA ANGLE FROM XY
				F5- (A) BLANK, (B) PH INC, (C) BETA ANGLE FROM X
				F6- (A) BLANK, (B) MIN/MAJ AXIS, PRODUCT AMPS X LENGTH
				
				// NOT YET DONE... F7- (A) BLANK, (B) INCIDENT AMPLITUDE (Volts/m)
	\endverbatim
	*/
	void ex_card(enum excitation_type itmp1, int itmp2, int itmp3, int itmp4, nec_float tmp1, nec_float tmp2, nec_float tmp3, nec_float tmp4, nec_float tmp5, nec_float tmp6);
	
	
	
	/*! 5: "tl" card, transmission line parameters
	
	\remark
	To generate a transmission line between any two points on the structure. Characteristic impedance, length, and shunt admittance are the defining parameters.
	
	\verbatim
	TL TRANSMISSION LINE 
		I1- PORT 1 TAG #, BLANK/0, USE I2 AS ABSOLUTE
		I2- SEGMENT#, OR ABSOLUTE END 1 SEGMENT, -1=CANCEL NETS/LINES
		I3- AS I1 FOR PORT 2
		I4- AS I2 FOR PORT 2
		F1- LINE Zo, -=CROSSED LINE
		F2- LINE LENGTH METERS, BLANK=STRAIGHT LINE P1 TO P2
		F3- REAL SHUNT ADM., END 1 MHOS
		F4- IMAG SHUNT ADM., END 1
		F5- REAL SHUNT ADM., END 2
		F6- IMAG SHUNT ADM., END 2
	\endverbatim
	*/
	void tl_card(int itmp1, int itmp2, int itmp3, int itmp4, nec_float tmp1, nec_float tmp2, nec_float tmp3, nec_float tmp4, nec_float tmp5, nec_float tmp6);
	
	/*! 4: "nt" card, network parameters
	\verbatim
		NT	NETWORKS
			I1- PORT 1 TAG #, BLANK/0, USE I2 AS ABSOLUTE
			I2- SEGMENT#, OR ABSOLUTE END 1 SEGMENT, -1=CANCEL NETS/LINES
			I3- AS I1 FOR PORT 2
			I4- AS I2 FOR PORT 2
			F1- REAL OF Y(11), MHOS
			F2- IMAG OF Y(11)
			F3- REAL OF Y(12)
			F4- IMAG OF Y(12)
			F5- REAL OF Y(22)
			F6- IMAG OF Y(22)
	\endverbatim
	*/
	void nt_card(int itmp1, int itmp2, int itmp3, int itmp4, nec_float tmp1, nec_float tmp2, nec_float tmp3, nec_float tmp4, nec_float tmp5, nec_float tmp6);
	
	/*! "xq" execute card - calc. including radiated fields
	
	\verbatim
	XQ	EXECUTE ACCUMULATED CARD DECK
		itmp1-
			0=NO PATTERN,
			1=XY PATTERN,
			2= YZ PATTERN,
			3=BOTH
		(DO NOT USE FOR RADIAL GND SCREEN OR 2ND GND MEDIUM)
	
		NOTES: FOR A SINGLE FREQUENCY, XQ, NE, NH, RP CAUSE IMMEDIATE EXECUTION
		FOR MULTIPLE FREQS, ONLY XQ, RP CAUSE EXECUTION
	\endverbatim
	*/
	void xq_card(int itmp1);
	
	/*! "gd" card, ground representation */
	void gd_card(nec_float tmp1, nec_float tmp2, nec_float tmp3, nec_float tmp4);
	
	/*! \brief Standard radiation pattern parameters 
	
	\param 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:
		\arg \c O - normal mode. Space-wave fields are computed. An infinite ground plane is included if it has been specified previously on a GN card; otherwise, the antenna is in free space.
		\arg \c 1 - surface wave propagating along ground is added to the normal space wave. This option changes the meaning of some of the other parameters on the RP card as explained below, and the results appear in a special output format. Ground parameters must have been input on a GN card. The following options cause calculation of only the space wave but with special ground conditions. Ground conditions include a two-medium ground (cliff where the media join in a circle or a line), and a radial wire ground screen. Ground parameters and dimensions must be input on a GN or GD card before the RP card is read. The RP card only selects the option for inclusion in the field calculation. (Refer to the GN and GD cards for further explanation.)
		\arg \c  2 - linear cliff with antenna above upper level. Lower medium parameters are as specified for the second medium on the GN card or on the GD card.
		\arg \c 3 - circular cliff centered at origin of coordinate system: with antenna above upper level. Lower medium parameters are as specified for the second medium on the GN card or on the GD card.
		\arg \c 4 - radial wire ground screen centered at origin.
		\arg \c 5 - both radial wire ground screen and linear cliff.
		\arg \c 6 - both radial wire ground screen ant circular cliff.
	
	\param n_theta The number of theta angles.