Introduction to AEL

Application Extension Language (AEL) is a general purpose programming language, modeled after the popular C programming language. AEL is used to configure, customize and extend the capabilities of the design environment. Like C, AEL has an extensive set of built-in function libraries, including functions for file input/output, math, string manipulation, list handling, and database query.

In general, you can use AEL for these tasks:

• Organizing libraries and palettes of components.
• Defining the interface to new user-defined components.
• Creating new components with layout artwork.
• Defining custom layout artwork functions.
• Defining the interface to discrete-valued simulation components.
• Creating custom utility functions, such as parts list generators and bill of materials.
• Automating routine tasks, such as repetitive command sequences, batch analysis, or optimizations.

For a table that shows where each function in the AEL manual can be used, see Where to Use AEL Functions.

Note Only a small subset of the language is used for component, library, or palette definitions. If you just want to customize a library or palette, you can skip the general language description and start at the section Using AEL for Library Definition.

General AEL Structure

The AEL language is similar to the C language in many ways. AEL is a procedural language, with many of the same language components as C, such as the use of variables and functions, arithmetic expressions, program flow, and logic statements. However, there are significant differences between AEL and the C language:

• AEL has no pre-processor; therefore, the #if, #ifdef, #ifndef, #endif, #define, #undef and #include directives are not supported. However, AEL files can reference other AEL files using the load() function, which has an effect similar to #include.
• Variables, pass parameters and function return values are not typed; therefore, the C keywords int, char, float, double, long, short, unsigned, auto, register, and typedef are not supported. Although a value has a particular type, the type of a variable, pass parameter, or function return is dependent only on the most recently associated value, not on the declaration of the variable, parameter, or function. Supported values are long, double, string, and boolean.
• AEL also supports complex numbers and lists which are not supported by C.
• AEL does not support structures or unions which are part of standard C, nor does it support external or static variables. All variables defined outside of a function are global.
• Variables can be declared globally (outside a function definition), local to a function, or declared within a compound statement.
• AEL supports a large subset of the C operators and logic and control constructs. However, AEL does not support the right arrow (->) and period (.). Brackets ([ ]) are supported for list access only. For example:

  a=list("yes", "no")
  b=[0] - "yes"
  b=[1] - "no"

  The switch, case, and default logic and control constructs are supported.

• AEL does not support casting; however, there are several type conversion functions.
• AEL features automatic garbage collection, a language feature that automatically re-claims storage when it is no longer needed.

Note If you are unfamiliar with the C language, refer to The C Programming Language by Kernighan and Ritchie.

Language Specifics

The AEL language can be described in terms of the six classes of tokens: comments, identifiers, keywords, constants, operators, and other separators. Like the C language, blanks, tabs, new lines, and comments are ignored except as separators for other tokens.

Comments

The characters /* or // introduce a comment. If the characters /* are used, the comment ends with the next occurrence of the characters */. If the characters // are used, the comment continues to the end of the line.

Naming Convention for Variables

Lists

All lists are 0 based, starting at 0, not 1.

Identifiers

An identifier is a sequence of letters, digits, and underscore, where the first character must not be a digit. Case is significant for identifiers. There is no limit to the length of an identifier. Identifiers are used to represent function names, variable names, or statement labels.

Keywords

These identifiers are reserved for use as keywords:

Constants

AEL supports two constant forms not supported by C: the null value and the imaginary number. These constants represent internal data types not found in C. The list is also an internal data type, but there is no constant expression for a list. The supported forms of constants are:

A string constant consists of one or more characters enclosed in quotation marks (" "). Unlike C, AEL does not allow you to treat strings as arrays of characters. A string constant can have embedded non-printable characters, expressed using the backslash:

Note If you do not want to convert control characters, use 2 single quotes around the string instead of quotation marks; for example: '' \usr\dsn\nim.dsn ''.

Predefined Global Constants

To simplify the use of the database query functions, a set of symbolic constants, called global variables, have been predefined. The global boolean definitions are: TRUE, FALSE. Other global variables are shown with the applicable function definition.

Note that literally thousands of functions and global variables are defined in the Advanced Design System Design Environment (DE). To ensure that your functions and global variables do not interfere with those provided in the program, you should add a special prefix to your functions and variables. Further, different setups or users at your site should use unique definitions to distinguish newly-created sets of functions and variables (such as, by using a special prefix). For example:

mc1_varname
mimic_abc

Caution Do not use a dollar sign ($) as a special operator, since this character is used in expressions.

Operators

Constants and identifiers can be combined, by using operators, to form expressions. Expressions can be combined again, by using operators, to form more complex expressions. Expressions are the building blocks of AEL. Expressions can be used in assignments to variables and passed as parameters when calling AEL functions. AEL expressions are described and evaluated in the same way as in the C language, where operators are applied in order of their precedence. As with C, the default precedence applied in evaluating an expression can be overridden by grouping operands with parentheses. The following table lists (by operator precedence) the mathematical operators that are recognized in expressions.

Operators which have one operand are called unary operators. These include !, ~, ++, −−, −, *, and &. The operand follows the operator except for ++ and −−. The operator follows the operand in the post-increment and post-decrement use of ++ and −−. Unlike C, the unary * and & operators can be used only with identifiers. However, they generate the address or dereference an address much like C does.

Binary operators have two operands which are separated by the operator. Most of the operators fall into this category. Most of the binary operators perform mathematical operations on real numbers, but there are a few exceptional operators.

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. In AEL 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 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 in AEL 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.

The operators ~, &, ^, |, <<, and >> are considered bitwise operators and work only with integers, manipulating the binary bits of the value.

There are several assignment operators: =, +=, -=. *=, /=, %=, ^=, |=, &=, <<=, and >>=. These operators always have an identifier as the left hand operand, and modify the value of the variable as well as returning its value after modification. Multiple assignments are supported (e.g., a=b=4) which evaluate right to left.

As in C, there is only one ternary operator, the conditional evaluation operator, which has the form:

expression ? expression : expression

This operator evaluates the first expression and tests it. If the value of the first expression is zero it evaluates the third expression, and if not zero it evaluates the second expression.

An expression can also be a function call, which takes the following form:

identifier( argument_list )

The identifier is the name of the function and argument_list is a list of comma separated expressions representing the values of the parameters passed to the function. The function can return a value for use as an operand in evaluating additional expressions.

The sequential evaluation operator is used to cause several comma separated expressions to be evaluated in left-to-right order, with only the last value returned.

Other Separators

In addition to the operators, several other separators are used in AEL to form statements:

Building AEL Programs

AEL programs consist of a sequence of one or more of the following forms of AEL statements:

• Comment
• Simple statement
• Compound statement
• Variable declaration
• Function definition
• Control and logic statements

Comment

Comments are allowed anywhere, as long as the contents of the comment are not required to complete a statement or function definition. Comments begin with // or /*. In the first case, the comment continues to the end of the line, and in the second case the comment ends with */.

// single line comment
/* multi-line comment */

Simple Statement

A simple AEL statement is an AEL expression terminated by a semicolon (;) where the resulting value of the expression is discarded. Expressions often have side effects caused by evaluation which can be more important than the resulting value. Some examples of simple AEL statements are:

Compound Statement

A compound statement is several statements grouped together inside braces { }. Any type of statement can be contained in a compound statement. Compound statements are used to define the body of a function, switch statement, or the action of a conditional or loop statement.

Variable Declaration

The keyword decl begins a variable declaration, followed by a comma-separated identifier list, and terminated by a semicolon. Each identifier can be given an initial value using the = assignment operator. An example of a variable declaration is:

decl a, b=5, cosA=cos(A);

A variable declaration without an initial value has the value NULL. A variable can be declared more than once, in which case the first declaration prevails and the identity of the variable is maintained through subsequent declarations.

Note If a variable is declared with an initial value, the 2nd declaration prevails. That is, if a global variable is re-declared and initialized, then the global variable writes over the previous value; if the global variable is declared but is not initialized, the previous value is retained.

A variable declaration outside of a function definition is considered global. Inside a function definition a variable is considered local to the function. Variable declarations contained inside a compound statement are hidden from expressions outside the compound statement.

AEL Lists

Declaration and Initialization of an AEL List:

An AEL list is a collection of AEL values. It is created by:

list(<val1>, <val2>, etc...);

where <valx> is any valid AEL value, including another AEL list.

Example:

decl a = list(1,2,3);
decl b = -3.44;
decl c = list(1,1.5, "hello",a, b);

Printing Lists:

The value of a list can be printed using the identify_value() function.

Example:

fputs(stderr,identify_value(c));
// output is:  list(1,1.5,"hello", list(1,2,3), -3.44)

See List Management Functions for documentation on traversing lists and other operations on lists.

Function Definitions

The general form of a function definition is:

defun identifier (parameter_list)
{
      statements (body)
}

The keyword defun begins a function definition. The name of the function is the identifier. The parameter_list is a list of comma-separated identifiers defining the parameters of the functions. A return statement (consisting of a return keyword optionally followed by an expression and terminated by a semicolon) ends the function and specifies the return value. All AEL functions return a value. If the return statement is missing or no value was given for the return statement, the return value is NULL. If a function returning a NULL value is used in the context of an expression, the evaluation of the expression can fail, causing an AEL error.

Note AEL functions must be defined before they can be called.

Control and Logic Statements

AEL supports many of the C control and logic capabilities. The control and logic statements which can be used are:

goto label;
if (expression) block
else if (expression) block
else block
for (statement; expression; statement) block
do block while (expression);
while (expression) block
switch (expression) {case statements}

where:

label is a defined statement label;
expression is a combination of values, functions, and operators evaluating to a single value;
statement is also a single expression where the value is discarded; and
block is a single statement, or several statements enclosed in braces.

If goto is used within a function definition, the label must be defined in the same function definition. Switch and case statements are the same as case statements in C language.

AEL Arrays

Declaration and Initialization

AEL supports multidimensional arrays. An array must be initialized in a declaration or in an assignment statement.

Note The number of elements in the initialization statement MUST be the same as the loop. You can initialize an array to one element, and then resize it later using the resize_array() function.

Note In AEL arrays, {} and [] are treated the same. If you are using HPvars, {} is a row vector and [] is a column vector.

Array elements are separated by ",". Array elements can be integers, doubles, or complex numbers. Sequences can also be used to initialize an integer or double array.

When specifying values in a dimension, you can use the following inside of either {}'s or []'s:

• scalar values separated by commas
• a sequence
• a sequences with steps

If you are specifying an array with more than one dimension, you can specify an inner dimension WITHOUT using {}'s or []'s by using a ";" to separate the dimensions.

Examples:

Row vectors or one dimensional array:

decl x = {1+3i, 4-5i, 9+3i, 10i};

This array consists of the following elements:

x[0] = 1+3i
x[1] = 4-5i
x[2] = 9+3i
x[3] = 0+10i

x = [1+3i, 4-5i, 9+3i, 10i];

This array consists of the following elements:

x[0] = 1+3i
x[1] = 4-5i
x[2] = 9+3i
x[3] = 0+10i

x = {1::10)

This array shows initializing with a sequence and consists of the following elements:

x[0] = 1
x[1] = 2
x[2] = 3
x[4] = 4
x[5] = 5
...
x[9] = 10

x = {1::0.5::2)

This array shows initializing with a sequence and a step (how much to increment) and consists of the following elements:

x[0] = 1
x[1] = 1.5
x[2] = 2

Column vector or two dimensional array with row dimension being 0:

decl z;
z = {{1},{2},{3}};
z = [1;2;3];

Both examples produce the same array and consists of the following elements:

z[0] = {1} (one dimensional array)
z[1] = {2}
z[2] = {3}
z[0,0] = 1 (scalar values)
z[1,0] = 2
z[2,0] = 3

Matrix or a two dimensional array:

decl y;
y = { {1,2}, {3,4}, {5,6}, {7,8} };
y = [ 1,2; 3,4; 5,6; 7,8 ];

Both examples produce the same array and consists of the following elements:

y[0] = {1,2} (one dimensional array)
y[1] = {3,4}
y[2] = {5,6}
y[3] = {7,8}
y[0,0] = 1 (scalar values)
y[0,1] = 2
y[1,0] = 3
y[1,1] = 4
y[2,0] = 5
y[2,1] = 6
y[3,0] = 7
y[3,1] = 8

Three dimensional array:

decl s;
s = {[0,1;2,3],[4,5;6,7]};
s = {{{0,1},{2,3}},{{4,5},{6,7}}}

Both examples produce the same array and consists of the following elements:

s[0] = 0,1},{2,3 (two dimensional array)
s[1] = 4,5},{6,7
s[0,0] = {0,1} (one dimensional array)
s[0,1] = {2,3}
s[1,0] = {4,5}
s[1,1] = {6,7}
s[0,0,0] = 0 (scalar values)
s[0,0,1] = 1
s[0,1,0] = 2
s[0,1,1] = 3
s[1,0,0] = 4
s[1,0,1] = 5
s[1,2,0] = 6
s[1,1,1] = 7

Printing Arrays

The value of an array can be printed using the identify_value() function.

Example:

// this would output "{1+3i, 4-5i, 9+3i, 10i\}"
fprintf(stdout, "%s\n", identify_value(x));

// this would output "{{1,2},{3,4},{5,6},{7,8}}"
fprintf\(stdout, "%s\n", identify_value(y));

Operations Between Arrays

Some operations on a whole array can be executed. These include assignments, additions, subtraction, multiplication (which is essentially matrix multiplication), division, and negation.

When assignments are made, the receiver of the assignment will point to the same array as the original array. However, when a modification is made to an array, a new array is created so that other variables pointing to that array will not be modified. This is a significant difference between AEL arrays and C arrays.

Example:

decl x = {1,2,3,4};

// z = {1,2,3,4}
decl z = x;

// x = {1,2,3,4} and z = {5,5}
z = {5,5};

When addition or subtraction is executed between whole arrays, the math is executed one element at a time. Therefore, the array bounds must be exactly the same. Element by element multiplication, division and power are also supported by using the operators: .*, ./, and .**.

Example:

decl x = {1,2,3,4};
decl y = {9,8,7,6};

// z = {10,10,10,10};
decl z = x + y;

x = { {1,2}, {3,4} };
y = { {10,9}, {8,7} };

// z = { {-9,-7}, {-5,-3} };
z = x - y;

// z = { {10,18}, {24,28} };
z = x .* y;

When multiplication is executed between whole arrays, matrix multiplication is executed. Therefore, the arrays must be 2 dimensional and the array bounds must be compatible for matrix multiplication, which is row1 x col1 * row2 x col2 where the dimension of col1 must equal the dimension of row2. The new array will have the dimensions row1 x col2; that is, 4 x 2 * 2 x 8 = 4 x 8.

Example:

x = { {1,2}, {3,4} };
y = { {10,9}, {8,7} };

// z = { {26,23}, {62,55} };
z = x * y;

Note Currently, the following short hand notations are supported: +=, -=, *=.

Operations Between Scalar and Arrays

Any math operation between an array and scalar values is legal. The result of such expressions is an array.

Example:

decl x = {1,2,3,4};

// x = "{6,7,8,9}"
x += 5; 

// x = "{32,28,24,22}"
x = 100 / x * 2;

Transpose

Transposition of arrays is supported. The syntax is:

Example:

decl x = {1,2,3,4};

// y = {{1},{2},{3},{4}}
y = x';

Access and Operations on Array Elements

Individual elements are accessed by specifying the array name followed by the index(s) enclosed in square brackets "[]". There are three ways to access elements of multidimensional arrays:

• The indices can be separated by commas and the whole sequence enclosed in square brackets; for example, y[1,3]
• Each index can be enclosed in square brackets; for example, y[1][3]
• An index can be an AEL sequence; for example, y[1::3]

When individual elements are accessed, they are treated as any other scalar variable. That is they can be assigned, printed, parameters, or simply accessed. Note that the indices begin with 0.

Example:

// x's 2nd element is modified to a new value
x[1] = 10-10i;

// an element in y is printed, the value printed is "4" 
fprintf(stderr, "%s",identify_value(y[1,1])); 

// an element in y is changed from "7" to "50"
y[3][0] = 50;

// this loop produces the sum of all elements of x
sum = 0;
for ( i=0; i<4; i++)
sum += x\[i];

Looping

It is possible to loop with for and while statements, like in C. The first three examples below will print out 0 1 2 3 4 5 6 7 8 9. The 4th example prints out 1 2 3 4 6 7 8 9 10.

For Loop Example

decl i;
for (i=0; i<10; i++)
   fprintf(stderr,"%i ",i);

While Loop Example

decl stop, cnt;
stop = FALSE;
cnt = 0;
while (!stop)
{ 
   fprintf(stderr, "%i ",cnt++);
   if (cnt == 10)
     stop = TRUE;
}

While Loop Example

decl i;
i = 0;
while (TRUE) 
{ 
   fprintf(stderr, "%i ",i++);
   if (i == 10)
     break;
}

While Loop with Continue Example

decl i;
i = 0;
while (TRUE) 
{ 
   i++;
   if (i == 5)
     continue;
   fprintf(stderr, "%i ",i);
   if (i == 10)
     break;
}

AEL Array Functions (Used in AEL Scripts)

The AEL array functions used in AEL scripts are:
offset_array(), resize_array(), array_size(), array_type(), array_lowerBound(), array_upperBound(), and convert_array().

Writing, Loading and Testing AEL Functions

For component and artwork definitions, you can refer to the AEL files supplied with the program. These files, which define the entire element sets for each simulator, contain hundreds of examples. The files are located in the installation directory for your application:

$HPEESOF_DIR/circuit/ael (for Analog/Rf applications)
$HPEESOF_DIR/adsptolemy/ael (for Signal Processing applications)
$HPEESOF_DIR/de/ael (for the Design Environment, all applications)

You can use any text editor to write AEL files.

Note There is a special procedure to install an AEL file so that the functions defined in the file can be used in a circuit simulation. Refer to Chapter 1 in the Measurement Expressions manual for more information.

Playing an AEL Macro

In the ADS Main window, you can replay an AEL macro using the Tools > Playback Macro command. You can execute AEL statements interactively by typing the statement in the Tools > Command Line dialog box. For example, the first value in a list could be examined by typing:

fputs(stderr, car(list(1,2,3)));

The value 1 would be displayed in stderr.

Loading AEL Files

You can load AEL files by executing the load() command, either from the Command Line dialog box or as a statement in an AEL file. For example:

load("myfunc.ael");

Any number of functions can be declared in a single AEL file and any function in the loaded file can then be executed by entering the function name and parameters. For example:

testit(1,2, "myfunc");

You can load AEL files automatically when you start the program in one of these ways:

• By adding the name of the file containing the functions to one of the configuration variables LOCAL_AEL or USER_AEL and specifying the path to the file in the AEL_PATH variable. LOCAL_AEL is a project-specific variable that is reloaded every time a project is loaded (once per project). USER_AEL is a user-specific variable that is loaded once per program session (once per user). For details on configuring these variables, refer to Customizing the ADS Environment in the Customization and Configuration manual.
• By using the -m option; for example, ads -m startup.ael.
• By placing the file in the networks subdirectory of a project, which automatically loads the file when opening the project.

When files are loaded automatically by the program, these files are also compiled automatically. Any file loaded is re-compiled if it is modified or if its compiled version does not exist. Compiling greatly increases the speed in which the function is loaded and it also performs a simplified syntax check. When creating AEL files, you can perform a quick check of their syntax by pre-compiling the AEL file. For details on manually compiling AEL files, refer to the section Using the AEL Compiler.

Testing AEL Functions

You can test most functions by loading the AEL file from the Command Line dialog box. Debugging of the program is limited to adding fputs() and fprintf() statements in the file to determine function values and code execution. When using fputs() and fprintf() statements be sure to direct the fputs() and fprintf() output to standard error, stderr, or to a file, since stdout is used by the project design environment to communicate with other programs.

On UNIX, the results of an fputs() or fprintf() statement sent to stderr will be displayed in the terminal window that the program was started in. On a PC, the program needs to be started as follows:

ads -d daemon.log

This command opens the program with a window that contains all debugging statements and the results of fputs() and fprintf() statements sent to stderr. On UNIX, this method creates a logging file called daemon.log. For example, to see something print to a UNIX terminal or PC window:

• In the Main window, choose Tools > Command Line.
• In the dialog, type:
  fputs(stderr, "hello world!");
• Click Apply.

AEL Loading Context

When an AEL file is loaded, functions and variable references are resolved according to the loading context, which specifies the AEL vocabulary to search. New definitions in the AEL file are also added to the context vocabulary.

CmdOp and SimCmd Loading Contexts

The Advanced Design System contains two important contexts, called SimCmd and CmdOp. When AEL files are loaded at program start-up or when you enter AEL from the Command Line, the context is CmdOp. When the dialog callbacks are invoked, the context is SimCmd. SimCmd is a superset of CmdOp; that is, when the context is SimCmd, all of the definitions in CmdOp are accessible. But when the context is CmdOp, the definitions in SimCmd cannot be accessed and fail with the message: "could not find global word".

An AEL file that contains new AEL functions or variables can be loaded automatically at program start up. The functions or variables are then accessible from the Command Line and menu commands.

The default loading context is CmdOp, which is also the context in which all AEL definitions in ADS get loaded. The normal context for project's networks .ael files is a project-specific context. This context is a superset of SimCmd. When the definitions in the file must be accessed while running the program, the context must be CmdOp.

The default loading context can be overwritten by specifying the optional second argument (the context name) for the load() function. This can be specified when loading the AEL file from another startup AEL file, or from the command line. For example, to load an AEL file "test" in the SimCmd, you can use the following load command:

load ("test", "SimCmd");

The loading context within a particular AEL file can be fixed using the AEL directive #voc(). The argument to #voc() specifies the new loading context. If no argument is specified, the loading context is reset to the default for the file. The loading context fixed using #voc() overrides that set by the load() function. For example, when placed in an AEL file that is loaded in the CmdOp context, #voc(SimCmd) causes the lines in the AEL file following it to be loaded in SimCmd context. When a #voc() directive is encountered, or the end of file is reached, the loading context reverts back to CmdOp.

....         //Loading context is CmdOp
#voc(SimCmd) //Loading context is set to SimCmd
....         //AEL code is loaded in SimCmd
#voc()       //Loading context is reset to CmdOp

Using the AEL Compiler

When creating AEL functions, you can pre-compile the AEL file by using the AEL compiler, aelcomp, in a stand-alone mode. Any errors in syntax are reported by the compiler and a compiled atf AEL file is produced. The compiler is invoked automatically by the Design Environment whenever an AEL file is loaded that has been modified since the last compile or is missing its compiled atf counterpart. To run the AEL compiler, enter the following instruction at the command line:

aelcomp <input>.ael <output>.atf

• The input file and output file names are required and must be specified with their extensions. Normally, the extensions ael and atf are used for the input and output files, respectively.
• Aelcomp has one option, -version, which prints out version info on aelcomp itself. To use this option at the command line, type

aelcomp -version

On UNIX, you must set the shared library path before you run the AEL compiler. Using a bourne shell (sh) or k shell (ksh), enter the following at the command line to set the shared library path:

$HPEESOF_DIR=<your complete installation path>
export HPEESOF_DIR
PATH=$HPEESOF_DIR/bin:$PATH
export PATH
. bootscript.sh

Customizing the Parts List

The Parts List command has extensive customization capability using AEL function calls. To configure the Pick and Place Options, simply modify the routines called each time a Pick and Place Report is generated. These routines are located in the de_parts.ael file located in your program installation directory under de/ael.

Parts List Example Using an AEL Macro

In this example, the AEL macro traverses the database to query information about a design and generates a simple parts list (Parts List Example). To run the macro enter this instruction at the command line:

plist();

Parts List Example