FarfieldPlot Object

Defines the settings for the farfield plots and recalculates the farfield plot if necessary.

• General Methods

• Calculation at User Defined Points

• Plot Style

• Scaling and Plot Modes

• Farfield Orientation, Origin and Coordinate Systems

• Decoupling Plane Settings

• Farfield Calculation Secondary Results

• Phase Center Calculation

• Default Settings

• Examples

General Methods

Reset

Resets all internal values to their default settings.

Plottype ( enum type )

Defines the type of the farfield plot.

type can have one of the following values:

Vary ( enum{"angle1", "angle2"} varyAngle )

Varies the first or the second coordinate respectively if  the plot type is set to "polar" or "cartesian" using Plottype. The coordinate type depends on the active coordinate system:

Phi ( double angleInDegree )

Sets the constant value for the second angle (e.g. phi), if the Vary method is set to "angle1".

Please note: angleInDegree must be a double value here. Any expression is not allowed.

Theta ( double angleInDegree )

Sets the constant value for the first angle (e.g. theta), if the Vary method is set to "angle2".

Please note: angleInDegree must be a double value here. Any expression is not allowed.

Step ( double angleInDegree )

Sets the theta step width used to calculate the farfield plot. Step sizes need to be a divisor of 180°. A checking mechanism automatically reduces the entered step size if this criterion is not met.

Please note: angleInDegree must be a double value here. Any expression is not allowed.

Step2 ( double angleInDegree )

Sets the phi step width used to calculate the farfield plot. Step sizes need to be a divisor of 180°. A checking mechanism automatically reduces the entered step size if this criterion is not met.

Please note: angleInDegree must be a double value here. Any expression is not allowed.

SetLockSteps ( bool bFlag )

Enforce a common step width for theta step and phi step.

SetPlotRangeOnly ( bool bFlag )

Activates the phi and theta plot range.

SetThetaStart ( double angleInDegree )

Sets the lower bound of the displayed theta range.

Please note: angleInDegree must be a double value here. Any expression is not allowed.

SetThetaEnd ( double angleInDegree )

Sets the upper bound of the displayed theta range.

Please note: angleInDegree must be a double value here. Any expression is not allowed.

SetPhiStart ( double angleInDegree )

Sets the lower bound of the displayed phi range.

Please note: angleInDegree must be a double value here. Any expression is not allowed.

SetPhiEnd ( double angleInDegree )

Sets the upper bound of the displayed phi range.

Please note: angleInDegree must be a double value here. Any expression is not allowed.

UseFarfieldApproximation ( bool bFlag )

Enables or disables the farfield approximation. If disabled, the farfield calculation is more accurate in areas close to the antenna. On the other hand computation time increases if farfield approximation is disabled.

SetMultipolNumber ( integer nmax )

Restricts the maximal order of the plotted multipoles to nmax. If the calculated number of multipol orders is smaller, then nmax is ignored. This setting affects only broadband farfields.

SetFrequency ( double frequency )

Sets the farfield plot frequency. This setting affects only broadband farfields.

SetTime ( double time )

Sets the desired time for a transient farfield plot. time does not include the delay due to the finite distance to the farfield origin. This setting affects only broadband farfields.

SetTimeDomainFF ( bool bFlag )

This setting switches from the farfield calculation to the transient field display. This setting affects only broadband farfields.

SetMovieSamples ( integer Nsamples )

Sets the number of movie samples used for the broadband farfield animation. Set Nsamples equal to zero to use the frequency samples of the broadband monitor as a default value.

Plot

Starts the farfield calculation if necessary and refreshes the plot window.

StoreSettings

Applies all farfield plot specific settings without refreshing the plot window.

ASCIIExportSummary ( filename  fileName )

This method offers ASCII file export of the summarized settings concerning the farfield plot (array pattern, monitor name, component, plot type, step angle, frequency) as well as the most important farfield values characterizing the current calculation (radiation efficiency, total efficiency, maximum directivity, maximum gain). The summary is saved to a file named fileName.

ASCIIExportVersion ( string version )

Use this method to select the ascii export version to maintain compatibility. However, older ascii export versions may not support all features. Supported versions are 2009 and 2010.

ASCIIExportAsSource ( filename fileName )

This method creates a farfield source from the selected farfield plot (2D/3D plot type only). The data are saved to a file named fileName. This file can be used for defining a farfield excitation.

ASCIIExportAsBroadbandSource ( filename fileName )

This method creates a broadband farfield source from the selected farfield plot (2D/3D plot type only). Other farfield results generated by the same excitation are automatically collected and merged into the farfield source file.

CopyFarfieldTo1DResults ( name ResultFolder, name ResultName )

Copies the active 1D farfield to the subfolder ResultFolder in the 1D Results folder using the name ResultName. If empty strings are passed a default folder and/or a default name is derived from the farfield settings.

IncludeUnitCellSidewalls ( bool flag )

This method affects the farfield calculation for periodic and unit cell boundaries. If flag is true, the farfield integration considers periodic and unit cell boundaries like open boundaries. Otherwise, these side wall contributions are ignored, and the aperture field comprises the open and Floquet port boundaries only.

Calculation at User Defined Points

CalculatePoint ( double thetaInDegree , double phiInDegree, enum fieldComponent, name farfieldName ) double

CalculatePointNoApprox ( double  thetaInDegree , double phiInDegree, double radius, enum fieldComponent, name farfieldName ) double

Calculates a single farfield value from the farfield result item farfieldName at the specified angles thetaInDegree and phiInDegree. If farfieldName = "" the currently selected farfield will be taken. There are different field components available for the resulting farfield mode, which itself is selected by the SetPlotMode method. The result will be influenced also by SetScaleLinear.

In case of CalculatePointNoApprox method the calculation is done without using the farfield approximation. Thus, radial field components may exist.

fieldComponent is a concatenation of four component specifiers separated by space:

fieldComponent = <Coord.System> +" " + <Polarization> +" " + <Component> +" " + <ComplexComp.>

Allowed values are:

The absolute value of the field vector is accessible via:

fieldComponent = <Coord.System> +" " + "abs"

The axial ratio and the component ratios are accessible through

fieldComponent = <Coord.System> +" " + <Polarization> +" " + "axialratio"

fieldComponent = <Coord.System> +" " + <Polarization> +" " + "compratio12"

fieldComponent = <Coord.System> +" " + <Polarization> +" " + "compratio21"

where compratio12 refers to comp1/comp2.

AddListItem ( double thetaInDegree , double phiInDegree, double radius )

CalculateList ( name farfieldName )

GetListItem ( long index, enum fieldComponent ) double

The above three commands work the same way as CalculatePoint, but they can calculate more than one point in only one call. This procedure is much faster than calling CalculatePoint one by one.

First, all points have to be added using AddListItem. After once calling CalculateList, the results can be inquired using the GetListItem command, providing the 0-based index of the points in the same order as adding them before. Depending on the fieldComponent identifier,  the point coordinates or the farfield result can be returned.

Note: If the radius for a point is set to 0, the farfield approximation will be used.

Use Reset to delete the point list.

The identifier fieldComponent may have one of the values as listed in the table for the CalculatePoint method or additionally one the following values:

Please see the second example how to apply these methods.

Plot Style

SetColorByValue ( bool bFlag )

Enables or disables mapping of plot values to colors using the current color ramp for plot types 2D or 3D.

SetTheta360 ( bool bFlag )

This settings extends the plot range of the polar angle (theta, elevation, alpha) to the full circle. The plot range of the corresponding lateral angle (phi, azimuth, epsilon) is reduced accordingly, depending on the active plot type.

DrawStepLines ( bool bFlag )

In case of plot type "3D", draws black lines at each angular step, if activated.

SymmetricRange ( bool bFlag )

Choose the plot range of the lateral angles (phi, azimuth, epsilon) symmetric about the origin. This setting is also applied to the polar angles if possible.

DrawIsoLongitudeLatitudeLines ( bool bFlag )

Draws iso lines for the longitude and the latitude of the active coordinate system, if activated.

ShowStructure ( bool bFlag )

Enables to plot the structure into the 3D-farfield plot.

SetStructureTransparent ( bool bFlag )

Plots the structure transparent.

SetFarfieldTransparent ( bool bFlag )

Plots the farfield transparent. This setting affects only 3D farfield plots.

FarfieldSize ( integer size )

Size of the farfield. Valid range is between 0 and 100.

Scaling and Plot Modes

SetPlotMode ( enum plotMode )

GetPlotMode ( enum plotMode )

SetPlotMode specifies the mode for the farfield plot. GetPlotMode returns the currently set plot mode.

plotMode can have one of the following values:

SetSpecials ( enum option )

Activates additional farfield plot settings. Allowed values of option are:

Distance ( double radius )

Set the radius of the virtual sphere for which the farfield is calculated. Available for plot modes e-field / h-field and power pattern.

Please note: radius must be a double value here. Any expression is not allowed.

SetScaleLinear ( bool bFlag )

If activated the farfield is plotted using linear scaling. Otherwise the scaling is logarithmic.

IsScaleLinear bool

Returns True if the farfield is plotted linearly. Otherwise returns False.

SetInverseAxialRatio ( bool bFlag )

If activated the inverse IEEE axial ratio is plotted.

IsInverseAxialRatio bool

Returns true if the inverse IEEE axial ratio is plotted.

SetLogRange ( double range )

Sets the logarithmic farfield plot range in dB. For plot type "polar" the plot ranges maximum will be at the next 10 dB step above the plots maximum (i.e. 20 dB if the maximum is 14). For plot types "cartesian", 2D and 3D the ranges maximum will be the plots maximum.

Please note: range must be a double value here. Any expression is not allowed.

SetLogNorm ( double norm )

Sets the logarithmic farfield plot normalization in dB. This setting requires the deactivation of the maximum normalization.

Please note: norm must be a double value here. Any expression is not allowed.

GetLogRange double

Returns the currently defined logarithmic plot range.

SetMainLobeThreshold ( double limit )

Sets the threshold used for the main lobe width calculation. limit is in dB.

DBUnit ( enum unitCode )

Sets the a unit for linear and logarithmic farfield plots.

unitCode can have one of the following values:

EnableFixPlotMaximum ( bool bFlag  )

If activated all farfield plots are scaled to the same  fixed maximum value set with SetFixPlotMaximumValue. Otherwise the plot maximum is recalculated  for each farfield plot automatically.

IsPlotMaximumFixed bool

Returns True if the current plot maximum is fixed else returns False.

SetFixPlotMaximumValue ( double plotMax )

Sets the plot maximum value to plotMax. If scaling to fixed plot maximum is activated all farfield plots are scaled to plotMax.

GetFixPlotMaximumValue double

Returns the currently set fixed plot maximum value.

Farfield Orientation, Origin and Coordinate Systems

Origin ( enum originType )

The origin type of the farfield calculation.

originType can have one of the following values:

Userorigin (double x, double y, double z )

 Sets origin of the farfield calculation if the origin type is set to free.

Please note: x, y, and z must be double values here. Any expression is not allowed.

Phistart (double x, double y, double z )

Thetastart (double x, double y, double z )

Set new origin vectors in global cartesian coordinates for the x'-axis and z'axis. The x'axis defines the new start of the angle phi, the z'-axis defines the new start of the angle theta. Therefore Phistart is used to set the new x'-axis, Thetastart to set the new z'-axis. The resulting vectors will be normalized to 1. The x'-axis will be orthogonalized to the z'-axis. Please make sure that the axes are not parallel and that the vectors do not have zero length. The y'-axis will be determined automatically.

Please note: x, y, and z must be double values here. Any expression is not allowed.

SetAxesType ( enum type )

Specifies the alignment of the farfield coordinate system. The following rotation types are available:

PolarizationVector (double x, double y, double z )

Set the polarization vector or y'-axis in global cartesian coordinates . You may enter any numbers, the resulting vector will be normalized to 1 later.

SetCoordinateSystemType ( enum coordSys )

Sets the coordinate system to the type coordSys. According to the chosen coordinate system different field components are calculated based on the respective coordinate transforms.

coordSys can have one of the following values:

SetPolarizationType ( enum polarization )

Sets the polarization type to polarization. Supported values are "linear", "circular" and "slant".

SlantAngle(double angle )

Sets the slant angle to angle. This settings is only required for the polarization type "slant".

Decoupling Plane

UseDecouplingPlane ( bool bFlag )

Enable or disable a PEC plane for the farfield calculation. For models containing a (possibly discontinuous) PEC plane which touches the boundaries of the calculation domain you have to use a decoupling plane (e.g. a coplanar antenna on a substrate).

DecouplingPlaneAxis ( enum{"x", "y", "z"} axis )

This command sets the normal of the user defined PEC-plane. The normal is always aligned with one of the three cartesian coordinate axes x, y, or z.

DecouplingPlanePosition ( double position )

Enter here the coordinate of the user defined decoupling plane in normal direction.

Please note: position must be a double value here. Any expression is not allowed.

SetUserDecouplingPlane ( bool bFlag )

If activated the user defined decoupling plane is used for the farfield calculation instead of an automatically detected decoupling plane.

Farfield Calculation Secondary Results

Getmax double

Returns the maximum of the plotted farfield component.

Getmin double

Returns the minimum of the plotted farfield component.

GetMean double

Returns the average value of the plotted farfield component.

GetRadiationEfficiency double

Returns the calculated radiation efficiency of the currently active farfield plot.

GetTotalEfficiency double

Returns the calculated total efficiency of the currently active farfield plot.

GetSystemRadiationEfficiency double

Returns the calculated radiation efficiency of the currently active farfield plot for the complete system (CST DESIGN STUDIO model) if available.

GetSystemTotalEfficiency double

Returns the calculated total efficiency of the currently active farfield plot for the complete system (CST DESIGN STUDIO model) if available.

GetTRP double

Returns the total radiated power in W(rms).

GetTotalRCS double

Returns the total radar cross section of the currently active RCS plot with the active unit scaling.

GetTotalACS double

Returns the total absorption cross section of the currently active RCS plot with the active unit scaling.

GetMainLobeDirection double

Returns the main lobe direction of the farfield in degrees. This method only applies to "polar" plots.

GetMainLobeVector ( double_ref x, double_ref y, double_ref z )

Returns the direction of the 3D farfield main lobe.

GetAngularWidthXdB double

Returns the angular width of the farfield in degrees according to the currently active main lobe threshold. This method only applies to "polar" plots.

GetSideLobeSuppression double

Returns the side lobe suppression. This method only applies to "polar" plots.

GetSideLobeLevel double

Returns the side lobe level. This method only applies to "polar" plots.

GetFrontToBackRatio double

Returns the ratio of the front field value (in main lobe direction) to the back field value (antipodal main lobe direction) using the current farfield plot component and scaling.

Phase Center Calculation

EnablePhaseCenterCalculation ( bool bFlag )

If activated the phase center is being calculated as soon as the farfield is replotted.

SetPhaseCenterComponent ( enum{"theta", "phi", "boresight"} component )

Selects the desired farfield component which is used for the phase center calculation. Theta and phi use the phase of the corresponding spherical components. Boresight evaluates the farfield in +z' direction, extracts the polarization vector from this field and uses this reference to calculate the phase.

SetPhaseCenterPlane ( enum{"both", "e-plane", "h-plane"} component )

The phase center is calculated in either the E-plane (x' = 0), H-plane (y' = 0) or in both planes. Select the desired plane here.

SetPhaseCenterAngularLimit ( double angleInDegrees )

The phase center is calculated using the phase values around the z'axis in the x' = 0 (E-Plane) and y' = 0 (H-Plane) planes with a constant distance from the origin. To limit the area around the z'-axis taken into account for the calculation in those planes you may specify an angle here.

ShowPhaseCenter ( bool bFlag )

Visualizes the phase center in the 3D-farfield plot.

GetPhaseCenterResult ( enum{"x", "y", "z"} direction, enum{"avg", "eplane", "hplane"} mode ) double

Returns the previously calculated  phase center location in global coordinates  for a given direction and mode. The direction may be either "x", "y" or "z". The mode may be either "avg" (for averaged phase center location), "eplane" (for the phase center location calculated in the E-plane) or "hplane" (for the phase center location calculated in the H-plane).

GetPhaseCenterResultExpr string

Returns the previously calculated  phase center location in global coordinates  as character string as displayed in the main view window.

GetPhaseCenterResultExprAvg string

Returns the previously calculated  phase center location in global coordinates  as character string. The phase center location is average by the values calculated in the E-plane and H-plane.

GetPhaseCenterResultExprEPlane string

Returns the previously calculated  phase center location calculated in the E-plane in global coordinates  as character string.

GetPhaseCenterResultExprHPlane string

Returns the previously calculated  phase center location calculated in the H-plane in global coordinates  as character string.

Default Settings:

Plottype ("polar")

Vary ("angle1")

Phi (0.0)

Theta (0.0)

Step (30.0)

Step2 (30.0)

SetLockSteps (True)

SetPlotRangeOnly (False)

SetThetaStart (0.0)

SetThetaEnd (180.0)

SetPhiStart (0.0)

SetPhiEnd (360.0)

UseFarfieldApproximation (True)

SetColorByValue (True)

SetTheta360 (False)

DrawStepLines (False)

CartSymRange (False)

DrawIsoLongitudeLatitudeLines (False)

ShowStructure (False)

SetStructureTransparent (False)

SetFarfieldTransparent (True)

FarfieldSize (50)

SetPlotMode ("directivity")

SetInverseAxialRatio (False)

Distance (1.0)

SetScaleLinear (False)

SetLogRange (40.0)

SetLogNorm (0.0)

SetMainLobeThreshold (3.0)

DBUnit ("0")

EnableFixPlotMaximum (False)

SetFixPlotMaximumValue (1.0)

Origin ("bbox")

Userorigin (0.0, 0.0, 0.0)

Phistart (1.0, 0.0, 0.0)

Thetastart (0.0, 0.0, 0.0)

SetAxesType ("user")

PolarizationVector (0.0, 1.0, 0.0)

SetCoordinateSystemType ("spherical")

UseMirrorPlane (False)

SetUserMirrorPlane (False)

EnablePhaseCenterCalculation (False)

SetPhaseCenterComponent ("boresight")

SetPhaseCenterPlane ("both")

SetPhaseCenterAngularLimit (30.0)

ShowPhaseCenter (False)

SetTimeDomainFF (False)

SetMovieSamples (0)

IncludeUnitCellSidewalls (True)

Example:

This example demonstrate some general settings for a farfield plot:

With FarfieldPlot

     .Reset

     .Plottype ("3d")

     .Step (5)

     .SetColorByValue (True)

     .DrawStepLines (False)

     .DrawIsoLongitudeLatitudeLines (False)

     .SetTheta360 (False)

     .CartSymRange (False)

     .UseFarfieldApproximation (False)

     .SetPlotMode ("Efield")

     .SetInverseAxialRatio (False)

     .Distance (1)

     .SetScaleLinear (True)

     .SetLogRange (50)

     .DBUnit ("0")

     .EnableFixPlotMaximum (False)

     .SetFixPlotMaximumValue (1.0)

     .SetAxesType ("mainlobe")

     .Phistart (1.0, 0.0, 0.0)

     .Thetastart (0.0, 1.0, 1.0)

     .PolarizationVector (1.0, 1.0, 0.0)

     .Origin ("free")

     .Userorigin (0.0, 0.0, 5.0)

     .SetUserMirrorPlane (False)

     .UseMirrorPlane (False)

     .MirrorPlaneAxis ("X")

     .MirrorPlanePosition (0.0)

     .EnablePhaseCenterCalculation (True)

     .SetPhaseCenterAngularLimit (36.3)

     .SetPhaseCenterComponent ("Theta")

     .SetPhaseCenterPlane ("both")

End With

SelectTreeItem("Farfields\farfield (f=16) [1]")

FarfieldPlot.Plot

SelectTreeItem("Farfields\farfield (f=30) [1]")

FarfieldPlot.Plot

The second example calculates theta and phi component and the phases along a user defined path:

FarfieldPlot.Reset

n = 0

For phi=0 To 360 STEP 5

     theta = 90

     FarfieldPlot.AddListItem theta, phi, 0 ' zero radius for farfield approximation

     n = n + 1

Next phi

FarfieldPlot.CalculateList "Farfields\f [1]"

For i=0 To n-1

     theta_am = FarfieldPlot.GetListItem(i, "Spherical linear theta abs")

     theta_ph = FarfieldPlot.GetListItem(i, "Spherical linear theta phase")

     phi_am = FarfieldPlot.GetListItem(i, "Spherical linear phi abs")

     phi_ph = FarfieldPlot.GetListItem(i, "Spherical linear phi phase")

     position_theta = FarfieldPlot.GetListItem(i, "Point_T")

     position_phi = FarfieldPlot.GetListItem(i, "Point_P")

     ' further process your results here

Next i