Introduction to Simulator Expressions

This document describes the simulator expressions that are available for use with several Agilent EEsof EDA products. For a complete list of available simulator functions, refer to the Alphabetical Listing of Simulator Functions in Chapter 2 or consult the index.

Simulator expressions are functions that you define before they are used internally during simulation run-time. They can be entered into the program using various methods, depending on which product you are using. Unlike the expressions described in the Measurement Expressions documentation, simulator expressions are evaluated at the beginning of a simulation, not after the simulation has completed.
Although there is some overlap among many of the more commonly used functions, simulator expressions and measurement expressions are derived from separate sources, evaluated at different times, and can have subtle differences in their usages. Thus, these two types of expressions need to be considered separately. For an overview of how simulator expressions are evaluated, refer to How Simulator Expressions are Evaluated.

Note that if a particular term is used in a simulator expression, the term must be defined before the simulation is run. For example, if you use the variable R in a simulator expression, and R = S(1,1), where the results of S(1,1) will not be known until after the simulation is complete, an error will be returned by the simulator.

How Simulator Expressions Are Evaluated

Within this document you will find:

• Information on simulator expressions syntax.
• A functions reference table that provides a complete list of all available simulator functions. Individual functions are also listed in the index for your convenience.
• Information specific to entering simulator expressions in your product.

You will also find a complete list of functions that can be used as simulator expressions individually, or combined together as a nested expression. These expressions have been separated into libraries and are listed in alphabetical order within each library. The expressions available include:

• Data Access Functions

• Harmonic Balance Functions

• Math Functions

• S-Parameter Analysis Functions

• Transient Source Functions

• Utility Functions

Note All predefined expressions, functions, constants, and variables listed in this chapter are reserved names. You can use them in your expressions; however, you cannot redefine them to something else.

Simulator Expressions Syntax

Use the following guidelines when creating simulator expressions:

• Simulator expressions are based on the mathematical syntax in Application Extension Language (AEL).
• Function names, variable names, and constant names are all case sensitive in simulator expressions.
• Use commas to separate arguments.
• White space between arguments is acceptable.

The general form of an expression is:
expressionName = nonconstantExpression

For example:
x1 = 4.3 + freq;
syc_a = cos(1.0+sin(pi*3 + 2.0*x1))
Zin = 7.8 ohm + j*freq * 1.9 ph
y = if (x equals 0) then 1.0e100 else 1/x endif

Case Sensitivity

All variable names, functions names, and equation names are case sensitive in simulator expressions.

Predefined Expressions

The following expressions are predefined:

gaussian	=	_gaussian_tol(10.0)	default gaussian distribution
nfmin	=	_nfmin()	the minimum noise figure
omega	=	2.0*pi*freq	the analysis frequency
rn	=	_rn()	the noise resistance
sopt	=	_sopt	the optimum noise match
tempkelvin	=	temp + 273.15	the analysis temperature
uniform	=	_uniform_tol(10.0)	default uniform distribution

Constants and Variables

Many predefined constants and predefined global variables are available. Predefined Simulator Variables and Constants Reserved Names lists the simulator constants and variables and provides a brief description of each.

Constants

An integer constant is represented by a sequence of digits optionally preceded by a negative sign (e.g. 14 , -3 ).

A real number contains a decimal point and/or an exponential suffix using the e notation (e.g. 14.0 , -13e-10 ).

The only complex constant is the predefined constant j , which is equal to the square root of -1. It can be used to generate complex constants from real and integer constants (e.g., j*3 , 9.1 + j*1.2e-2 ). The predefined functions complex() and polar() can also be used to enter complex constants into an expression.

A string constant is delimited by single or double quotes (e.g. 'string' , "this is a string" ). Always use vertical quotes (e.g. ' <string> ') as opposed to open quotes (e.g. ` <string>').

Variables

Variables can be modified and swept. The main difference between expressions and variables is that a variable can be directly swept and modified by an analysis but an expression cannot. Note however, that any instance parameter that depends on an expression is updated whenever one of the variables that the expression depends upon is changed (e.g. by a sweep).

The general form of variables is:
variableName = constantExpression

Note Once a variable has been defined, it cannot be redefined with another variableName = constantExpression statement. This will create an error.

For example:
x1 = 4.3inches + 3mils
syc_a = cos(1.0+sin(pi*3))
Zin = 7.8k - j*3.2k

The type of a variable is determined by the type of its value. For example, x=1 is an integer, x=1+j is complex, and x = "Tuesday" is a string.

Predefined Constants and Variables Reserved Names

When you are using simulator expressions, keep in mind that predefined constants and variables are reserved words. You can use these constants and variables, but you cannot redefine them to something else. Predefined Simulator Variables and Constants Reserved Names lists the simulator constants and variables available and provides a brief description of each.

Units and Scale Factors

The fundamental units for the simulator are shown in Fundamental Units in the Simulator. A parameter with a given dimension assumes its value has the corresponding units. For example, for a resistance, R=10 its assumed to be 10 Ohms.

Fundamental Units in the Simulator

Dimension	Fundamental Unit
Frequency	Hertz
Resistance	Ohms
Conductance	Siemens
Capacitance	Farads
Inductance	Henries
Length	meters
Time	seconds
Voltage	Volts
Current	Amperes
Power	Watts
Distance	meters
Temperature	Celsius

Recognizing Scale Factors

Variations on the fundamental units in the simulator are referred to as scale factors. A scale factor is a single word that begins with a letter or an underscore character (_). The remaining characters, if any, consist of letters, digits, and underscores. The value of a scale factor is resolved using the following rules in the order shown:

1. If the scale factor exactly matches one of the predefined scale-factor words (Predefined Scale Factor Words), then use the numerical equivalent; otherwise, go to rule 2.

   Predefined Scale Factor Words

   Scale Factor Word	Numerical Equivalent	Meaning
   mil	2.54*10 -5	mils
   mils	2.54*10 -5	mils
   in	2.54*10 -2	inches
   ft	12*2.54*10 -2	feet
   mi	5280*12*2.54*10 -2	miles
   cm	1.0*10 -2	centimeters
   PHz	1.0*10 15	petahertz
   dB	1.0	decibels
   nmi	1852	nautical miles

2. If the scale factor exactly matches one of the scale-factor units (Scale Factor Units) except for m , then use the numerical equivalent; otherwise, go to rule 3.
   

   Scale Factor Units

   Scale Factor Unit	Numerical Equivalent	Meaning
   A	1.0	Amperes
   F	1.0	Farads
   H	1.0	Henries
   Hz	1.0	Hertz
   meter meters metre metres	1.0	meters
   Ohm Ohms	1.0	Ohms
   S	1.0	Siemens
   sec	1.0	seconds
   V	1.0	Volts
   W	1.0	Watts

3. If the first character of the scale factor is one of the legal scale-factor prefixes (Scale Factor Prefixes), then use the numerical equivalent; otherwise, go to rule 4.

   Scale Factor Prefixes

   Prefix	Numerical Equivalent	Meaning
   T	10 12	Tera
   G	10 9	Giga
   M	10 6	Mega
   K	10 3	kilo
   k	10 3	kilo
   _ (underscore)	1	(no scale)
   m	10 -3	milli
   u	10 -6	micro
   n	10 -9	nano
   p	10 -12	pico
   f	10 -15	femto
   a	10 -18	atto

4. The scale factor is not recognized.
   Important considerations include:
   • Scale factors are case sensitive.
   • A single m means milli, not meters.
   • A lower case f by itself means femto. An upper case F by itself means Farad.
   • A lower case a by itself means atto. An upper case A by itself means Ampere.
   • The imperial units ( mils , in , ft , mi , nmi ) do not accept prefixes.
   • The simulator will report a warning if an unrecognized scale factor is encountered, and use a scale-factor value of 1.0.
   • It is not required that the characters following a scale-factor prefix match one of the scale-factor units.
   • There are no scale factors for dBm , dBW , or temperature. Simulator functions are provided to convert these values to the corresponding fundamental units (Watts and Celsius).

Mathematical Operators and Hierarchy

Simulator expressions are evaluated from left to right, unless there are parentheses. Operators are listed from higher to lower precedence in Arithmetic and Boolean Operator Precedence. Operators on the same line have the same precedence. For example, a+bc means a+(bc), because multiplication has a higher precedence than addition. Similarly, a+b-c means (a+b)-c, because addition and subtraction have the same precedence (and because + is left-associative).

The operators !, &&, and || work with the logical values. The operands are tested for the values TRUE and FALSE, and the result of the operation is either TRUE or FALSE. A logical test of a value is TRUE for non-zero numbers or strings with non-zero length, and FALSE for 0.0 (real), 0 (integer), NULL or empty strings. Note that the right hand operand of && is only evaluated if the left hand operand tests TRUE, and the right hand operand of || is only evaluated if the left hand operand tests FALSE.

The Boolean operators >=, <=, >, <, ==, != , and, or, equals, and not equals also produce logical results, producing a logical TRUE or FALSE upon comparing the values of two expressions. These operators are most often used to compare two real numbers or integers. These operators operate differently than C with string expressions in that they actually perform the equivalent of strcmp() between the first and second operands, and test the return value against 0 using the specified operator.

Arithmetic and Boolean Operator Precedence

Operator	Name	Example
( )	function call	foo(expr_list)
[ ]	indexer, array	X[expr_list]
**	exponentiation	expr**expr
*	multiply	expr * expr
+	add	expr + expr
::	sequence operator	exp::expr::expr
<	less than	expr < expr
==	equal	expr == expr
&&	logical and	expr && expr
logical or	expr	expr

Conditional Expressions

The simulator supports simple in-line conditional expressions:
A = if boolExpr then expr else expr {{endif
A = if}} boolExpr then expr elseif boolExpr then expr else expr endif
boolExpr is a valid Boolean expression, that is, an expression that evaluates to TRUE or FALSE.
expr is any valid non-Boolean expression.
The else is required because the conditional expression must always evaluate to some value.
There can be any number of occurrences of elseif expr then expr.
A conditional expression can legally occur as the right-hand side of an expression or function definition or, if parenthesized, anywhere in an expression that a variable can occur. The dimensionality and number of points in these expressions follow the same matching conditions required for the basic operators. The type of the result depends on the type of the true and false expressions. The size of the result depends on the size of the condition, the true expression, and the false expression.

Boolean expressions

A Boolean expression must evaluate to TRUE or FALSE and, therefore, must contain a relational operator ( equals, =, ==, notequals, !=, <, >, <=, or >= ).
The only legal place for a Boolean expression is directly after an if or an elseif.
A Boolean expression cannot stand alone, that is,
x = a > b
is illegal.

Precedence

Tightest binding: equals, =, ==, notequals, !=, >, <, >=, <=
not, !
and
Loosest binding: or, ||
All arithmetic operators have tighter binding than the Boolean operators.

Evaluation

Boolean expressions are short-circuit evaluated. For example, if when evaluating a and b , expression a evaluates to FALSE, expression b will not be evaluated.
During evaluation of Boolean expressions with arithmetic operands, the operand with the lower type is promoted to the type of the other operand. For example, in 3 equals x +j*b, 3 is promoted to complex.
A complex number cannot be used with < , > , <= , or >=. Nor can an array (and remember that strings are arrays). This will cause an evaluation-time error.
Pointers can be compared only with pointers.

Examples

Protect against divide by zero:
f(a) = if a equals 0 then 1.0e100 else 1.0/a endif

Nested if's #1:
{{f(mode) = if mode equals 0 then 1-a else f2(mode) endif
f2(mode) = if mode equals 1 then log(1-a) else f3(mode) endif
f3(mode) = if mode equals 2 then exp(1-a) else 0.0 endif}}

Nested if's #2:
f(mode) = if mode equals 0 then 1-a elseif mode equals 1 then log(1-a) \
elseif mode equals 2 then exp(1-a) else 0.0 endif

Soft exponential:
{{exp_max = 1.0e16
x_max = ln(exp_max)
exp_soft(x) = if x<x_max then exp(x) else (x+1-x_max)*exp_max endif}}

Functions

You can define your own functions in simulator expressions. These functions can then be used in other expressions.

The general form of a function is:
functionName ( [ arg1, ..., argn ] ) = expression

For example:
y_srl(freq, r, l) = 1.0/(r + j*freq*l)
expl(a,b) = exp(a)*step(b-a) + exp(b)*(a-b-1)*step(a-b)

In expression , the function's arguments can be used, as can any other ADS Simulator variables, expressions, or functions. For a complete list of available simulator functions, refer to the Alphabetical Listing of Simulator Functions in Chapter 2 or consult the index.

Note The trigonometric functions always expect the argument to be specified in radians. If you want to specify the angle in degrees, then use the function deg() to convert radians to degrees, or you can use the function rad() to convert degrees to radians.

Another example of defining and using a function is:
B(x) = makearray(1,x*1.0,x*2.1,x*3.0)
B_2 = B(2)[2]
returns 4.2

Predefined Functions Reserved Names

Predefined Function Reserved Names lists predefined functions which are reserved names. Many functions in the list are used only internally, or are obsolete, so they are not described in the documentation. However, the names are still reserved.