Go to www.awrcorp.com
Back to search page Click to download printable version of this guide.

12.7. Equation Syntax

The basic form for an equation consists of the variable name on the left side of the assignment operator and a mathematical expression on the right. The syntax of the expression follows the general rules of algebra.

If the expression is not valid, the equation displays in green and an error displays in the Error window. If the equation is not visible, double-click the error in the Error window to display it.

12.7.1. Operators

You can use the following operators:

Operator Precedence Level Description
+ 1 Unary positive
- 1 Unary negative
! 1 Logical not
~ 1 Bitwise not
^ 2 Power of
* 3 Multiply
/ 3 Divide
%,mod 3 Modulus
+ 4 Add
- 4 Subtract
sll 5 Shift Left Logical
srl 5 Shift Right Logical
< 6 Less than
> 6 Greater than
<= 6 Less than or equal to
>= 6 Greater than or equal to
== 6 Equality
!= 7 Inequality
&,and 8 bit-wise AND
nand 8 bit-wise NAND
xor 9 bit-wise exclusive OR
xnor 9 bit-wise exclusive NOR
|,or 10 bit-wise OR
nor 10 bit-wise NOR
&& 11 logical AND
|| 12 logical OR
= 13 Assignment
: 13 Display value
<< 13 Declare external parameter

12.7.2. Variable Definitions

You can make assignments to constants or to mathematical expressions:

A = 6
val = x * (4 + y)

12.7.2.1. Function Definitions

You can define functions by following the variable name with a list of arguments enclosed in parentheses. The following example creates a function that takes two arguments:

sum( a, b ) = a + b

You use this function by replacing the arguments "a" and "b" with any valid mathematical expression. The following equation assigns variable "c" to (-3) + (2*4) = 5:

c = sum( -3, 2*4 )

12.7.2.2. Representing Complex Numbers

You can assign a variable to a complex number by using the imaginary global constant "i" or "j" as a multiplier:

complexZ = 50 - j*1.3

12.7.2.3. Array Indexing

An array is an n-dimensional data set, where n is 0-, 1-, or 2-dimensional. The data type must be real, complex, or string.

  • Scalar - 0-dimensional array

  • Vector - 1-dimensional array

  • List - 1-dimensional array

  • Matrix - 2-dimensional array

Array indexes are 1-based. If a floating-point value is used as an array index, it is first truncated to an integer.

Arrays may be sliced by using an index wildcard '*':

x - returns whole array

x[*] - returns whole 1D array

x[*,*] - returns whole 2D array

x[*, 1] - returns first column in 2D array

x[3, *] - returns third row in 2D array

Indices can also be vectors, and therefore use any vector syntax.

Array Indexing Examples:

x[{1, 3, 5}]

returns the first, third, and fifth elements of an array.

x[stepped(1, 10, 1)]

returns the first 10 elements

x[stepped(1, vlen(x), 2)]

returns every other element in the array

12.7.2.4. Precedence

Common algebraic precedence applies to mathematical expressions. The order in which equations are arranged on the screen determines their computation precedence. For a variable to be used in another equation it must come earlier in the computation order as follows:

  • Equations that are lower on the page are placed after ones that are higher.

  • If two equations are on the same line on the page, the one to the right is placed after the one to the left.

If a variable name referenced in an equation is defined more than once, the value taken is from the one most recently defined before the referencing equation. In the following example "b" has a value of 2 and "c" has a value of 3.

a = 1		a = 2		b = a
a = 3
c = a

12.7.3. Built-in Functions

You can use built-in functions from the following categories.

MATH OPERATIONS

The following functions can be performed on a matrix, vector, or scalar. They can be performed on real and complex numbers unless otherwise specified.

Function Description
arccos(x) or acos(x) inverse cosine of x, with result in radians
arcsin(x) or asin(x) inverse sine of x, with result in radians
arctan(x) or atan(x) inverse tangent of x, with result in radians
atan2(y, x) four quadrant inverse tangent of y/x, with result in radians. x and y must be real.
acosh(x) inverse hyperbolic cosine of x, with result in radians
asinh(x) inverse hyperbolic sine of x, with result in radians
atanh(x) inverse hyperbolic tangent of x, with result in radians
cos(x) cosine of x, with x in radians
sin(x) sine of x, with x in radians
tan(x) tangent of x, with x in radians
cosh(x) hyperbolic cosine of x, with x in radians
sinh(x) hyperbolic sine of x, with x in radians
tanh(x) hyperbolic tangent of x, with x in radians
ceil(x) Returns the smallest integer value not less than x. x must be real.
erf(x) error function at x
erfc(x) complementary error function at x
exp(x) natural exponent of x
expm1(x) e raised to the power of x-1
floor(x) Returns the largest integer value not greater than x. x must be real.
fmod(x, y) Returns the floating point remainder of x divided by y. x and y must be real.
heaviside(x) Returns 1 if arg is greater than or equal to 0, 0 otherwise. x must be real.
hypot(x, y) Euclidean distance between x and y. x and y must be real.
int(x) Returns the truncated integer value of x. x must be real.
integrate(x) Calculates the area under the curve for the data in x. x must be real, contain at least two points, and have swept data. Uses trapezoidal rule.
lgamma(x) Calculates the natural logarithm of the absolute value of the gamma function at x.
log(x) natural logarithm of x
log10(x) base 10 logarithm of x
log1p(x) natural logarithm of x+1
pow(x, y) x raised to the power of y
round(x, s) Returns the rounded number of x with step size s. x must be real.
sign(x) Returns 0 if x is equal to 0, 1 if arg is greater than 0, -1 otherwise. x must be real.
sinc(x) Returns sin(x)/x for non-zero x, returns 1 if x is zero.
sqrt(x) square root of x
tgamma(x) Calculates the value of the gamma function at x.
trunc(x) Rounds x to the nearest integer towards zero.

TYPE CONVERSION

The following functions can be performed on a matrix, vector, or scalar. Any argument of type "str" is a string and any other arguments must be real values.

Function Description
bin(str) Returns the decimal representation of the binary value represented by str.
cint(x) Returns x as a rounded integer. x must be real, and can be scalar or array.
complex(real, imag) Returns a complex number made from real and imag.
cstr(x) Returns arg as a string. x must be real, and can be scalar or array.
dbpolar(dbMag, ang) Returns a complex number made from 10^(dbMag/20) and ang in degrees.
dec2binvect(dec,n) Converts a dec (decimal) value to a binary number. Returns an integer vector with minimum length of n bits.
hex(str) Returns the decimal representation of the hexadecimal value represented by str.
oct(str) Returns the decimal representation of the octal value represented by str.
polar(mag, ang) Returns a complex number made from mag and ang in degrees.
str2dec(str, base) Converts the string str into a numeric value using base as the representation base. For example, if str is 123 and base is 10 (decimal), the generated value is 123. If base is 8 (octal) the value is 83. If base is 16 (hexadecimal) the value is 291.

UNIT CONVERSION

The following functions can be performed on a matrix, vector, or scalar. They can be performed on real numbers only.

Function Description
awg_dia(x) Returns wire diameter in meters given gauge. Valid gauge values are: 0, 1, 2, 4, 6, 8, 10, 12, 13, 14, 16, 18, 20, 22, 24, 25, 26, 28, 30, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 44, 46
ctof(x) Returns x*9/5+32.0 where x is in degree Celsius
ctok(x) Returns x+273.15 where x is in degree Celsius
db(x) Returns 20*log10(x)
db_pow(x) Returns 10*log10(x)
deg(x) Returns x multiplied by 180/pi (converts radians to degrees)
ftoc(x) Returns (x-32)*5/9 where x is in degree Fahrenheit
ftok(x) Returns (x-32)*5/9+273.15 where x is in degree Fahrenheit
ktoc(x) Returns x-273.15 where x is in degree Kelvin
ktof(x) Returns (x-273.15)*9/5+32.0 where x is in degree Kelvin
lin(x) Returns 10^(x/20)
lin_pow(x) Returns 10^(x/10)
rad(x) Returns x multiplied by pi/180 (converts degrees to radians)

VECTOR OPERATIONS

The following functions can be performed on a matrix, vector, or scalar. They can be performed on real and complex numbers unless otherwise specified.

Function Description
amax(x) Returns the maximum value of array x over all dimensions (all traces). x must be real.
amax1(x) Returns the maximum value of array x over the first dimension (per trace). x must be real.
amin(x) Returns the minimum value of array x over all dimensions (all traces). x must be real.
amin1(x) Returns the minimum value of array x over the first dimension (per trace). x must be real.
asize(x) Returns the size of an array for an output equation measurement. This function returns two values: the first is the number of points on the x-axis and the second is the number of swept traces for the measurement x.
assign_array(array, index, value) Assigns value to the entry in the array at index. Note that index and value can be arrays thus allowing assignment of multiple values at once. The type of array and value must be the same. The size of index and value must be the same.
asum(x) Returns the sum of all elements in array x. x must be real or complex.
concat(a, b) Concatenates vectors a and b. Arguments must have the same type.
csum(x) Returns the cumulative sum of x versus the swept data of x
deltawin(y, swpval1, swpval2, winwidth, winpos) Returns a vector of the difference between the maximum and minimum y values across a moving window. The difference is calculated as the maximum to minimum change in y data over the x value sweep range specified by winwidth. swpval1 and swpval2 define the minimum and maximum swept x value range and must be positive values. winwidth must be ≤ (swpval2 - swpval1). For winpos=1 (extend right) the window ranges from x[i] to x[i]+winwidth, for winpos=2 (center) the window ranges from x[i]-winwidth/2 to x[i]+winwidth/2, and for winpos=3 (extend left) the window ranges from x[i] to x[i]-winwidth.
der(x, y) Returns the finite difference derivative of x with respect to y. Arguments must be real scalars or real vectors. If both arguments are vectors, then they must be of equal size.
fill(n, val) Returns a 1-dimensional array of length n with all values equal to val.
find_index(x, val) Returns the index of a value in array x which is closest to val.
find_index_range(x, val1, val2) Returns a list of indices {i1,...,i2} where i1 corresponds to the index whose value in array x is closest to val1, and i2 corresponds to the index whose value in array x is closest to val2.
histogram(x, bin_type) Computes the histogram of data values represented in x. x must be a real vector. The bin_type parameter controls how the data is binned. bin_type<0 means bin_type specifies the number of bins. bin_type=0 means the number of bins is auto-calculated using number_of_points/ln(2.0). bin_type>0 means bin_type specifies the width of a bin.
interp(type, x, y, new_x) Returns interpolated y data at new X points. x, y, and new_x must be real vectors, and x and y must be the same size. type can be 0 (linear), 1 (polynomial), 2 (rational), or 3 (cubic spline).
interp_poly(order, x, y, new_x) Returns interpolated y data at new X points using polynomial interpolation. x, y, and new_x must be real vectors, and x and y must be the same size. order is the order of the polynomial and can be between 1 and 100 inclusive.
lin_reg(x) Returns a least-squares-fit line to x. x must be a real vector. The returned data is versus the original swept data of x.
max(a, b) Returns a vector of value a[i]>b[i]. Arguments must be real scalars or real vectors. If both arguments are vectors, then they must be of equal size.
min(a, b) Returns a vector of value a[i]<b[i]. Arguments must be real scalars or real vectors. If both arguments are vectors, then they must be of equal size.
mmult(x, y) Returns the matrix product of matrices x and y.
mov_avg(x, n) Calculates the moving average of x using a window size of 2*n+1. n is the number of points on either side of the current point. x may be real or complex and n must be a real scalar that is rounded to an integer. This can be used to smooth a graph. For complex x, averaging is performed on real and imaginary parts (for example, on Cartesian coordinates, rather than polar).
stack(n, vec) Returns a 2-dimensional array whose size is n by vlen(vec). The values of the array are the values of vec stacked up n times.
stack2(n, vec) Returns a 2-dimensional array ("matrix") whose size is n by vlen(vec)/n. vec is split into n equal size pieces to create the matrix columns.
transpose(x) Transposes x which contains 2D data.
unwrap(x, d) Unwraps phase. x represents the swept data (usually phase) and must be real. d is the threshold that causes an offset of 2*d to be added to the data if there is more than d change from one point to the next. d must be real and scalar. This function will maintain the sweep data for x if it exists.
vlen(x) Returns the length of the vector x.

ADDITIONAL FUNCTIONS

Function Description
assign_sweep(x, y) Assign sweep data of y to x.
assign_swpunit(x, unitType) Returns x with a unit type assigned to its sweep data. unitType must be a real scalar in the range of 0 to 16 with values of: 0 (none), 1 (frequency), 2 (capacitance), 3 (inductance), 4 (resistance), 5 (conductance), 6 (length: metric), 7 (length: English), 8 (temperature), 9 (angle), 10 (time), 11 (voltage), 12 (current), 13 (power: log), 14 (power: linear), 15 (dB), 16 (string).
circle(radius, ctr_re, ctr_im, num_pts) Returns complex data representing a circle of given radius and center point (ctr_re, ctr_im) with num_pts number of points. num_pts must be between 2 and 1000 inclusive.
col() See row() and col().
DataFile(name) or DataFile(name, "c") Returns an array of the Data File name from the Project Browser. DataFile(name) returns a real array and DataFile(name, "c") returns a complex array. You cannot place these functions in Output Equation documents. If the imported file data is needed there, you can write the DataFile(..) function in a Global Definitions document.
DataFileCol(name, columnName) Returns the column with name columnName of the Data File name from the Project Browser. If the column contains real data, a vector of real values is returned. If the column contains complex data, a vector of complex values is returned.
data_file(name, type, args) Converts the values in the data file name into a numeric vector. Type and arg parameters are reserved for future use and should be set to "". See "vfile".
find_pv(val, e_series) Finds the nearest preferred value to val as defined by the IEC60063 standard. e_series may be 3, 6, 12, 24, 48, 96, or 192. Non-positive values are returned unchanged. This function is typically used to find standard values for resistors, capacitors, and inductors.
if(cond, trueval, falseval) If cond is true, then evaluates to trueval, otherwise evaluates to falseval. cond must be real and scalar. cond may use equation operators such as Y = if(X==0,1,2). (See “Operators” for information about equations operators.) If vectors, the lengths of cond, trueval, and falseval must match.
marker(graph, mN) Returns a vector of real values corresponding to the values displayed on marker mN in graph. The arguments are text and must be enclosed in quotation marks. For example, marker("Gain","m2") returns values on marker "m2" in graph "Gain". If units are known, the values are in base units; for example, frequency is in Hz. Complex values are returned as the two real values displayed on mN, which depend on properties set on graph. This function updates automatically if mN is moved.
plot_vs(y, x) Plots the array y versus the vector x. x must be real and the first dimension of y must match the length of x.
plot_vs2(y, x, unitType) Plots the array y versus the vector x with the unitType set. x must be real and the first dimension of y must match the length of x. See "assign_swpunit" for unit types.
row(), col(), row(data_var_name, row#), col(data_var_name, col#) Accesses any row or column of data in a text data file. The data file must be in text format and must not contain any header information. Data can be column, space, or white space delimited. Before using row() and col() functions, the target data file must be "declared" using the DataFile() function: Data_Var_Name = DataFile("file_name"). After the data file is declared, the Row() and Col() functions access the specified row or column in the data file: Row_Var_Name = Row(Data_Var_Name, Row#) Col_Var_Name = Col(Data_Var_Name, Col#) NOTE: The DataFile() function uses a text string to identify its argument, so the file name is in quotes. Once declared, the Data_Var_Name is just a variable, so it is not in quotes when used in the Row() and Col() functions.
subsweep(meas, x1, x2) Returns the measurement meas over the sweep range.
subsweepi(meas, start, count) Returns the measurement meas from start to start + count, where start and count are integer numbers referring to the vector index.
swpunit(x) Returns the unit type (see "assign_swpunit") for the sweep data of x.
swpvals(x) Returns the sweep data of x. x is real.
vfile(name) Converts values in the text data file name into a numeric vector. If the text file contains one value per line, vfile name returns a vector of double values. If the text file contains two values per line, vfile returns a vector of complex values. name may start with a symbolic directory name (template $XXX). See the following section for more information. Remember to add a backslash after the symbolic directory name.

SYMBOLIC DIRECTORY NAMES

You can use the following symbolic directory names with vfile name and data_file name functions.

Name Description Typical directory
$MWO Replaced with the AWR Design Environment platform installation folder name. C:\Program Files (x86)\AWR\AWRDE\_version_
$PRJ Replaced with the name of the folder containing the project file. C:\Users\_user_\Documents\_project_folder_name_
$APPDATAUSER Replaced with the name pointing to the AppDataUser directory. C:\Users\user\AppData\Local\AWR\Design Environment\_version_
$DATA Replaced with the name of the Data folder within the \AWRDE installation folder C:\Program Files (x86)\AWR\AWRDE\_version_\Data

COMPLEX NUMBER FUNCTIONS

You can use the following complex number functions, where z is a complex number.

Function Description
real(z) Returns the real part of a complex number.
imag(z) Returns the imaginary part of a complex number.
angle(z) Returns the angle (in radians) of a complex number.
conj(z) Returns the complex conjugate of a complex number.
abs(z) Returns the magnitude of a complex number.

SWEPT FUNCTIONS

You can use the following functions for generating a vector of real values. These functions are useful for generating a frequency sweep in the AWR Microwave Office program for use with the SWPFRQ and SWPVAR blocks.

Function Description
concat(a, b) Concatenates vectors a and b. Arguments must have the same type.
points(start, stop, points) Generates a vector of real numbers from start to stop, with a total length of points.
stepped(start, stop, step) Generates a vector of real numbers from start to stop with step size between consecutive numbers.
swpdec(start, stop, points) Generates a vector of real numbers from start to stop with points per decade.
swpoct(start, stop, points) Generates a vector of real numbers from start to stop with points per octave.
swplin(start, stop, points) Generates a vector of real numbers from start to stop with a total length of points.
swpspan(center, span, points) Generates a vector of real numbers with a center and a span with a total length of points.
swpspanst(center, span, step) Generates a vector of real numbers with a center and a span with step size between consecutive numbers.
swpstp(start, stop, step) Generates a vector of real numbers from start to stop with step size between consecutive numbers.

FUNCTIONS THAT REFERENCE GENERALIZED MDIF DOCUMENTS

The following functions support pulling values from generalized MDIF data documents. You can use these functions in the Global Equations or within a schematic document. You cannot use them directly in Output Equations, however since Output Equations can reference Global Equations, you can still use the values returned from these functions from within the Output Equations.

  • IndexMD: This function is used to retrieve values by index. This function takes a variable number of arguments and returns a scalar, 1-D or 2-D array.

    IndexMD("MDIF_DOC_NAME", "IndepVar1_Name", Var1_Index,... "IndepVarNS_Name", VarNS_Index, "DependVar_Name")

    Argument Description
    "MDIF_DOC_NAME" Document name for the MDIF is the name of the document in the Project Browser (not the file name)
    "IndepVar1_Name" Name of the independent variable used to define a slice of data. Must match one of the independent variable names within the MDIF.
    Var1_Index Index of the "IndepVar1_Name" variable used to define the slice of data.
    "IndepVarNS_Name" Name of the independent variable used to define a slice of data. Must match one of the independent variable names within the MDIF. 'NS' defines how many slice dimensions are passed into the function and must be no more than the number of dimensions in the MDIF.
    VarNS_Index Index of the "IndepVarN_Name" independent variable used to define the slice of data.
    "DependVar_Name" Defines the dependent value quantity returned from the function. Name must match one of the dependent variable names within the MDIF. Return type is either real or complex, depending on type of the named variable within the MDIF file. Dimensions of the returned data are ND-NS, where ND is the number of dimensions of the data in the MDIF file, and NS is the number of slices defined as arguments to the function. A maximum of two dimensions can be returned, so function returns an error if ND-NS > 2. When ND=NS, a scalar is returned (all dimensions are specified).

  • LookupMD: This function is very similar to IndexMD, except the values of the independent variables are passed in instead of the indices. This function does not do any interpolation, so it returns the closest match for the passed in values.

    LookupMD("MDIF_DOC_NAME", "IndepVar1_Name", Var1_Value,... "IndepVarNS_Name", VarNS_Value, "DependVar_Name")

  • InterpMD: This function can be used to interpolate values from the arbitrary dimension data set. Even though the syntax looks similar to IndexMD or LookupMD, the usage is more complex, partly because the variables used to define the slice dimensions can be either independent or dependent values. This makes the function very flexible, although it should be used with care. The main reason for allowing dependent variables to be used for slice dimensions is for the case where a sweep is represented as an integer index within the independent values in the MDIF, but the actual value of the swept quantity is stored as a dependent value. For example, for load pull files, the power may be swept by an iPower index, and then you can use different dependent power values (such as Pava_Src) as the dimension to interpolate over).

    InterpMD("MDIF_DOC_NAME", "Var1_Name", Var1_Values,... "VarND_Name", VarND_Values, "DependVar_Name")

    Argument Description
    "MDIF_DOC_NAME" Document name for the MDIF is the name of the document in the Project Browser (not the file name)
    "Var1_Name" Name of the variable used to define a slice of data. Must match one of the independent or dependent variable names within the MDIF.
    Var1_Values Values for the variable that defines the slice of data. Value can be a scalar or a vector. If vector, the length of the vector determines one of the dimensions of the value returned from the function. If MDIF data is on a regular grid and the specified value matches one of the values on that regular grid, this function automatically reduces the dimension of the space being interpolated over. This can be useful for performance reasons, and it can also be used to get around the limits on the interpolation dimensions.
    "IndepVarND_Name" Name of the variable used to define a slice of data. Must match one of the independent or dependent variable names within the MDIF. Number of slices passed in must be equal to the number of dimensions in the MDIF file (ND=NS).
    VarND_Values Index of the "IndepVarN_Name" independent variable used to define the slice of data.
    "DependVar_Name" Defines the dependent value quantity returned from the function. Name must match one of the dependent variable names within the MDIF. Return type is either real or complex, depending on type of the named variable within the MDIF file. Dimensions of the returned data are a scalar if all the Var[X]_Values are scalar. If one of the Var[X]_Values is a vector, the returned value has the same dimension as Var[X]_Values. If two arguments (Var[X]_Values and Var[Y]_Values) have vector values, the returned value has a dimension equal to Size[X]*Size[Y]. A maximum of 2 dimensions can be returned, so the function returns an error if more than two Var[X]_Values are vectors.

    NOTES ON INTERPOLATION
    - The type and limitations of the interpolation depend on the structure of the data. If the data is on a regular grid and all data points are defined on that grid, then linear interpolation is used, which can support up to 10 dimensions of data. For data that does not conform to a regular grid, thin plate spline interpolation is used, which can currently interpolate up to 3 dimensions. It is also possible to have mixed regular and irregular data (when you interpolate over dependent values from a data set that has regular independent values). In these cases, you can reduce the number of dimensions interpolated over by making sure one or more of the Var[X]_Values are scalar values that correspond to a matching independent value in the MDIF data set. For each matching value, the number of dimensions required to be interpolated is reduced by one.

    INTERPOLATION OPTIONS
    - The MDIF data document has interpolation options you can control (choose Options > Project Options and click the Interpolation/Passivity tab on the Project Options dialog box). Not all options that you can set are used for MDIF data interpolation. Currently, only the Method option changes the interpolation, and can be Linear, Rational function, or Spline curve. When the interpolation is performed over 1-dimension, these settings are always respected. Interpolation over a higher than 1-dimension data set is still a 1-d interpolation under certain conditions (see the previous paragraph). The following table shows what interpolation methods you can use with what type of data. If an incompatible method is selected, a compatible method is auto-selected instead. For most use, the Linear default is good, otherwise the code chooses another method when needed.

    Structure Dimensions Methods Supported
    Uniform 1 Linear, Rational, Spline
    Uniform 2-3 Linear, Spline
    Uniform 3-10 Linear
    Non-uniform 1 Linear, Rational, Spline
    Non-uniform 2-3 Spline
    Non-uniform >3 Not currently supported

You can use the following built-in variables in the AWR Microwave Office program to return simulation frequencies and temperatures.

BUILT-IN VARIABLES IN AWR Microwave Office

Variable Description
_ANG_U Reserved for AWR Microwave Office use.
_CAP_U Reserved for AWR Microwave Office use.
_COND_U Reserved for AWR Microwave Office use.
_CURR_U Reserved for AWR Microwave Office use.
_FREQ Variable containing the simulation frequency (in Hz) when used in a schematic. For HB analysis, _FREQ contains the frequency set (fundamental plus harmonics and products) for the current sweep point. _FREQ contains the project frequency list when used in the Output Equation window. Units are always in Hz. Reserved for AWR Microwave Office use.
_FREQH1 Variable containing the first tone of a harmonic balance simulation. Reserved for AWR Microwave Office use, in the schematic window.[1]
_FREQH2 Variable containing the second tone of a harmonic balance simulation. Reserved for AWR Microwave Office use, in the schematic window.[1]
_FREQH3 Variable containing the third tone of a harmonic balance simulation. Reserved for AWR Microwave Office use, in the schematic window.[1]
_FREQ_U Reserved for AWR Microwave Office use.
_IND_U Reserved for AWR Microwave Office use.
_LEN_U Reserved for AWR Microwave Office use.
_PI Reserved for AWR Microwave Office use.
_RES_U Reserved for AWR Microwave Office use.
_TEMP Variable used for the default temperature of many models. The units for this variable are determined by the project temperature units (“Project Options Dialog Box: Global Units Tab ”), unless Dependent parameters use base units is selected on the Options dialog box Schematic tab, in which case the variable has units of Kelvin. [2]
_TEMPK Variable used to set the noise temperature (in Kelvin) for any model that does not have a temperature parameter. Passive elements have their noise contributors scaled by _TEMPK/290.0.[2] Reserved for AWR Microwave Office use.
_TIME_U Reserved for AWR Microwave Office use.
_VOLT_U Reserved for AWR Microwave Office use.

[1] Units are always in Project Units unless Dependent parameters use base units is selected for the project. See “Determining Project Units” for details.

[2] See “Using Temperature in Simulations” for information on the correct use of _TEMP and _TEMPK.

BUILT-IN VARIABLES IN AWR VSS

You can use the following built-in variables in the AWR VSS™ (VSS) system diagram windows:

Variable Description
_BLKSZ Variable containing the Block Size setting from the System Simulator Options dialog box Advanced tab.
_DRATE Variable containing the default data rate computed from: _DRATE = _SMPFRQ/_SMPSYM when _SMPFRQ is in Hz. The units are cycles per second. This variable may be swept, although if so, _SMPFRQ, _SMPSYM, _TFRAME, and _TSTEP are not updated.
_FREQ For RF Budget Analysis, array variable containing the frequency list from the RF Frequencies tab of the System Options dialog box. For RF Inspector and Time Domain simulations, variable containing the first frequency from the frequency list in the RF Frequencies tab of the System Options dialog box. Units are always in Hz. Reserved for AWR Microwave Office use.
_SMPFRQ Variable containing the default Sampling Frequency Span from the System Simulator Options dialog box Basic tab. _SMPFRQ = _DRATE*_SMPSYM when _SMPFRQ is in Hz. The units are in Hertz if system diagrams are configured to use base units for dependent parameters on the Project Options dialog box Schematics/Diagrams tab. If they are not, the units are in the project frequency units. This variable may be swept, although if so, _DRATE, _SMPSYM, _TFRAME, and _TSTEP are not updated.
_SMPSYM Variable containing the default Oversampling Rate from the System Simulator Options dialog box Basic tab. _SMPSYM = _SMPFRQ/_DRATE when _SMPFRQ is in Hz.
_TAMB Variable containing the Ambient Temperature from the System Simulator Options dialog box RF Options tab. The units are in Kelvin if system diagrams are configured to use base units for dependent parameters on the Project Options dialog box Schematics/Diagrams tab. If they are not, the units are in the project temperature units. This variable can be swept.
_TFRAME Variable containing the default time step between data samples, _TFRAME = 1/_DRATE.
_TSTEP Variable containing the default time step between waveform samples, _TSTEP=1/_SMPFRQ when _SMPFRQ is in Hz.
_Z0 Variable containing the impedance setting from the System Simulator Options dialog box RF Options tab, Impedance option.

USING BUILT-IN FREQUENCY VARIABLES

The AWR Design Environment platform allows you to sweep frequencies in several different ways, and each measurement can use a different frequency sweep. When a circuit is analyzed, several different frequency sweeps may be performed to complete all of the measurements. Built-in variables are available that represent the frequency during each simulation.

_FREQ is the reserved variable name for the simulation frequency vector (set of values). For linear simulations, _FREQ is the set of frequencies in the sweep. For nonlinear simulations, _FREQ is the set of harmonic (spectral) frequencies being analyzed. For example, if you make a resistor a function of _FREQ, it has a list of values: one for each value in _FREQ. For linear analysis, each value is a function of the corresponding sweep frequency. However, for each frequency point in a nonlinear simulation, that same resistor has a different list of values, each of which is a function of the corresponding harmonic frequency in the analysis, so the resistor is properly frequency-dependent in both cases.

You can access the nonlinear input (tone 1) frequency sweep with the _FREQH1 variable. This allows you to make the frequency of one tone dependent on another. For example, assume you use a PORT1 element as the tone 1 input signal, and want a second tone source with a frequency 0.01 less than tone 1. You can place a PORTFN element with the parameters Tone=2 and Freq=_FREQH1-0.01. (The tone number used by a signal port is either set in its parameter list, or on the Port tab of the Element Options: PORT dialog box (right-click the port and choose Properties).

With one PORT1 element (using tone 1) as the input signal, harmonic balance settings that specify 5 harmonics for tone 1, and a frequency sweep of 1, 2, and 3 GHz, assuming the project global units are set to GHz, during the sweep, the following are the values of the variables for each frequency in the sweep:

_FREQH1=1 _FREQ={1e9,2e9,3e9,4e9,5e9}

_FREQH1=2 _FREQ={2e9,4e9,6e9,8e9,10e9}

_FREQH1=3 _FREQ={3e9,6e9,9e9,12e9,15e9}

Note that _FREQ values are always in Hz. Equations that use _FREQ to calculate frequency-dependent element and parameter values should anticipate this.

GLOBAL CONSTANTS

You can use the following global constants without using the constants command:

Global Constant Description
_PI The mathematical constant π (3.14159...)
i, j The imaginary number defined by √-1.

You can use the following global constants by using the constants("name") function. For example, call constants("boltzmann") to get the value 1.3806226e-23.

Global Constant Value
e 2.7182818284590452354
ln10 2.30258509299404568402
pi 3.14159265358979323846
c0 2.997924562e8
e0 8.85418792394420013968e-12
u0 3.14159265358979323846*4e-7
boltzmann 1.3806226e-23
qelectron 1.6021918e-19
planck 6.6260755e-34
M_E 2.7182818284590452354
M_LOG2E 1.4426950408889634074
M_LOG10E 0.43429448190325182765
M_LN2 0.69314718055994530942
M_LN10 2.30258509299404568402
M_PI 3.14159265358979323846
M_TWO_PI 6.28318530717958647652
M_PI_2 1.57079632679489661923
M_PI_4 0.78539816339744830962
M_1_PI 0.31830988618379067154
M_2_PI 0.63661977236758134308
M_2_SQRTPI 1.12837916709551257390
M_SQRT2 1.41421356237309504880
M_SQRT1_2 0.70710678118654752440
M_DEGPERRAD 57.2957795130823208772
P_Q 1.6021918e-19
P_C 2.997924562e8
P_K 1.3806226e-23
P_H 6.6260755e-34
P_EPS0 8.85418792394420013968e-12
P_U0 3.14159265358979323846*4e-7
P_CELSIUS0 273.15

12.7.4. Using String Type Variables

Equations can use string-type variables in addition to real and complex types. You must manually add the quotes to differentiate string-type data from string-type equations.

You must enclose the NET parameter for subcircuit elements in quotes. For example:

NET="One"

You can concatenate strings using the '+' operator.

Some model parameters are a list of available values. These are different than string-types; you can tell because there is no quote around the string name. An excellent example is an MDIF file. In the following figure, note the NET parameter is set as a string-type by the quotes, but the C parameter has a list of available settings.

For any model parameter of this type, you can type in a variable name for the parameter, then set the variable to an integer that indicates the position in the drop-down list to use, starting with 0. You do NOT use the text available in the drop-down menu. The following example shows the C parameter set to a variable, and the variable set to 1, so it uses the second item in the list.

If you want to sweep through the first five elements of this model, you set up the schematic accordingly.

12.7.5. Defining Vector Quantities

Equations support real, complex, or string type vector quantities. To define a vector, use the following syntax:

x={10, 25, 30, 50}
x={i, 3*i, 2*i}
x={"One", "Two", "Three", "Four"}

Vectors cannot mix types, such as strings and numbers. The vector type is determined by the last member. To reference a particular value, use the following syntax:

x={10, 25, 30, 50}		x[1]:
10
x={i, 3*i, 2*i}			x[2]:
(0,3)
x={"One","Two","Three","Four"}	x[3]: "Three"

The array index must be in the range [1,N], where N is the number of items in the vector. You can also define a vector using the stepped function with the following syntax:

stepped(start,stop,step)

If start is less than stop, then step must be greater than 0. If stop is less than start, then step must be less than 0.

Array references are independent variables that you can tune and optimize, and which are always constrained between 1 and N. You can override these constraints to fall within this range. Optimizers must support discrete optimization of vector quantities, except for gradient-based optimizers, which cannot function with discrete values. AWR Design Environment platform Pointer and Random optimizers support discrete values.

12.7.6. Swept Measurement Data in Output Equations

The example presented here demonstrates swept measurement data in an output equation.

The schematic in the following figure generates a three dimensional (3D) sweep. Zin measured at port 1 is the sum of the simulation frequency in GHz and variables A and B.

You can consider the Zin data as being stored in the following format.

When you specify a measurement, the sweep settings in the Modify Measurement Equation dialog box allow a form of filtering that can take “slices” from the data.

The following examples show the selected options from the Modify Measurement Equation dialog box, the portions of the data that are extracted, and the resulting data when the measurement is used in an Output Equations document. Each example increments an integer suffix on the variable name to distinguish it from the others. The simplest case is when the measurement uses only one sweep. Here, frequency is specified as the x-axis, but A and B are fixed.

In output equations:

Zin1 = Sweep.$Freq:Re(ZIN(1))[X,1,2]
Zin1:  {111,112,113,114,115}
swpvals(Zin1): {1e9,2e9,3e9,4e9,5e9}

Note that the SWPFRQ block is used with ID=Freq as the sweep frequencies of the measurement defining Zin1. Other than the variable name used, all of the information in output equations is numeric. Here, the variable Zin1 becomes the 1D array (vector) of Zin values when: frequency is swept, A=10, and B=200. The swpvals( ) function can get the vector of corresponding frequency values. However, the names of the swept variables do not mean anything in output equations. If the swept variable A is set to Select with tuner, the size of the vectors stays the same, but the Zin1 values correspond to the column selected by tuning A.

The next example shows that when one of the swept variables is set to Plot all traces, the output equation becomes a 2D array.

The following is a visual representation of the data in the output equation:

swpvals(Zin2):          Zin2:
        10        311,312,313,314,315
        20        321,322,323,324,325
        30        331,332,333,334,335
        40        341,342,343,344,345

Because the swept variable A is set to Use for x-axis, its values are now the sweep values. The data now has as many columns as there are frequencies, and one row for each A value. To see how the data is stored, plot the measurement in a tabular graph. The first column of the tabular graph shows the sweep values. The remaining columns show the measurement data, with rows corresponding to the sweep values in order, and the measurement values for the nth parameter value in the nth column after the sweep values.

In output equations:

Zin2 = Sweep.$Freq:Re(ZIN(1))[*,X,3]                
asize(Zin2):{4,5}
Zin2[*,3]: {313,323,333,343}	    Values for 3rd frequency point
Zin2[2,*]: {321,322,323,324,325}	Values for 2nd sweep point of A 

If there are other equations that calculate a variable “x”, and you want the row of Zin2 data for the A value closest to x, plotted vs. frequency, you can use the following equations:

A_index = Findindex(swpvals(Zin2),x)
Zin2_row = Zin2[A_index,*]
Answer = plot_vs2(Zin2_row,swpvals(Zin1),1)

You can use multiple output equations for the same measurement, but with a different swept parameter set to Use for x-axis, in order to access the list of values for that parameter. In this example, Zin2 does not include the frequency values; its sweep values are the values of the swept variable A. The equation for Answer refers to the output equation in the previous example: swpvals(Zin1) provides the frequency list.

In the following example, swept variable B is also set to Plot all traces. When additional swept parameters are set to Plot all traces, the output equation data is still a 2D array, with a column for each combination of parameter values.

The data displays similar to the following (as in a tabular graph):

swpvals(Zin3):                        Zin3:
        1e9     111,121,131,141, 211,221,231,241, 311,321,331,341
        2e9     112,122,132,142, 212,222,232,242, 312,322,332,342
        3e9     113,123,133,143, 213,223,233,243, 313,323,333,343
        4e9     114,124,134,144, 214,224,234,244, 314,324,334,344
        5e9     115,125,135,145, 215,225,235,245, 315,325,335,345

The first four columns of Zin3 data correspond to the four values of A in increasing order, and the lowest value of B. The next four columns are for the next B value, and so on. The order of sweeps is alphabetical, based on the ID parameter of the SWPVAR block, except that frequency is always the first (fastest) sweep when set to Plot all traces. (Spaces are added for clarity; the data does not distinguish columns other than by index number.)

In output equations:

Zin3 = Sweep.$Freq:Re(ZIN(1))                
asize(Zin3):{5,12}	dim=asize(Zin3)  rows=dim[1]=5	cols=dim[2]=12

The function asize(Zin3) returns the dimensions of the array as {5,12} (5 rows, and 12 columns). However, without additional information, there is no way to determine how many swept variables there are, or how many values each has. Again, you can use the other equations to determine the number of A values:

Num_A = asize(swpvals(Zin2))	Num_A:4 

This shows that every 4th column in Zin3 data corresponds to the same A value. (You use equations to determine this, rather than setting Num_A=4, so that everything scales automatically if the schematic is edited and the number of sweep points changes.) To get the Zin values for the 4th frequency, and the A value closest to x, at all B values:

Zin3[3,stepped(A_index,cols,Num_A)]: {134,234,334}

To plot this versus values of B, you need another output equation where the measurement sets B to Use for x-axis, so you can get its sweep values as follows:

The data displays as follows:

swpvals(Zin4):		Zin4:
        100	    112,122,132,142
        200	    212,222,232,242
        300	    312,322,332,342

In output equations:

Zin4 = Sweep.$Freq:Re(ZIN(1))[2,*,X]                
Zin3_vs_B = plot_vs2(Zin3,swpvals(Zin4),4)

12.7.6.1. Inconsistent X-axis Values

Some measurements have a different list of x-axis values for each simulation in a sweep. The simplest example of this is a frequency spectrum measurement like Pharm, after a harmonic balance simulation where the input frequency is swept. For example, if the input frequency is swept through the values 1, 1.1, and 1.2 (GHz), and the harmonic balance simulation is set up to simulate 5 harmonics, then the Pharm measurement consists of 6 points per input frequency (DC and 5 harmonics). However, at each input frequency, F0, there is a different set of harmonic frequencies for the x-axis, N*F0, where N=1,2,3,4,5. If you set the frequency sweep to Plot all traces, and plot the measurement on a rectangular graph, it displays as shown in the following figure (traces are set to Step Color, so each color represents a different input frequency):

If you use this measurement in output equations:

HB = HB.AP_HB:DB(|Pharm(PORT_2)|)[*]

The data displays as follows:

swpvals(HB):                             HB:
        1        0      -23.227    0        -23.867    0        -24.546
        2        1e9     5.5535    1.1e9     5.6228    1.2e9     5.6869
        3        2e9    -5.5815    2.2e9    -6.0023    2.4e9    -6.4105
        4        3e9    -19.718    3.3e9    -19.822    3.6e9    -19.979
        5        4e9    -23.948    4.4e9    -24.617    4.8e9    -25.334
        6        5e9    -13.251    5.5e9    -13.67     6e9      -14.158

The vector returned by swpvals cannot hold all of the x-axis values; so the function just returns a vector of integers (row index numbers). Instead, the data in the array “HB” holds one pair of columns, x and y values, for each input frequency: odd columns are x-axis (spectral frequency) values, and even columns are the corresponding harmonic power levels. There are simple ways of segregating the x and y values if necessary. For example:

asize(HB):{6,6}	dim=asize(HB)  rows=dim[1]=6	cols=dim[2]=6

Frequencies = HB[*,stepped(1,cols-1,2)]   ; all rows, but odd columns only

Frequencies: { {0,0,0},{1,1.1,1.2},{2,2.2,2.4},{3,3.3,3.6},…}

or, visually:

        0      0        0	
        1e9    1.1e9    1.2e9	
        2e9    2.2e9    2.4e9	
        3e9    3.3e9    3.6e9	
        4e9    4.4e9    4.8e9	
        5e9    5.5e9    6e9

If an additional parameter (for example, the input power level) is swept, another six columns of data are added for each additional input power level.

12.7.6.2. Inconsistent Number of Points in Each Sweep

Some measurements do not have an identical number of points in each sweep. For example, transient analyses have variable time step sizes, and may require a different number of time points when simulating each value of a swept parameter. A Vtime measurement from a transient simulator may have a different number of points for each simulation in a sweep.

In output equations:

Tran = Transient.HS:Vtime(PORT_2,1)[*]

Here, the size of the data array depends on the sweep with the largest number of points, and the “empty” elements of the array are set to the highest number possible. Equations recognize and ignore these values: math operations are not performed on them. These values display in brackets in the following table (rounded to 4 digits).

0            5.8921e-008  0            5.8921e-008  0            5.8921e-008
5e-012       1.2765e-007  5e-012       1.7561e-007  5e-012       2.7556e-007
1e-011       2.7636e-007  1e-011       5.2287e-007  1e-011       1.2869e-006
2.6e-011     3.2271e-006  2.6e-011     1.6813e-005  2.6e-011     0.00017125
6.4952e-011  0.00095671   3.5631e-011  0.00013135   3.4824e-011  0.0021303
7.3714e-011  0.0028257    4.3336e-011  0.00064518   4.2103e-011  0.010124
1e-010       0.021405     4.95e-011    0.0020934    4.85e-011    0.022758
[1.798e308] [1.798e308]   6.6888e-011  0.019187     5.4897e-011  0.040639
[1.798e308] [1.798e308]   7.434e-011   0.030976     5.9902e-011  0.055256
[1.798e308] [1.798e308]   8.1792e-011  0.045444     7.3073e-011  0.095886
[1.798e308] [1.798e308]   1e-010       0.08099      8.9661e-011  0.14767
[1.798e308] [1.798e308]  [1.798e308]  [1.798e308]   1e-010       0.17911

Legal and Trademark Notice