ADS Design Kit Tutorial

This chapter provides step-by-step instructions for creating the basic parts of a sample design kit consisting of several typical RFIC foundry kit components:

A device with model reference
An include component
A device with subcircuit model
A device with Symbolically Defined Device (SDD) reference

Even though these components may not be typical for all design kits, the steps are applicable to a design kit in any technology.

To complete this tutorial, it is assumed that you have a basic working knowledge of Advanced Design System, including the location of the ADS installation directory for your computer or site. This tutorial will refer to your ADS installation directory, which is defined as $HPEESOF_DIR. For example, on a PC, an ADS 2008 installation is typically installed in C:/ADS2008. If you cannot find the installation directory on your computer or the site-wide installation on a networked system, contact your system administrator or CAD manager. For simplicity, the tutorial steps will assume a typical PC installation.

Note
The directory delimiter slash is shown as a forward slash ( / ). This should be used in most cases in a design kit, especially in AEL files, where the backslash character ( / ) is interpreted as a string formatting character. For example, "\n" is interpreted as a new line character. The AEL system() function is one of the rare cases where the back slash character may be required, and each backslash must be preceded by an extra backslash to tell the system to interpret it literally. The list of known characters that cause this problem are:\n=new line
\r=return
\f=form feed
\b=back space
\t=tab

Tutorial Overview

The list below shows the basic steps that will be performed in this tutorial and includes a short description of each section so you can quickly get a sense of what is required to build a simple design kit.

Note
The completed sample design kit is available with the ADS design kit software. For more information, refer to ADS Design Kit Tutorial.

Creating the ads.lib File describes how to create the file (ads.lib) that contains the design kits that will be loaded.
Creating the boot.ael File describes how to create a boot file (boot.ael) to load the design kit.
Creating Component Symbols explains how to create a schematic symbol (*.dsn) for each component in your design kit.
Creating Component Definitions discusses how to build a component definition AEL file (mykit_item.ael) which defines how the component is netlisted along with other properties.
Testing Your Component lists a few steps you can use to verify that your components are working properly.
Providing Basic Documentation gives an example for creating a simple text file (about.txt) used to document the design kit.
Making Components Accessible simply describes the two methods available for setting up easy access to your design kit components.
Creating a Component Palette and Bitmaps describes how to create bitmaps (*.bmp) for your design kit components. The AEL file (palette.ael), which loads the bitmaps onto a palette and makes the palette available in an ADS schematic window, is also described in this section.
Adding a Netlist Include Component describes how to create a netlist include component which can be used to include model files (*.net) in your netlist.
Creating an Example Design Using your Design Kit shows an example schematic that uses the design kit created in the tutorial.
Adding Components to the Library Browser describes two methods for making your design kit components visible in the ADS library browser.
Adding Demand Loaded Components describes how to create the item definition file (*.idf) used for dynamically loading design kit components.
Using a Subcircuit Model provides an outline of how to include a subcircuit model in your design kit using the information learned in the tutorial.
Adding a Resistor with SDD Subcircuit Model describes another component that uses a subcircuit model in a netlist file. It is included in the tutorial to show a simple example of using a Symbolically Defined Device (SDD) to define arbitrary current/voltage relationships.

Building the Basic Design Kit Parts

The first step in creating a design kit is to create the directory in which to store the basic design kit parts after they have been built. This will be the directory that you will eventually archive and distribute as the design kit. Create that directory now. You can create this directory anywhere but to simplify the tutorial, it is assumed that it will be created in the home directory ($HOME). Name this directory my_design_kit.

Create the following subdirectories in my_design_kit.design_kit

doc
circuit/symbols
circuit/ael
circuit/models
circuit/bitmaps/pc*
circuit/bitmaps/unix*
circuit/records*
de/ael

Note
Directories noted with an asterisk are optional directories that are used in this tutorial.

Creating the ads.lib File

As you will learn in The ads.lib Template, the ads.lib file contains the information that tells ADS which design kits to load and where to get the specific instructions for loading each kit.

To create the my_design_kit/design_kit/ads.lib file that will be used in this tutorial:

Open a text editor.
Enter the following line, exactly as it is written here , in a text file.
MY_DESIGN_KIT | path_to_design_kit_directory | de/ael/boot | mykit_v1
Save the file as:
$HOME/my_design_kit/design_kit/ads.lib

Note that this assumes that you have created the my_design_kit/design_kit subdirectories under your $HOME directory as described in Building the Basic Design Kit Parts.

This is now the template ads.lib file described in Understanding the ADS Design Kit File Structure and The ads.lib Template. The path cannot be entered at this time since it requires knowledge of where the design kit will be installed on the end user's system.

The design kit infrastructure software will set the path after the design kit has been installed and when the ads.lib file is being copied to a predefined directory on the user's system. This is described in detail in Design Kit Installation and Setup. You will do this manually in the next step for your own testing.

For testing the design kit, this information will need to be available in the user customization directory for design kits, $HOME/hpeesof/design_kit.

Determine if there is already a file named ads.lib in $HOME/hpeesof/design_kit.
If there is not, simply copy the ads.lib file created in the last step to that location. If there is already a file by that name, add the contents of the new file to the existing file.
Further edit this ads.lib file to set the actual design kit directory. For this tutorial, that directory is $HOME/my_design_kit on a PC. This will be different on unix.
Save the ads.lib file and close the text editor.

Creating the boot.ael File

An ael file called boot.ael must be provided so that ADS knows how to load the design kit. From the boot.ael file, you can load other AEL files, such as those that will load the item definition and palettes as described in later sections.

To create the de/ael/boot.ael file:

Open a text editor.
Copy the text in The Boot File (boot.ael) into a new file. The sample boot.ael provided in The Boot File (boot.ael) includes more information than is required. This is provided to teach you about printing debug information from an AEL file.
The Boot File (boot.ael)

// boot.ael - This file resides in the de/ael directory of the
// design kit.It is loaded by the design kit infrastructure
// software if it is listed in the file ads.lib in one of 4
// predefined locations, one of which is $HOME/hpeesof/design_kit.
// This file is used to load other AEL files such as palette.ael.
// It is also used to set up some global variables for use in
// other files. One global variable that is available by default:
// designKitRecord - this is a list which contains the 4 fields
// from ads.lib (kit name, path, boot file, version).
// As soon as the design kit load process has finished, this
// variable is unset, so save the values as a variable with a
// different name if you want access to them later.
//
// The following debug print statements can be used to view the
// values of these variables:
//
// To print a field in the list:
fputs(stderr, designKitRecord[0]);
// Now save the path variable so it is available for later use.
// Any variables declared in this file must be unique to this
// design kit.
// If you copy this boot file to make another design kit, these
// names must be changed.
decl MYKIT_PATH = designKitRecord[1];
// To view the path variable:
fputs(stderr, MYKIT_PATH);
// Comment out all debug print statements before shipping your
// design kit.
// These path names will be used later to load other files.
decl MYKIT_BITMAP_DIR = sprintf("%s/circuit/bitmaps/%s/", MYKIT_PATH, on_PC?"pc":"unix");
decl MYKIT_CIRCUIT_AEL_DIR = sprintf("%s/circuit/ael/", MYKIT_PATH);
decl MYKIT_CIRCUIT_MODEL_DIR = sprintf("%s/circuit/models/", MYKIT_PATH);
decl MYKIT_DE_AEL_DIR = sprintf("%s/de/ael/", MYKIT_PATH);
// To print a variable:
fputs(stderr, MYKIT_BITMAP_DIR);
Save the file as $HOME/my_design_kit/de/ael/boot.ael

The Boot File (boot.ael) shows the contents of your new boot.ael file. This code will be added to later in this tutorial. By accessing certain global variables, you can get the values from the ads.lib file, as described in Creating the ads.lib File. These values are stored in a list called designKitRecord.

Debug tips are included directly in the boot.ael code for your convenience. Remember to remove all debug print statements before you ship your design kit.

Note

Variables such as those in The Boot File (boot.ael) called MYKIT_PATH, etc., are global variables. The scope of an AEL variable is not restricted to the file in which it is defined. In other words, this variable must be unique in the system to avoid being overwritten by another declaration of the same variable. Therefore, in the future when you build design kits, make sure that each AEL variable name is unique. One way to do this is to include the name and version of the design kit in the variable name.

Viewing Debug Output

On unix, debug output is visible in the window from which ADS was invoked. On PC, edit the shortcut property Target and add -d daemon.log to the end of the command line (Example: C:/ADS2003C/bin/hpads.exe -d daemon.log). This will enable you to view output to stderr in a log window. Look for text in red. All other text is a communication log. The information is also saved to a file called daemon.log in the ADS startup directory.

Another option for displaying debug information is using the de_info() function to output messages to an info dialog that will pop up from ADS. Instead of fputs(stderr, "comment"); , you can use bq.de_info(identify_value("comment")); .

You can even define a utility function such as:

defun debug_print(msg)
{
de_info(identify_value(msg));
}

To use this function, simply call:

debug_print("msg");

Creating Component Symbols

The next part of your design kit to be created is a schematic symbol for each of your components. The tutorial will guide you through one method of symbol creation, copying an existing symbol. Basic Parts of an ADS Design Kit describes two other methods in Schematic Symbol.

Before creating your symbols, start ADS and create a new project called my_kit_prj in which to build the component symbols. You can create this project anywhere, but to simplify the tutorial, it is assumed that the project will be created in your home directory.

To copy an existing symbol:

Open a schematic page in your new project.
In the schematic window, choose View > Create/Edit Schematic Symbol. The Symbol Generator dialog box appears.
In the Symbol Generator dialog box, select the Copy/Modify tab.
Set the Symbol Category to Devices-BJT.
Click the BJTNPN symbol so the SYM_BJT_NPN appears in the Symbol Name field, then click OK.
Note
There may be a warning about symbol pin/component port mismatch - this can be ignored.
Once you have copied the built-in symbol, you can edit the symbol if desired. However it will not be modified for this example.
Choose File > Save Design As and save the symbol file as a new symbol called SYM_mykit_npn.dsn.

You should now have a symbol for use in your design kit. The file containing this symbol was saved in the networks directory of the project as a .dsn file. You may also see an .ael file with the same name, which will not be used.

At this time, you should delete any .ael files that may be present and copy the symbol file into the proper subdirectory of the design kit directory. That directory is $HOME/my_design_kit/circuit/symbols.

Creating Component Definitions

A component definition is added to the design environment by a create_item() command provided in an AEL file. The create_item() command is very complex.

Basic Parts of an ADS Design Kit also includes more information about the create_item() function. For this tutorial, the most you need to understand is how to define a symbol, a list of parameters, and how the component is netlisted. These are all parts of the item definition.

The create_item() functions for your sample components should be defined as follows in a file called mykit_item.ael.

For a small design kit, all the item definitions could be combined into one file like this. Another acceptable method is to create a separate file for each item. This is especially recommended if there are parameter callbacks associated with each component. In this case, a file called mykit_npn.ael would be appropriate. It is, however, acceptable to leave all components in one mykit_item.ael file, which is what the tutorial will instruct you to do.

Since the create_item() command is somewhat complex, you might find it helpful to let the system start to create your component definition for you. You can follow the steps below, which will guide you through creating and modifying the file, or you can skip steps 1-10 and just copy and paste the code shown in The Item Definition File (mykit_item.ael). Save the file as mykit_item.ael in the circuit/ael directory of your design kit and then perform step 11, which instructs the design kit to load the item definition.

To create a component definition for your BJT component:

From the ADS Main window, choose File > New Design to open a new design in ADS. The New Design dialog box appears.
In the New Design dialog box, name the design mykit_npn. Click OK to close the New Design dialog. A new schematic window is generated with the title mykit_npn.
From the new schematic window, choose File > Design Parameters. The Design Parameters dialog box appears.
In the General tab, enter the following information:
- Description: MYKIT Nonlinear Bipolar Transistor, NPN
- Component Instance Name: BJT
- Symbol Name: SYM_mykit_npn
  Note
  Type the symbol name directly into the Symbol Name field. When building future design kits, you can select a standard symbol by choosing the More Symbols button.
- Library Name: MY_DESIGN_KIT
- Model: Built-in Component
- Artwork Type: None
  Accept the defaults for all other fields.

In the Parameters tab, enter the information provided in the following table for the first parameter, Model, and then click the Add button. Repeat for all parameters listed in the table.

Parameter Name	Value Type	Default Value	Parameter Type	Parameter Description
Model	String	""	Unitless	Model Instance Name
Area	Real	1.0	Unitless	Scaling Factor, (default: 1.0)
Region	Real	1	Unitless	DC operating region,
Temp	Real	25	Temperature	Device operating temperature, (default: 25)

Note
The Design Parameter dialog box contains a parameter option check box labeled Not Edited. This is used if a parameter value never needs to be modified by the user. However, until ADS2002C, it also made the parameter un-editable by callbacks as well, so do not set that flag if the parameter needs to be modified by a parameter callback in a design kit supporting ADS prior to ADS2002C.

Click OK in the Design Parameters dialog to save and exit from the dialog.
Save the design, without entering anything in the schematic window.
Find the AEL file which was saved with the item definition. It will be in the networks directory of the project and will be called mykit_npn.ael.
Copy mykit_npn.ael to your design kit circuit/ael directory and rename it mykit_item.ael.
Edit the file so that it looks the same as the file shown below. Also, delete the last 3 lines of the file.

In order for ADS to read the new mykit_item.ael file just created, the boot file must be modified to load the mykit_item.ael file. Add the following line to the end of the my_design_kit/de/ael/boot.ael and save the boot.ael file.

load(strcat(MYKIT_CIRCUIT_AEL_DIR,"mykit_item"), "CmdOp");
Note
When writing AEL code, you must be very careful that each quote, semi-colon, parenthesis and bracket is exactly as shown. The AEL interpreter will fail if there are errors in the file, and it may not tell you where the errors are. If you get error messages when starting ADS, check your file against the file in The Item Definition File (mykit_item.ael) or compare it against the tutorial file shipped with the software.

The Item Definition File (mykit_item.ael)

set_simulator_type(1);
create_item("mykit_npn",
          "MYKIT Nonlinear Bipolar Transistor,NPN",
          "BJT",NULL, NULL, NULL,
          standard_dialog, "",
          CmpModelNetlistFmt, "",
          ComponentAnnotFmt,
          "SYM_mykit_npn",
          no_artwork, NULL,
          ITEM_PRIMITIVE_EX,
      create_parm("Model", "Model instance name", 0,
          "StdFileFormSet",UNITLESS_UNIT,prm("StdForm","BJTM1")),
      create_parm("Area","Scaling Factor, (default: 1.0)",
          PARM_OPTIMIZABLE | PARM_STATISTICAL,
          "StdFileFormSet",UNITLESS_UNIT,prm("StdForm","")),
      create_parm("Region",
          "DC operating region, 0=off, 1=on, 2=rev, 3=sat, (default: on)",
          0, "StdFileFormSet",UNITLESS_UNIT,prm("StdForm","")),
      create_parm("Temp", "Device operating temperature, (default: 25)",
          PARM_OPTIMIZABLE | PARM_STATISTICAL,
          "StdFileFormSet",TEMPERATURE_UNIT,prm("StdForm","")));

Testing Your Component

You will now be able to test your first component if you have set up all the files defined so far in this chapter. The files shown in Tutorial Directory and File Locations should now be saved in their respective directories under the design kit top level directory ($HOME/my_design_kit).

Tutorial Directory and File Locations

Directory	File(s)
design_kit	ads.lib (plus a copy of it in $HOME/hpeesof/design_kit/ads.lib)
de/ael	boot.ael
circuit/symbols	SYM_mykit_npn.dsn
circuit/ael	mykit_item.ael

To test your new component:

Restart ADS to automatically pick up the new files.
From the ADS Main window, choose DesignKit > List Design Kits. The List ADS Design Kits dialog box appears. Your design kit should be listed in the Name column of the dialog and the Status should be enabled.
Open a schematic window and type the name of your component in the Component History dialog.
After entering the component, locate your cursor onto the schematic page and place your component.
If there are no apparent problems after performing the steps listed above, your new design kit component should be ready to use.

Providing Basic Documentation

Using a text editor, you will now create the about.txt file to document your new design kit. This file should include the information listed in the template in Design Kit about.txt Template. Note that the template is only a suggested format for the file. You may modify the format of the file or include information not listed in the template.

To create the my_design_kit/doc/about.txt file:

Open a text editor.
Add the following information to a file:
Name: MY_DESIGN_KIT
Version: 1.0
Date: 11/20/2002
Description: This design kit contains the components mykit_npn and mykit_include.
Revision History: Rev. 1.
Save the new file as $HOME/my_design_kit/doc/about.txt

Making Components Accessible

There are two methods for accessing your design kit components:

A component palette on the schematic window
The ADS Library Browser

The component palette is on the left border of the schematic window. The library browser can be opened by choosing Insert > Component > Component Library. The default tool bars also include a Display Component Library List button to open the library browser.

Library control and records files are used to load the necessary information into the library browser.

While this tutorial will show you how to setup both the component palette and the library browser, you may decide to only provide one or the other. For more information on choosing one of the two, refer to Component Palette vs. Library Browser.

Creating a Component Palette and Bitmaps

Defining a component palette consists of two steps:

Creating two bitmap files (one for pc and one for unix) for each component.
Writing an AEL function to connect the bitmap to the component and load the definition into the system.

Basic Parts of an ADS Design Kit, discusses the details of bitmap creation for design kits. A new tool offered within ADS is the _DesignGuide Developer Studio_.

The Developer Studio can be installed from your ADS installation CD, if it is not already installed, and it does not require a license to run. A design guide is different than a design kit, but the bitmap tool can be used for both. For more information on the differences between DesignGuides and design kits, refer to Design Kits versus Libraries. This tool is mentioned here because it provides a bitmap editor which is specially designed to create bitmaps for use in ADS. The Save As UNIX and Save As PC menu picks facilitate saving the bitmaps in both formats. Sample bitmaps for all ADS components are available with the tool to copy as starting material. For an explanation of how to use the various features of the tool, refer to Bitmap Editor.

For a design kit with a large number of components, more than one palette group may be defined. For the sample kit in this tutorial, all components will go into one palette.

To create your UNIX and PC bitmaps:

From the ADS Main window, choose DesignGuide > DesignGuide Developer Studio > Start DesignGuide Studio. The DesignGuide Developer Studio dialog box appears. A warning dialog may appear; however, this does not apply to using just the bitmap editor so close the warning dialog box and proceed with step 2.
From the Developer Studio dialog, choose Tools > Bitmap Editor. The Bitmap Editor dialog box appears.
From the Bitmap Editor, choose File > Open. The Open Bitmap dialog box appears.
Sample bitmaps are provided in:
$HPEESOF_DIR/designguides/projects/dgstudio/ui/bitmaps/adsbmps
Open the bitmap for BJTNPN.BMP and edit the bitmap as needed to customize it for your design kit (see The mykit_npn.bmp File in the Bitmap Editor).

Note
On unix, change the Filter in the Open Bitmap dialog box to capital *.BMP to see the BJTNPN.BMP file.

The mykit_npn.bmp File in the Bitmap Editor

After editing your bitmap file, save a UNIX and a PC version of the bitmap in the appropriate design kit directories. Remember that these are:

my_design_kit/circuit/bitmaps/pc

my_design_kit/circuit/bitmaps/unix
Name the BJT bitmap mykit_npn.bmp
The final step in making the palette available is to create an AEL file called palette.ael , which contains a function call to the ADS design kit infrastructure function, {*}dk_define_palette_group().*

Note
The function dk_define_palette_group() was first introduced in ADS 2003A. If your design kit will support earlier versions of Advanced Design System, use the function de_define_palette_group() instead. For more information about the palette function, refer to Component Palette.

To create the de/ael/palette.ael file:

Open a text editor.

Copy the code below into a file.

dk_define_palette_group(SCHEM_WIN, "analogRF_net",
            "MYKIT Components","MYKIT Components", 0,
            "mykit_npn", "MYKIT NPN Bipolar Transistor",
             strcat(MYKIT_BITMAP_DIR,"mykit_npn") );

Note
Do not include the file extension (.bmp) on the bitmap name in dk_define_palette_group(). This will cause the function to fail on some unix systems.

Save the file as $HOME/my_design_kit/de/ael/palette.ael

In order for ADS to read the new palette.ael file, the boot file must be modified to load the palette.ael file. Add the following line to my_design_kit/de/ael/boot.ael now:
load(strcat(MYKIT_DE_AEL_DIR,"palette"), "CmdOp");

Note
The load() function does not need the .ael extension on the filename it is loading. If the file palette.atf is found with a newer time stamp than palette.ael , the palette.ael file will not be recompiled. If palette.ael is newer, it will be recompiled into a new palette.atf and then loaded.

For more information about the palette function, refer to Component Palette.

At this time, you can test that the palette is loaded correctly. The files shown in the table below should now be saved in their respective directories under the design kit top level directory.

Tutorial Directory and File Locations

Directory	File(s)
design_kit	ads.lib (plus a copy of it in $HOME/hpeesof/design_kit/ads.lib)
de/ael	boot.ael
circuit/symbols	SYM_mykit_npn.dsn
circuit/ael	mykit_item.ael
doc	about.txt
circuit/bitmaps/pc	mykit_npn.bmp
circuit/bitmaps/unix	mykit_npn.bmp

To test your changes:

Restart ADS to load the design kit.
Open the my_kit_prj project in ADS.
From the schematic window, select the new palette called MYKIT Components from the Component Palette List.
From the palette list on the left side panel of the schematic window, select the mykit_npn component and drag it onto the schematic page.

Adding a Netlist Include Component

The tutorial sample design kit will get its model data from a netlist file with a model card that would typically be translated from another simulator such as HSpice, with the ADS Netlist Translator.

For the ADS simulator to find an externally referenced file, a design kit must contain a netlist include component. A built-in component called NetlistInclude is provided on the Data Items palette. On this component, you must browse to or manually enter the name of the included file. The built-in NetlistInclude component is handy for testing while building a design kit, but customers who use a design kit should not have to know where the model files are stored or be bothered with manually entering the file name. The tutorial will guide you through creating a custom include component where the file name is defined automatically for the design kit user.

Note
If you place the NetlistInclude component and double click to view its parameters, select the IncludeFiles parameter and notice the field on the right side of the dialog called Section. This is one implementation of selecting a corner case as defined in a section of a model file. In your design kit, you will want to present the user with the list of available corner case labels, as opposed to making them fill in a blank. This is done by the definition of forms and formsets, as described in Forms and Formsets. An example of a component using this capability is also include in Example Process Component with Forms and Formsets.

Creating a Netlist Include Component Symbol

Create a netlist include component symbol, using the same process as described in Creating Component Symbols.

Open the my_kit_prj project in ADS if it is not already open.
In the schematic window, choose View > Create/Edit Schematic Symbol. The Symbol Generator dialog box appears.
In the Symbol Generator dialog box, select the Copy/Modify tab.
Set the Symbol Category to Data Items.
Click the Netlist symbol so the NetlistInclude appears in the Symbol Name field, then click OK.
Once you have copied the built-in symbol, you can edit the symbol.
It is beneficial for the words on the symbol to identify the design kit. Change the words NETLIST INCLUDE to MY KIT INCLUDE , as shown in MY KIT INCLUDE Component Symbol.

MY KIT INCLUDE Component Symbol

For more information on editing symbol text, refer to Editing Existing Text and Text Attributes.

Choose File > Save Design As and save the symbol file as a new symbol called, SYM_mykit_include.dsn.
Copy the saved symbol file, SYM_mykit_include.dsn , from the $HOME/my_kit_prj/networks directory to the $HOME/my_design_kit/circuit/symbols directory.

Creating the Netlist Include Component Bitmap

A bitmap must also be created for the new mykit_include component.

To create bitmaps for the include component, use the same general process as described in Creating a Component Palette and Bitmaps:

Create a bitmap that looks like the one in The mykit_include.bmp Bitmap.

The mykit_include.bmp Bitmap
Save the UNIX and PC versions of the bitmap to the $HOME/my_design_kit/circuit/bitmaps/unix (and pc) directories. The bitmap files should be named mykit_include.bmp.
Modify the palette file (de/ael/palette.ael) to add the new component to the palette as shown below.

dk_define_palette_group(SCHEM_WIN, "analogRF_net",
        "MYKIT Components", "MYKIT Components", 0,
        "mykit_npn", "MYKIT NPN Bipolar Transistor",
                     strcat(MYKIT_BITMAP_DIR,"mykit_npn"),
        "mykit_include", "MYKIT Netlist Include",
                     strcat(MYKIT_BITMAP_DIR,"mykit_include") );

In a palette with a long list of components, make sure that a custom include or process component is placed at the top of the palette. This is a visual reminder to users that this component must be present in a schematic in order to simulate a circuit that uses any of the other components on that palette.

Modifying the Item Definition File

Open the $HOME/my_design_kit/circuit/ael/mykit_item.ael file.
Append the netlist callback and item definition for the include component to your existing item definition file ( mykit_item.ael ). The create_item() function call that you add should look like:

The create_item() Function Call

set_simulator_type(1);
defun mykit_include_netlist_cb (cbP, clientData, callData)
{
    decl fileName="", netlistString="";
    fileName = strcat(MYKIT_CIRCUIT_MODEL_DIR, "mykit_models.net");
    netlistString=strcat(netlistString, "#ifndef MYKIT_INCLUDE\n");
    netlistString=strcat(netlistString, "#define MYKIT_INCLUDE\n");
    netlistString=strcat(netlistString, "#include "",
fileName,"\"\n");
    netlistString=strcat(netlistString, "#endif\n");
    return(netlistString);
}
create_item("mykit_include",                        // name
            "MYKIT Netlist Include",                // label
            "mykit_include",                        // prefix
            ITEM_UNIQUE|ITEM_NOT_NETLIST_IF_SUB,    // attribute
            0,                                      // priority
            NULL,                                   // iconName
            standard_dialog,                        // dialogName
            NULL,                                   // dialogData
            ComponentNetlistFmt,                    // netlistFormat
            "mykit_include",                        // netlistData
            ComponentAnnotFmt,                      // displayFormat
            "SYM_mykit_include",                    // symbolName
            no_artwork,                             // artworkType
            NULL,                                   // artworkData
            0,                                      // extraAttrib
            list (dm_create_cb (ITEM_NETLIST_CB,
"mykit_include_netlist_cb", NULL, TRUE)));

This item does not contain any parameters, but it does contain a netlist callback on the last line. This is provided so that when the component is netlisted for the simulator, the netlisting code can determine the location of the model file to include. Using path information saved in boot.ael , the callback generates a #include statement that points to the file mykit_models.net with a full path. The additional lines using pre-processor commands, that is, lines that start with the "#" symbol, are used to avoid component redefinition. For more information on the pre-processor commands for netlist include components refer to Avoiding Illegal Nested Subcircuits.

Notice that the netlist callback function is defined before the create_item() function. This is required if the .ael file will be compiled into an .idf file for demand-loaded components.
For more information on netlist callbacks, refer to Netlist Callbacks.

Adding a Model File

For this tutorial example, a simple NPN model with a few default values will be added to the design kit.

To add the my_design_kit/circuit/models/mykit_models.net file:

Open a text editor.
Copy the text below into a file.
model MYKIT_NPN_MODEL BJT NPN=1 PNP=0 Lateral=0 RbModel=0 Approxqb=1
Save the model file as:
$HOME/my_design_kit/circuit/models/mykit_models.net

Your design kit should now contain the files shown in the following table.

Directory	File(s)
design_kit	ads.lib (plus a copy of it in $HOME/hpeesof/design_kit/ads.lib)
de/ael	boot.ael
circuit/symbols	SYM_mykit_npn.dsn
circuit/ael	mykit_item.ael
doc	about.txt
circuit/bitmaps/pc	mykit_npn.bmp
circuit/bitmaps/unix	mykit_npn.bmp
circuit/models	mykit_models.net

Creating an Example Design Using your Design Kit

Now, your design kit is ready for use in designing a circuit.

To use your new design kit:

Restart ADS to make sure all the information is loaded.
Start a new project and open a schematic window. Name the project bjt_dc_prj.
Choose Insert > Template > BJT_curve_tracer to place an instance of the BJT_curve_tracer template on your schematic page.
Using the BJT and Include components from your design kit, complete the schematic as shown in Example Schematic.

Example Schematic
Set the model parameter on the BJT to MYKIT_NPN_MODEL. This is the same name as the model in the model file created in Adding a Model File.
Simulate the circuit. Your plot should be similar to the plot shown in IC.i vs. VCE Simulation Results.

IC.i vs. VCE Simulation Results
Save the design and the data display. Call the files bjt_dc.dsn and bjt_dc.dds.
Using the File > Archive menu pick from the ADS Main window, archive the project. Save the archived project as bjt_dc_prj.zap in the my_design_kit/examples directory.
This completes the first part of the tutorial. You have now created a simple design kit. You could, at this point, refer to Packaging for Distribution to prepare your design kit for distribution to an end user.

The example design kit that is shipped with the ADS software is included in an archived copy of the project saved at this state.

The sample design kit is located in $HPEESOF_DIR/examples/DesignKit/bjt_dc_prj/design_kit. From the ADS unarchive dialog box, you can browse to the examples directory of the shipped design kit and unarchive it anywhere on your system to compare it to the example you have just created.

The last part of the tutorial will cover the following topics:

Adding Components to the Library Browser

Adding Demand Loaded Components

Using a Subcircuit Model

Adding a Resistor with SDD Subcircuit Model

Accessing the Supplied Sample Kit

Adding Components to the Library Browser

This is an optional step. If you choose to access your components from the component palette only, you may skip this step. The many advantages of the library browser, especially when using the control and records files, are outlined in Component Palette vs. Library Browser. Information is also provided to help you decide if you should use the library browser in its simple form, complex form, or not at all.

Using the library_group() Function

The simplest way to setup design kit components to be visible in the library browser is by using the library_group() function. This is added to the palette.ael file.

To setup your tutorial components to be visible in the library browser:

In a text editor, open the $HOME/my_design_kit/de/ael/palette.ael file.
Add the following line to the end of the file.
library_group("MYKIT", "MYKIT Components", "mykit_npn", "mykit_include");
Note that the names of the components that are listed here must match the names in the item definition file mykit_items.ael. For more details on the library_group() function, refer to Library Browser, as well as Component Definition Functions.
Save the palette.ael file.
Restart ADS and open the library browser from the Insert > Component > Component Library menu pick in the schematic window.
Verify that the library is listed, that the components are selectable, and that you can place the components in a schematic.

Setting Up a Control and Records Files

The second method for defining libraries for the library browser consists of setting up a control file and a set of one or more records files. For more information on the details of the file formats, refer to Library Browser.

To setup the control file, my_design_kit/circuit/records/mykit.ctl:

In a text editor, open the $HOME/my_design_kit/de/ael/palette.ael file that you edited in Using the library_group() Function.
Comment out the library_group() function call that you entered in the palette.ael file in the previous section of the tutorial.

Open a text editor and create the file shown below.

<?xml version="1.0" ?>
<LIBRARIES>
  <LIBRARY>
    <NAME>MYKIT from control file</NAME>
    <CATEGORY>DL</CATEGORY>
    <RECORD_FILES>mykit.rec</RECORD_FILES>
  </LIBRARY>
</LIBRARIES>

Save the new file as mykit.ctl in the $HOME/my_design_kit/circuit/records directory.
Continue to the next section to write the records file.

To create the records file, which is referred to in the control file shown above:

In a text editor, create the file my_design_kit/circuit/records/mykit.rec, as shown below.

<?xml version="1.0" ?>
<COMPONENTS>
  <COMPONENT>
    <NAME>mykit_npn</NAME>
    <DESCRIPTION>MYKIT NPN Bipolar Transistor</DESCRIPTION>
    <LIBRARY>MYKIT</LIBRARY>
    <PLACEMENT>NOLAYOUT</PLACEMENT>
  </COMPONENT>
  <COMPONENT>
    <NAME>mykit_include</NAME>
    <DESCRIPTION>MYKIT Netlist Include</DESCRIPTION>
    <LIBRARY>MYKIT</LIBRARY>
    <PLACEMENT>NOLAYOUT</PLACEMENT>
  </COMPONENT>
</COMPONENTS>

Save the new file as mykit.rec , in the $HOME/my_design_kit/circuit/records directory.
After saving both the control and records files, restart ADS. The mykit.ctl and mykit.rec files will be located automatically by the software when the design kit is loaded.
Open a project and a schematic window.

Access the library browser and verify that the library is now called "MYKIT from control file". If it is displayed as expected, edit the control file to remove the words "from control file". This text was inserted temporarily to ensure that the browser entries actually came from the control file and not from the library_group() function as defined in Using the library_group() Function.

Note
The format of the control and records files is very strict. Each space, bracket and slash is very important. If you do not see your library in the library browser, check your files very carefully against the files shown above. Correct any errors that you may find and restart ADS.

To make it easier to see your library, collapse all libraries from the toolbar by clicking the Collapse Libraries icon in the Component Library/Schematic dialog box.

Adding Demand Loaded Components

There is one more optional step in the tutorial related to setting up components.

You can specify that components be loaded into ADS only when they are selected for placement. This is called demand-loading.

As described in Demand Loaded Components, one more file can be added to the circuit/records directory. This file is called an item definition file (*.idf) and is a binary version of all the item definitions created in the mykit_item.ael file.

Note
The example design kit shipped with ADS was saved after the previous section so it does not contain the .idf file described in this section. This is because this section replaces some of the files created in previous sections of the tutorial.

The advantages of using an item definition file are:

Dynamic loading of components
Faster loading speed
Lower memory usage
When the item definition file (.idf) is used, components are loaded into a hash table and then loaded into ADS only when needed. For a large kit, there is a substantial loading time and memory usage savings.

The .idf file is created by a utility program called hpedlibgen that is shipped with ADS and is stored in the bin directory under $HPEESOF_DIR (the ADS installation directory).

Note
$HPEESOF_DIR/bin must be in your path to use this utility; however, it should already be in your path if you are running ADS. You will also need to configure certain environment variables, either by sourcing $HPEESOF_DIR/bin/bootscript.sh or adding the environment variables manually as described in ADS Simulator Input Syntax.

For the next step in the tutorial,

Open a text editor and create a file in the circuit/records directory called mykit.list. This file will be used by hpedlibgen and must contain the name of all AEL files with item definitions in them, one filename per line in the list file. For our small kit, there is only one file. A larger kit may use one file per component.
The file mykit.list for the tutorial should contain the single line:
../ael/mykit_item.ael
The section on Demand Loaded Components describes how the create_item() function call must be the last function in the block of functions related to each component. The program hpedlibgen uses the end of this function as the key to start reading the next item. This tutorial has not set up any parameter callbacks or other items that would typically be stored with the item definition other than the single netlist callback for the include component.
Enter the command to create the .idf file now. The syntax for running the program for the tutorial is:
hpedlibgen -list mykit.list -out mykit.idf

To test the file, follow the steps below to remove the other methods of defining components and palettes that have been described so far in the tutorial.

Move the file circuit/ael/mykit_item.ael away to a safe place outside of the design kit directory.
Edit the file de/ael/boot.ael and comment out the line to load mykit_item.ael as shown below.
// load(strcat(MYKIT_CIRCUIT_AEL_DIR,"mykit_item"), "CmdOp");
Note that comment characters in AEL are two forward slashes at the beginning of the line (//) or the traditional C programming slash and asterisk pair delimiting a complete block of code (/* this text is commented out */).
In palette.ael , make sure the library_group() function call is commented out.

Restart ADS to make sure the components are still available and can be placed from the palette and from the library browser.

Their visibility on the palette or in the library browser is not an indication of success. The demand loading will take place when the items are selected and placed. This can be verified by checking the communication log between ADS and the library browser for a query of the form:
QUERY_ITEM_DEFINITION_RESPONSE dsn-type component-name library-name library-title ATF-file file-date file-location
The communication log will be generated if ADS is started with the optional command line argument "-d daemon.log". On a PC, add this to the shortcut property "Target". The file daemon.log will be saved into the directory from which ADS is started.

Using a Subcircuit Model

The section on Adding a Model File explains how to set up a component that refers to a model card in an included netlist file. It is also possible to use a subcircuit model in the same manner if a simple model card is not sufficient to represent the model.

As with a simple model card, the subcircuit model is typically translated from another simulator with the ADS SPICE or Spectre Netlist Translator, or it can be generated from IC-CAP.

The files or code fragments listed here can be added to the design kit created in the tutorial as an example of a subcircuit model for the BJT transistor.

The files that need to be modified or added are:

circuit/ael/mykit_item.ael	-	add the new item definition
circuit/bitmaps	-	add new bitmaps
circuit/models/mykit_models.net	-	add new model to the model file
circuit/records/mykit.rec file	-	add new component
circuit/records/mykit.idf file	-	recompile to add new component
circuit/symbols	-	no change, ok to reuse the same symbol
de/ael/palette.ael	-	add new component

The new content for each file is listed below. Refer to the earlier sections in the tutorial for a reminder of the steps required to update the sample kit.

The steps below provide a general outline of the process.

Add the new item definition to circuit/ael/mykit_item.ael as shown in my_design_kit/circuit/ael/mykit_item.ael.

set_simulator_type(1);
create_item( "mykit_npn_subckt",
             "MYKIT Nonlinear Bipolar Transistor Subckt, NPN",
             "BJT",
             NULL, NULL, NULL,
             standard_dialog, "",
             CmpModelNetlistFmt, "",
             ComponentAnnotFmt,
             "SYM_mykit_npn",
             no_artwork, NULL,
             ITEM_PRIMITIVE_EX,
create_parm("Model", "Model instance name", PARM_NOT_EDITED,
            "StdFileFormSet",UNITLESS_UNIT,
            prm("StdForm","bjt_nhf"))
);

Add the new bitmaps (see my_design_kit/circuit/bitmaps/mykit_npn_subckt.bmp) to the pc and unix subdirectories.

my_design_kit/circuit/bitmaps/mykit_npn_subckt.bmp

Add the new model to the model file circuit/models/mykit_models.net as shown below.

; subckt model for npn
define bjt_nhf (C B E )
L:LE E 4 L=1.015E-10
L:LB B 5 L=1.959E-10
C:CC C 0 C=2.505E-13
NPN:Q1 C 5 4 Area = 1
model NPN BJT NPN=yes \
Is = 1.467E-15 Bf = 221.5 Nf = 0.9915 Vaf = 44.63 Ikf = 100 \
Ise = 2.823E-13 Ne = 2.5 Br = 6.493 Nr = 0.9902 Var = 1.841 \
Ikr = 100 Isc = 5.706E-15 Nc = 1.171 Rb = 3.579 Irb = 1E-12 \
Rbm = 3.202 \
Re = 0.4211 \
Rc = 0.3492 \
Xtb = 0 \
Eg = 1.11 \
Xti = 3 \
Cje = 2.458E-12 \
Vje = 1.004 \
Mje = 0.502 \
Tf = 1.886E-11 \
Xtf = 13.97 \
Vtf = 0.2296 \
Itf = 2.225 \
Ptf = 30.72 \
Cjc = 1.685E-12 \
Vjc = 0.6296 \
Mjc = 0.3898 \
Xcjc = 0.3 \
Tr = 1E-09 \
Cjs = 9.985E-14 \
Vjs = 0.8137 \
Mjs = 0.3509 \
Fc = 0.9 \
Tnom = 27 \
end bjt_nhf

Note
In the file above, mykit_models.net, the define keyword is used to define a subcircuit model. ADS does not support nested subcircuits, so another define cannot be included before the matching end keyword. A design kit user can inadvertently cause this to happen. See Avoiding Illegal Nested Subcircuits for tips on how to prevent this from happening.

Add the new component to the records file circuit/records/mykit.rec as shown in my_design_kit/circuit/records/mykit.rec.

<COMPONENT>
 <NAME>mykit_npn_subckt</NAME>
 <DESCRIPTION>MYKIT NPN Bipolar Transistor Subckt</DESCRIPTION>
 <LIBRARY>MYKIT</LIBRARY>
 <PLACEMENT>NOLAYOUT</PLACEMENT>
</COMPONENT>

Recompile the item definition file to add the new components.
hpedlibgen -list mykit.list -out mykit.idf
Since you can re-use the same symbols, there is no need to change the circuit/symbols.

Add the new component to the de/ael/palette.ael file as shown below.

dk_define_palette_group(SCHEM_WIN, "analogRF_net", "MYKIT Components",
             "MYKIT Components", 0,
             "mykit_npn", "MYKIT NPN Bipolar Transistor",
                    strcat(MYKIT_BITMAP_DIR,"mykit_npn"),
             "mykit_npn_subckt", "MYKIT NPN Bipolar Transistor Subckt",
                    strcat(MYKIT_BITMAP_DIR,"mykit_npn_subckt"),
             "mykit_include", "MYKIT Netlist Include",
                    strcat(MYKIT_BITMAP_DIR,"mykit_include")
);

The new component is used the same way the old component was used. In the example project, delete the existing npn component and place an instance of the new subckt npn.

Avoiding Illegal Nested Subcircuits

ADS does not support nested subcircuits. Nested subcircuits will occur in a netlist when a hierarchical schematic has an include component that includes a file with a subcircuit used in any level of hierarchy other than the top level. To prevent this from occurring, set the priority of the netlist include component to zero ("0"). Setting the priority to zero netlists the include statement at the top-level of the design regardless of where it is placed in the design hierarchy.

As part of the netlist callback you should include pre-processor commands that allow only the first include statement to be used by the simulator. This is important if the user adds multiple instances of the include schematic in a design. If the model file is included more than once a redefinition error will occur. Using pre-processor commands will avoid this problem by limiting the include to the first instance in the netlist.

Example netlist

#ifndef MYKIT_NETLIST_INCLUDE |
#define MYKIT_NETLIST_INCLUDE

#include "<path>/mykit_models.net"

#endif

For more information on the pre-processor commands, refer to Model Files.

If more than one netlist include component is used in the design, there could be confusion as to which component is used. It is not straightforward to define which component will be netlisted first in a hierarchical design. Your design kit instructions should include a warning that includes components only be placed once, at the top-most, analog schematic of the design hierarchy. To further prevent multiple components, use the ITEM_UNIQUE attribute in the create_item() function call. This will prevent the user from placing more than one netlist include component in a single schematic. In a hierarchical design it is not possible to limit the number of netlist include components, since the schematic design files can be used in multiple designs.

Note
Previous versions of the Design Kit Development documentation recommended using the ITEM_NOT_NETLISTED_IF_SUB attribute with netlist include components to avoid nested subcircuits. This can create a issue if the top-level schematic is a digital schematic, since design kit components are not valid on digital schematics. Agilent EEsof EDA recommends using the method described above for avoiding illegal nested subcircuits.

Adding a Resistor with SDD Subcircuit Model

This section describes another component that uses a subcircuit model in a netlist file. It is included in the tutorial to show a simple example of using a Symbolically Defined Device (SDD) to define arbitrary current/voltage relationships. It also shows the need for defining a noise voltage source for this resistor , which is calculated using the relationship Vn=4kTReff.

Two versions of the resistor model are included with different resistivities (ρ) to demonstrate the use of forms and selecting types from the edit component dialog when placing a component. An example of a circuit which contains this component is shown in Example Circuit and is also included in the bjt_dc_prj shipped with the sample design kit code.

Example Circuit

In this example, a single current source is used to drive 1 amp through the resistor such that the value of the voltage across the resistor equals the resistance value specified on the component. Performing a simulation and then annotating the DC results (use the menu pick Simulate > Annotate DC Solution ) will verify that the correct model is being selected for simulation: the annotated voltage should equal the resistance specified on the component.

You do not always need to create a custom symbol for each design kit component. Sometimes you can use a built-in ADS symbol. In this case, the item definition in mykit_res.ael uses the built-in ADS resistor symbol SYM_R.

The file or code fragments listed here can be added to the design kit created in the tutorial. These files are also included with the ADS software in the $HPEESOF_DIR/examples/DesignKit/bjt_dc_prj/design_kit directory. It is highly recommended that you copy the file mykit_res.ael from this location since copying it from the text in the documentation is highly prone to introducing errors due to wrapping of text.

The files to modify or add to the design kit are listed below. Refer to the tutorial for the actual steps for updating the sample kit.


circuit/ael/mykit_res.ael	-	save the new item definition
circuit/bitmaps	-	add the new bitmaps mykit_res.bmp
circuit/models/mykit_models.net	-	add the new model
de/ael/boot.ael	-	add code to load AEL file mykit_res.ael
de/ael/palette.ael	-	add new component to the palette
optional:
circuit/records/mykit.rec	-	add new component for the library browser
circuit/records/mykit.list	-	add new item definition file mykit_res.ael for hpedlibgen
circuit/records/mykit.idf	-	recompile to add new component for demand loading

The steps below provide a general outline of the process.

Copy the new item definition for the resistor from the file mykit_res.ael in the $HPEESOF_DIR/examples/DesignKit/bjt_dc_prj/design_kit directory. This file is shown on the following pages.

mykit_res.ael

/*------------------------------------------------------------------------+/
FILE         : mykit_res.ael

COMMENTS     : Component definition :

[ global variables ]

[ forms and formsets ]

[ netlist callback function ]

[ parameter callback functions ]

item definition

/+------------------------------------------------------------------------*/

/*-**-- utility function to check parameter value with respect to ranges --*-/

defun parm_checkRange

(

name,

actual,

min,

max,

unitString

)

{

// check within some relative margin to compensate for round-off error.

decl scale;

if (is_string(unitString) && strlen(unitString) > 0)

scale = evaluate(sprintf("1 %s", unitString));

else

{

scale = 1;

unitString = "";

}

if (max > 0.0 && (actual-max)/max > 1.e-5)

{

warning("aelcmd", 16, "", fmt_tokens(list("The maximum", name,

"is", max/scale, unitString, "."))

);

}

else if (min > 0.0 && (min-actual)/min > 1.e-5)

{

warning("aelcmd", 16, "", fmt_tokens(list("The minimum", name,

"is", min/scale, unitString, "."))

);

}

return;

}

/-------- global variables -------------------------------------------------------/

decl res_type_default = "form_res_type_myres1";

decl res_length_default = 3.0e-6;

decl res_width_default = 5.0e-6;

decl res_height_default = 5.0e-6;

// typ model parameters: list(typeLabel, list(rho), ...

decl res_modelList = list("my resistor 1 (length >= 2.0um)",

list(12.5e-3),

"my resistor 2 (length >= 1.0um)",

list(8.5e-3)

);

// Width ranges: list(typeLabel, list(lmin, lmax), ...)

decl res_ranges = list("my resistor 1 (length >= 2.0um)",

list(2.0e-6, 0.0),

"my resistor 2 (length >= 1.0um)",

list(1.0e-6, 0.0)

);

/-------- forms and formsets ----------------------------------------------------/

// Type

create_constant_form("form_res_type_myres1",

"my resistor 1 (length >= 2.0um)", 0, "myres1",
"my_resistor1");

create_constant_form("form_res_type_myres2",

"my resistor 2 (length >= 1.0um)", 0, "myres2",
"my_resistor2");

create_form_set("formset_res_type","form_res_type_myres1",

"form_res_type_myres2");

/-------- netlist callback function ---------------------------------------------/

/-------- default value parameter callback function -----------------------------/

defun res_parm_defaultValue_cb

(

cbP,

parmName,

parmDefP

)

{

decl parmH = NULL;

/-------- calculate default parameter value ---------------------------------------/

if (!strcmp(parmName, "Type"))

{

parmH = prm(res_type_default);

}

else if (!strcmp(parmName, "length"))

{

parmH = prm("StdForm", sprintf("%g um", res_length_default/1.0e-6));

}

else if (!strcmp(parmName, "width"))

{

parmH = prm("StdForm", sprintf("%g um", res_width_default/1.0e-6));

}

else if (!strcmp(parmName, "height"))

{

parmH = prm("StdForm", sprintf("%g um", res_height_default/1.0e-6));

}

else if (!strcmp(parmName, "R"))

{

decl formDefP = dm_find_form_definition(res_type_default);

decl formLabel = dm_get_form_definition_attribute(formDefP,
DM_FORM_LABEL);

decl modelList = car(cdr(member(formLabel, res_modelList)));

decl Rho = nth(0, modelList);

decl R = Rho*res_length_default / res_width_default / res_height_default;

R = round(R*1.0e2)*1.0e-2; // round to 0.01 Ohm

parmH = prm("StdForm", sprintf("%g Ohm", R));

}

/-------- return to calling function --------------------------------------------/

return parmH;

}

/-------- modified value parameter callback function ------------------------------/

defun res_parm_modified_cb

(

cbP,       // callback function pointer

parmName,  // clientData

itemInfoP  // itemInfo pointer

)

{

decl parmList = NULL;

decl type, modelList, rangeList;

decl Rho;

decl L, W, H, R;

/--------- calculate dependent parameter values -------------------------------------/

type = pcb_get_form_value(itemInfoP, "Type");

modelList = car(cdr(member(type, res_modelList)));

rangeList = car(cdr(member(type, res_ranges)));

if (listlen(modelList) == 1)

{

Rho = nth(0, modelList);

if (!strcmp(parmName, "length") || !strcmp(parmName, "width")
|| !strcmp(parmName, "height") || !strcmp(parmName,
"Type")) ||
{

// get mks value of independent parameter(s)

L = pcb_get_mks(itemInfoP, "length");

W = pcb_get_mks(itemInfoP, "width");

H = pcb_get_mks(itemInfoP, "height");

parm_checkRange("resistor length", L, nth(0, rangeList),

nth(1, rangeList), "um");

R = Rho * L / W / H;

R = round(R*1.0e2)*1.0e-2; // round to 0.01 Ohm

// build return structure with dependent parameter(s)

parmList = pcb_set_mks(parmList, "R", R);

}

else if (!strcmp(parmName, "R"))

{

// get mks value of independent parameter(s)

R = pcb_get_mks(itemInfoP, "R");

W = pcb_get_mks(itemInfoP, "width");

H = pcb_get_mks(itemInfoP, "height");

// calculate dependent parameter(s)

L = R / Rho * W * H;

L = round(L*1.0e8)*1.0e-8; // round to 0.01 um

parm_checkRange("resistor length", L,

nth(0, rangeList), nth(1, rangeList), "um");

// build return structure with dependent parameter(s)

parmList = pcb_set_mks(parmList, "length", L);

}

}

/-------- return to calling function ---------------------------------------------/

return parmList;

}

/------- item definition ------------------------------------------------------/

create_item(

"mykit_res",                                    // name

"An ideal resistor",                            // description label

"R",                                            // prefix

0,                                              // attributes

NULL,                                           // priority

"MY_RES",                                       // iconName

standard_dialog,                                  // dialogName

NULL,                                           // dialogData

"%0b'%p'%1e:%t %# %44?0%:%31?%C%:_net%c%;%;%e %1b%r%8?%29?%:%30?%p
%:%k%?[%1i]%;=%p %;%;%;%e%e",

//  CmpModelNetlistFmt,                            // netlist format string

NULL,                                            // netlist data

ComponentAnnotFmt,                               // display format string

"SYM_R",                                         // symbol name

no_artwork,                                      // artwork type

NULL,                                            // artwork data

ITEM_PRIMITIVE_EX                                // extra attributes

,create_parm(                                    // parameter

"Type",                                        // name

"Resistor type",                               // label

PARM_DISCRETE_VALUE,                           // attrib

"formset_res_type",                            // formSet

UNITLESS_UNIT,                                 // unit code

prm(res_type_default)                          // default value

,list(dm_create_cb(PARM_DEFAULT_VALUE_CB,  // parameter default value

// callback function

"res_parm_defaultValue_cb", // function name

"Type",                     // clientData

TRUE),                      // callback enableFlag

dm_create_cb(PARM_MODIFIED_CB,                 // parameter modified value

// callback function

"res_parm_modified_cb",     // function name

"Type",                     // clientData

TRUE)                   // parameter modified value

// callback function

)

)

,create_parm(                                    // parameter

"length",                                      // name

"length, R=f(length, width, height)",          // label

PARM_OPTIMIZABLE|PARM_STATISTICAL,             // attrib

"StdFileFormSet",                              // formSet

LENGTH_UNIT,                                   // unit code

prm("StdForm", "3 um")                         // default value

,list(dm_create_cb(PARM_DEFAULT_VALUE_CB,     // parameter default value

// callback function

"res_parm_defaultValue_cb", // function name

"length",                   // clientData

TRUE),                      // callback enableFlag

dm_create_cb(PARM_MODIFIED_CB,           // parameter modified value

// callback function

"res_parm_modified_cb",     // function name

"length",                                          // clientData

TRUE)                       // parameter modified value

// callback function

)

)

,create_parm(                                      // parameter

"width",                                        // name

"width, R=f(length,width,height)",              // label

PARM_OPTIMIZABLE|PARM_STATISTICAL,              // attrib

"StdFileFormSet",                               // formSet

LENGTH_UNIT,                                    // unit code

prm("StdForm", "5 um")                          // default value

,list(dm_create_cb(PARM_DEFAULT_VALUE_CB,   // parameter default value

// callback function

"res_parm_defaultValue_cb",  // function name

"width",                     // clientData

TRUE),                       // callback enableFlag

dm_create_cb(PARM_MODIFIED_CB,        // parameter modified

// value callback function

"res_parm_modified_cb",      // function name

"width",                     // clientData

TRUE)                    // parameter modified

// value callback function

)

)

,create_parm(                                      // parameter

"height",                                       // name

"height, R=f(length, width, height)",           // label

PARM_OPTIMIZABLE|PARM_STATISTICAL,              // attrib

"StdFileFormSet",                               // formSet

LENGTH_UNIT,                                    // unit code

prm("StdForm", "5 um")                          // default value

,list(dm_create_cb(PARM_DEFAULT_VALUE_CB,   // parameter default

// value callback function

"res_parm_defaultValue_cb",  // function name

"height",                    // clientData

TRUE),                       // callback enableFlag

dm_create_cb(PARM_MODIFIED_CB,        // parameter modified

// value callback function

"res_parm_modified_cb",      // function name

"height",                    // clientData

TRUE)                    // parameter modified

// value callback function

)

)

,create_parm(                                     // parameter

)

)

,create_parm(                                      // parameter

"R",                                             // name

"R, length=f(R, width, height)",                 // label

PARM_REAL|PARM_NOT_NETLISTED,                    // attrib

"StdFileFormSet",                                // formSet

RESISTANCE_UNIT,                                 // unit code

prm("StdForm", "")                               // default value

,list(dm_create_cb(PARM_DEFAULT_VALUE_CB,    // parameter default

// value callback function

"res_parm_defaultValue_cb",   // function name

"R",                          // clientData

TRUE),                        // callback enableFlag

dm_create_cb(PARM_MODIFIED_CB,         // parameter modified

// value callback function

"res_parm_modified_cb",       // function name

"R",                          // clientData

TRUE)                     // parameter modified

// value callback function

)

)

);

Add the new bitmaps (see mykit_res.bmp) to the pc and unix subdirectories.

mykit_res.bmp

Add the new model to the model file as shown below.

; subckt models for resistor with SDD
define myres1 ( n1 n2)
parameters  length= width= height=
l=length
w=width
h=height
rho=12.5e-3
reff=rho*l/h/w
vn=sqrt(4*boltzmann*(273+temp)*reff)
V_Source:vn  n1 _net1 V_Noise=vn SaveCurrent=0
SDD:r1 _net1 n2 n2 n1 I[2,0]=0 I[1,0]=(_v1)/(rho*l/h/w)
end myres1
define myres2 ( n1 n2)
parameters  length= width= height=
l=length
w=width
h=height
rho=8.5e-3
reff=rho*l/h/w
vn=sqrt(4*boltzmann*(273+temp)*reff)
V_Source:vn  n1 _net1 V_Noise=vn SaveCurrent=0
SDD:r1 _net1 n2 n2 n1 I[2,0]=0 I[1,0]=(_v1)/(rho*l/h/w)
end myres2

In my_design_kit/de/ael/boot.ael, add the code to load the AEL file mykit_res.ael.
load(strcat(MYKIT_CIRCUIT_AEL_DIR, "mykit_res"), "CmdOp");

Add the new component to the palette.ael file as shown below.

dk_define_palette_group(SCHEM_WIN, "analogRF_net", "MYKIT Components",
        "MYKIT Components", 0,
        "mykit_npn", "MYKIT NPN Bipolar Transistor",
                strcat(MYKIT_BITMAP_DIR,"mykit_npn"),
        "mykit_res", "MYKIT Resistor with SDD",
                strcat(MYKIT_BITMAP_DIR,"mykit_res"),
        "mykit_include", "MYKIT Netlist Include",
                strcat(MYKIT_BITMAP_DIR,"mykit_include") );
library_group("MYKIT", "MYKIT Components", "mykit_npn", "mykit_res",
"mykit_include");

Add the new component to the circuit records files as shown in my_design_kit/circuit/records/mykit_res.rec.

<COMPONENT>
 <NAME>mykit_res</NAME>
 <DESCRIPTION>MYKIT Resistor with SDD</DESCRIPTION>
 <LIBRARY>MYKIT</LIBRARY>
 <PLACEMENT>NOLAYOUT</PLACEMENT>
</COMPONENT>

Add mykit_res.ael to the temporary file mykit.list. Rerun hpedlibgen to recompile the item definition file to add the new components.
hpedlibgen -list mykit.list -out mykit.idf
Since you can re-use the same symbols, there is no need to change the circuit/symbols.

Accessing the Supplied Sample Kit

A copy of the completed tutorial design kit is available with the ADS design kit software. This can be used to compare the files as you build them in the tutorial. However, since the tutorial builds the files slowly, it is recommended that you go through the process as described in the tutorial.

The sample design kit is located in:

$HPEESOF_DIR/examples/DesignKit/bjt_dc_prj/design_kit

ADS Design Kit Tutorial

Tutorial Overview

Building the Basic Design Kit Parts

Creating the ads.lib File

Creating the boot.ael File

Viewing Debug Output

Creating Component Symbols

Creating Component Definitions

Testing Your Component

Tutorial Directory and File Locations

Providing Basic Documentation

Making Components Accessible

Creating a Component Palette and Bitmaps

The mykit_npn.bmp File in the Bitmap Editor

Tutorial Directory and File Locations

Adding a Netlist Include Component

Creating a Netlist Include Component Symbol

MY KIT INCLUDE Component Symbol

Creating the Netlist Include Component Bitmap

The mykit_include.bmp Bitmap

Modifying the Item Definition File

Adding a Model File

Creating an Example Design Using your Design Kit

Example Schematic

IC.i vs. VCE Simulation Results

Adding Components to the Library Browser

Using the library_group() Function

Setting Up a Control and Records Files

Adding Demand Loaded Components

Using a Subcircuit Model

my_design_kit/circuit/bitmaps/mykit_npn_subckt.bmp

Avoiding Illegal Nested Subcircuits

Example netlist

Adding a Resistor with SDD Subcircuit Model

Example Circuit

mykit_res.bmp

Accessing the Supplied Sample Kit

Contents

Additional Resources